Guía de integración del flujo de código de autorización de OAuth 2.0

Secuencia de llamadas

Descripción general

OAuth 2.0 es un protocolo de autorización ampliamente utilizado que permite a las aplicaciones de terceros acceder a los recursos del usuario mediante su consentimiento, sin necesidad de exponer sus credenciales. En el flujo de código de autorización de OAuth 2.0, el cliente debe dirigir al usuario al punto de conexión de autorización (Authorization Endpoint) del servidor de autorización para obtener el permiso correspondiente.

Este documento tiene como objetivo detallar cómo construir y utilizar la URL de autorización según el protocolo OAuth 2.0, proporcionando ejemplos prácticos y consideraciones importantes.

I. Construcción de la URL para obtener el código de autorización

Estructura básica de la URL de autorización

La URL de autorización es la dirección que utiliza el cliente para realizar una solicitud al servidor de autorización. Está compuesta por los siguientes componentes:

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

Descripción de los parámetros

Pasos para construir la URL de autorización

1. Determinar la dirección del servidor de autorización Entorno sandbox: https://account-sml.esignglobal.com/oauth

   Entorno de producción: https://account.esignglobal.com/oauth

2. Configurar los valores de los parámetros Configure los valores de cada parámetro según sus necesidades reales. A continuación se muestra un ejemplo:
   • response_type: code
   • clientId: your-client-id-12345
   • redirectUri: https://your-app.com/callback
   • scope: signature
   • state: random-state-value
3. Construir parámetros de consulta Una vez concatenados los parámetros anteriores en formato clave-valor a la dirección del servidor de autorización, utilice & para unir cada parámetro. Tenga en cuenta que los valores de los parámetros deben codificarse en URL.

   Resultado de ejemplo:

   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 el resultado de la concatenación Asegúrese de que la dirección concatenada cumpla con los siguientes requisitos:
   • El orden de los parámetros puede ser cualquiera
   • Los valores de los parámetros están correctamente codificados en URL
   • Se han incluido todos los parámetros obligatorios

Código de ejemplo

A continuación se muestra código de ejemplo para construir la dirección de autorización en varios lenguajes de programación comunes:

Ejemplo en 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)

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

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

Consideraciones importantes

Al construir y utilizar la dirección de autorización, se deben tener en cuenta los siguientes puntos:

1. Correctitud de la codificación URL Todos los valores de los parámetros deben someterse a codificación URL (percent-encoding）， para asegurar que los caracteres especiales (como :、/、? 等） no modificarán la estructura de la URL. Por ejemplo,https://your-app.com/callback debe codificarse como https%3A%2F%2Fyour-app.com%2Fcallback。
2. Consistencia de la dirección de redireccionamientoredirect_uri El valor del parámetro debe coincidir exactamente con la dirección de devolución de llamada registrada por el cliente en el servidor de autorización, incluido el protocolo (http o https）、nombre de host, puerto y ruta. De lo contrario, el servidor de autorización rechazará la solicitud.
3. state Seguridad del parámetrostate El parámetro se utiliza para prevenir ataques de falsificación de solicitudes entre sitios (CSRF). El cliente debe generar una cadena aleatoria e impredecible y, tras completar la autorización por parte del usuario, verificar si el valor de state coincide con el valor enviado inicialmente.
4. Razonabilidad del alcance de los permisosscope El parámetro define el alcance de los permisos solicitados por el cliente. Debe elegirse un alcance de permisos mínimo según las necesidades reales, evitando solicitar recursos del usuario en exceso, mejorando así la confianza del usuario.
5. Diferenciación de entornos Durante las fases de desarrollo y pruebas, por lo general se utiliza un entorno de sandbox (como account-sml.esignglobal.com ), tras el lanzamiento oficial, es necesario cambiar al entorno de producción (como account.esignglobal.com ). Asegúrese de utilizar la dirección correcta del servidor de autorización en cada entorno.
6. Procesamiento de información tras una autorización exitosa Tras finalizar la autorización, el servicio de autorización de eSignGlobal utilizará redirect_uriconcatenar y devolvercodeybaseUrl , a través de baseUrl se podrá identificar el centro de datos donde se encuentran los datos del autorizador; al ejecutar solicitudes openapi, es necesario realizarlas según el centro de datos correspondiente.
7. Manejo de errores Si el usuario deniega la autorización o se produce otro error, el servidor de autorización devolverá a través de redirect_uri la información de error (como error y error_description parámetros), el cliente debe gestionar adecuadamente estos errores y proporcionar una respuesta clara al usuario.