Open Cloud unterstützt den OAuth 2.0-Autorisierungsfluss mit und ohne PKCE, abhängig davon, ob Ihre Clients vertraulich oder öffentlich sind.
- Vertrauliche Clients sind Apps, die in der Lage sind, Credits geheim zu halten, wie eine Website, die auf ihrem Backend sicher speichern und wiederholen kann, Geheimnisse.
- Öffentliche Clients sind Apps, die keine Geheimnisse halten können, wie mobile und Web-Browser-Apps.
Wir empfehlen den OAuth 2.0-Autorisierungscode-Fluss mit PKCE für alle Clients und fordern ihn für öffentliche Clients ein.
Lagere das Clientgeheimnis an einem sicheren Ort und bringe es nie der öffentlichzugänglich. Schlechte Akteure können es verwenden, um deine Anwendung zu impersonieren.
Um den Autorisierungscode-Fluss zu implementieren, führt deine App die folgenden Schritte aus:
- Erstellen einer Code-Prüferin und Code-Herausforderung (nur PKCE).Dies ermöglicht es Ihnen, eine Herausforderung in Ihre Anfragen einzubeziehen, anstatt den Client-Geheimnis, was die Sicherheit verbessert.
- Senden Sie eine GET Anfrage an den Autorisierungs-Endpunkt mit den entsprechenden Parametern.
- Behandle den Autorisierungs-Callback.Nach der Autorisierung verwende den Autorisierungscode von Roblox in einer Weiterleitungsanfrage an die URL, die du während der Schöpfungangegeben hast.Parst den Autorisierungscode für spätere Verwendung.
- Sende eine POST Anfrage an den Token-Endpunkt mit dem Codes.Wenn es erfolgreich ist, erhalten Sie Zugriff- und Aktualisungstoken, mit denen Sie API-Aufrufe ausführen können.
- Rufe jede Open Cloud API auf, die OAuth 2.0-Authentifizierung basierend auf der Referenzdokumentation für die Ressourcen unterstützt, auf die du Zugriffmöchtest.
Die folgenden Abschnitte beschreiben jeden Schritt ausführlicher.
Erstelle eine Codeherausforderung (nur für PKCE)
Bevor du den Autorisierungsprozess startest, musst du eine Code-Herausforderung von einem Code-Verifizierer generieren.Du kannst Bibliotheken oder integrierte Funktionen in der Programmiersprache deiner Wahl verwenden, um den Code-Prüfer zu erstellen, den Hash zu berechnen und Base64-Verschlüsselung durchzuführen, um die Code-Herausforderung zu generieren.
Wenn du den Code-Prüfer erstellst, verwende nur unreservierte Zeichen, einschließlich Groß- und Kleinsbuchstaben (A-Z, a-z), Dezimalzahlen (0-9), Unterstriche (-), Punkt (.), Unterstriche (_) und Tilde (~), mit einer Mindestlänge von 43 Zeichen und einer maximalen Länge von 128 Zeichen.
Das folgende Beispiel zeigt, wie man Javascript verwendet, um einen Code-Verifier zu erstellen und die Code-Herausforderung mit dem SHA-256-Hashing-Algorithmus zu generieren:
Generate Code Challenge
const crypto = require('crypto');
// base64URL encode the verifier and challenge
function base64URLEncode(str) {
return str.toString('base64')
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=/g, '');
}
// create sha256 hash from code verifier
function sha256(buffer) {
return crypto.createHash('sha256').update(buffer).digest(`base64`);
}
// create a random code verifier
var code_verifier = base64URLEncode(crypto.randomBytes(32));
// generate a challenge from the code verifier
var code_challenge = base64URLEncode(sha256(code_verifier));
Für PKCE benötigen Sie sowohl den Code-Verifier als auch die Herausforderungswerte in späteren Schritten.
Erstelle die Autorisierungs-URL
Siehe die Autorisierungs-Endpunkt-Referenzdokumentation für vollständige Informationen darüber, wie die Autorisierungs-URL konstruiert wird.
Um den Autorisierungsprozess des Benutzers zu starten, erstelle eine Autorisierungs-URL mit den erforderlichen Parametern:
- client_id : Die Client-ID deiner App, die nach Registrierung deiner App erhalten wurde.
- redirect_uri : Die Weiterleitungs- URI deiner App, der Wiederaufnahmepunkt deiner App.
- scope : Die angeforderten Bereiche, die die Zugriffsberechtigungen definieren, die deine App in einer zeilengeschlossenen Liste benötigt.
- response_type : Setze es auf code , um den Autorisierungscode-Fluss anzugeben. Erforderlich für PKCE nur
- code_challenge : Die Code-Herausforderung, die aus einem Code-Verifizierer generiert wurde.
- code_challenge_method : Setze diesen Parameternwert auf S256 , um anzuzeigen, dass die Code-Herausforderung mit dem SHA-256-Algorithmus transformiert wurde, der am weitesten verbreiteten und sichersten Code-Herausforderungsmethode.
- state : Ein undurchsichtiger, sicherer zufälliger Wert, um den Zustand zwischen der Anfrage und dem Callbackzu erhalten. Erforderlich für nicht-PKCE nur
- client_secret : Das Geheimnis des Clients deiner App, das nach Registrierung deiner App erhalten wurde.Wenn Sie Authentifizierung mit PKCE verwenden, lassen Sie diesen Parameter weg.Deine Autorisierungsanforderungs-URL muss gut formatiert sein, wie im folgenden Beispiel:
Beispiel-PKCE-Autorisierungs-URL
Wenn Benutzer die URL besuchen, werden sie durch den Autorisierungsfluss geführt. Wenn erfolgreich, leitet Roblox den Benutzer auf die angegebene redirect_uri um.
Autorisierungsrückrufe verwalten
Wenn ein Autorisierungsfluss erfolgreich ist, erhält deine App eine GET Anfrage vom Roblox-Autorisierungsserver auf der redirect_uri, die du angegeben hast.In der Anfrage erhalten Sie code (Codes) und state (wenn Sie zuvor einen Wert bereitgestellt haben) Parameter.
Der code -Parameter enthält einen Autorisierungscode, den die App gegen ein Zugriffstoken vom Autorisierungsserver eintauschen kann.Die meisten Backend-Server-Sprachen haben standardmäßige Wege, um Anfrage参数 als dekodierte Objekte zuzugreifen.Du musst den code-Parameter erhalten und ihn zum Austausch gegen Zugriffs-Token verwenden.
Der state-Parameter ist ein undurchsichtiger Wert, den du zuerst in der Anfrageangegeben hast.Sie können diesen Parameter verwenden, um den Zustand oder Kontext des Autorisierungsprozesses zu wahren.
Zum Beispiel könnten Sie eine GET Anfrage mit der folgenden URL erhalten, wenn Sie Ihre Weiterleitungs- URI auf https://example.com/redirect festgelegt haben.
Beispiel-Umleitungs-URL
Wenn die Autorisierung fehlschlägt, erhält deine App eine GET Anfrage an die angegebene Weiterleitungs-URL mit den error , error_description und state (falls geltend) Parametern.
- Der error-Parameter gibt den spezifischen OAuth 2.0-Fehler an, der während des Autorisierungsprozesses aufgetreten ist.
- Der error_description -Parameter liefert zusätzliche Details des Fehlers.
- Der state-Parameter hilft deiner App, den Zustand im Falle eines Fehlers zu erhalten.
Tausche einen Autorisierungscode gegen Zugriffstoken aus
Wenn du die Autorisierung code analysiert hast, tausche sie gegen Token aus, um auf gewünschte Roblox-Ressourcen zuzugreifen:
Fordern Sie ein Zugriffs-Token und Aktualisierungstoken an, indem Sie eine POST Anfrage an den Token-Austausch-Endpunkt senden.Die Anfrage muss den Codes, die Client-ID und den Code-Verifizierungs-Wert (PKCE) oder den Client-Geheimnis-Wert (non-PKCE) im x-www-form-urlencoded Format enthalten.
Parst die gültigen Token aus der empfangenen Antwort.Das Zugriffs-Token ist 15 Minuten gültig.Lagere das Aktualisierungstoken sicher, typischerweise auf der Serverseite, damit du es verwenden kannst, um in Zukunft neue Token zu erhalten.
Beispiel-Token-Endpunktantwort{"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.eyJzdWIiOiIyMDY3MjQzOTU5IiwibmFtZSI6ImxpbmtzZ29hdCIsIm5pY2tuYW1lIjoibGlua3Nnb2F0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoibGlua3Nnb2F0IiwiY3JlYXRlZF9hdCI6MTYwNzM1NDIzMiwicHJvZmlsZSI6Imh0dHBzOi8vd3d3LnJvYmxveC5jb20vdXNlcnMvMjA2NzI0Mzk1OS9wcm9maWxlIiwibm9uY2UiOiIxMjM0NSIsImp0aSI6IklELnltd3ZjTUdpOVg4azkyNm9qd1I5IiwibmJmIjoxNjkxNjM5Njk4LCJleHAiOjE2OTE2NzU2OTgsImlhdCI6MTY5MTYzOTY5OCwiaXNzIjoiaHR0cHM6Ly9hcGlzLnJvYmxveC5jb20vb2F1dGgvIiwiYXVkIjoiNzI5MDYxMDM5Nzk4NzkzNDk2NCJ9.kZgCMJQGsariwCi8HqsUadUBMM8ZOmf_IPDoWyQY9gVX4Kx3PubDz-Q6MvZ9eU5spNFz0-PEH-G2WSvq2ljDyg","scope": "openid profile"}
Rufe eine Ressourcenmethode auf
Jetzt, da du das erforderliche Zugriffs-Token hast, kannst du es verwenden, um authentifizierte Anrufe an Ressourcenmethoden zu machen.Füge das Zugriffs-Token in den Header aller API-Anfragen ein, um sie zu autorisieren.
Zum Beispiel können Sie testen, ob Ihre App ordnungsgemäß funktioniert, indem Sie den gesamten Autorisierungsfluss durchlaufen und dann eine GET an den Benutzerinformations-Endpunkt mit einem Zugriffstoken senden.Stellen Sie sicher, dass Sie die openid oder beide openid und profile Bereiche vor dem Aufruf dieser Endpunkt haben.Wenn erfolgreich, sieht die Antwort von diesem Endpunkt wie folgt aus:
Beispiel-Benutzerinformationsantwort
{
"sub": "12345678",
"name": "Jane Doe",
"nickname": "robloxjanedoe",
"preferred_username": "robloxjanedoe",
"created_at": 1607354232,
"profile": "https://www.roblox.com/nutzer/12345678/profil"
}