Autenticazione OAuth 2.0

L'autenticazione OAuth 2.0 è una funzione beta che potrebbe essere soggetta a cambi per le future versioni.Tutti i punti finali del cloud aperti supportano anche autenticazione della chiave API.

Per guide di implementazione complete e informazioni su OAuth 2.0, inclusa un'applicazionedi esempio, vedi il OAuth 2.0 Overview.

Questo documento descrive i punti finali che puoi chiamare per implementare il flusso di autorizzazione del codice OAuth 2.0, nonché altri punti finali utili per implementare l'autenticazione nelle tue app.

Base URL
https://apis.roblox.com/oauth

Endpoints
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

Autorizzazione

GET v1/authorize

Ottiene l'autorizzazione dall'utente per autenticarsi con il suo AccountRoblox.Si aspetta un URL di autorizzazione valido costruito con i parametri specificati.Questo endpoint supporta l'autorizzazione PKCE.

Parametri di query

Nome	Descrizione	Richiesto	Esempio
client_id	L'ID del cliente dell'app.	yes	816547628409595165403873012
redirect_uri	L'URL a cui gli utenti vengono reindirizzati dopo il completamento del flusso di autorizzazione.	yes	https://www.roblox.com/example-redirect
scope	Gli scopi richiesti, spazio delimitato.Usa lo scope openid per ricevere un token ID.Usa il openid e profile campo per ottenere maggiori informazioni sull'utente.	yes	openid profile
response_type	Le credenziali che l'app vuole restituire.Il predefinito è il inserisci / scrividi autorizzazione del codice di concessione.	yes	none , code
prompt	Specifica le pagine di autenticazione e consenso che vengono mostrate agli utenti.Alcune schermate sono richieste per le app di terze parti e non possono essere saltate.	no	none , login , consent , select_account
nonce	Il numero crittografico che lega il token con il client.	no	<random_value_1>
stato	Un valore opaco che impedisce la contraffazione delle richieste cross-site, un tipo di attacco malevolo.Ritornato all'app dopo l'autorizzazione.	no	<app-provided-opaque-value>
code_challenge	La stringa di risultato dell'applicazione del code_challenge_method al code_verifier .	no	Base64-URL-encoded string
code_challenge_method	La funzione che viene applicata al code_verifier .	no	S256

Richiesta

Example Request of Directing to Authorization Flow
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

Risposta

Dopo aver chiamato questo endpoint, l'utente viene reindirizzato all'URL di reindirigo specificato con il codice di autorizzazione in un parametro di query code.Il codice di autorizzazione:

Ha una durata di un minuto.
Può essere riscattato solo una volta.
È invalido dopo un uso.

Scambiaredi token

Per ottenere token per accedere alle API, scambia un codice di autorizzazione per un insieme di token confidenziali.Tutti i punti finali del token supportano due tipi di autenticazione del client:

Schema di autenticazione HTTP di base con un header di autorizzazione: Authorization: Basic Base64 encoded(<client_id>:<client_secret>) .
ID client e segreto nel corpo della richiesta come parametri.

La seguente lista descrive i vari token che ricevi da questo endpoint.

Token di accesso - Rappresenta l'autorizzazione da parte di un creatore o utente per un'app di terze parti per accedere alle loro risorse Roblox protette.È una stringa che denota una specifica scala, durata e altri attributi di accesso.Una volta che il server di autorizzazione Roblox emette un token di accesso a un'applicazione, il token:
- È valido per 15 minuti.
- Può essere utilizzato più volte prima che scada.
- Può essere invalidato prima che scada se un utente dell'app revoca l'autorizzazione.
Aggiorna token - Aggiorna una Sessionedi autorizzazione.Un'app può utilizzare il token di aggiornamento per ottenere un nuovo set di token, che include un token di accesso, un token di aggiornamento e un token di identità.Un token di aggiornamento:
- È valido per 90 giorni.
- Può essere utilizzato solo una volta prima che scada per aggiornare i gettoni.
- Può essere invalidato prima che scada se un utente dell'app revoca l'autorizzazione.
Token ID - Fornisce la prova che l'identità di un utente è stata autenticata.Il suo contenuto dipende dagli scopi richiesti e può contenere informazioni di base sull'utente, tra cui il nome e l'Nome utentedel display di Roblox dell'utente.Il token ID è solo per scopi di autenticazione dell'identità e non fornisce l'accesso a nessuna risorsa Roblox.

POST v1/token

Ottieni un insieme di token con un codice di autorizzazione.

Richiesta

(x-www-form-urlencoded)

Chiave	Valore
codice	<authorization code>
code_verifier	<pkce code verifier value>
grant_type	autorizzazione_codice
client_id	<client_id>
client_secret	<client_secret>

Esempio di richiesta di ottenimento del token
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'

Risposta

Esempio di ottenimento della risposta del token
{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 899,
  "scope": "universe-messaging-service:publish"
}

POST v1/token

Ottieni un set di token con un token di aggiornamento.

Richiesta

(x-www-form-urlencoded)

Chiave	Valore
grant_type	refresh_token
refresh_token	<refresh_token>
client_id	<client_id>
client_secret	<client_secret>

Esempio richiesta di aggiornamento del token
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'

Risposta

Esempio richiesta di aggiornamento del token
{
  "access_token": "...",
  "refresh_token": "...",
  "token_type": "Bearer",
  "expires_in": 899,
  "scope": "universe-messaging-service:publish"
}

POST v1/token/introspect

Ricevi informazioni su un token.Verifica se il token è attualmente valido e non è scaduto ancora.Utile per la validazione senza stato.Usa solo se l'API a cui stai accedendo non richiede una risorsa, come Assets API, o se vuoi solo vedere reclami specifici del token.

Anche se l'utente ha revocato l'autorizzazione collegata al token di accesso, l'endpoint mostra ancora il token di accesso come valid: true perché controlla se il token è attivo in base alla sua durata (solitamente 15 minuti per i token di accesso).

Richiesta

(x-www-form-urlencoded)

Chiave	Valore
token	<access_token> , <refresh_token> o <id_token>
client_id	<client_id>
client_secret	<client_secret>

Esempio richiesta di token Introspect
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'

Risposta

Risposta del token Introspect di esempio
{
  "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

Verifica se un token può accedere a una risorsa specifica ottenendo l'elenco delle risorse utente per le quali l'utente ha dato il permesso.Questo è utile per la validazione statale.

Richiesta

(x-www-form-urlencoded)

Chiave	Valore
token	<access_token>
client_id	<client_id>
client_secret	<client_secret>

Esempio di richiesta di risorse di token ottenute
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'

Risposta

Il valore U in ids indica che una scoperta ha concesso l'accesso a una risorsa di proprietà dell'autorizzante owner .

Esempio di risposta alle risorse di token ottenute
{
  "resource_infos": [
    {
      "owner": {
        "id": "1516563360",
        "type": "User"
      },
      "resources": {
        "universe": {
          "ids": ["3828411582"]
        },
        "creator": {
          "ids": ["U"]
        }
      }
    }
  ]
}

POST v1/token/revoke

Rivoca una sessione di autorizzazione utilizzando il token di aggiornamento fornito.

Richiesta

(x-www-form-urlencoded)

Chiave	Valore
token	<refresh_token>
client_id	<client_id>
client_secret	<client_secret>

Esempio richiesta di revoca del token
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'

Risposta

200 OK con una risposta vuota

Informazioni sull'utente

GET /v1/userinfo

Ottiene l'ID utente Roblox e altri metadati dell'utente.

Richiesta

Header di autorizzazione : Authorization: Bearer <access_token>

Esempio di richiesta di informazioni utente
curl --location --request GET 'https://apis.roblox.com/oauth/v1/userinfo' \
--header 'Authorization: Bearer eyjlflabtfl...4gxqYBG'

Risposta

Puoi usare il valore sub per identificare in modo univoco l'utente.Gli utenti possono cambiare il loro nome utente e il Nome Visualizzatodi Roblox, quindi non usarli come identificatori univoci per riferirsi agli utenti sulla tua applicazione.

Reclamo	Descrizione
sub	ID utente Roblox.
nome	Nome di visualizzazione di Roblox.
nickname	Nome VisualizzatoRoblox.
preferred_username	Nome utente Roblox.
created_at	Tempo di creazione dell'account Roblox come timestamp Unix.
profilo	URL profilo account Roblox.
immagine	Fotografo dell'avatar di Roblox.Può essere nullo se l'immagine del colpo alla testa dell'avatar non è ancora stata generata o è stata moderata.

Esempio utente con scopo profilo
{
  "sub": "1516563360",
  "name": "exampleuser",
  "nickname": "exampleuser",
  "preferred_username": "exampleuser",
  "created_at": 1584682495,
  "profile": "https://www.roblox.com/utenti/1516563360/profilo",
  "picture": "https://tr.rbxcdn.com/03dc2a9abe7b1aacaaf93ea46d5c0646/150/150/AvatarHeadshot/Png"
}

Esempio utente senza scopo di profilo
{
  "sub": "1516563360"
}

Scoperta

Il documento di scoperta OpenID Connect (OIDC) è un documento JSON che contiene metadati sui dettagli della configurazione del cloud aperto, inclusa una lista di scope e affermazioni correlate all'identità che sono supportate.Puoi usarlo per scoprire dinamicamente le informazioni sugli endpoint Open Cloud OAuth 2.0 e sulla configurazione, come l'endpoint di autorizzazione, il punto di interfaccia del token e il Impostaredi chiavi pubbliche.

Dopo aver recuperato e recuperato il documento di scoperta dall' URI del documento di scoperta, puoi ispezionare manualmente i campi nella risposta per verificare le informazioni o creare la tua mappa personalizzata della libreria per i campi nella risposta dello schema per automatizzare il tuo flusso di lavoro.

GET .well-known/openid-configuration

Risposta

Tutte le risposte della documentazione di scoperta seguono lo stesso schema della risposta di esempio seguente.

Non tutti i seguenti ambiti e affermazioni sono disponibili per i creatori di app di terze parti, poiché alcuni possono essere utilizzati solo da app ufficiali di Roblox.

Risposta del documento di scoperta di esempio
{
  "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/risorse",
  "userinfo_endpoint": "https://apis.roblox.com/oauth/v1/userinfo",
  "jwks_uri": "https://apis.roblox.com/oauth/v1/certs",
  "registration_endpoint": "https://creare.roblox.com/dashboard/credenziali",
  "service_documentation": "https://creare.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"
  ]
}

Parametri di query

Richiesta

Risposta

Richiesta

Risposta

Richiesta

Risposta

Richiesta

Risposta

Richiesta

Risposta

Richiesta

Risposta

Richiesta

Risposta

Risposta

Su questa pagina