Open Cloud admite el flujo de autorización OAuth 2.0 con y sin PKCE, dependiendo de si sus clientes son confidenciales o públicos.
- Clientes confidenciales son aplicaciones que son capaces de mantener las credenciales en secreto, como un sitio web que puede almacenar y recuperar secretos de manera segura en su backend.
- Clientes públicos son aplicaciones que no pueden mantener secretos, como aplicaciones móviles y de navegador web.
Recomendamos el flujo de código de autorización OAuth 2.0 con PKCE para todos los clientes y lo requerimos para los clientes públicos.
Almacene el secreto del cliente en un lugar seguro y nunca lo exponga al público. Los actores malintencionados pueden usarlo para suplantar su aplicación.
Para implementar el flujo de código de autorización, su aplicación realiza los siguientes pasos:
- Generar un verificador de código y un desafío de código (solo PKCE). Esto le permite incluir un desafío en sus solicitudes en lugar del secreto del cliente, lo que mejora la seguridad.
- Enviar una solicitud GET al endpoint de autorización con los parámetros apropiados.
- Manejar la callback de autorización. Después de obtener la autorización, use el código de autorización de Roblox en una solicitud de redirección a la URL que especificó durante la creación de la aplicación. Analice el código de autorización para su uso posterior.
- Enviar una solicitud POST al endpoint de token con el código de autorización. Si tiene éxito, recibirá tokens de acceso y actualización con los que realizar llamadas a la API.
- Llamar a cualquier API de Open Cloud que admita autenticación OAuth 2.0 según la documentación de referencia para los recursos que desea acceder.
Las siguientes secciones describen cada paso con mayor profundidad.
Generar un desafío de código (solo para PKCE)
Antes de iniciar el proceso de autorización, necesita generar un desafío de código a partir de un verificador de código. Puede usar bibliotecas o funciones incorporadas en el lenguaje de programación de su elección para crear el verificador de código, calcular el hash y realizar una codificación Base64 para generar el desafío de código.
Al crear el verificador de código, use solo caracteres no reservados, incluidos letras mayúsculas y minúsculas (A-Z, a-z), dígitos decimales (0-9), guiones (-), puntos (.), guiones bajos (_) y tildes (~), con una longitud mínima de 43 caracteres y una longitud máxima de 128 caracteres.
El siguiente ejemplo muestra cómo usar Javascript para crear un verificador de código y generar el desafío de código utilizando el algoritmo hash SHA-256:
Generar Desafío de Código
const crypto = require('crypto');
// codificación base64URL del verificador y desafío
function base64URLEncode(str) {
return str.toString('base64')
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=/g, '');
}
// crear hash sha256 a partir del verificador de código
function sha256(buffer) {
return crypto.createHash('sha256').update(buffer).digest(`base64`);
}
// crear un verificador de código aleatorio
var code_verifier = base64URLEncode(crypto.randomBytes(32));
// generar un desafío a partir del verificador de código
var code_challenge = base64URLEncode(sha256(code_verifier));
Para PKCE, necesita tanto los valores de verificador de código como de desafío en pasos posteriores.
Construir la URL de autorización
Consulte la documentación de referencia del endpoint de autorización para obtener información detallada sobre cómo construir la URL de autorización.
Para iniciar el proceso de autorización del usuario, construya una URL de autorización con los parámetros requeridos:
- client_id: El ID de cliente de su aplicación obtenido después de registrar su aplicación.
- redirect_uri: La URI de redirección de su aplicación, el punto de reentrada de su aplicación.
- scope: Los ámbitos solicitados que definen los permisos de acceso que su aplicación necesita en una lista separada por espacios.
- response_type: Establecerlo en code para indicar el flujo de código de autorización.
Requerido solo para PKCE
- code_challenge: El desafío de código generado a partir de un verificador de código.
- code_challenge_method: Establezca este valor de parámetro en S256 para indicar que el desafío de código se transformó utilizando el algoritmo SHA-256, el método de desafío de código más ampliamente admitido y seguro.
- state: Un valor aleatorio y opaco para mantener el estado entre la solicitud y la callback.
Requerido solo para no-PKCE
- client_secret: El secreto de cliente de su aplicación obtenido después de registrar su aplicación. Si está utilizando autenticación con PKCE, omita este parámetro. Su URL de solicitud de autorización debe estar bien formateada, como en el siguiente ejemplo:
Ejemplo de URL de Autorización PKCE
Cuando los usuarios visiten la URL, se les llevará a través del flujo de autorización. Si tiene éxito, Roblox redirige al usuario a la redirect_uri especificada.
Manejar las callbacks de autorización
Cuando un flujo de autorización es exitoso, su aplicación recibe una solicitud GET del servidor de autorización de Roblox en la redirect_uri que usted especificó. En la solicitud, recibe code (código de autorización) y state (si proporcionó un valor anteriormente) como parámetros.
El parámetro code contiene un código de autorización que la aplicación puede intercambiar por un token de acceso del servidor de autorización. La mayoría de los lenguajes de servidor permiten acceder a parámetros de consulta como objetos decodificados de manera estándar. Necesitará obtener el parámetro code y usarlo para intercambiar por tokens de acceso.
El parámetro state es un valor opaco que inicialmente proporcionó en la solicitud de autorización. Puede usar este parámetro para mantener el estado o contexto del proceso de autorización.
Por ejemplo, puede recibir una solicitud GET con la siguiente URL si especificó que su URI de redirección es https://example.com/redirect.
Ejemplo de URL de Redirección
Si la autorización falla, su aplicación recibe una solicitud GET a la URL de redirección especificada con los parámetros error, error_description y state (si corresponde).
- El parámetro error indica el error específico de OAuth 2.0 que ocurrió durante el proceso de autorización.
- El parámetro error_description proporciona detalles adicionales del error.
- El parámetro state ayuda a su aplicación a mantener el estado en caso de un fracaso.
Intercambiar un código de autorización por tokens de acceso
Cuando haya analizado el code de autorización, intercámbielo por tokens para acceder a los recursos de Roblox deseados:
Solicite un token de acceso y un token de actualización enviando una solicitud POST al endpoint de intercambio de tokens. La solicitud debe incluir el código de autorización, el ID de cliente y el valor del verificador de código (PKCE) o el secreto del cliente (no-PKCE) en formato x-www-form-urlencoded.
Analice los tokens aplicables de la respuesta recibida. El token de acceso es válido por 15 minutos. Almacene el token de actualización de forma segura, típicamente en el lado del servidor, para que pueda usarlo para obtener nuevos tokens en el futuro.
Ejemplo de Respuesta del Endpoint de 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.eyJzdWIiOiIyMDY3MjQzOTU5IiwibmFtZSI6ImxpbmtzZ29hdCIsIm5pY2tuYW1lIjoibGlua3Nnb2F0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoibGlua3Nnb2F0IiwiY3JlYXRlZF9hdCI6MTYwNzM1NDIzMiwicHJvZmlsZSI6Imh0dHBzOi8vd3d3LnJvYmxveC5jb20vdXNlcnMvMjA2NzI0Mzk1OS9wcm9maWxlIiwibm9uY2UiOiIxMjM0NSIsImp0aSI6IklELnltd3ZjTUdpOVg4azkyNm9qd1I5IiwibmJmIjoxNjkxNjM5Njk4LCJleHAiOjE2OTE2NzU2OTgsImlhdCI6MTY5MTYzOTY5OCwiaXNzIjoiaHR0cHM6Ly9hcGlzLnJvYmxoveC5jb20vb2F1dGgvIiwiYXVkIjoiNzI5MDYxMDM5Nzk4NzkzNDk2NCJ9.kZgCMJQGsariwCi8HqsUadUBMM8ZOmf_IPDoWyQY9gVX4Kx3PubDz-Q6MvZ9eU5spNFz0-PEH-G2WSvq2ljDyg","scope": "openid profile"}
Realizar una llamada a un método de recurso
Ahora que tiene el token de acceso requerido, puede usarlo para realizar llamadas autenticadas a los métodos de recursos. Incluya el token de acceso en el encabezado de todas las solicitudes a la API para autorizarlas.
Por ejemplo, puede probar si su aplicación funciona correctamente pasando por todo el flujo de autorización y luego realizando una solicitud GET al endpoint de información del usuario con un token de acceso. Asegúrese de tener los ámbitos openid o tanto openid como profile antes de llamar a este endpoint. Si tiene éxito, la respuesta de ese endpoint se verá así:
Ejemplo de Respuesta de Información del Usuario
{
"sub": "12345678",
"name": "Jane Doe",
"nickname": "robloxjanedoe",
"preferred_username": "robloxjanedoe",
"created_at": 1607354232,
"profile": "https://www.roblox.com/users/12345678/profile"
}