Guide d'intégration du flux de code d'autorisation OAuth 2.0

Séquence d'appels

Vue d'ensemble

OAuth 2.0 est un protocole d'autorisation largement utilisé qui permet aux applications tierces d'accéder aux ressources de l'utilisateur avec son consentement, sans exposer ses identifiants. Dans le flux de code d'autorisation d'OAuth 2.0, le client doit rediriger l'utilisateur vers le point de terminaison d'autorisation (Authorization Endpoint) du serveur d'autorisation afin d'obtenir son accord.

Ce document a pour objectif de détailler comment construire et utiliser l'URL d'autorisation conformément au protocole OAuth 2.0, en fournissant des exemples concrets et des points de vigilance.

I. Construction de l'URL pour obtenir le code d'autorisation

Structure de base de l'URL d'autorisation

L'URL d'autorisation est l'URL utilisée par le client pour initier une requête auprès du serveur d'autorisation. Elle se compose des éléments suivants :

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

Description des paramètres

Nom du paramètre	Requis ?	Description
`response_type`	Requis	Type d'autorisation, généralement `code`(indiquant l'utilisation du flux de code d'autorisation)
`clientId`	Requis	Identifiant unique du client,c'est-à-dire APP ID
`redirectUri`	Obligatoire	Adresse de redirection après l'autorisation, doit correspondre à l'URL de rappel enregistrée lors de l'inscription du client
`scope`	Obligatoire	Portée des autorisations demandées, actuellement prise en charge pour`signature`、`stamp`、`comparisons`, une fois autorisé, vous pouvez appeler les openapi existants d'eSignGlobal. Plusieurs scopes peuvent être séparés par des espaces
`state`	Facultatif	Chaîne aléatoire utilisée pour prévenir les attaques CSRF, générée par le client et vérifiée pour sa cohérence lors du rappel

Étapes de construction de l'URL d'autorisation

Déterminer l'adresse du serveur d'autorisation Environnement sandbox : https://account-sml.esignglobal.com/oauth
Environnement de production : https://account.esignglobal.com/oauth
Définir les valeurs des paramètres Définissez la valeur de chaque paramètre en fonction des besoins réels. Voici un exemple :
- response_type: code
- clientId: your-client-id-12345
- redirectUri: https://your-app.com/callback
- scope: signature
- state: random-state-value
Concaténer les paramètres de requête Une fois les paramètres ci-dessus concaténés à l'URL du serveur d'autorisation sous forme de paires clé-valeur, utilisez & pour joindre chaque paramètre. Notez que les valeurs des paramètres doivent être encodées en URL.
Exemple de résultat de concaténation :
```
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
```
Vérifier le résultat de la concaténation Assurez-vous que l'URL concaténée respecte les exigences suivantes :
- L'ordre des paramètres n'a pas d'importance
- Les valeurs des paramètres sont correctement encodées en URL
- Tous les paramètres obligatoires sont inclus

Code d'exemple

Voici des exemples de code pour concaténer l'URL d'autorisation dans plusieurs langages de programmation courants :

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

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

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

Remarques

Lors de la construction et de l'utilisation de l'URL d'autorisation, veuillez noter les points suivants :

Exactitude de l'encodage URL Toutes les valeurs de paramètres doivent être encodées en URL (percent-encoding), afin que les caractères spéciaux (comme :、/、? etc.) ne perturbent pas la structure de l'URL. Par exemple, https://your-app.com/callback doit être encodé en https%3A%2F%2Fyour-app.com%2Fcallback。
Cohérence de l'URI de redirectionredirect_uri La valeur du paramètre doit correspondre exactement à l'URI de redirection enregistré auprès du serveur d'autorisation, y compris le protocole (http ou https), le nom d'hôte, le port et le chemin. Sinon, le serveur d'autorisation rejettera la demande.
state Sécurité du paramètre state Le paramètre est utilisé pour prévenir les attaques par requête inter-sites (CSRF). Le client doit générer une chaîne aléatoire et imprévisible, et vérifier après l'autorisation que la valeur dans la redirection state correspond bien à la valeur initialement envoyée.
Pertinence de la portée des autorisationsscope Le paramètre définit la portée des autorisations demandées par le client. Il convient de choisir une portée minimale adaptée aux besoins réels, afin d'éviter de solliciter excessivement les ressources de l'utilisateur et ainsi renforcer sa confiance.
Distinction des environnements Lors des phases de développement et de test, on utilise généralement un environnement sandbox (tel que account-sml.esignglobal.com ), après la mise en production, il faut basculer vers l'environnement de production (tel que account.esignglobal.com ), afin de s'assurer d'utiliser la bonne adresse du serveur d'autorisation dans chaque environnement.
Traitement des informations après une autorisation réussie Une fois l'autorisation terminée, le service d'autorisation eSignGlobal retournera via redirect_uriconcaténer et renvoyercodeetbaseUrl, grâce à baseUrlil est possible d'identifier le centre de données où se trouvent les données de l'autorisant ; lors de l'exécution de requêtes openapi, il convient d'initier la requête en fonction du centre de données correspondant.
Gestion des erreurs Si l'utilisateur refuse l'autorisation ou si une autre erreur survient, le serveur d'autorisation retournera via redirect_uri les informations d'erreur (telles que error et error_description paramètres), le client doit gérer correctement ces erreurs et fournir un retour clair à l'utilisateur.