Open Cloud unterstützt den OAuth 2.0-Authorisierungsfluss mit und ohne PKCE, abhängig davon, ob Ihre Clients vertraulich oder öffentlich sind.
- Vertrauliche Clients sind Apps, die in der Lage sind, Anmeldeinformationen geheim zu halten, wie beispielsweise eine Website, die sicher Geheimnisse in ihrem Backend speichern und abrufen kann.
- Öffentliche Clients sind Apps, die keine Geheimnisse aufbewahren können, wie mobile und Webbrowser-Apps.
Wir empfehlen den OAuth 2.0-Authorisierungscodefluss mit PKCE für alle Clients und verlangen ihn für öffentliche Clients.
Bewahren Sie das Client-Geheimnis an einem sicheren Ort auf und geben Sie es niemals öffentlich bekannt. Böse Akteure können es nutzen, um sich als Ihre Anwendung auszugeben.
Um den Authorisierungscodefluss zu implementieren, führt Ihre App die folgenden Schritte aus:
- Generieren Sie einen Code-Verifier und eine Code-Herausforderung (nur PKCE). Dies ermöglicht Ihnen, eine Herausforderung in Ihren Anfragen anstelle des Client-Geheimnisses aufzunehmen, was die Sicherheit verbessert.
- Senden Sie eine GET-Anfrage an den Authorisierungs-Endpunkt mit den entsprechenden Parametern.
- Behandeln Sie den Authorisierungs-Callback. Nach Erhalt der Autorisierung verwenden Sie den Authorisierungscode von Roblox in einer Weiterleitungsanfrage an die URL, die Sie bei der Erstellung der App angegeben haben. Analysieren Sie den Authorisierungscode für die spätere Verwendung.
- Senden Sie eine POST-Anfrage an den Token-Endpunkt mit dem Authorisierungscode. Wenn erfolgreich, erhalten Sie Zugriffs- und Aktualisierungstoken, mit denen Sie API-Aufrufe tätigen können.
- Rufen Sie eine beliebige Open Cloud API auf, die die OAuth 2.0-Authentifizierung unterstützt, basierend auf der Referenzdokumentation für die Ressourcen, auf die Sie zugreifen möchten.
Die folgenden Abschnitte beschreiben jeden Schritt im Detail.
Generieren Sie eine Code-Herausforderung (nur für PKCE)
Bevor Sie den Autorisierungsprozess initiieren, müssen Sie eine Code-Herausforderung aus einem Code-Verifier generieren. Sie können Bibliotheken oder integrierte Funktionen in der von Ihnen gewählten Programmiersprache verwenden, um den Code-Verifier zu erstellen, den Hash zu berechnen und die Base64-Codierung durchzuführen, um die Code-Herausforderung zu erzeugen.
Bei der Erstellung des Code-Verifiers verwenden Sie nur unreservierte Zeichen, einschließlich Groß- und Kleinbuchstaben (A-Z, a-z), Dezimalziffern (0-9), Bindestrich (-), Punkt (.), Unterstrich (_), und Tilde (~), mit einer Mindestlänge von 43 Zeichen und einer maximalen Länge von 128 Zeichen.
Das folgende Beispiel zeigt, wie Sie mit Javascript einen Code-Verifier erstellen und die Code-Herausforderung unter Verwendung des SHA-256-Hash-Algorithmus generieren:
Code-Herausforderung erstellen
const crypto = require('crypto');
// base64URL codieren den Verifier und die Herausforderung
function base64URLEncode(str) {
return str.toString('base64')
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=/g, '');
}
// erstelle sha256 Hash aus dem Code-Verifier
function sha256(buffer) {
return crypto.createHash('sha256').update(buffer).digest(`base64`);
}
// erstelle einen zufälligen Code-Verifier
var code_verifier = base64URLEncode(crypto.randomBytes(32));
// generiere eine Herausforderung aus dem Code-Verifier
var code_challenge = base64URLEncode(sha256(code_verifier));
Für PKCE benötigen Sie sowohl die Werte des Code-Verifiers als auch der Herausforderung in späteren Schritten.
Konstruiere die Authorisierungs-URL
Siehe die Referenzdokumentation zum Authorisierungs-Endpunkt für vollständige Informationen darüber, wie Sie die Authorisierungs-URL konstruieren.
Um den Benutzer-Autorisierungsprozess zu initiieren, konstruiere eine Authorisierungs-URL mit den erforderlichen Parametern:
- client_id: Die Client-ID Ihrer App, die Sie nach der Registrierung Ihrer App erhalten haben.
- redirect_uri: Die Redirect-URI Ihrer App, der Wiedereintrittspunkt Ihrer App.
- scope: Die angeforderten Scopes, die die Zugriffsberechtigungen definieren, die Ihre App in einer durch Leerzeichen getrennten Liste benötigt.
- response_type: Setze es auf code, um den Authorisierungscodefluss anzuzeigen.
Erforderlich nur für PKCE
- code_challenge: Die Code-Herausforderung, die aus einem Code-Verifier generiert wurde.
- code_challenge_method: Setzen Sie diesen Parameterwert auf S256, um anzugeben, dass die Code-Herausforderung mit dem SHA-256-Algorithmus verarbeitet wurde, der am weitesten unterstützt und sichersten Code-Herausforderungsmethode.
- state: Ein opaker, sicherer Zufallswert zur Aufrechterhaltung des Status zwischen der Anfrage und dem Callback.
Erforderlich nur für nicht-PKCE
- client_secret: Ihr Client-Geheimnis, das Sie nach der Registrierung Ihrer App erhalten haben. Wenn Sie die Authentifizierung mit PKCE verwenden, lassen Sie diesen Parameter weg. Ihre Authorisierungsanforderungs-URL muss gut formatiert sein, wie im folgenden Beispiel:
Beispiel PKCE Authorisierungs-URL
Wenn Benutzer die URL besuchen, durchlaufen sie den Authorisierungsfluss. Wenn erfolgreich, leitet Roblox den Benutzer an die angegebene redirect_uri weiter.
Behandeln von Authorisierungs-Callbacks
Wenn ein Authorisierungsfluss erfolgreich ist, erhält Ihre App eine GET-Anfrage vom Roblox-Authorisierungsserver an der redirect_uri, die Sie angegeben haben. In der Anfrage erhalten Sie die Parameter code (Authorisierungscode) und state (wenn Sie zuvor einen Wert angegeben haben).
Der Parameter code enthält einen Authorisierungscode, den die App gegen ein Zugriffstoken vom Authorisierungsserver eintauschen kann. Die meisten Backend-Server-Sprachen haben standardisierte Möglichkeiten, um auf Abfrageparameter als dekodierte Objekte zuzugreifen. Sie müssen den code-Parameter abrufen und verwenden, um Zugriffstoken zu erhalten.
Der Parameter state ist ein opaker Wert, den Sie zu Beginn in der Authorisierungsanforderung angegeben haben. Sie können diesen Parameter verwenden, um den Status oder den Kontext des Authorisierungsprozesses zu erhalten.
Zum Beispiel könnten Sie eine GET-Anfrage mit der folgenden URL erhalten, wenn Sie Ihre Redirect-URI als https://example.com/redirect angegeben haben.
Beispiel Redirect-URL
Wenn die Authorisierung fehlschlägt, erhält Ihre App eine GET-Anfrage an die angegebene Weiterleitungs-URL mit den Parametern error, error_description, und state (falls zutreffend).
- Der Parameter error gibt den spezifischen OAuth 2.0-Fehler an, der während des Authorisierungsprozesses aufgetreten ist.
- Der Parameter error_description gibt zusätzliche Details zu dem Fehler an.
- Der Parameter state hilft Ihrer App, den Status im Falle eines Fehlers aufrechtzuerhalten.
Tauschen Sie einen Authorisierungscode gegen Zugriffstoken ein
Wenn Sie den Authorisierungs-code analysiert haben, tauschen Sie ihn gegen Token für den Zugriff auf die gewünschten Roblox-Ressourcen ein:
Fordern Sie ein Zugriffstoken und ein Aktualisierungstoken an, indem Sie eine POST-Anfrage an den Token-Austausch-Endpunkt senden. Die Anfrage muss den Authorisierungscode, die Client-ID und den Wert des Code-Verifiers (PKCE) oder das Client-Geheimnis (nicht-PKCE) im Format x-www-form-urlencoded enthalten.
Analysieren Sie die entsprechenden Token aus der empfangenen Antwort. Das Zugriffstoken ist 15 Minuten lang gültig. Bewahren Sie das Aktualisierungstoken sicher auf, typischerweise auf der Serverseite, damit Sie es in Zukunft verwenden können, um neue Token zu erhalten.
Beispiel Token-Endpunkt-Antwort{"access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IlBOeHhpb2JFNE8zbGhQUUlUZG9QQ3FCTE81amh3aXZFS1pHOWhfTGJNOWMiLCJ0eXAiOiJKV11234.eyJzdWIiOiIyMDY3MjQzOTU5IiwiYWlkIjoiM2Q2MWU3NDctM2ExNS00NTE4LWJiNDEtMWU3M2VhNDUyZWIwIiwic2NvcGUiOiJvcGVuaWQ6cmVhZCBwcm9maWxlOnJlYWQiLCJqdGkiOiJBVC5QbmFWVHpJU3k2YkI5TG5QYnZpTCIsIm5iZiI6MTY5MTYzOTY5OCwiZXhwIjoxNjkxNjQwNTk4LCJpYXQiOjE2OTE2Mzk2OTgsImlzcyI6Imh0dHBzOi8vYXBpcy5yb2Jsb3guY29tL29hdXRoLyIsImF1ZCI6IjcyOTA2MTAzOTc5ODc5MzQ5Nj1234.BjwMkC8Q5a_iP1Q5Th8FrS7ntioAollv_zW9mprF1ats9CD2axCvupZydVzYphzQ8TawunnYXp0Xe8k0t8ithg","refresh_token": "eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwia2lkIjoidGpHd1BHaURDWkprZEZkREg1dFZ5emVzRWQyQ0o1NDgtUi1Ya1J1TTBBRSIsInR5cCI6IkpXVCJ9..nKYZvjvXH6msDG8Udluuuw.PwP-_HJIjrgYdY-gMR0Q3cabNwIbmItcMEQHx5r7qStVVa5l4CbrKwJvjY-w9xZ9VFb6P70WmXndNifnio5BPZmivW5QkJgv5_sxLoCwsqB1bmEkz2nFF4ANLzQLCQMvQwgXHPMfCK-lclpVEwnHk4kemrCFOvfuH4qJ1V0Q0j0WjsSU026M67zMaFrrhSKwQh-SzhmXejhKJOjhNfY9hAmeS-LsLLdszAq_JyN7fIvZl1fWDnER_CeDAbQDj5K5ECNOHAQ3RemQ2dADVlc07VEt2KpSqUlHlq3rcaIcNRHCue4GfbCc1lZwQsALbM1aSIzF68klXs1Cj_ZmXxOSOyHxwmbQCHwY7aa16f3VEJzCYa6m0m5U_oHy84iQzsC-_JvBaeFCachrLWmFY818S-nH5fCIORdYgc4s7Fj5HdULnnVwiKeQLKSaYsfneHtqwOc_ux2QYv6Cv6Xn04tkB2TEsuZ7dFwPI-Hw2O30vCzLTcZ-Fl08ER0J0hhq4ep7B641IOnPpMZ1m0gpJJRPbHX_ooqHol9zHZ0gcLKMdYy1wUgsmn_nK_THK3m0RmENXNtepyLw_tSd5vqqIWZ5NFglKSqVnbomEkxneEJRgoFhBGMZiR-3FXMaVryUjq-N.Q_t4NGxTUSMsLVEppkTu0Q6rwt2rKJfFGuvy3s12345","token_type": "Bearer","expires_in": 899,"id_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6IkNWWDU1Mi1zeWh4Y1VGdW5vNktScmtReFB1eW15YTRQVllodWdsd3hnNzgiLCJ0eXAiOiJKV11234.eyJzdWIiOiIyMDY3MjQzOTU5IiwibmFtZSI6ImxpbmtzZ29hdCIsIm5pZ2tuYW1lIjoibGlua3Nnb2F0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoibGlua3Nnb2F0IiwiY3JlYXRlZF9hdCI6MTYwNzM1NDIzMiwicHJvZmlsZSI6Imh0dHBzOi8vd3d3LnJvYmxveC5jb20vdXNlcnMvMjA2NzI0Mzk1OS9wcm9maWxlIiwib25jZWUiOiIxMjM0NSIsImp0aSI6IklELnltd3ZjTUdpOVg4azkyNm9qd1I5IiwibmJmIjoxNjkxNjM5Njk4LCJleHAiOjE2OTE2NzU2OTgsImlhdCI6MTY5MTYzOTY5OCwiaXNzIjoiaHR0cHM6Ly9hcGlzLnJvYmxveC5jb20vb2F1dGgvIiwiYXVkIjoiNzI5MDYxMDM5Nzk4NzkzNDk2NCJ9.kZgCMJQGsariwCi8HqsUadUBMM8ZOmf_IPDoWyQY9gVX4Kx3PubDz-Q6MvZ9eU5spNFz0-PEH-G2WSvq2ljDyg","scope": "openid profile"}
Rufen Sie eine Ressourcenmethode auf
Jetzt, da Sie das erforderliche Zugriffstoken haben, können Sie es verwenden, um authentifizierte Aufrufe an Ressourcenmothoden zu tätigen. Fügen Sie das Zugriffstoken in den Header aller API-Anfragen ein, um diese zu autorisieren.
Zum Beispiel können Sie testen, ob Ihre App korrekt funktioniert, indem Sie den gesamten Authorisierungsfluss durchlaufen und dann eine GET-Anfrage an den Benutzerinformations-Endpunkt mit einem Zugriffstoken senden. Stellen Sie sicher, dass Sie entweder die openid oder sowohl die openid als auch die profile Scopes haben, bevor Sie diesen Endpunkt aufrufen. Wenn erfolgreich, sieht die Antwort von diesem Endpunkt so aus:
Beispiel Benutzerinformationsantwort
{
"sub": "12345678",
"name": "Jane Doe",
"nickname": "robloxjanedoe",
"preferred_username": "robloxjanedoe",
"created_at": 1607354232,
"profile": "https://www.roblox.com/users/12345678/profile"
}