OAuth 2.0 Autorisierungscode-Flow Integrationsleitfaden

Aufrufreihenfolge

Übersicht

OAuth 2.0 ist ein weit verbreitetes Autorisierungsprotokoll, das Drittanbieteranwendungen ermöglicht, über die Einwilligung des Nutzers auf dessen Ressourcen zuzugreifen, ohne dabei die Zugangsdaten preiszugeben. Im Authorization-Code-Flow von OAuth 2.0 muss der Client den Nutzer zum Autorisierungsendpunkt (Authorization Endpoint) des Autorisierungsservers weiterleiten, um die erforderliche Nutzereinwilligung zu erhalten.

Dieses Dokument erläutert detailliert, wie die Autorisierungs-URL gemäß dem OAuth 2.0-Protokoll zusammengesetzt und verwendet wird, und bietet praktische Beispiele sowie Hinweise.

1. URL-Zusammenstellung zur Erlangung des Autorisierungscodes

Grundstruktur der Autorisierungs-URL

Die Autorisierungs-URL ist die URL, die der Client verwendet, um eine Anfrage an den Autorisierungsserver zu senden. Sie setzt sich aus folgenden Komponenten zusammen:

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

Parameterbeschreibung

Schritte zum Erstellen der Autorisierungs-URL

1. Autorisierungsserver-Adresse bestimmen Sandbox-Umgebung: https://account-sml.esignglobal.com/oauth

   Produktionsumgebung: https://account.esignglobal.com/oauth

2. Parameterwerte festlegen Legen Sie die Werte der einzelnen Parameter entsprechend den tatsächlichen Anforderungen fest. Nachfolgend ein Beispiel:
   • response_type: code
   • clientId: your-client-id-12345
   • redirectUri: https://your-app.com/callback
   • scope: signature
   • state: random-state-value
3. Query-Parameter anhängen Nachdem die oben genannten Parameter als Schlüssel-Wert-Paare an die Autorisierungsserver-Adresse angehängt wurden, verwenden Sie & , um jeden Parameter anzuhängen. Beachten Sie, dass die Parameterwerte URL-codiert werden müssen.

   Beispiel für das Verkettungsergebnis:

   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. Verkettungsergebnis überprüfen Stellen Sie sicher, dass die zusammengesetzte Adresse den folgenden Anforderungen entspricht:
   • Die Reihenfolge der Parameter ist beliebig
   • Die Parameterwerte sind korrekt URL-codiert
   • Alle erforderlichen Parameter sind enthalten

Beispielcode

Im Folgenden finden Sie Beispielcode zum Anhängen der Autorisierungs-URL in verschiedenen gängigen Programmiersprachen:

Python-Beispiel

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-Beispiel

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

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

Hinweise

Beim Zusammenstellen und Verwenden der Autorisierungs-URL sind folgende Punkte zu beachten:

1. Korrektheit der URL-Kodierung Alle Parameterwerte müssen URL-kodiert werden (percent-encoding), um sicherzustellen, dass Sonderzeichen (wie :、/、? usw.) die Struktur der URL nicht beeinträchtigen. Zum Beispiel https://your-app.com/callback sollte kodiert werden als https%3A%2F%2Fyour-app.com%2Fcallback。
2. Konsistenz der Callback-URIredirect_uri Der Wert des Parameters muss vollständig mit der beim Autorisierungsserver registrierten Callback-Adresse übereinstimmen, einschließlich Protokoll (http oder https), Hostname, Port und Pfad. Andernfalls lehnt der Autorisierungsserver die Anfrage ab.
3. state Sicherheit des Parametersstate Der Parameter dient zur Verhinderung von Cross-Site-Request-Forgery-(CSRF)-Angriffen. Der Client sollte eine zufällige und nicht vorhersagbare Zeichenfolge generieren und nach Abschluss der Autorisierung durch den Benutzer den im Callback enthaltenen state Wert mit dem ursprünglich gesendeten Wert übereinstimmt.
4. Angemessenheit des Berechtigungsumfangsscope Der Parameter definiert den vom Client angeforderten Berechtigungsumfang. Es sollte ein minimaler Umfang entsprechend den tatsächlichen Anforderungen gewählt werden, um eine übermäßige Anforderung von Benutzerressourcen zu vermeiden und so das Nutzervertrauen zu stärken.
5. Umgebungsunterscheidung In Entwicklungs- und Testphasen wird üblicherweise eine Sandbox-Umgebung verwendet (z. B. account-sml.esignglobal.com ), nach dem produktiven Einsatz muss auf die Produktionsumgebung (z. B. account.esignglobal.com ), um sicherzustellen, dass in den verschiedenen Umgebungen die korrekte Adresse des Autorisierungsservers verwendet wird.
6. Verarbeitung der Informationen nach erfolgreicher Autorisierung Nach Abschluss der Autorisierung übermittelt der eSignGlobal-Autorisierungsdienst überredirect_uriverkettet zurückgegebencode und baseUrl , über baseUrl kann das Rechenzentrum identifiziert werden, in dem sich die Daten des Berechtigten befinden. Bei der Ausführung von OpenAPI-Anfragen müssen diese entsprechend dem jeweiligen Rechenzentrum initiiert werden.
7. Fehlerbehandlung Wenn der Benutzer die Autorisierung verweigert oder ein anderer Fehler auftritt, übermittelt der Autorisierungsserver über redirect_uri Fehlermeldungen zurück (z. B. error und error_description Parameter), der Client sollte diese Fehler ordnungsgemäß behandeln und dem Benutzer eine klare Rückmeldung geben.