Open Cloud prend en charge le flux d'autorisation OAuth 2.0 avec et sans PKCE, selon que vos clients sont confidentiels ou publics.
- Clients confidentiels sont des applications capables de garder les identifiants confidentiels, comme un site Web qui peut stocker et récupérer en toute sécurité des secrets sur son backend.
- Clients publics sont des applications qui ne peuvent pas garder de secrets, telles que les applications mobiles et les applications de navigateur Web.
Nous recommandons le flux de code d'autorisation OAuth 2.0 avec PKCE pour tous les clients et le requérons pour les clients publics.
Stockez le secret client dans un endroit sûr et ne le révélez jamais au public. Les acteurs malveillants peuvent l'utiliser pour usurper l'identité de votre application.
Pour mettre en œuvre le flux de code d'autorisation, votre application effectue les étapes suivantes :
- Générez un vérificateur de code et un défi de code (uniquement pour PKCE). Cela vous permet d'inclure un défi dans vos requêtes plutôt que le secret client, ce qui améliore la sécurité.
- Envoyez une requête GET à l'endpoint d'autorisation avec les paramètres appropriés.
- Gérez le rappel d'autorisation. Après avoir obtenu l'autorisation, utilisez le code d'autorisation de Roblox dans une requête de redirection vers l'URL que vous avez spécifiée lors de la création de l'application. Analysez le code d'autorisation pour une utilisation ultérieure.
- Envoyez une requête POST à l'endpoint de jeton avec le code d'autorisation. Si cela réussit, vous recevez des jetons d'accès et de rafraîchissement avec lesquels effectuer des appels API.
- Appelez toute API Open Cloud qui prend en charge l'authentification OAuth 2.0 sur la base de la documentation de référence pour les ressources que vous souhaitez accéder.
Les sections suivantes décrivent chaque étape plus en détail.
Générer un défi de code (uniquement pour PKCE)
Avant de commencer 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 le langage de programmation de votre choix pour créer le vérificateur de code, calculer le hachage 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 des lettres majuscules et minuscules (A-Z, a-z), des chiffres décimaux (0-9), un tiret (-), un point (.), un trait de soulignement (_) et un tilde (~), avec une longueur minimum de 43 caractères et une longueur maximum 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 :
Générer le défi de code
const crypto = require('crypto');
// encoder en base64URL le vérificateur et le défi
function base64URLEncode(str) {
return str.toString('base64')
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=/g, '');
}
// créer un hachage sha256 à partir du vérificateur de code
function sha256(buffer) {
return crypto.createHash('sha256').update(buffer).digest(`base64`);
}
// créer un vérificateur de code aléatoire
var code_verifier = base64URLEncode(crypto.randomBytes(32));
// générer un défi à partir du vérificateur de code
var code_challenge = base64URLEncode(sha256(code_verifier));
Pour PKCE, vous avez besoin à la fois des valeurs de vérificateur de code et de défi dans les étapes ultérieures.
Construire l'URL d'autorisation
Consultez la documentation de référence de l'endpoint d'autorisation pour des informations complètes sur la manière 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 l'enregistrement de votre application.
- redirect_uri: L'URI de redirection de votre application, le point de réentrée de votre application.
- scope: Les portées demandées qui définissent les autorisations d'accès dont votre application a besoin dans une liste séparée par des espaces.
- response_type: Réglez-le sur code pour indiquer le flux de code d'autorisation.
Requis uniquement pour PKCE
- code_challenge: Le défi de code généré à partir d'un vérificateur de code.
- code_challenge_method: Réglez cette valeur de paramètre sur S256 pour indiquer que le défi de code a été transformé à l'aide de l'algorithme SHA-256, la méthode de défi de code la plus largement supportée et sécurisée.
- state: Une valeur opaque, aléatoire et sécurisée pour maintenir l'état entre la requête et le rappel.
Requis uniquement pour non-PKCE
- client_secret: Le secret client de votre application obtenu après l'enregistrement de votre application. Si vous utilisez l'authentification avec PKCE, omettez ce paramètre. Votre URL de 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 guidés à travers le flux d'autorisation. Si cela réussit, Roblox redirige l'utilisateur vers l'redirect_uri spécifié.
Gérer les rappels d'autorisation
Lorsqu'un flux d'autorisation est réussi, votre application reçoit une requête GET du serveur d'autorisation Roblox à l'redirect_uri que vous avez spécifié. Dans la demande, vous recevez les paramètres code (code d'autorisation) et state (si vous avez fourni une valeur précédemment).
Le paramètre code contient un code d'autorisation que l'application peut échanger contre un jeton d'accès auprès du serveur d'autorisation. La plupart des langages de serveur back-end disposent de méthodes standard pour accéder aux paramètres de requête sous forme d'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 pourriez recevoir une requête GET avec l'URL suivante si vous avez spécifié votre URI de redirection pour être https://example.com/redirect.
Exemple d'URL de redirection
Si l'autorisation échoue, votre application reçoit une requête GET à l'URL de redirection spécifiée avec les paramètres error, error_description, et state (le cas échéant).
- Le paramètre error indique l'erreur OAuth 2.0 spécifique qui s'est produite lors du processus d'autorisation.
- Le paramètre error_description fournit des détails supplémentaires sur l'erreur.
- Le paramètre state aide votre application à maintenir l'état en cas d' échec.
Échanger un code d'autorisation contre des jetons d'accès
Lorsque vous avez analysé le code d'autorisation, échangez-le contre des jetons pour accéder aux ressources Roblox souhaitées :
Demandez un jeton d'accès et un jeton de rafraîchissement en envoyant une requête POST au point de terminaison d'échange de jeton. La demande doit inclure le code d'autorisation, l'ID client, et la valeur de vérificateur de code (PKCE) ou le secret client (non-PKCE) au format x-www-form-urlencoded.
Analysez les jetons applicables à partir 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 côté serveur, afin de pouvoir l'utiliser pour obtenir de nouveaux jetons à l'avenir.
Exemple de réponse de l'endpoint de jeton{"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 effectuer des appels authentifiés aux méthodes de ressource. Incluez le jeton d'accès dans l'en-tête de toutes les requêtes API pour les autoriser.
Par exemple, vous pouvez tester si votre application fonctionne correctement en traversant l'ensemble du flux d'autorisation, puis en faisant une requête GET au point de terminaison des informations utilisateur avec un jeton d'accès. Assurez-vous d'avoir les portées openid ou à la fois les portées openid et profile avant d'appeler ce point de terminaison. Si cela réussit, la réponse de ce point de terminaison ressemble à ceci :
Exemple de réponse des informations utilisateur
{
"sub": "12345678",
"name": "Jane Doe",
"nickname": "robloxjanedoe",
"preferred_username": "robloxjanedoe",
"created_at": 1607354232,
"profile": "https://www.roblox.com/users/12345678/profile"
}