Guida all'integrazione OAuth 2.0 - Flusso del codice di autorizzazione

Sequenza di chiamata

Panoramica

OAuth 2.0 è un protocollo di autorizzazione ampiamente utilizzato che consente alle applicazioni di terze parti di accedere alle risorse dell'utente tramite la sua autorizzazione, senza esporre le relative credenziali. Nella modalità del codice di autorizzazione di OAuth 2.0, il client deve reindirizzare l'utente all'endpoint di autorizzazione del server di autorizzazione (Authorization Endpoint) per ottenere il consenso dell'utente.

Questo documento ha lo scopo di illustrare nel dettaglio come comporre e utilizzare l'URL di autorizzazione secondo il protocollo OAuth 2.0, fornendo esempi pratici e note importanti.

1. Composizione dell'URL per ottenere il codice di autorizzazione

Struttura di base dell'URL di autorizzazione

L'URL di autorizzazione è l'indirizzo utilizzato dal client per inviare una richiesta al server di autorizzazione. È composto dalle seguenti sezioni:

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

Descrizione dei parametri

Fasi per la costruzione dell'URL di autorizzazione

1. Determinare l'indirizzo del server di autorizzazione Ambiente sandbox: https://account-sml.esignglobal.com/oauth

   Ambiente di produzione: https://account.esignglobal.com/oauth

2. Impostare i valori dei parametri Impostare i valori dei singoli parametri in base alle effettive necessità. Di seguito un esempio:
   • response_type: code
   • clientId: your-client-id-12345
   • redirectUri: https://your-app.com/callback
   • scope: signature
   • state: random-state-value
3. Composizione dei parametri di query Dopo aver concatenato i suddetti parametri in formato chiave-valore all'indirizzo del server di autorizzazione, utilizzare & per unire ciascun parametro. Si noti che i valori dei parametri devono essere codificati in URL.

   Esempio di risultato:

   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. Verifica del risultato Assicurarsi che l'indirizzo composto soddisfi i seguenti requisiti:
   • L'ordine dei parametri può essere arbitrario
   • I valori dei parametri sono stati correttamente codificati in URL
   • Tutti i parametri obbligatori sono inclusi

Codice di esempio

Di seguito sono riportati esempi di codice per la composizione dell'indirizzo di autorizzazione in diversi linguaggi di programmazione comuni:

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

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

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

Note importanti

Quando si compone e si utilizza l'URL di autorizzazione, è necessario prestare attenzione ai seguenti punti:

1. Correttezza della codifica URL Tutti i valori dei parametri devono essere codificati URL （percent-encoding）， per garantire che i caratteri speciali (come :、/、? ecc.) non compromettano la struttura dell'URL. Ad esempio, https://your-app.com/callback dovrebbe essere codificato come https%3A%2F%2Fyour-app.com%2Fcallback。
2. Coerenza dell'indirizzo di callbackredirect_uri Il valore del parametro deve corrispondere esattamente all'indirizzo di callback registrato dal client sul server di autorizzazione, inclusi il protocollo (http o https), nome host, porta e percorso. In caso contrario, il server di autorizzazione rifiuterà la richiesta.
3. state Sicurezza del parametrostate Il parametro serve a prevenire attacchi di falsificazione di richieste tra siti (CSRF). Il client dovrebbe generare una stringa casuale e imprevedibile e verificare, dopo il completamento dell'autorizzazione da parte dell'utente, se nel callback state corrisponde al valore inviato inizialmente.
4. Adeguatezza dell'ambito delle autorizzazioniscope Il parametro definisce l'ambito delle autorizzazioni richiesto dal client. Dovrebbe essere selezionato un ambito minimo in base alle effettive necessità, evitando di richiedere eccessivamente le risorse utente, al fine di aumentare la fiducia degli utenti.
5. Distinzione degli ambienti Durante le fasi di sviluppo e test, viene solitamente utilizzato un ambiente sandbox (come account-sml.esignglobal.com), dopo il rilascio ufficiale, è necessario passare all'ambiente di produzione (come account.esignglobal.com), assicurandosi di utilizzare l'indirizzo corretto del server di autorizzazione in ciascun ambiente.
6. Gestione delle informazioni dopo l'autorizzazione positiva Una volta completata l'autorizzazione, il servizio di autorizzazione eSignGlobal restituirà tramiteredirect_uriconcatenare e restituirecodeebaseUrl, tramitebaseUrlè possibile identificare il data center in cui risiedono i dati dell'autorizzante; durante l'esecuzione delle richieste openapi, è necessario inviare la richiesta in base al data center corrispondente.
7. Gestione degli errori Se l'utente rifiuta l'autorizzazione o si verifica un altro errore, il server di autorizzazione restituirà tramite redirect_uri le informazioni di errore (come error e error_description parametri), il client dovrebbe gestire correttamente questi errori e fornire un feedback chiaro all'utente.