Guia de Integração do Fluxo de Código de Autorização OAuth2.0

Sequência de Chamadas

Visão Geral

O OAuth 2.0 é um protocolo de autorização amplamente utilizado que permite que aplicativos de terceiros acessem recursos por meio da autorização do usuário, sem expor suas credenciais. No fluxo de código de autorização do OAuth 2.0, o cliente deve direcionar o usuário ao ponto de extremidade de autorização (Authorization Endpoint) do servidor de autorização para obter a permissão de autorização do usuário.

Este documento visa detalhar como montar e utilizar o endereço de autorização conforme o protocolo OAuth 2.0, fornecendo exemplos práticos e observações importantes.

1. Montagem da URL para Obter o Código de Autorização

Estrutura Básica do Endereço de Autorização

O endereço de autorização é a URL utilizada pelo cliente para enviar uma solicitação ao servidor de autorização. Ele é composto pelos seguintes componentes:

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

Descrição dos Parâmetros

Etapas para montar o endereço de autorização

1. Definir o endereço do servidor de autorização Ambiente de sandbox: https://account-sml.esignglobal.com/oauth

   Ambiente de produção: https://account.esignglobal.com/oauth

2. Definir os valores dos parâmetros Com base nas necessidades reais, defina os valores de cada parâmetro. Abaixo está um exemplo:
   • response_type: code
   • clientId: your-client-id-12345
   • redirectUri: https://your-app.com/callback
   • scope: signature
   • state: random-state-value
3. Concatenar parâmetros de consulta Após anexar os parâmetros acima ao endereço do servidor de autorização na forma de pares chave-valor, utilize & para conectar cada parâmetro. Observe que os valores dos parâmetros devem ser codificados em URL.

   Exemplo de resultado da concatenação:

   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. Verificar o resultado da concatenação Certifique-se de que o endereço concatenado atenda aos seguintes requisitos:
   • A ordem dos parâmetros pode ser arbitrária
   • Os valores dos parâmetros foram corretamente codificados em URL
   • Todos os parâmetros obrigatórios estão incluídos

Código de exemplo

Abaixo estão exemplos de código para concatenar o endereço de autorização em várias linguagens de programação comuns:

Exemplo em 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)

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

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

Observações

Ao montar e utilizar o endereço de autorização, observe os seguintes pontos:

1. Correção da codificação URL Todos os valores dos parâmetros devem ser codificados em URL (percent-encoding), para garantir que caracteres especiais (como :、/、? ) não comprometam a estrutura da URL. Por exemplo, https://your-app.com/callback deve ser codificado como https%3A%2F%2Fyour-app.com%2Fcallback。
2. Consistência do endereço de callbackredirect_uri O valor do parâmetro deve corresponder exatamente ao endereço de callback registrado no servidor de autorização pelo cliente, incluindo o protocolo (http ou https), nome de host, porta e caminho. Caso contrário, o servidor de autorização rejeitará a solicitação.
3. state Segurança do parâmetrostate O parâmetro é utilizado para prevenir ataques de falsificação de solicitação entre sites (CSRF). O cliente deve gerar uma string aleatória e imprevisível e, após o usuário concluir a autorização, verificar se o valor do callback em state corresponde ao valor enviado inicialmente.
4. Adequação do escopo de permissãoscope O parâmetro define o escopo de permissão solicitado pelo cliente. Deve-se selecionar um escopo mínimo conforme a necessidade real, evitando solicitações excessivas de recursos do usuário, o que aumenta a confiança do mesmo.
5. Diferenciação de ambientes Nas fases de desenvolvimento e teste, geralmente utiliza-se um ambiente sandbox (como account-sml.esignglobal.com ), após o lançamento oficial, é necessário alternar para o ambiente de produção (como account.esignglobal.com ), garantindo o uso do endereço correto do servidor de autorização em diferentes ambientes.
6. Processamento de informações após autorização bem-sucedida Após a conclusão da autorização, o serviço de autorização eSignGlobal retornará concatenando por meio deredirect_urios parâmetros concatenadoscodeebaseUrl, através debaseUrlé possível identificar o data center onde os dados do autorizador estão localizados; ao executar solicitações openapi, é necessário direcionar a requisição ao data center correspondente.
7. Tratamento de erros Se o usuário recusar a autorização ou ocorrer outro erro, o servidor de autorização retornará através de redirect_uri as informações de erro (como error e error_description nos parâmetros), o cliente deve tratar adequadamente esses erros e fornecer feedback claro ao usuário.