OAuth2.0授权码模式接入指南

调用时序

概述

OAuth 2.0 是一种广泛使用的授权协议，允许第三方应用程序通过用户的授权来访问其资源，而无需暴露用户的凭据。在 OAuth 2.0 的授权码模式中，客户端需要引导用户访问授权服务器的授权端点（Authorization Endpoint），以获取用户的授权许可。

本文档旨在详细说明如何根据 OAuth 2.0 协议拼接和使用授权地址，并提供实际的示例和注意事项。

一、拼接URL获取授权码

授权地址的基本结构

授权地址是客户端向授权服务器发起请求时所使用的 URL。它由以下几个部分组成：

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

参数说明

参数名	是否必填	描述
`response_type`	必填	授权类型，通常为 `code`（表示使用授权码模式）
`clientId`	必填	客户端的唯一标识符，即 APP ID
`redirectUri`	必填	授权完成后重定向的目标地址，必须与客户端注册时的回调地址一致
`scope`	必填	请求的权限范围，目前支持`signature`、`stamp`、`comparisons`，授权后，可请求eSign.AI已有的openapi。多个scope可用空格分割
`state`	可选	用于防止 CSRF 攻击的随机字符串，客户端生成并在回调时验证其一致性

授权地址拼接步骤

确定授权服务器地址 沙箱环境为：https://account-sml.esignglobal.com/oauth
正式环境为：https://account.esignglobal.com/oauth
设置参数值 根据实际需求，设置各个参数的值。以下是一个示例：
- response_type: code
- clientId: your-client-id-12345
- redirectUri: https://your-app.com/callback
- scope: signature
- state: random-state-value

拼接查询参数 将上述参数按照键值对的形式拼接到授权服务器地址后，使用 & 连接每个参数。注意，参数值需要进行 URL 编码。

示例拼接结果：

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

验证拼接结果 确保拼接后的地址符合以下要求：
- 参数顺序可以任意
- 参数值已正确进行 URL 编码
- 所有必填参数均已包含

示例代码

以下是几种常见编程语言中拼接授权地址的示例代码：

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)

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);

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);
    }
}

注意事项

在拼接和使用授权地址时，需要注意以下几点：

URL 编码的正确性 所有参数值必须经过 URL 编码（percent-encoding），以确保特殊字符（如 :、/、? 等）不会破坏 URL 的结构。例如，https://your-app.com/callback 应编码为 https%3A%2F%2Fyour-app.com%2Fcallback。
回调地址的一致性redirect_uri 参数的值必须与客户端在授权服务器上注册的回调地址完全一致，包括协议（http 或 https）、主机名、端口和路径。否则，授权服务器会拒绝请求。
state 参数的安全性state 参数用于防止跨站请求伪造（CSRF）攻击。客户端应生成一个随机且不可预测的字符串，并在用户完成授权后验证回调中的 state 值是否与最初发送的值一致。
权限范围的合理性scope 参数定义了客户端请求的权限范围。应根据实际需求选择最小化的权限范围，避免过度请求用户资源，从而提高用户信任度。
环境区分 在开发和测试阶段，通常使用沙箱环境（如 account-sml.esignglobal.com），在正式上线后，需切换到生产环境（如 account.esignglobal.com），确保在不同环境中使用正确的授权服务器地址。
授权成功后的信息处理 授权完成后，eSign.AI授权服务将通过redirect_uri拼接返回code和baseUrl，通过baseUrl可识别授权方数据所在的数据中心，执行openapi请求时，需要根据对应的数据中心发起请求。
错误处理 如果用户拒绝授权或发生其他错误，授权服务器会通过 redirect_uri 返回错误信息（如 error 和 error_description 参数），客户端应妥善处理这些错误，向用户提供清晰的反馈。