Hướng dẫn tích hợp chế độ mã ủy quyền OAuth2.0

Trình tự gọi

Tổng quan

OAuth 2.0 là một giao thức ủy quyền được sử dụng rộng rãi, cho phép các ứng dụng bên thứ ba truy cập tài nguyên của người dùng thông qua sự cho phép của họ mà không cần tiết lộ thông tin xác thực. Trong chế độ mã ủy quyền (Authorization Code) của OAuth 2.0, máy khách cần hướng người dùng truy cập vào điểm cuối ủy quyền (Authorization Endpoint) của máy chủ ủy quyền để lấy sự cho phép của người dùng.

Tài liệu này nhằm mục đích mô tả chi tiết cách xây dựng và sử dụng địa chỉ ủy quyền theo giao thức OAuth 2.0, đồng thời cung cấp các ví dụ thực tế và những lưu ý.

I. Xây dựng URL để lấy mã ủy quyền

Cấu trúc cơ bản của địa chỉ ủy quyền

Địa chỉ ủy quyền là URL được máy khách sử dụng khi gửi yêu cầu đến máy chủ ủy quyền. Nó bao gồm các thành phần sau:

https://<authorization-server-domain>/oauth?
    response_type=<response_type>&
    clientId=<client_id>&
    redirectUri=<redirect_uri>&
    scope=<scope>&
    state=<state>

Giải thích tham số

Tên tham số	Bắt buộc hay không	Mô tả
`response_type`	Bắt buộc	Loại ủy quyền, thường là `code`(biểu thị việc sử dụng chế độ mã ủy quyền)
`clientId`	Bắt buộc	Mã định danh duy nhất của client,tức là APP ID
`redirectUri`	Bắt buộc	Địa chỉ đích chuyển hướng sau khi cấp quyền hoàn tất, phải khớp với địa chỉ callback khi đăng ký client.
`scope`	Bắt buộc	Phạm vi quyền hạn yêu cầu, hiện hỗ trợ`signature`、`stamp`、`comparisons`, sau khi cấp quyền, có thể yêu cầu các openapi có sẵn của eSignGlobal. Các scope có thể phân cách bằng dấu cách.
`state`	Tùy chọn	Chuỗi ngẫu nhiên dùng để ngăn chặn tấn công CSRF, do client tạo ra và xác minh tính nhất quán khi callback.

Các bước ghép nối địa chỉ cấp quyền

Xác định địa chỉ máy chủ cấp quyền Môi trường sandbox là: https://account-sml.esignglobal.com/oauth
Môi trường production là: https://account.esignglobal.com/oauth
Thiết lập giá trị tham số Dựa trên nhu cầu thực tế, thiết lập giá trị cho từng tham số. Dưới đây là một ví dụ:
- response_type: code
- clientId: your-client-id-12345
- redirectUri: https://your-app.com/callback
- scope: signature
- state: random-state-value
Ghép các tham số truy vấn Sau khi ghép các tham số trên theo dạng cặp khóa-giá trị vào địa chỉ máy chủ ủy quyền, sử dụng & để nối từng tham số. Lưu ý, giá trị tham số cần được mã hóa URL.
Kết quả ghép mẫu:
```
https://account-sml.esignglobal.com/oauth?
    response_type=code&
    clientId=your-client-id-12345&
    redirectUri=https%3A%2F%2Fyour-app.com%2Fcallback&
    scope=signature&
    state=random-state-value
```
Kiểm tra kết quả ghép Đảm bảo địa chỉ sau khi ghép đáp ứng các yêu cầu sau:
- Thứ tự tham số có thể tùy ý
- Giá trị tham số đã được mã hóa URL chính xác
- Đã bao gồm tất cả các tham số bắt buộc

Mã ví dụ

Dưới đây là mã ví dụ về cách ghép địa chỉ ủy quyền trong một số ngôn ngữ lập trình phổ biến:

Ví dụ Python

import urllib.parse

# 定义参数
base_url = "https://account-sml.esignglobal.com/oauth"
params = {
    "response_type": "code",
    "clientId": "your-client-id-12345",
    "redirectUri": "https://your-app.com/callback",
    "scope": "signature",
    "state": "random-state-value"
}

# 拼接地址
query_string = urllib.parse.urlencode(params)
authorization_url = f"{base_url}?{query_string}"
print(authorization_url)

Ví dụ JavaScript

// 定义参数
const baseUrl = "https://account-sml.esignglobal.com/oauth";
const params = new URLSearchParams({
    response_type: "code",
    clientId: "your-client-id-12345",
    redirectUri: "https://your-app.com/callback",
    scope: "signature",
    state: "random-state-value"
});

// 拼接地址
const authorizationUrl = `${baseUrl}?${params.toString()}`;
console.log(authorizationUrl);

Ví dụ Java

import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

public class OAuthUrlBuilder {

    public static void main(String[ ] args) throws Exception {

        // 定义参数
        String baseUrl = "https://account-sml.esignglobal.com/oauth";
        String responseType = "code";
        String clientId = "your-client-id-12345";
        String redirectUri = "https://your-app.com/callback";
        String scope = "signature";
        String state = "random-state-value";

        // 拼接查询参数
        String queryString = String.format(
            "response_type=%s&clientId=%s&redirectUri=%s&scope=%s&state=%s",
            URLEncoder.encode(responseType, StandardCharsets.UTF_8),
            URLEncoder.encode(clientId, StandardCharsets.UTF_8),
            URLEncoder.encode(redirectUri, StandardCharsets.UTF_8),
            URLEncoder.encode(scope, StandardCharsets.UTF_8),
            URLEncoder.encode(state, StandardCharsets.UTF_8)
        );

        // 生成完整的授权地址
        String authorizationUrl = baseUrl + "?" + queryString;
        System.out.println(authorizationUrl);
    }
}

Các điểm cần lưu ý

Khi xây dựng và sử dụng URL ủy quyền, cần lưu ý các điểm sau:

Tính chính xác của mã hóa URL Tất cả các giá trị tham số phải được mã hóa URL (percent-encoding) để đảm bảo các ký tự đặc biệt (như :、/、? v.v.) không làm phá vỡ cấu trúc URL. Ví dụ,https://your-app.com/callback nên được mã hóa thành https%3A%2F%2Fyour-app.com%2Fcallback。
Tính nhất quán của địa chỉ chuyển hướngredirect_uri Giá trị của tham số phải hoàn toàn trùng khớp với địa chỉ chuyển hướng đã đăng ký bởi máy khách trên máy chủ ủy quyền, bao gồm giao thức (http hoặc https), tên máy chủ, cổng và đường dẫn. Nếu không, máy chủ ủy quyền sẽ từ chối yêu cầu.
state Tính bảo mật của tham sốstate Tham số này được sử dụng để ngăn chặn tấn công giả mạo yêu cầu liên trang (CSRF). Máy khách nên tạo một chuỗi ngẫu nhiên, không thể dự đoán và xác minh trong quá trình gọi lại sau khi người dùng hoàn tất ủy quyền rằng state có khớp với giá trị ban đầu đã gửi hay không.
Tính hợp lý của phạm vi quyềnscope Tham số xác định phạm vi quyền mà máy khách đang yêu cầu. Cần lựa chọn phạm vi quyền tối thiểu phù hợp với nhu cầu thực tế, tránh yêu cầu quá mức tài nguyên người dùng, qua đó nâng cao niềm tin của người dùng.
Phân biệt môi trường Trong giai đoạn phát triển và kiểm thử, thường sử dụng môi trường sandbox (như account-sml.esignglobal.com），sau khi chính thức đưa lên vận hành, cần chuyển sang môi trường production (như account.esignglobal.com），đảm bảo sử dụng đúng địa chỉ máy chủ ủy quyền trong các môi trường khác nhau.
Xử lý thông tin sau khi ủy quyền thành công Sau khi hoàn tất ủy quyền, dịch vụ ủy quyền eSignGlobal sẽ thông quaredirect_urinối để trả vềcodevàbaseUrl，thông quabaseUrlcó thể xác định được trung tâm dữ liệu chứa dữ liệu của bên ủy quyền, khi thực hiện yêu cầu openapi, cần phải khởi tạo yêu cầu dựa trên trung tâm dữ liệu tương ứng.
Xử lý lỗi Nếu người dùng từ chối ủy quyền hoặc xảy ra lỗi khác, máy chủ ủy quyền sẽ thông qua redirect_uri trả về thông tin lỗi (như error và error_description tham số), phía client cần xử lý các lỗi này một cách phù hợp, cung cấp phản hồi rõ ràng cho người dùng.