Open Cloud prend en charge le flux d'autorisation OAuth 2.0 avec et sans PKCE, selon que vos clients sont confidentiels ou public/publique.
- Clients confidentiels sont des applications capables de garder les données confidentielles, telles qu'un site Web qui peut stocker et récupérer en toute sécurité des secrets sur son arrière-plan.
- Les clients publics sont des applications qui ne peuvent pas garder de secrets, telles que les applications de navigateur mobile et web.
Nous recommandons le flux d'autorisation OAuth 2.0 avec PKCE pour tous les clients et l'exigeons pour les clients publics.
Stockez le secret du client dans un endroit sécurisé et ne le divulguez jamais au public/publique. Les acteurs malveillants peuvent l'utiliser pour se faire passer pour votre application.
Pour mettre en œuvre le flux de code d'autorisation, votre application effectue les étapes suivantes :
- Générer un vérificateur de code et un défi de code (PKCE uniquement).Cela vous permet d'inclure un défi dans vos demandes plutôt que le secret du client, ce qui améliore la sécurité.
- Envoyez une demande GET à l'extrémité d'autorisation avec les paramètres appropriés.
- Gérer le rappel d'autorisation.Après avoir obtenu l'autorisation, utilisez le code d'autorisation de Roblox dans une demande de redirection vers l'URL que vous avez spécifiée lors de la créationsde l'application.Analysez le code d'autorisation pour une utilisation ultérieure.
- Envoyez une demande POST à l'extrémité du jeton avec le code d'autorisation.Si vous réussissez, vous recevez des jetons d'accès et de mise à jour avec lesquels effectuer des appels d'API.
- Appellez n'importe quelle API Open Cloud qui prend en charge l'authentification OAuth 2.0 en fonction de la documentation de référence pour les ressources que vous souhaitez accès.
Les sections suivantes décrivent chaque étape plus en détail.
Générer un défi de code (pour PKCE uniquement)
Avant d'initier le processus d'autorisation, vous devez générer un défi de code à partir d'un vérificateur de code.Vous pouvez utiliser des bibliothèques ou des fonctions intégrées dans la langue de programmation de votre choix pour créer le vérificateur de code, calculer le hash et effectuer un encodage Base64 pour générer le défi de code.
Lors de la création du vérificateur de code, n'utilisez que des caractères non réservés, y compris les lettres majuscules et minuscules (A-Z, a-z), les chiffres décimaux (0-9), l'hyphen (-), la période (.), l'underscore (_) et la tilde (~), avec une longueur minimale de 43 caractères et une longueur maximale de 128 caractères.
L'exemple suivant montre comment utiliser Javascript pour créer un vérificateur de code et générer le défi de code en utilisant l'algorithme de hachage SHA-256 :
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));
Pour PKCE, vous avez besoin à la fois du vérificateur de code et des valeurs de défi dans les étapes ultérieures.
Construire l'URL d'autorisation
Voir la documentation de référence sur le point d'autorisation pour obtenir des informations complètes sur la façon de construire l'URL d'autorisation.
Pour initier le processus d'autorisation de l'utilisateur, construisez une URL d'autorisation avec les paramètres requis :
- client_id : L'ID client de votre application obtenu après enregistrement de votre application .
- redirect_uri : L' URI de redirection de votre app, le point de réentrée de votre app.
- scope : Les scopes demandés qui définissent les permissions d'accès dont votre application a besoin dans une liste séparée par des espaces.
- response_type : Définissez-le sur code pour indiquer le flux de code d'autorisation. Nécessaire pour PKCE uniquement
- code_challenge : Le défi de code généré à partir d'un vérificateur de code.
- code_challenge_method : Définissez la valeur de ce paramètre sur S256 pour indiquer que le défi de code a été transformé en utilisant l'algorithme SHA-256, la méthode de défi de code la plus largement soutenue et la plus sécurisée.
- state : Une valeur aléatoire opaque et sécurisée pour maintenir l'état entre la demande et le rappel. Nécessaire pour non-PKCE uniquement
- client_secret : Le secret client de votre application obtenu après enregistrement de votre application .Si vous utilisez l'authentification avec PKCE, omettez ce paramètre.L'URL de votre demande d'autorisation doit être bien formatée, comme dans l'exemple suivant :
Exemple d'URL d'autorisation PKCE
Lorsque les utilisateurs visitent l'URL, ils sont dirigés à travers le flux d'autorisation. S'ils réussissent, Roblox redirige l'utilisateur vers le redirect_uri spécifié.
Gérer les appels d'autorisation
Lorsqu'un flux d'autorisation est réussi, votre application reçoit une demande GET de la part du serveur d'autorisation Roblox au redirect_uri que vous avez spécifié.Dans la demande, vous recevez code (code d'autorisation) et state (si vous avez fourni une valeur précédemment) paramètres.
Le paramètre code contient un code d'autorisation que l'application peut échanger contre un jeton d'accès du serveur d'autorisation.La plupart des langages de serveur arrière-plan ont des façons standard d'accéder aux paramètres de requête en tant qu'objets décodés.Vous devrez obtenir le paramètre code et l'utiliser pour échanger des jetons d'accès.
Le paramètre state est une valeur opaque que vous avez initialement fournie dans la demande d'autorisation.Vous pouvez utiliser ce paramètre pour maintenir l'état ou le contexte du processus d'autorisation.
Par exemple, vous pouvez recevoir une requête GET avec l'URL suivante si vous avez spécifié que votre URI de redirection était https://example.com/redirect.
URL de redirection d'exemple
Si l'autorisation échoue, votre application reçoit une demande GET de redirection vers l'URL spécifiée avec les paramètres error, error_description et state (le cas applicable).
- Le paramètre error indique l'erreur spécifique d'OAuth 2.0 qui s'est produite pendant le processus d'autorisation.
- Le paramètre error_description fournit des détails supplémentaires de l'erreur.
- Le paramètre state aide votre application à maintenir l'état dans le cas d'une échec.
Échanger un code d'autorisation pour des jetons d'accès
Lorsque vous avez analysé l'autorisation code, échangez-la contre des jetons pour accéder aux ressources Roblox désirées :
Demandez un jeton d'accès et un jeton de rafraîchissement en envoyant une requête à l'extrémité d'échange de jetons .La demande doit inclure le code d'autorisation, l'ID du client et la valeur du vérificateur de code (PKCE) ou le secret du client (non-PKCE) au format x-www-form-urlencoded.
Analysez les jetons applicables de la réponse reçue.Le jeton d'accès est valide pendant 15 minutes.Stockez le jeton de rafraîchissement en toute sécurité, généralement du côté du serveur, afin que vous puissiez l'utiliser pour obtenir de nouveaux jetons à l'avenir.
Réponse de point final de jeton d'exemple{"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"}
Faire un appel à une méthode de ressource
Maintenant que vous avez le jeton d'accès requis, vous pouvez l'utiliser pour faire des appels authentifiés aux méthodes de ressource.Incluez le jeton d'accès dans l'en-tête de toutes les demandes API pour les autoriser.
Par exemple, vous pouvez tester si votre application fonctionne correctement en traversant l'ensemble du flux d'autorisation et en effectuant ensuite une demande à l'extrémité des informations de l'utilisateur avec un jeton d'accès.Assurez-vous d'avoir le openid ou les deux scopes openid et profile avant d'appeler cet endpoint.Si cela réussit, la réponse de cet endpoint ressemble à ceci :
Réponse aux informations utilisateur d'exemple
{
"sub": "12345678",
"name": "Jane Doe",
"nickname": "robloxjanedoe",
"preferred_username": "robloxjanedoe",
"created_at": 1607354232,
"profile": "https://www.roblox.com/utilisateurs/12345678/profil"
}