Chuyển tới nội dung chính

Luồng xác thực Channel App

Nếu ứng dụng của bạn yêu cầu xác thực để truy cập tài nguyên và bạn muốn tận dụng hệ sinh thái người dùng hiện có trong các cộng đồng Mezon, Channel App cung cấp tính năng nâng cao giúp nhà phát triển tích hợp xác thực và phân quyền người dùng kênh thông qua hệ thống người dùng của Mezon.

Channel App cung cấp cơ chế xác thực mạnh mẽ cho phép tích hợp liền mạch giữa ứng dụng web của bạn và cơ sở người dùng Mezon, loại bỏ nhu cầu hệ thống quản lý người dùng riêng biệt.

Xác thực dựa trên Hash là gì?​

Xác thực dựa trên hash là phương pháp bảo mật trong đó:

  • Dữ liệu xác thực người dùng được nhúng trong chuỗi hash đã ký mật mã bởi nền tảng Mezon
  • Hash chứa thông tin người dùng và được kiểm tra bằng chữ ký HMAC-SHA256
  • Ứng dụng web của bạn kiểm tra chữ ký hash để xác thực người dùng
  • Không cần chuyển hướng OAuth2 bên ngoài

Tổng quan kiến trúc​

Bằng cách làm theo Hướng dẫn Bắt đầu, bạn đã có channel app trên nền tảng Mezon với ứng dụng web được tích hợp. Hãy khám phá mối quan hệ giữa các thành phần khác nhau trong luồng xác thực.

Cấu trúc dữ liệu Hash​

Dữ liệu hash nhận từ Mezon chứa các thành phần sau:

Định dạng Hash thô​

query_id=AAHdF6UqAAAAAB0XpSoKhRAd&user=%7B%22id%22%3A123456789%2C%22username%22%3A%22mezon_dev%22%2C%22mezon_id%22%3A%22mezon.dev%40ncc.asia%22%7D&auth_date=1640995200&signature=abc123def456&hash=7f3c4e8a9b2d1f6e5c8a7b4e9d2f8c1e6a9b3c7d

Các tham số đã giải mã​

  • query_id: Mã định danh truy vấn duy nhất từ Mezon
  • user: Chuỗi JSON được mã hóa URL chứa thông tin người dùng
  • auth_date: Unix timestamp thời điểm tạo xác thực
  • signature: Dữ liệu chữ ký bổ sung để kiểm tra
  • hash: Chữ ký HMAC-SHA256 của toàn bộ dữ liệu (dùng để kiểm tra)

Cấu trúc đối tượng User​

{
  "id": 123456789,
  "username": "mezon_dev",
  "display_name": "Mezon Dev",
  "avatar_url": "https://cdn.mezon.ai/avatar.jpg",
  "mezon_id": "mezon.dev@ncc.asia"
}

Triển khai luồng xác thực Hash như thế nào?​

Bước 1: Triển khai Frontend​

Khi Mezon mở channel app của bạn, nó truyền dữ liệu xác thực người dùng qua tham số truy vấn URL. Trích xuất dữ liệu này và gửi tới backend để kiểm tra.

Trích xuất dữ liệu xác thực từ URL​

// Extract authentication data from URL query parameters
function getAuthDataFromURL() {
  const urlParams = new URLSearchParams(window.location.search);
  const authData = urlParams.get('data');
  
  if (!authData) {
    console.warn('No authentication data found in URL');
    return null;
  }
  
  // Decode the URL-encoded data
  return decodeURIComponent(authData);
}

// Get the authentication data
const rawHashData = getAuthDataFromURL();

if (rawHashData) {
  console.log('Authentication data received:', rawHashData);
  // Process the hash data for authentication
  authenticateWithHash(rawHashData);
} else {
  console.error('No authentication data available');
  // Handle the case where no auth data is present
}

Triển khai Frontend đầy đủ​

Dưới đây là triển khai HTML và JavaScript toàn diện để xử lý xác thực Mezon qua tham số URL:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Mezon Channel App Authentication</title>
    <style>
      body {
        font-family: Arial, sans-serif;
        margin: 0;
        padding: 20px;
        background: var(--mezon-bg-color, #f5f5f5);
        color: var(--mezon-text-color, #333);
      }

      .auth-container {
        max-width: 600px;
        margin: 0 auto;
        padding: 20px;
        background: var(--mezon-card-bg, #ffffff);
        border-radius: 8px;
        box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
      }

      .status {
        padding: 10px;
        border-radius: 5px;
        margin: 10px 0;
      }

      .status.loading {
        background-color: #fff3cd;
        color: #856404;
      }
      .status.success {
        background-color: #d4edda;
        color: #155724;
      }
      .status.error {
        background-color: #f8d7da;
        color: #721c24;
      }
      .status.info {
        background-color: #d1ecf1;
        color: #0c5460;
      }

      .auth-details {
        background: #f8f9fa;
        padding: 15px;
        border-radius: 5px;
        margin: 15px 0;
        font-family: monospace;
        font-size: 12px;
        white-space: pre-wrap;
      }

      button {
        background: var(--mezon-button-bg, #007bff);
        color: var(--mezon-button-text, white);
        border: none;
        padding: 10px 20px;
        border-radius: 5px;
        cursor: pointer;
        margin: 5px;
      }

      button:hover {
        background: var(--mezon-button-hover, #0056b3);
      }
    </style>
  </head>
  <body>
    <div class="auth-container">
      <h1>Mezon Channel App Authentication</h1>

      <div id="connectionStatus" class="status info">Initializing...</div>

      <div id="authSection">
        <h3>Authentication Status</h3>
        <div id="authStatus" class="status info">Ready to authenticate</div>
      </div>

      <div id="userInfo" style="display: none;">
        <h3>Authenticated User</h3>
        <div id="userDetails" class="auth-details"></div>
      </div>
    </div>

    <script>
      class MezonAuthApp {
        constructor() {
          this.authEndpoint = "/api/auth/mezon-hash"; // Your backend auth endpoint
          this.init();
        }

        init() {
          this.updateConnectionStatus();
          this.checkForAuthData();
        }

        updateConnectionStatus() {
          const statusEl = document.getElementById("connectionStatus");
          statusEl.className = "status success";
          statusEl.innerHTML = "✅ Channel App Loaded";
        }

        checkForAuthData() {
          // Extract authentication data from URL
          const authData = this.getAuthDataFromURL();
          
          if (authData) {
            this.updateAuthStatus("Authentication data found", "info");
            this.authenticateWithHash(authData);
          } else {
            this.updateAuthStatus("No authentication data found in URL", "info");
          }
        }

        getAuthDataFromURL() {
          const urlParams = new URLSearchParams(window.location.search);
          const authData = urlParams.get('data');
          
          if (!authData) {
            console.warn('No authentication data found in URL');
            return null;
          }
          
          try {
            // Decode the URL-encoded data
            const decodedData = decodeURIComponent(authData);
            console.log('Authentication data received');
            return decodedData;
          } catch (error) {
            console.error('Error decoding authentication data:', error);
            return null;
          }
        }

        authenticateWithHash(rawHashData) {
          console.log("Processing hash data for authentication");
          this.updateAuthStatus("Processing authentication...", "loading");

          try {
            // Process hash data
            const authModel = this.processHashData(rawHashData);

            // Send to backend for validation
            this.sendAuthRequest(authModel);
          } catch (error) {
            console.error("Error processing hash data:", error);
            this.updateAuthStatus(
              "Error processing authentication data",
              "error"
            );
          }
        }

        processHashData(rawHashData) {
          // Base64 encode the hash data for secure transmission
          const encodedHashData = btoa(rawHashData);

          return {
            hashData: encodedHashData,
          };
        }

        async sendAuthRequest(authModel) {
          try {
            const response = await fetch(this.authEndpoint, {
              method: "POST",
              headers: {
                "Content-Type": "application/json",
              },
              body: JSON.stringify(authModel),
            });

            if (!response.ok) {
              throw new Error(`Authentication failed: ${response.statusText}`);
            }

            const result = await response.json();
            this.handleAuthSuccess(result);
          } catch (error) {
            console.error("Authentication request failed:", error);
            this.updateAuthStatus(
              `Authentication failed: ${error.message}`,
              "error"
            );
          }
        }

        handleAuthSuccess(result) {
          console.log("Authentication successful:", result);
          this.updateAuthStatus("Authentication successful!", "success");

          // Store the authentication token
          if (result.token) {
            localStorage.setItem("auth_token", result.token);
          }

          // Display user information
          if (result.user) {
            this.displayUserInfo(result.user);
          }

          // Redirect or continue with app initialization
          // window.location.href = '/dashboard';
        }

        displayUserInfo(user) {
          const userInfoDiv = document.getElementById("userInfo");
          const userDetailsDiv = document.getElementById("userDetails");

          userDetailsDiv.textContent = JSON.stringify(user, null, 2);
          userInfoDiv.style.display = "block";
        }

        updateAuthStatus(message, type) {
          const authStatusEl = document.getElementById("authStatus");
          authStatusEl.className = `status ${type}`;
          authStatusEl.textContent = message;
        }
      }

      // Initialize the app when DOM is ready
      const mezonAuthApp = new MezonAuthApp();
    </script>
  </body>
</html>

Trình xử lý xác thực đơn giản​

Để tích hợp vào ứng dụng hiện có, đây là lớp JavaScript đơn giản:

class SimpleMezonAuth {
  constructor(options = {}) {
    this.authEndpoint = options.authEndpoint || "/api/auth/mezon-hash";
    this.onSuccess = options.onSuccess || this.defaultSuccessHandler;
    this.onError = options.onError || this.defaultErrorHandler;

    this.init();
  }

  init() {
    this.startAuthFlow();
  }

  startAuthFlow() {
    // Extract auth data from URL
    const authData = this.getAuthDataFromURL();
    
    if (authData) {
      this.processAuthentication(authData);
    } else {
      this.onError('No authentication data found in URL');
    }
  }

  getAuthDataFromURL() {
    const urlParams = new URLSearchParams(window.location.search);
    const authData = urlParams.get('data');
    
    if (!authData) {
      return null;
    }
    
    try {
      return decodeURIComponent(authData);
    } catch (error) {
      console.error('Error decoding auth data:', error);
      return null;
    }
  }

  async processAuthentication(rawHashData) {
    try {
      const authData = {
        hashData: btoa(rawHashData),
      };

      const response = await fetch(this.authEndpoint, {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(authData),
      });

      const result = await response.json();

      if (result.success) {
        this.onSuccess(result);
      } else {
        this.onError(result.error);
      }
    } catch (error) {
      this.onError(error.message);
    }
  }

  defaultSuccessHandler(result) {
    console.log("Authentication successful:", result);
    if (result.token) {
      localStorage.setItem("auth_token", result.token);
    }
  }

  defaultErrorHandler(error) {
    console.error("Authentication failed:", error);
  }
}

// Usage example:
// const auth = new SimpleMezonAuth({
//     authEndpoint: '/api/auth/mezon-hash',
//     onSuccess: (result) => {
//         console.log('User authenticated:', result.user);
//         window.location.href = '/dashboard';
//     },
//     onError: (error) => {
//         alert('Authentication failed: ' + error);
//     }
// });

Bước 2: Triển khai Backend​

Ở phía máy chủ, bạn cần định nghĩa endpoint nhận thông tin hash người dùng và kiểm tra nó.

Quy trình kiểm tra Hash​

Quy trình kiểm tra hash liên quan đến việc hiểu cơ chế và dữ liệu mà Mezon sử dụng. Quy trình tạo token hash gồm 3 bước:

  1. MD5 Hash: App Secret của bạn được hash bằng MD5, kết quả dùng làm khóa cho bước 2
  2. HMAC-SHA256: Dùng HMAC-SHA256 với khóa từ bước 1 để hash chuỗi "WebAppData", kết quả dùng ở bước 3
  3. Final Hash: Dùng toàn bộ dữ liệu gửi từ frontend (trừ phần hash) làm đầu vào cho bước 3, kết hợp với kết quả từ bước 2 làm khóa. Hash toàn bộ dữ liệu bằng HMAC-SHA256 để có chuỗi hash cuối cùng
const crypto = require('crypto');

function validateMezonHash(appSecret, hashData) {
  try {
    // Parse hash data
    const delimiter = '&hash=';
    const index = hashData.indexOf(delimiter);
    const queryData = hashData.substring(0, index);
    const receivedHash = hashData.substring(index + delimiter.length);

    // Step 1: MD5 hash of app secret
    const hashedSecret = crypto.createHash('md5').update(appSecret).digest('hex');

    // Step 2: HMAC-SHA256 of "WebAppData" with hashed secret
    const secretKey = crypto.createHmac('sha256', hashedSecret).update('WebAppData').digest();

    // Step 3: HMAC-SHA256 of query data with secret key
    const computedHash = crypto.createHmac('sha256', secretKey).update(queryData).digest('hex');

    // Compare hashes
    return computedHash === receivedHash;
  } catch (error) {
    console.error('Hash validation error:', error);
    return false;
  }
}

// Usage example
app.post('/api/auth/mezon-hash', (req, res) => {
  const { hashData } = req.body;
  const rawHashData = Buffer.from(hashData, 'base64').toString('utf-8');

  const isValid = validateMezonHash(process.env.MEZON_APP_SECRET, rawHashData);

  if (isValid) {
    // Extract user data and create session
    const userData = parseUserData(rawHashData);
    const token = generateJWTToken(userData);

    res.json({
      success: true,
      accessToken: token,
      user: userData
    });
  } else {
    res.status(401).json({
      success: false,
      error: 'Invalid hash signature'
    });
  }
});

Ví dụ triển khai Backend đầy đủ (Node.js/Express)​

const express = require("express");
const crypto = require("crypto");
const jwt = require("jsonwebtoken");
const app = express();

app.use(express.json());

// Utility functions
function validateMezonHash(appSecret, hashData) {
  try {
    const delimiter = "&hash=";
    const index = hashData.indexOf(delimiter);
    const queryData = hashData.substring(0, index);
    const receivedHash = hashData.substring(index + delimiter.length);

    // Hash validation process
    const hashedSecret = crypto
      .createHash("md5")
      .update(appSecret)
      .digest("hex");
    const secretKey = crypto
      .createHmac("sha256", hashedSecret)
      .update("WebAppData")
      .digest();
    const computedHash = crypto
      .createHmac("sha256", secretKey)
      .update(queryData)
      .digest("hex");

    return computedHash === receivedHash;
  } catch (error) {
    console.error("Hash validation error:", error);
    return false;
  }
}

function parseUserData(hashData) {
  const delimiter = "&hash=";
  const queryData = hashData.substring(0, hashData.indexOf(delimiter));

  const params = new URLSearchParams(queryData);
  const userJSON = decodeURIComponent(params.get("user"));
  const user = JSON.parse(userJSON);

  return {
    query_id: params.get("query_id"),
    user: user,
    auth_date: parseInt(params.get("auth_date")),
    signature: params.get("signature"),
  };
}

function generateJWTToken(userData) {
  const payload = {
    user_id: userData.user.id,
    username: userData.user.username,
    mezon_id: userData.user.mezon_id,
    exp: Math.floor(Date.now() / 1000) + 60 * 60 * 24, // 24 hours
  };

  return jwt.sign(payload, process.env.JWT_SECRET);
}

// Authentication endpoint
app.post("/api/auth/mezon-hash", async (req, res) => {
  try {
    const { hashData } = req.body;

    if (!hashData) {
      return res.status(400).json({
        success: false,
        error: "Hash data is required",
      });
    }

    // Decode base64 hash data
    const rawHashData = Buffer.from(hashData, "base64").toString("utf-8");
    console.log("Received hash data:", rawHashData);

    // Validate hash signature
    const isValid = validateMezonHash(
      process.env.MEZON_APP_SECRET,
      rawHashData
    );
    if (!isValid) {
      return res.status(401).json({
        success: false,
        error: "Invalid hash signature",
      });
    }

    // Parse user data
    const userData = parseUserData(rawHashData);
    console.log("Parsed user data:", userData);

    // Check if user exists in your database
    const user = await findOrCreateUser(userData.user);
    if (!user) {
      return res.status(401).json({
        success: false,
        error: "User not found or cannot be created",
      });
    }

    // Generate JWT token
    const accessToken = generateJWTToken(userData);

    // Return successful authentication
    res.json({
      success: true,
      accessToken: accessToken,
      expiresIn: 86400, // 24 hours in seconds
      user: {
        id: user.id,
        username: user.username,
        email: user.email,
        displayName: user.displayName,
      },
    });
  } catch (error) {
    console.error("Authentication error:", error);
    res.status(500).json({
      success: false,
      error: "Internal server error",
    });
  }
});

// Mock user database operations
async function findOrCreateUser(mezonUser) {
  // Implement your user lookup/creation logic here
  // This could involve database queries to find existing users
  // or create new users based on Mezon data

  // Example implementation:
  let user = await User.findOne({ email: mezonUser.mezon_id });

  if (!user) {
    // Create new user if doesn't exist
    user = await User.create({
      email: mezonUser.mezon_id,
      username: mezonUser.username,
      displayName: mezonUser.display_name || mezonUser.username,
      avatarUrl: mezonUser.avatar_url,
      mezonId: mezonUser.id,
    });
  }

  return user;
}

app.listen(3000, () => {
  console.log("Server running on port 3000");
});

Luồng xác thực hoàn chỉnh​

Luồng hoàn chỉnh hoạt động như sau:

  1. Người dùng mở channel app trong Mezon
  2. Mezon tạo hash với dữ liệu người dùng và chữ ký mật mã
  3. Mezon tải ứng dụng web của bạn kèm dữ liệu xác thực trong tham số truy vấn URL (?data=...)
  4. Frontend trích xuất dữ liệu xác thực: JavaScript đọc tham số data từ URL
  5. Giải mã dữ liệu: Frontend giải mã URL chuỗi xác thực
  6. Xử lý hash: Frontend mã hóa base64 hash và gửi tới backend
  7. Kiểm tra hash: Backend kiểm tra chữ ký bằng xác minh mật mã
  8. Xác thực người dùng: Backend tìm/tạo người dùng và tạo JWT token
  9. Thiết lập phiên: Frontend lưu token và chuyển hướng tới ứng dụng

Xử lý lỗi và khắc phục sự cố​

Các tình huống lỗi thường gặp​

Xử lý lỗi Frontend​

// Comprehensive error handling in your service
public authenticateWithHash(authModel: MezonHashAuthModel): Observable<any> {
  return this.http.post('/api/auth/mezon-hash', authModel).pipe(
    map(response => ({ ...response, loading: false })),
    catchError((error: HttpErrorResponse) => {
      console.error('Authentication failed:', error);

      let errorMessage = 'Authentication failed';
      if (error.error?.error) {
        errorMessage = error.error.error;
      } else if (error.status === 401) {
        errorMessage = 'Invalid authentication credentials';
      } else if (error.status === 0) {
        errorMessage = 'Network error - please check your connection';
      }

      return of({
        loading: false,
        success: false,
        error: errorMessage
      });
    })
  );
}

Xử lý lỗi Backend​

app.post("/api/auth/mezon-hash", async (req, res) => {
  try {
    // ... authentication logic
  } catch (error) {
    console.error("Authentication error:", error);

    // Return appropriate error responses
    if (error.name === "ValidationError") {
      return res.status(400).json({
        success: false,
        error: "Invalid request data",
      });
    } else if (error.name === "JsonWebTokenError") {
      return res.status(500).json({
        success: false,
        error: "Token generation failed",
      });
    } else {
      return res.status(500).json({
        success: false,
        error: "Internal server error",
      });
    }
  }
});

Các thực hành bảo mật tốt nhất​

  1. Luôn kiểm tra chữ ký hash trước khi xử lý dữ liệu người dùng
  2. Dùng biến môi trường cho cấu hình nhạy cảm như app secret
  3. Triển khai xử lý lỗi phù hợp mà không lộ chi tiết nội bộ
  4. Thêm giới hạn tốc độ để ngăn lạm dụng endpoint xác thực
  5. Ghi log các lần thử xác thực để giám sát bảo mật
  6. Kiểm tra dữ liệu người dùng trước khi tạo bản ghi cơ sở dữ liệu
  7. Dùng HTTPS cho mọi giao tiếp trong môi trường production

Kiểm thử triển khai của bạn​

Kiểm thử Backend​

// Test hash validation
const assert = require("assert");

function testHashValidation() {
  const appSecret = "test-secret";
  const validHashData =
    "query_id=test&user=%7B%22id%22%3A123%7D&auth_date=1640995200&hash=valid-hash";

  // Test with valid hash
  const isValid = validateMezonHash(appSecret, validHashData);
  console.log("Hash validation test:", isValid ? "PASSED" : "FAILED");
}

testHashValidation();

Đây là phần kết thúc tài liệu Luồng xác thực Channel App toàn diện. Xác thực dựa trên hash cung cấp cách an toàn và liền mạch để xác thực người dùng từ Mezon vào ứng dụng của bạn mà không cần luồng đăng nhập riêng.