Implementação de aplicativo OAuth 2.0

*Este conteúdo é traduzido por IA (Beta) e pode conter erros. Para ver a página em inglês, clique aqui.

O Open Cloud suporta o fluxo de autorização OAuth 2.0 com e sem PKCE, dependendo de 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 possa armazenar e recuperar segredos de forma segura em seu backend.
  • Clientes públicos são apps que não podem manter segredos, como aplicativos de navegador móvel e da web.

Recomendamos o fluxo de código de autorização OAuth 2.0 com PKCE para todos os clientes e exigimos isso para clientes públicos.

Para implementar o fluxo de código de autorização, seu aplicativo realiza os seguintes passos:

  1. Gerar um verificador de código e um desafio de código (PKCE apenas).Isso permite que você inclua um desafio em suas solicitações em vez do segredo do cliente, o que melhora a segurança.
  2. Envie um GET pedido de solicitação para o ponto de autorização com os parâmetros apropriados.
  3. Lidar com o retorno de chamadaautorização.Após obter autorização, use o código de autorização do Roblox em um pedido de redirecionamento para a URL que você especificou durante a criaçõesdo aplicativo.Analise o código de autorização para uso posterior.
  4. Envie um POST pedido de solicitação ao ponto de extremidade de token com o código de autorização.Se for bem-sucedido, você recebe tokens de acesso e atualização com os quais fazer chamadas de API.
  5. Chame qualquer API de Nuvem Aberta que suporte a 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 maior profundidade.

Gerar um desafio de código (apenas para PKCE)

Antes de iniciar o processo de autorização, você precisa gerar um desafio de código de um verificador de código.Você pode usar bibliotecas ou funções integradas na linguagem de programação de sua escolha para criar o verificador de código, calcular o hash e executar o código de codificação 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 um comprimento mínimo de 43 caracteres e um comprimento máximo 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.

Construir a URL de autorização

Para iniciar o processo de autorização do usuário, construa um 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 reentrada 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-o para 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 verificador de código.
  • code_challenge_method : Defina esse 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. 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 esse parâmetro.O URL da solicitação de autorização deve ser bem formatado, como no seguinte exemplo:
Exemplo de URL de autorização PKCE
https://apis.roblox.com/oauth/v1/authorize?client_id=7290610391231237934964

    &code_challenge=PLEKKVCjdD1V_07wOKlAm7P02NC-LZ_1hQfdu5XSXEI

    &code_challenge_method=S256

    &redirect_uri=https://example.com/redirect

    &scope=openid%20profile

    &response_type=code

    &state=abc123

Quando os usuários visitam o URL, eles são levados através do fluxo de autorização. Se for bem-sucedido, o Roblox redireciona o usuário para o especificado redirect_uri.

Lidar com chamadas de autorização

Quando um fluxo de autorização é bem-sucedido, seu aplicativo recebe um pedido de GET solicitação 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 state (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 idiomas de servidor de back-end tem maneiras padrão de acessar os 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ê inicialmente forneceu na solicitar / pedirde autorização.Você pode usar esse parâmetro para manter o estado ou o contexto do processo de autorização.

Por exemplo, você pode receber um pedido GET com a seguinte URL se especificar que sua URI de redirecionamento seja https://example.com/redirect.

Exemplo de URL de redirecionamento
https://example.com/redirect?code=10c45PNuquKnFJ6pUcy5-fHkghEM6lSegm-7hj9mVEprub1dSDuStuKK_EAUXY7AHTD63xcnmvxSLthp-C8g3jzIGZVzuXSd20Y2dEYI9hx0LZmPg95ME4z2K03UheiZbroyXUjYyB3ReoMqobzDVPzyx6IS8kj2Uu-11Xq_0JiTYxtDatuqXRNIAmJT8gMJmbSyOLOP_vnDvbeMUiBsqCRrkTGVbWSwYSc8sTVVE-535kYdqQOgNjH1ffCoZLGl8YYxLnpb2CXJlRQPrcjkA&state=6789

Se a autorização falhar, o seu aplicativo recebe um pedido de GET solicitação 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 do erro.
  • O parâmetro state ajuda o seu aplicativo a manter o estado no caso de um falha.

Trocar um código de autorização por tokens de acesso

Quando você tiver analisado a autorização code, troque-a por tokens para acessar recursos do Roblox desejados:

  1. Solicite um token de acesso e um token de atualização enviando um pedido POST de token de troca de token.O pedido deve incluir o código de autorização, o ID do cliente e o valor do verificador de código (PKCE) ou do segredo do cliente (não-PKCE) no formato x-www-form-urlencoded.

  2. Analise os tokens aplicáveis na resposta recebida.O token de acesso é válido por 15 minutos.Guarde o token de atualização de forma segura, geralmente no lado do servidor, para que você possa usá-lo para obter novos tokens no futuro.

    Resposta de Endpoint de Token de Exemplo
    {

      "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"

    }

Faça uma chamada para um método de recurso

Agora que você tem o token de acesso necessário, você pode usá-lo para fazer chamadas autenticadas a 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 o seu aplicativo funciona corretamente atravessando todo o fluxo de autorização e depois fazendo um pedido ao ponto de informação do usuário com um token de acesso.Certifique-se de ter o openid ou ambos os âmbitos openid e profile antes de chamar este endpoint.Se for bem-sucedido, a resposta desse endpoint parece com isso:

Resposta de Informação de Usuário de Exemplo
{

  "sub": "12345678",

  "name": "Jane Doe",

  "nickname": "robloxjanedoe",

  "preferred_username": "robloxjanedoe",

  "created_at": 1607354232,

  "profile": "https://www.roblox.com/usuários/12345678/perfil"

}