Open Cloud supporta il flusso di autorizzazione OAuth 2.0 con e senza PKCE, a seconda che i tuoi client siano riservati o pubblici.
- Client riservati sono app che sono in grado di mantenere le credenziali riservate, come un sito web che può memorizzare e recuperare in modo sicuro i segreti sul suo backend.
- Client pubblici sono app che non possono mantenere segreti, come app mobili e browser web.
Raccomandiamo il flusso di autorizzazione con codice OAuth 2.0 con PKCE per tutti i client e lo richiediamo per i client pubblici.
Memorizza il client secret in un luogo sicuro e non esporlo mai al pubblico. I malintenzionati possono usarlo per impersonare la tua applicazione.
Per implementare il flusso di autorizzazione, la tua app esegue i seguenti passaggi:
- Genera un code verifier e un code challenge (solo PKCE). Questo ti consente di includere una sfida nelle tue richieste anziché il client secret, il che migliora la sicurezza.
- Invia una richiesta GET all'endpoint di autorizzazione con i parametri appropriati.
- Gestisci il callback di autorizzazione. Dopo aver ottenuto l'autorizzazione, utilizza il codice di autorizzazione di Roblox in una richiesta di reindirizzamento all'URL che hai specificato durante la creazione dell'app. Analizza il codice di autorizzazione per un uso successivo.
- Invia una richiesta POST all'endpoint del token con il codice di autorizzazione. Se ha successo, ricevi access token e refresh token con cui effettuare chiamate API.
- Chiama qualsiasi API Open Cloud che supporta l'autenticazione OAuth 2.0 in base alla documentazione di riferimento per le risorse a cui desideri accedere.
Le sezioni seguenti descrivono ciascun passaggio in maggiore dettaglio.
Generare un code challenge (solo per PKCE)
Prima di avviare il processo di autorizzazione, devi generare un code challenge da un code verifier. Puoi utilizzare librerie o funzioni integrate nel linguaggio di programmazione di tua scelta per creare il code verifier, calcolare l'hash e eseguire la codifica Base64 per generare il code challenge.
Quando crei il code verifier, utilizza solo caratteri non riservati, tra cui lettere maiuscole e minuscole (A-Z, a-z), cifre decimali (0-9), trattino (-), punto (.), trattino basso (_), e tilde (~), con una lunghezza minima di 43 caratteri e una lunghezza massima di 128 caratteri.
Il seguente esempio mostra come utilizzare Javascript per creare un code verifier e generare il code challenge utilizzando l'algoritmo di hashing SHA-256:
Genera Code Challenge
const crypto = require('crypto');
// codifica base64URL il verifier e la challenge
function base64URLEncode(str) {
return str.toString('base64')
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=/g, '');
}
// crea hash sha256 dal code verifier
function sha256(buffer) {
return crypto.createHash('sha256').update(buffer).digest(`base64`);
}
// crea un code verifier casuale
var code_verifier = base64URLEncode(crypto.randomBytes(32));
// genera una challenge dal code verifier
var code_challenge = base64URLEncode(sha256(code_verifier));
Per PKCE, hai bisogno sia del code verifier che dei valori di challenge nei passaggi successivi.
Costruire l'URL di autorizzazione
Consulta la documentazione di riferimento dell'endpoint di autorizzazione per informazioni complete su come costruire l'URL di autorizzazione.
Per avviare il processo di autorizzazione dell'utente, costruisci un URL di autorizzazione con i parametri richiesti:
- client_id: L'ID client della tua app ottenuto dopo aver registrato la tua app.
- redirect_uri: L'URI di reindirizzamento della tua app, il punto di reinserimento della tua app.
- scope: Gli scope richiesti che definiscono i permessi di accesso necessari per la tua app in un elenco separato da spazi.
- response_type: Impostalo su code per indicare il flusso di codice di autorizzazione.
Richiesto solo per PKCE
- code_challenge: La challenge generata da un code verifier.
- code_challenge_method: Imposta questo valore di parametro su S256 per indicare che la code challenge è stata trasformata utilizzando l'algoritmo SHA-256, il metodo di challenge più ampiamente supportato e sicuro.
- state: Un valore opaco e casuale sicuro per mantenere lo stato tra la richiesta e il callback.
Richiesto solo per non-PKCE
- client_secret: Il client secret della tua app ottenuto dopo aver registrato la tua app. Se stai utilizzando l'autenticazione con PKCE, ometti questo parametro. L'URL della tua richiesta di autorizzazione deve essere ben formattato, come nell'esempio seguente:
Esempio URL di Autorizzazione PKCE
Quando gli utenti visitano l'URL, vengono guidati attraverso il flusso di autorizzazione. Se ha successo, Roblox reindirizza l'utente all' redirect_uri specificato.
Gestire i callback di autorizzazione
Quando un flusso di autorizzazione ha successo, la tua app riceve una richiesta GET dal server di autorizzazione di Roblox all' redirect_uri che hai specificato. Nella richiesta, ricevi i parametri code (codice di autorizzazione) e state (se hai fornito un valore in precedenza).
Il parametro code contiene un codice di autorizzazione che l'app può scambiare per un access token dal server di autorizzazione. La maggior parte dei linguaggi di server backend ha modi standard per accedere ai parametri di query come oggetti decodificati. Dovrai ottenere il parametro code e usarlo per scambiare per access token.
Il parametro state è un valore opaco che hai inizialmente fornito nella richiesta di autorizzazione. Puoi usare questo parametro per mantenere lo stato o il contesto del processo di autorizzazione.
Ad esempio, potresti ricevere una richiesta GET con il seguente URL se hai specificato il tuo URI di reindirizzamento come https://example.com/redirect.
Esempio URL di Reindirizzamento
Se l'autorizzazione fallisce, la tua app riceve una richiesta GET all'URL di reindirizzamento specificato con i parametri error, error_description e state (se applicabile).
- Il parametro error indica il specifico errore OAuth 2.0 che si è verificato durante il processo di autorizzazione.
- Il parametro error_description fornisce ulteriori dettagli sull'errore.
- Il parametro state aiuta la tua app a mantenere lo stato in caso di un fallimento.
Scambiare un codice di autorizzazione per access token
Quando hai analizzato il code di autorizzazione, scambialo per token per accedere alle risorse desiderate di Roblox:
Richiedi un access token e un refresh token inviando una richiesta POST all' endpoint di scambio token. La richiesta deve includere il codice di autorizzazione, l'ID client e il valore del code verifier (PKCE) o client secret (non-PKCE) in formato x-www-form-urlencoded.
Analizza i token applicabili dalla risposta ricevuta. L'access token è valido per 15 minuti. Memorizza il refresh token in modo sicuro, tipicamente sul lato server, in modo da poterlo utilizzare per ottenere nuovi token in futuro.
Esempio Risposta Endpoint Token{"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.eyJzdWIiOiIyMDY3MjQzOTU5IiwibmFtZSI6ImxpbmtzZ29hdCIsIm5pZ2tuYW1lIjoibGlua3Nnb2F0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoibGlua3Nnb2F0IiwiY3JlYXRlZF9hdCI6MTYwNzM1NDIzMiwicHJvZmlsZSI6Imh0dHBzOi8vd3d3LnJvYmxveC5jb20vdXNlcnMvMjA2NzI0Mzk1OS9wcm9maWxlIiwib25nY2UiOiIxMjM0NSIsImp0aSI6IklELnltd3ZjTUdpOVg4azkyNm9qd1I5IiwibmJmIjoxNjkxNjM5Njk4LCJleHAiOjE2OTE2NzU2OTgsImlhdCI6MTY5MTYzOTY5OCwiaXNzIjoiaHR0cHM6Ly9hcGlzLnJvYmxveC5jb20vb2F1dGgvIiwiYXVkIjoiNzI5MDYxMDM5Nzk4NzkzNDk2NCJ9.kZgCMJQGsariwCi8HqsUadUBMM8ZOmf_IPDoWyQY9gVX4Kx3PubDz-Q6MvZ9eU5spNFz0-PEH-G2WSvq2ljDyg","scope": "openid profile"}
Effettuare una chiamata a un metodo risorsa
Ora che possiedi l'access token richiesto, puoi usarlo per effettuare chiamate autenticata ai metodi risorsa. Includi l'access token nell'intestazione di tutte le richieste API per autorizzarle.
Ad esempio, puoi testare se la tua app funziona correttamente passando attraverso l'intero flusso di autorizzazione e poi effettuando una richiesta GET all' endpoint delle informazioni sull'utente con un access token. Assicurati di avere gli scope openid o sia openid che profile prima di chiamare questo endpoint. Se ha successo, la risposta da quell' endpoint appare così:
Esempio Risposta Informazioni Utente
{
"sub": "12345678",
"name": "Jane Doe",
"nickname": "robloxjanedoe",
"preferred_username": "robloxjanedoe",
"created_at": 1607354232,
"profile": "https://www.roblox.com/users/12345678/profile"
}