Open Cloud suporta o fluxo de autorização OAuth 2.0 com e sem PKCE, dependendo se seus clientes são confidenciais ou públicos.
- Clientes confidenciais são aplicativos que são capazes de manter as credenciais em sigilo, como um site que pode armazenar e recuperar segredos com segurança em seu backend.
- Clientes públicos são aplicativos que não podem manter segredos, como aplicativos móveis e de navegador web.
Recomendamos o fluxo de código de autorização OAuth 2.0 com PKCE para todos os clientes e o exigimos para clientes públicos.
Armazene o segredo do cliente em um local seguro e nunca o exponha ao público. Agentes mal-intencionados podem usá-lo para se passar pela sua aplicação.
Para implementar o fluxo de código de autorização, seu aplicativo realiza os seguintes passos:
- Gere um código de verificação e um desafio de código (apenas PKCE). Isso permite que você inclua um desafio em suas requisições em vez do segredo do cliente, o que melhora a segurança.
- Envie uma requisição GET para o ponto de extremidade de autorização com os parâmetros apropriados.
- Trate o callback de autorização. Após obter a autorização, use o código de autorização da Roblox em uma requisição de redirecionamento para a URL que você especificou durante a criação do aplicativo. Analise o código de autorização para uso posterior.
- Envie uma requisição POST para o ponto de extremidade de token com o código de autorização. Se for bem-sucedido, você receberá tokens de acesso e de atualização com os quais poderá fazer chamadas de API.
- Chame qualquer API Open Cloud que suporte autenticação OAuth 2.0 com base na documentação de referência para os recursos que você deseja acessar.
As seções a seguir descrevem cada passo em maior profundidade.
Gere um desafio de código (apenas para PKCE)
Antes de iniciar o processo de autorização, você precisa gerar um desafio de código a partir de um código de verificação. Você pode usar bibliotecas ou funções integradas na linguagem de programação de sua escolha para criar o código de verificação, calcular o hash e realizar a codificação Base64 para gerar o desafio de código.
Ao criar o código de verificação, use apenas caracteres não reservados, incluindo letras maiúsculas e minúsculas (A-Z, a-z), dígitos decimais (0-9), hífen (-), ponto (.), sublinhado (_) e til (~), com um comprimento mínimo de 43 caracteres e um comprimento máximo de 128 caracteres.
O exemplo a seguir mostra como usar Javascript para criar um código de verificação e gerar o desafio de código usando o algoritmo de hash SHA-256:
Gerar Desafio de Código
const crypto = require('crypto');
// codifique em base64URL o verificador e o desafio
function base64URLEncode(str) {
return str.toString('base64')
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=/g, '');
}
// crie um hash sha256 a partir do código de verificação
function sha256(buffer) {
return crypto.createHash('sha256').update(buffer).digest(`base64`);
}
// crie um código de verificação aleatório
var code_verifier = base64URLEncode(crypto.randomBytes(32));
// gere um desafio a partir do código de verificação
var code_challenge = base64URLEncode(sha256(code_verifier));
Para PKCE, você precisará tanto do código de verificação quanto dos valores de desafio nas etapas seguintes.
Construa a URL de autorização
Consulte a documentação de referência do ponto de extremidade de autorização para informações completas sobre como construir a URL de autorização.
Para iniciar o processo de autorização do usuário, construa uma URL de autorização com os parâmetros necessários:
- client_id: O ID do cliente do seu aplicativo obtido após registrar seu aplicativo.
- redirect_uri: A URI de redirecionamento do seu aplicativo, o ponto de re-entrada do seu aplicativo.
- scope: Os escopos solicitados que definem as permissões de acesso que seu aplicativo precisa em uma lista separada por espaço.
- response_type: Defina como code para indicar o fluxo de código de autorização.
Necessário apenas para PKCE
- code_challenge: O desafio de código gerado a partir de um código de verificação.
- code_challenge_method: Defina o valor deste parâmetro como S256 para indicar que o desafio de código foi transformado usando o algoritmo SHA-256, o método de desafio de código mais amplamente suportado e seguro.
- state: Um valor opaco e aleatório seguro para manter o estado entre a requisição e o callback.
Necessário apenas para não-PKCE
- client_secret: O segredo do cliente do seu aplicativo obtido após registrar seu aplicativo. Se você estiver usando autenticação com PKCE, omita este parâmetro. Sua URL de requisição de autorização deve estar bem formatada, como no seguinte exemplo:
Exemplo de URL de Autorização PKCE
Quando os usuários acessam a URL, eles são levados pelo fluxo de autorização. Se for bem-sucedido, a Roblox redireciona o usuário para a redirect_uri especificada.
Trate os callbacks de autorização
Quando um fluxo de autorização é bem-sucedido, seu aplicativo recebe uma requisição GET do servidor de autorização da Roblox na redirect_uri que você especificou. Na requisição, você recebe code (código de autorização) e state (se você forneceu um valor anteriormente) como parâmetros.
O parâmetro code contém um código de autorização que o aplicativo pode trocar por um token de acesso do servidor de autorização. A maioria das linguagens de servidor backend tem maneiras padrão de acessar parâmetros de consulta como objetos decodificados. Você precisará obter o parâmetro code e usá-lo para trocar por tokens de acesso.
O parâmetro state é um valor opaco que você forneceu inicialmente na requisição de autorização. Você pode usar este parâmetro para manter o estado ou contexto do processo de autorização.
Por exemplo, você pode receber uma requisição GET com a seguinte URL se você especificou sua URI de redirecionamento como https://example.com/redirect.
Exemplo de URL de Redirecionamento
Se a autorização falhar, seu aplicativo recebe uma requisição GET para a URL de redirecionamento especificada com os parâmetros error, error_description e state (se aplicável).
- O parâmetro error indica o erro específico do OAuth 2.0 que ocorreu durante o processo de autorização.
- O parâmetro error_description fornece detalhes adicionais sobre o erro.
- O parâmetro state ajuda seu aplicativo a manter o estado em caso de falha.
Troque um código de autorização por tokens de acesso
Quando você tiver analisado o code de autorização, troque-o por tokens para acessar os recursos da Roblox desejados:
Solicite um token de acesso e um token de atualização enviando uma requisição POST para o ponto de extremidade de troca de token. A requisição deve incluir o código de autorização, ID do cliente e o valor do código de verificação (PKCE) ou segredo do cliente (não-PKCE) no formato x-www-form-urlencoded.
Analise os tokens aplicáveis da resposta recebida. O token de acesso é válido por 15 minutos. Armazene o token de atualização com segurança, tipicamente no lado do servidor, para que você possa usá-lo para obter novos tokens no futuro.
Exemplo de Resposta do Ponto de Extremidade 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.eyJzdWIiOiIyMDY3MjQzOTU5IiwibmFtZSI6ImxpbmtzZ29hdCIsIm5pZ2tuYW1lIjoibGlua3Nnb2F0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoibGlua3Nnb2F0IiwiY3JlYXRlZF9hdCI6MTYwNzM1NDIzMiwicHJvZmlsZSI6Imh0dHBzOi8vd3d3LnJvYmxveC5jb20vdXNlcnMvMjA2NzI0Mzk1OS9wcm9maWxlIiwib25jZWUiOiIxMjM0NSIsImp0aSI6IklELnltd3ZjTUdpOVg4azkyNm9qd1I5IiwibmJmIjoxNjkxNjM5Njk4LCJleHAiOjE2OTE2NzU2OTgsImlhdCI6MTY5MTYzOTY5OCwiaXNzIjoiaHR0cHM6Ly9hcGlzLnJvYmxveC5jb20vb2F1dGgvIiwiYXVkIjoiNzI5MDYxMDM5Nzk4NzkzNDk2NCJ9.kZgCMJQGsariwCi8HqsUadUBMM8ZOmf_IPDoWyQY9gVX4Kx3PubDz-Q6MvZ9eU5spNFz0-PEH-G2WSvq2ljDyg","scope": "openid profile"}
Faça uma chamada para um método de recurso
Agora que você tem o token de acesso necessário, pode usá-lo para fazer chamadas autenticadas para métodos de recurso. Inclua o token de acesso no cabeçalho de todas as requisições de API para autorizá-las.
Por exemplo, você pode testar se seu aplicativo funciona corretamente passando por todo o fluxo de autorização e, em seguida, fazendo uma requisição GET para o ponto de extremidade de informação do usuário com um token de acesso. Certifique-se de ter o escopo openid ou ambos os escopos openid e profile antes de chamar este ponto de extremidade. Se for bem-sucedido, a resposta daquele ponto de extremidade se parecerá com isto:
Exemplo de Resposta de Informação do Usuário
{
"sub": "12345678",
"name": "Jane Doe",
"nickname": "robloxjanedoe",
"preferred_username": "robloxjanedoe",
"created_at": 1607354232,
"profile": "https://www.roblox.com/users/12345678/profile"
}