Authentification OAuth 2.0 | Documentation

L'authentification OAuth 2.0 est une fonctionnalité bêta qui pourrait être sujette à changement pour les futures versions. Tous les points de terminaison Open Cloud prennent également en charge l'authentification par clé API.

Pour des guides d'implémentation complets et des informations sur OAuth 2.0, y compris une application d'exemple, consultez l'aperçu d'OAuth 2.0.

Ce document décrit les points de terminaison que vous appelez pour implémenter le flux de code d'autorisation OAuth 2.0, ainsi que d'autres points de terminaison utiles pour mettre en œuvre l'authentification dans vos applications.

URL de base
https://apis.roblox.com/oauth

Points de terminaison
GET v1/authorize
POST v1/token
POST v1/token/introspect
POST v1/token/resources
POST v1/token/revoke
GET v1/userinfo
GET .well-known/openid-configuration

Autorisation

GET v1/authorize

Obtient l'autorisation de l'utilisateur pour s'authentifier avec son compte Roblox. S'attend à une URL d'autorisation valide construite avec les paramètres spécifiés. Ce point de terminaison prend en charge l'autorisation PKCE.

Paramètres de requête

Nom	Description	Obligatoire	Exemple
client_id	L'ID client de l'application.	oui	816547628409595165403873012
redirect_uri	L'URL vers laquelle les utilisateurs sont redirigés après l'achèvement du flux d'autorisation.	oui	`https://www.roblox.com/example-redirect``
scope	Les scopes demandés, délimités par des espaces. Utilisez le scope openid pour recevoir un ID token. Utilisez le scope openid et profile pour obtenir plus d'informations sur l'utilisateur.	oui	openid profile
response_type	Les informations d'identification que l'application souhaite récupérer. Par défaut, c'est le type d'octroi de code d'autorisation.	oui	none, code
prompt	Spécifie quelles pages d'authentification et de consentement sont affichées aux utilisateurs. Certains écrans sont nécessaires pour les applications tierces et ne peuvent pas être ignorés.	non	none, login, consent, select_account
nonce	Le nombre cryptographique qui lie le jeton au client.	non	<random_value_1>
state	Une valeur opaque qui empêche le vol de requêtes inter-sites, un type d'attaque malveillante. Renvoie à l'application après l'autorisation.	non	<app-provided-opaque-value>
code_challenge	La chaîne résultante de l'application de la code_challenge_method au code_verifier.	non	Chaîne encodée Base64-URL
code_challenge_method	La fonction appliquée au code_verifier.	non	S256

Requête

Exemple de requête pour diriger vers le flux d'autorisation
https://apis.roblox.com/oauth/v1/authorize?client_id=816547628409595165403873012&redirect_uri=https://my-app.com/redirect&scope=openid&response_type=code&nonce=12345&state=6789

Réponse

Après avoir appelé ce point de terminaison, l'utilisateur est redirigé vers l'URL de redirection spécifiée avec le code d'autorisation dans un paramètre de requête code. Le code d'autorisation :

A une durée de vie d'une minute.
Ne peut être échangé qu'une seule fois.
Est invalide après une utilisation.

Échange de jetons

Pour obtenir des jetons pour accéder aux API, échangez un code d'autorisation contre un ensemble de jetons confidentiels. Tous les points de terminaison de jetons prennent en charge deux types d'authentification client :

Schéma d'authentification de base HTTP avec un en-tête d'autorisation : Authorization: Basic Base64 encoded(<client_id>:<client_secret>).
ID client et secret dans le corps de la requête en tant que paramètres.

La liste suivante décrit les différents jetons que vous recevez de ce point de terminaison.

Jeton d'accès - Représente l'autorisation d'un créateur ou d'un utilisateur pour qu'une application tierce accède à ses ressources Roblox protégées. C'est une chaîne désignant un scope spécifique, une durée de vie et d'autres attributs d'accès. Une fois le serveur d'autorisation Roblox émet un jeton d'accès à une application, le jeton :
- Est valide pendant 15 minutes.
- Peut être utilisé plusieurs fois avant son expiration.
- Peut être invalidé avant son expiration si un utilisateur de l'application révoque l'autorisation.
Jeton de rafraîchissement - Rafraîchit une session d'autorisation. Une application peut utiliser le jeton de rafraîchissement pour obtenir un nouvel ensemble de jetons, qui comprend un jeton d'accès, un jeton de rafraîchissement et un ID token. Un jeton de rafraîchissement :
- Est valide pendant 90 jours.
- Peut être utilisé une seule fois avant son expiration pour rafraîchir les jetons.
- Peut être invalidé avant son expiration si un utilisateur de l'application révoque l'autorisation.
ID token - Fournit une preuve que l'identité d'un utilisateur a été authentifiée. Son contenu dépend des scopes demandés et peut contenir des informations de base sur l'utilisateur, y compris le nom d'affichage et le nom d'utilisateur Roblox. L'ID token est uniquement à des fins d'authentification d'identité et ne donne pas accès à des ressources Roblox.

POST v1/token

Obtenez une série de jetons avec un code d'autorisation.

Requête

(x-www-form-urlencoded)

Clé	Valeur
code	<authorization code>
code_verifier	<pkce code verifier value>
grant_type	authorization_code
client_id	<client_id>
client_secret	<client_secret>

Exemple de requête d'obtention de jeton
curl --location --request POST 'https://apis.roblox.com/oauth/v1/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=840974200211308101' \
--data-urlencode 'client_secret=RBX-CR9...St12L' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'code=yCnq4ofX1...XmGpdx'

Réponse

Exemple de réponse d'obtention de jeton
{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 899,
  "scope": "universe-messaging-service:publish"
}

POST v1/token

Obtenez une série de jetons avec un jeton de rafraîchissement.

Requête

(x-www-form-urlencoded)

Clé	Valeur
grant_type	refresh_token
refresh_token	<refresh_token>
client_id	<client_id>
client_secret	<client_secret>

Exemple de requête de rafraîchissement de jeton
curl --location --request POST 'https://apis.roblox.com/oauth/v1/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=refresh_token' \
--data-urlencode 'refresh_token=Ujfstayclfdlbm...BGydlsnU' \
--data-urlencode 'client_id=840974200211308101' \
--data-urlencode 'client_secret=RBX-CR9...St12L'

Réponse

Exemple de requête de rafraîchissement de jeton
{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 899,
  "scope": "universe-messaging-service:publish"
}

POST v1/token/introspect

Recevez des informations sur un jeton. Vérifie si le jeton est actuellement valide et n'a pas encore expiré. Utile pour la validation sans état. Utilisez-le seulement si l'API à laquelle vous accédez ne nécessite pas une ressource, comme l'API des actifs, ou si vous voulez simplement voir des revendications spécifiques du jeton.

Même si l'utilisateur a révoqué l'autorisation liée au jeton d'accès, le point de terminaison indique toujours le jeton d'accès comme valid: true car il vérifie si le jeton est actif en fonction de sa durée de vie (généralement 15 minutes pour les jetons d'accès).

Requête

(x-www-form-urlencoded)

Clé	Valeur
token	<access_token>, <refresh_token> ou <id_token>
client_id	<client_id>
client_secret	<client_secret>

Exemple de requête d'introspection de jeton
curl --location --request POST 'https://apis.roblox.com/oauth/v1/token/introspect' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=eyjlflabtfl...4gxqYBG' \
--data-urlencode 'client_id=840974200211308101' \
--data-urlencode 'client_secret=RBX-CR9...St12L'

Réponse

Exemple de réponse d'introspection de jeton
{
  "active": true,
  "jti": "RT.2GcjvTduKzk6QY9tjTfm",
  "iss": "https://apis.roblox.com/oauth/",
  "token_type": "Bearer",
  "client_id": "840974200211308101",
  "aud": "4239311013248676173",
  "sub": "1516563360",
  "scope": "universe-messaging-service:publish",
  "exp": 1676394509,
  "iat": 1660842510
}

POST v1/token/resources

Vérifiez si un jeton peut accéder à une ressource spécifique en obtenant la liste des ressources utilisateur pour lesquelles l'utilisateur a donné la permission. Ceci est utile pour la validation avec état.

Requête

(x-www-form-urlencoded)

Clé	Valeur
token	<access_token>
client_id	<client_id>
client_secret	<client_secret>

Exemple de demande d'obtention des ressources du jeton
curl --location --request POST 'https://apis.roblox.com/oauth/v1/token/resources' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=eyjlflabtfl...4gxqYBG' \
--data-urlencode 'client_id=840974200211308101' \
--data-urlencode 'client_secret=RBX-CR9...St12L'

Réponse

La valeur U dans ids indique qu'un scope a accordé l'accès à une ressource possédée par le propriétaire autorisant.

Exemple de réponse d'obtention des ressources du jeton
{
  "resource_infos": [
    {
      "owner": {
        "id": "1516563360",
        "type": "User"
      },
      "resources": {
        "universe": {
          "ids": ["3828411582"]
        },
        "creator": {
          "ids": ["U"]
        }
      }
    }
  ]
}

POST v1/token/revoke

Révoquez une session d'autorisation en utilisant le jeton de rafraîchissement fourni.

Requête

(x-www-form-urlencoded)

Clé	Valeur
token	<refresh_token>
client_id	<client_id>
client_secret	<client_secret>

Exemple de demande de révocation de jeton
curl --location --request POST 'https://apis.roblox.com/oauth/v1/token/revoke' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'token=Ujfstayclfdlbm...BGydlsnU' \
--data-urlencode 'client_id=840974200211308101' \
--data-urlencode 'client_secret=RBX-CR9...St12L'

Réponse

200 OK avec une réponse vide

Informations sur l'utilisateur

GET /v1/userinfo

Obtient l'ID utilisateur Roblox et d'autres métadonnées utilisateur.

Requête

En-tête d'autorisation : Authorization: Bearer <access_token>

Exemple de demande d'informations utilisateur
curl --location --request GET 'https://apis.roblox.com/oauth/v1/userinfo' \
--header 'Authorization: Bearer eyjlflabtfl...4gxqYBG'

Réponse

Vous pouvez utiliser la valeur sub pour identifier de manière unique l'utilisateur. Les utilisateurs peuvent changer leur nom d'utilisateur et leur nom d'affichage Roblox, donc ne les utilisez pas comme identifiants uniques pour faire référence aux utilisateurs sur votre application.

Revendication	Description
sub	ID utilisateur Roblox.
name	Nom d'affichage Roblox.
nickname	Nom d'affichage Roblox.
preferred_username	Nom d'utilisateur Roblox.
created_at	Heure de création du compte Roblox sous forme de timestamp Unix.
profile	URL du profil du compte Roblox.
picture	Image du portrait de l'avatar Roblox. Peut être null si l'image du portrait de l'avatar n'a pas encore été générée ou a été modérée.

Exemple d'utilisateur avec le scope de profil
{
  "sub": "1516563360",
  "name": "exampleuser",
  "nickname": "exampleuser",
  "preferred_username": "exampleuser",
  "created_at": 1584682495,
  "profile": "https://www.roblox.com/users/1516563360/profile",
  "picture": "https://tr.rbxcdn.com/03dc2a9abe7b1aacaaf93ea46d5c0646/150/150/AvatarHeadshot/Png"
}

Exemple d'utilisateur sans le scope de profil
{
  "sub": "1516563360"
}

Découverte

Le document de découverte OpenID Connect (OIDC) est un document JSON qui contient des métadonnées sur les détails de configuration d'Open Cloud, y compris une liste de scopes et de revendications liés à l'identité qui sont pris en charge. Vous pouvez l'utiliser pour découvrir dynamiquement des informations sur les points de terminaison et la configuration OAuth 2.0 d'Open Cloud, comme le point de terminaison d'autorisation, le point de terminaison de jeton et l'ensemble de clés publiques.

Après avoir récupéré et récupéré le document de découverte à partir de l'URI du document de découverte, vous pouvez soit inspecter manuellement les champs de la réponse pour vérifier les informations, soit créer votre propre bibliothèque personnalisée mappant les champs du schéma de réponse pour automatiser votre flux de travail.

GET .well-known/openid-configuration

Réponse

Toutes les réponses des documents de découverte suivent le même schéma que la réponse d'exemple suivante.

Tous les scopes et revendications suivants ne sont pas disponibles pour les créateurs d'applications tierces, car certains ne peuvent être utilisés que par des applications Roblox officielles.

Exemple de réponse du document de découverte
{
  "issuer": "https://apis.roblox.com/oauth/",
  "authorization_endpoint": "https://apis.roblox.com/oauth/v1/authorize",
  "token_endpoint": "https://apis.roblox.com/oauth/v1/token",
  "introspection_endpoint": "https://apis.roblox.com/oauth/v1/token/introspect",
  "revocation_endpoint": "https://apis.roblox.com/oauth/v1/token/revoke",
  "resources_endpoint": "https://apis.roblox.com/oauth/v1/token/resources",
  "userinfo_endpoint": "https://apis.roblox.com/oauth/v1/userinfo",
  "jwks_uri": "https://apis.roblox.com/oauth/v1/certs",
  "registration_endpoint": "https://create.roblox.com/dashboard/credentials",
  "service_documentation": "https://create.roblox.com/docs/reference/cloud",
  "scopes_supported": [
    "openid",
    "profile",
    "email",
    "verification",
    "credentials",
    "age",
    "premium",
    "roles"
  ],
  "response_types_supported": ["none", "code"],
  "subject_types_supported": ["public"],
  "id_token_signing_alg_values_supported": ["ES256"],
  "claims_supported": [
    "sub",
    "type",
    "iss",
    "aud",
    "exp",
    "iat",
    "nonce",
    "name",
    "nickname",
    "preferred_username",
    "created_at",
    "profile",
    "email",
    "email_verified",
    "verified",
    "age_bracket",
    "premium",
    "roles",
    "internal_user"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ]
}