OAuth 2.0 Authorization Code Flow Integration Guide

Call Sequence

Overview

OAuth 2.0 is a widely used authorization protocol that allows third-party applications to access user resources with user consent without exposing their credentials. In the OAuth 2.0 Authorization Code flow, the client must direct the user to the authorization server's Authorization Endpoint to obtain user authorization.

This document aims to detail how to construct and use the authorization URL according to the OAuth 2.0 protocol, providing practical examples and important notes.

1. Constructing the URL to Obtain an Authorization Code

Basic Structure of the Authorization URL

The authorization URL is the URL used by the client to initiate a request to the authorization server. It consists of the following parts:

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

Parameter Description

Steps to construct the authorization URL

1. Determine the authorization server address Sandbox environment: https://account-sml.esignglobal.com/oauth

   Production environment: https://account.esignglobal.com/oauth

2. Set parameter values Set the values of each parameter according to actual needs. The following is an example:
   • response_type: code
   • clientId: your-client-id-12345
   • redirectUri: https://your-app.com/callback
   • scope: signature
   • state: random-state-value
3. Concatenate Query Parameters After appending the above parameters as key-value pairs to the authorization server address, use & to join each parameter. Note that parameter values must be URL-encoded.

   Example concatenated result:

   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

4. Verify the concatenated result Ensure the concatenated address meets the following requirements:
   • Parameters can be in any order
   • Parameter values are correctly URL-encoded
   • All required parameters are included

Example Code

Below are example codes for concatenating the authorization address in several common programming languages:

Python Example

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 Example

// 定义参数
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 Example

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

Notes

When constructing and using the authorization URL, please note the following points:

1. Correctness of URL Encoding All parameter values must be URL-encoded (percent-encoding), to ensure that special characters (such as ":、/、? etc.) do not break the URL structure. For example,https://your-app.com/callback should be encoded as https%3A%2F%2Fyour-app.com%2Fcallback。
2. Consistency of the Callback Addressredirect_uri The parameter value must exactly match the callback address registered by the client on the authorization server, including the protocol (http or https ), hostname, port, and path. Otherwise, the authorization server will reject the request.
3. state Security of the Parameterstate The parameter is used to prevent Cross-Site Request Forgery (CSRF) attacks. The client should generate a random and unpredictable string, and after the user completes authorization, verify that the state value in the callback matches the originally sent value.
4. Reasonableness of the Scopescope The parameter defines the permission scope requested by the client. A minimal scope should be selected based on actual needs to avoid over-requesting user resources, thereby enhancing user trust.
5. Environment Separation During the development and testing phases, a sandbox environment is typically used (e.g., account-sml.esignglobal.com), after going live, you need to switch to the production environment (e.g., account.esignglobal.com), ensuring that the correct authorization server address is used in different environments.
6. Processing Information After Successful Authorization After authorization is completed, the eSign.AI authorization service will use redirect_uriconcatenate and returncodeandbaseUrl, throughbaseUrlthe data center where the authorizer's data resides can be identified. When executing OpenAPI requests, requests must be initiated based on the corresponding data center.
7. Error Handling If the user denies authorization or another error occurs, the authorization server will return via redirect_uri error information (such as error and error_description parameters), the client should properly handle these errors and provide clear feedback to the user.