O 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 credenciais confidenciais, como um site que pode armazenar e recuperar segredos em seu back-end com segurança.
- Clientes públicos são aplicativos que não podem manter segredos, como aplicativos de celular e navegador da web.
Recomendamos o fluxo de autorização OAuth 2.0 com PKCE para todos os clientes todos e exigimos para clientes públicos.
Armazene o segredo do cliente em um lugar seguro e nunca o expouse ao público. Os atores maliciosos podem usá-lo para imitar sua aplicação.
Para implementar o fluxo de código de autorização, seu aplicativo executa os seguintes passos:
- Gerar um verificador de código e desafio de código (somente PKCE). Isso permite que você inclua um desafio em suas solicitações, em vez do segredo do cliente, o que melhora a segurança.
- Envie uma solicitação GET para o ponto de autorização com os parâmetros apropriados.
- Gerencie o retorno de chamada de autorização. Depois de obter a autorização, use o código de autorização do Roblox em uma solicitação de direcionamento para a URL que você especificou durante a criaçõesdo aplicativo. Processar o código de autorização para uso posterior.
- Envie uma solicitação de POST ao Token Endpoint com o código de autorização. Se bem-sucedido, você recebe acesso e atualiza tokens com quais fazer chamadas de API.
- Chame qualquer API de Nuvem Aberta que suporte autenticação OAuth 2.0 com base na documentação de referência para os recursos que você deseja acesso.
As seções a seguir descrevem cada etapa em mais profundidade.
Gerando um Desafio de Código (somente para PKCE)
Antes de iniciar o processo de autorização, você precisa gerar um desafio de código a partir de um verificador de código. Você pode usar bibliotecas ou funções incorporadas na linguagem de programação de sua escolha para criar o desafio de código, calcular o hash e executar o encriptamento Base64 para gerar o desafio de código.
Ao criar o verificador de código, 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 tilde (~), com uma long度 mínima de 43 caracteres e uma long度 máxima de 128 caracteres.
O seguinte exemplo mostra como usar Javascript para criar um verificador de código e gerar o desafio de código usando o algoritmo de hashing SHA-256:
Generate Code Challenge
const crypto = require('crypto');
// base64URL encode the verifier and challenge
function base64URLEncode(str) {
return str.toString('base64')
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=/g, '');
}
// create sha256 hash from code verifier
function sha256(buffer) {
return crypto.createHash('sha256').update(buffer).digest(`base64`);
// create a random code verifier
var code_verifier = base64URLEncode(crypto.randomBytes(32));
// generate a challenge from the code verifier
var code_challenge = base64URLEncode(sha256(code_verifier));
Para PKCE, você precisa tanto do verificador de código quanto dos valores de desafio em etapas posteriores.
Construindo a URL de Autorização
Veja a documentação do ponto de autorização para obter 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 da sua aplicativoé obtido após o registro de sua aplicação.
- redirect_uri : A URL de redirecionamento de sua aplicativo, o ponto de entrada de novo da sua aplicativo.
- scope : Os scopes solicitados que definem as permissões de acesso que seu aplicativo precisa em uma lista separada por espaço.
- response_type : Definido para code para indicar o fluxo de autorização. Requer apenas para PKCE
- code_challenge : O desafio de código gerado a partir de um verificador de código.
- code_challenge_method : Defina este valor de parâmetro para 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 aleatório opaco e seguro para manter o estado entre a solicitação e o retorno de chamada. Requerido apenas para não-PKCE
- client_secret : O segredo do cliente da sua aplicativoobtido após o registro de sua aplicação. Se você estiver usando autenticação com PKCE, omita este parâmetro. A URL de solicitação de autorização deve ser bem formatada, como na seguinte exemplo:
Exemplo de URL de Autorização PKCE
Quando os usuários visitam o URL, eles são levados através do fluxo de autorização. Se tiver sucesso, o Roblox redireciona o usuário para o redirect_uri especificado.
Gerenciando Autorizações
Quando um fluxo de autorização é bem-sucedido, sua aplicação recebe uma solicitação GET do servidor de autorização do Roblox na redirect_uri que você especificou. Na solicitar / pedir, você recebe code (código de autorização) e 1> state1> (se você forneceu um valor anteriormente) 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 dos linguagens de back-end têm maneiras padrão de acessar parâmetros de consulta como objetos de descompilação. 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ê inicialmente forneceu na solicitar / pedirde 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 solicitação GET com a seguinte URL se você especificou sua URL de redirecionamento para ser https://example.com/redirect.
Exemplo de URL de Redirecionamento
Se a autorização falhar, seu aplicativo recebe uma solicitação de GET para a URL de redirecionamento especificada com o error, error_description e 2> state2> (se Aplicável) parâmetros.
- 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 do erro.
- O parâmetro state ajuda seu aplicativo a manter o estado no caso de um falha.
Exchange um código de autorização por tokens de acesso
Quando você analisou a autorização code, troque-a por tokens para acessar recursos desejados do Roblox:
Pedir um token de acesso e atualizar um token ao enviar uma solicitação POST para o token exchange endpoint. A solicitação deve incluir o código de autorização, ID do cliente e o valor do verificador de código (PKCE) ou secreto do cliente em x-www-form-urlencoded formato.
Analise os tokens aplicáveis na resposta recebida. O token de acesso é válido por 15 minutos. Armazene o token de atualização com segurança, geralmente no lado do servidor, para que você possa usá-lo para obter novos tokens no futuro.
Exemplo de Resposta de Ponto de Termo 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.eyJzdWIiOiIyMDY3MjQzOTU5IiwibmFtZSI6ImxpbmtzZ29hdCIsIm5pY2tuYW1lIjoibGlua3Nnb2F0IiwicHJlZmVycmVkX3VzZXJuYW1lIjoibGlua3Nnb2F0IiwiY3JlYXRlZF9hdCI6MTYwNzM1NDIzMiwicHJvZmlsZSI6Imh0dHBzOi8vd3d3LnJvYmxveC5jb20vdXNlcnMvMjA2NzI0Mzk1OS9wcm9maWxlIiwibm9uY2UiOiIxMjM0NSIsImp0aSI6IklELnltd3ZjTUdpOVg4azkyNm9qd1I5IiwibmJmIjoxNjkxNjM5Njk4LCJleHAiOjE2OTE2NzU2OTgsImlhdCI6MTY5MTYzOTY5OCwiaXNzIjoiaHR0cHM6Ly9hcGlzLnJvYmxveC5jb20vb2F1dGgvIiwiYXVkIjoiNzI5MDYxMDM5Nzk4NzkzNDk2NCJ9.kZgCMJQGsariwCi8HqsUadUBMM8ZOmf_IPDoWyQY9gVX4Kx3PubDz-Q6MvZ9eU5spNFz0-PEH-G2WSvq2ljDyg","scope": "openid profile"}
Fazendo uma chamada para um método de recursos
Agora que você tem o token de acesso necessário, você pode usá-lo para fazer chamadas autenticadas para métodos de recursos. Inclua o token de acesso no cabeçalho de todas as solicitações de API para autorizá-las.
Por exemplo, você pode testar se sua aplicação funciona corretamente ao passar por todo o fluxo de autorização e, em seguida, fazer uma solicitação GET para o user information endpoint com um token de acesso. Certifique-se de que você tem o openid ou ambos os 2>openid2> e 5>
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"
}