Thư viện oauth2-server là một giải pháp mạnh mẽ và tuân thủ tiêu chuẩn để xây dựng máy chủ cấp phép OAuth 2.0 cho các ứng dụng Node.js. Bài viết này sẽ hướng dẫn bạn cách thiết lập và sử dụng các tính năng cốt lõi của thư viện này một cách nhanh chóng.

Cài đặt và Cấu hình Cơ bản

Để bắt đầu với oauth2-server, bạn cần cài đặt nó thông qua trình quản lý gói npm:

npm install oauth2-server

Mô-đun chính này được thiết kế không phụ thuộc vào framework HTTP cụ thể, cho phép nó hoạt động với bất kỳ máy chủ HTTP Node.js nào. Tuy nhiên, đối với các framework phổ biến như Express hay Koa, thư viện cung cấp các adapter chuyên biệt (ví dụ: express-oauth-server hoặc koa-oauth-server) để tích hợp dễ dàng và hiệu quả hơn.

Tổng quan các Tính năng Chính

Thư viện oauth2-server cung cấp một bộ chức năng toàn diện, bao gồm:

• Hỗ trợ đầy đủ các Luồng Cấp phép OAuth 2.0:
  • Mã ủy quyền (Authorization Code)
  • Thông tin xác thực máy khách (Client Credentials)
  • Mã làm mới (Refresh Token)
  • Thông tin xác thực của chủ sở hữu tài nguyên (Resource Owner Password Credentials)
  • Các luồng cấp phép mở rộng (Extension Grants)
• Giao diện lập trình linh hoạt:
  • Tương thích với Promise, hàm callback, generator ES6 và cú pháp async/await.
  • Tuân thủ nghiêm ngặt các tiêu chuẩn OAuth 2.0 (RFC 6749) và Bearer Token (RFC 6750).
• Thiết kế độc lập với lưu trữ:
  • Có thể tích hợp với bất kỳ hệ quản trị cơ sở dữ liệu nào như PostgreSQL, MySQL, MongoDB, Redis, v.v.

Ví dụ Khởi tạo Nhanh

Khởi tạo Máy chủ OAuth

Đầu tiên, bạn cần tạo một thể hiện của OAuth2Server, truyền vào đối tượng model của riêng bạn để xử lý logic nghiệp vụ:

const OAuth2Framework = require('oauth2-server');

const authService = new OAuth2Framework({
  model: require('./my-data-model'), // Triển khai logic dữ liệu của bạn
  accessTokenLifetime: 3600, // Thời gian sống của access token (giây)
  allowBearerTokensInQueryString: true // Cho phép truyền token qua query string
});

Đối tượng Request và Response

oauth2-server sử dụng các đối tượng Request và Response riêng biệt, có thể được tạo từ các đối tượng request/response HTTP thông thường:

const AuthRequest = OAuth2Framework.Request;
const AuthResponse = OAuth2Framework.Response;

// Giả định một yêu cầu HTTP đến
let clientReq = new AuthRequest({
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: {
    username: 'user@example.com',
    password: 'password123'
  },
  query: {}
});

// Đối tượng phản hồi sẽ được máy chủ OAuth điền
let serverRes = new AuthResponse({
  headers: {}
});

Xác thực Access Token

Sử dụng phương thức authenticate để kiểm tra tính hợp lệ của access token từ client:

authService.authenticate(clientReq, serverRes)
  .then((grantedToken) => {
    console.log('Xác thực token thành công:', grantedToken);
    // Token hợp lệ, tiếp tục xử lý yêu cầu
  })
  .catch((validationError) => {
    console.error('Xác thực token thất bại:', validationError.message);
    // Token không hợp lệ hoặc hết hạn
  });

Xử lý Yêu cầu Ủy quyền

Phương thức authorize được dùng để xử lý yêu cầu ủy quyền từ client, thường là trong luồng cấp phép Authorization Code:

const AccessDeniedError = require('oauth2-server/lib/errors/access-denied-error');

authService.authorize(clientReq, serverRes)
  .then((authCode) => {
    console.log('Yêu cầu ủy quyền được chấp thuận. Mã ủy quyền:', authCode);
    // Chuyển hướng người dùng với authCode
  })
  .catch((authError) => {
    if (authError instanceof AccessDeniedError) {
      console.warn('Người dùng đã từ chối yêu cầu ủy quyền.');
    } else {
      console.error('Lỗi trong quá trình ủy quyền:', authError.message);
    }
  });

Cấp phát Access Token

Sử dụng phương thức token để cấp phát access token và refresh token cho client sau khi xác thực thành công hoặc đổi mã ủy quyền:

authService.token(clientReq, serverRes)
  .then((issuedTokens) => {
    console.log('Cấp phát token thành công:', issuedTokens);
    // Gửi issuedTokens về client
  })
  .catch((issueError) => {
    console.error('Không thể cấp phát token:', issueError.message);
  });

Hiểu sâu hơn về Model Layer

Một trong những điểm mạnh của oauth2-server là thiết kế độc lập với lưu trữ thông qua khái niệm "Model". Nhà phát triển cần triển khai một đối tượng Model chứa các phương thức xử lý logic nghiệp vụ cụ thể, ví dụ:

• Xác thực thông tin đăng nhập của người dùng.
• Kiểm tra tính hợp lệ của client (clientId, clientSecret, redirectUri).
• Lưu trữ và truy xuất access token, refresh token, và mã ủy quyền.
• Quản lý phạm vi (scopes) quyền.

Thiết kế này mang lại sự linh hoạt tối đa, cho phép bạn tích hợp oauth2-server vào bất kỳ hệ thống backend nào với cơ sở dữ liệu và cơ chế xác thực hiện có. Việc nắm vững các luồng cấp phép OAuth 2.0 và cách triển khai Model layer là chìa khóa để tận dụng triệt để thư viện này trong các dự án của bạn.