OAuth 2.0 Noções Básicas

Table of Contents

Prefácio

Este documento é um tutorial para descrever o uso básico de Authlete APIs a fim de implementar o servidor de autorização OAuth 2.0 que suporta o fluxo de concessão de código de autorização.

Componentes

Neste tutorial, assumimos os seguintes componentes. Observe que apenas os consoles e APIs da Authlete estão funcionando, enquanto um servidor de autorização e um servidor de recursos realmente não existem.

Em vez disso, você usará o comando curl para simular como esses servidores fazem solicitações de API para Authlete ao receber solicitações de autorização, solicitações de token e solicitações de introspecção de tokens de clientes.

AS FODNs para cada componente são as seguintes. O servidor de autorização e o cliente não existem como indicado acima, mas suas FQDNs são pelo menos necessárias para explicar o fluxo OAuth.

Component FQDN
Authlete API api.authlete.com
Authlete Service Owner console so.authlete.com
Authlete Developer console cd.authlete.com
Servidor de Autorização as.example.com
Cliente client.example.org
Resource server N/A

Configuração do ambiente

Consulte as instruções “Inscreva-se na Authlete e criando um serviço” para criar um novo serviço de API Authlete e cadastrar um cliente no serviço.

Neste tutorial, assumimos que as seguintes propriedades são geradas ou especificadas.

Item Valor
ID do cliente Auto-generetad, por exemplo. 12818600553323
segredo do client Gerado automaticamente, por exemplo. -olDIKD9BihRfB8O1JxobUEKBZ7PIV5Z6oaqxAshmoUtUZgB-wjmmxTYDiDV6vM_Mgl267PeNrRftq8cWplvmg
Tipo de cliente CONFIDENTIAL
Redirecionar uris https://client.example.org/cb/example.com
Método de autenticação do cliente CLIENT_SECRET_BASIC

Vamos tentar o fluxo de concessão de código de autorização usando este ambiente, na próxima seção.

Passo a passo

Aqui está um diagrama de sequência neste tutorial. Os números de mensagens no diagrama podem ajudá-lo a entender os seguintes passos.

<figure class=“figure bg-transparent border-0”>

Solicitação de autorização do cliente ao servidor de autorização

O cliente faz uma solicitação de autorização ao servidor de autorização via agente de usuário (mensagem nº 2, nº 3). Neste tutorial, vamos supor que os seguintes valores são especificados como paramters na solicitação.

de itens Valor
client_id 12818600553323
response_type code
redirect_uri https://client.example.org/cb/example.com

O servidor de autorização deve receber o seguinte conteúdo (dobrado para legibilidade) como sequência de consulta HTTP GET do agente de usuário.

redirect_uri=https://client.example.org/cb/example.com
 &response_type=code
 &client_id=12818600553323

O servidor de autorização deve avaliar esses parâmetros por si só. As regras típicas de avaliação são mostradas abaixo. Depois disso, o servidor de autorização vai processar o fluxo de concessão de código de autorização, uma vez que o valor de response_type É code.

  • Se um cliente associado ao ID do cliente 12818600553323 foi registrado no servidor de autorização
  • Se o valor do redirecionamento uri https://client.example.org/cb/example.com partidas com um dos URIs registrados para o cliente
  • Se valores de outros parâmetros, como response_type, scope são aplicáveis para o cliente, ou seja, permitido para o cliente especificar em sua solicitação

Authlete /auth/authorization A API faz o processo de avaliação em nome do servidor de autorização. Vamos fazer uma solicitação a esta API atuando como o servidor de autorização.

For Linux/Mac, execute curl command as follows (message #4). Make sure to replace API Key, API Secret, Client ID by your own values generated in the previous step.

curl -s -X POST https://api.authlete.com/api/auth/authorization \
-u '<API Key e.g. 10738933707579>:<API Secret e.g. Xg6jVpJCvsaXvy2ks8R5WzjdMYlvQqOym3slDX0wNhQ>' \
-H 'Content-Type: application/json' \
-d '{ "parameters": "redirect_uri=https://client.example.org/cb/example.com&response_type=code&client_id=<Client ID e.g. 12818600553323>" }'

If you are using Windows 10's bundled curl.exe command via PowerShell, make sure the command is curl.exe instead of curl, escape " characters and use ` to break lines. (message #4). Make sure to replace API Key, API Secret, Client ID by your own values generated in the previous step.

curl.exe -s -X POST https://api.authlete.com/api/auth/authorization `
-u '<API Key e.g. 10723797812772>:<API Secret e.g. ekYoYTI84qZcpe6bXGzDwduQ1fGBYxJT8K8Tnwd7poc>' `
-H 'Content-Type: application/json' `
-d '{\"parameters\" : \"redirect_uri=https://client.example.org/cb/example.com&response_type=code&client_id=<Client ID e.g. 12800697055611>\"}'

Se a solicitação for apropriada, Authlete faz a seguinte resposta (omitida para brevidade) (mensagem #5).

{
   "resultMessage" : "[A004001] Authlete has successfully issued a ticket to the service (API Key = 10738933707579) for the authorization request from the client (ID = 12818600553323). [response_type=code, openid=false]",
   "type" : "authorizationResponse",
   "resultCode" : "A004001",
   "client" : { [...] },
   "ticket" : "cA0xUty6I64PnFTjer2g-iM5KIfGpssUHqkfDoMr0xk",
   "action" : "INTERACTION",
   [...]
   "service" : {
      [...]
      "supportedClaims" : [
         [...]
      ],
      "supportedScopes" : [
         [...]
      ],
   }
}

Preste atenção a três pares de teclas/valores na resposta; resultMessage, action e ticket.

{
   [...]
   "ticket" : "cA0xUty6I64PnFTjer2g-iM5KIfGpssUHqkfDoMr0xk",
   "action" : "INTERACTION",
   "resultMessage" : "[A004001] Authlete has successfully issued a ticket to the service (API Key = 10738933707579) for the authorization request from the client (ID = 12818600553323). [response_type=code, openid=false]",
  • resultMessage fornece resultado legível por humanos do processamento da solicitação. (Veja também Interpretando os códigos de resultado da Authlete)
  • action indica o que o servidor de autorização deve fazer em seguida.
  • ticket é necessário que o servidor de autorização faça uma solicitação a outra API na próxima etapa.

A Authlete também fornece informações de serviço e cliente na resposta. O servidor de autorização os utiliza para perguntar ao proprietário do recurso se ele ou ela autoriza o acesso do cliente ao serviço.

Autenticação e confirmação do usuário de concessão de acesso

A interação real entre o proprietário do recurso e o servidor de autorização está fora de alcance neste tutorial. Na maioria dos casos, o servidor de autorização autenticaria o usuário com algumas credenciais (por exemplo, ID/senha), determinaria funções e privilégios para o usuário e perguntaria ao usuário se ele ou ela autoriza o acesso (mensagem nº 6, #7).

Emissão de um código de autorização

Vamos supor que o servidor de auhtorização atinja o seguinte estado após a conclusão do processo anterior:

  • O servidor de autorização autenticou o proprietário do recurso, e determinou que um identificador para o proprietário do recurso, seja compartilhado com Authlete como um valor de subject parâmetro, é testuser01.
  • O servidor de autorização recebeu o consentimento do proprietário do recurso.

O servidor de autorização faz uma solicitação para Authlete /auth/authorization/issue para emissão de um código de autorização. Ele especifica valores de subject e ticket que eram uma parte da resposta de /auth/authorization API, como parâmetros de solicitação.

Execute curl command as follows (message #8). Make sure to replace API Key, API Secret, Ticket by your own values generated in the previous steps.

curl -s -X POST https://api.authlete.com/api/auth/authorization/issue \
-u '<API Key e.g. 10723797812772>:<API Secret e.g. ekYoYTI84qZcpe6bXGzDwduQ1fGBYxJT8K8Tnwd7poc>' \
-H 'Content-Type: application/json' \
-d '{ "ticket": "<Ticket e.g. bi2Kxe2WW5mK_GZ_fDFOpK1bnY6xTy40Ap_8nxf-7AU>", "subject": "testuser01" }'

Execute curl.exe as follows (message #8). Make sure to replace API Key, API Secret, Ticket by your own values generated in the previous steps.

curl.exe -s -X POST https://api.authlete.com/api/auth/authorization/issue `
-u '<API Key e.g. 10723797812772>:<API Secret e.g. ekYoYTI84qZcpe6bXGzDwduQ1fGBYxJT8K8Tnwd7poc>' `
-H 'Content-Type: application/json' `
-d '{ \"ticket\": \"<Ticket e.g. bi2Kxe2WW5mK_GZ_fDFOpK1bnY6xTy40Ap_8nxf-7AU>\", \"subject\": \"testuser01\" }'

Se a solicitação for apropriada, Authlete faz a seguinte resposta (mensagem #9).

{
   "responseContent" : "https://client.example.org/cb/example.com?code=3GIJORjvgaEdu2u4KHyaQdGxfHDFsiViwGyZUxeBVrM",
   "authorizationCode" : "3GIJORjvgaEdu2u4KHyaQdGxfHDFsiViwGyZUxeBVrM",
   "action" : "LOCATION",
   "accessTokenDuration" : 0,
   "resultMessage" : "[A040001] The authorization request was processed successfully.",
   "type" : "authorizationIssueResponse",
   "resultCode" : "A040001",
   "accessTokenExpiresAt" : 0
}

Preste atenção a três pares de teclas/valores na resposta; resultMessage, action e responseContent.

  • resultMessage fornece resultado legível por humanos do processamento da solicitação. (Veja também Interpretando os códigos de resultado da Authlete)
  • action indica o que o servidor de autorização deve fazer em seguida. O valor nesta resposta é LOCATION, o que significa que o servidor de autorização deve fazer uma resposta de redirecionamento de volta ao agente do usuário.
  • responseContent é suposto ser o conteúdo da resposta do servidor de autorização.

Espera-se que o servidor de autorização faça a seguinte resposta (dobrada para legibilidade) ao agente do usuário (mensagem nº 10).

HTTP/1.1 302 Found
Location: https://client.example.org/cb/example.com
 ?code=3GIJORjvgaEdu2u4KHyaQdGxfHDFsiViwGyZUxeBVrM

Seria outro caso em que o servidor de autorização determina que ele não vai emitir tokens para o cliente devido ao resultado do autenticação e confirmação anteriores. Nessa situação, o servidor de autorização tem que dizer ao cliente que a autorização fluxo é encerrado.

Authlete /auth/authorization/fail A API suporta o processo de rescisão em termos de mensagens a serem enviadas ao cliente e método de transferência para a resposta.

Para resumir, um servidor de autenticação geralmente faz uma solicitação para qualquer um /auth/authorization/issue ou /auth/authorization/fail API dependendo do resultado da autenticação e consentimento do usuário.

Solicitação de token

Aqui assumimos que o agente de usuário recebe o formulário de resposta de redirecionamento do servidor de autorização. Ele enviaria a seguinte solicitação (dobrada para legibilidade) ao cliente (mensagem #11).

GET /cb/example.com?code=3GIJORjvgaEdu2u4KHyaQdGxfHDFsiViwGyZUxeBVrM HTTP/1.1
Host: client.example.org

O cliente iria extrair o valor do code parâmetro, crie uma solicitação de token com o valor e envie-o para o servidor de autorização da seguinte forma (dobrado para legibilidade). https://as.example.com/token é o token endpoint URI neste tutorial (mensagem #12).

POST /token HTTP/1.1
Host: as.example.com
Authorization: Basic base64(12818600553323:-olDIKD9BihRfB8O1JxobUEKBZ7PIV5Z6oaqxAshmoUtUZgB-wjmmxTYDiDV6vM_Mgl267PeNrRftq8cWplvmg)
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
 &code=3GIJORjvgaEdu2u4KHyaQdGxfHDFsiViwGyZUxeBVrM
 &redirect_uri=https://client.example.org/cb/example.com

O servidor de autorização deve avaliar parâmetros na solicitação, fazer uma resposta de token de volta ao cliente. Neste tutorial, vamos usar Authlete /auth/token API para avaliar a solicitação e criar a resposta.

Execute curl command as follows (message #13). Make sure to replace API Key, API Secret, Client ID, Client Secret and Code by your own values generated in the previous steps.

curl -s -X POST https://api.authlete.com/api/auth/token \
-u '<API Key e.g. 10723797812772>:<API Secret e.g. ekYoYTI84qZcpe6bXGzDwduQ1fGBYxJT8K8Tnwd7poc>' \
-H 'Content-Type: application/json' \
-d '{ "clientId": "<Client ID e.g. 12800697055611>", "clientSecret": "<Client Secret e.g. dcDHEXr_tXNi7QdIMXLSXpXAy_j7Cr4C4LT2xAukQcW_09E2Ag1jTBdwpQrG-HBxflPF4Bz_Nb9Zd_ySAxOs6A>", "parameters": "grant_type=authorization_code&code=<Code e.g. GrYz5vtk6VaF0jxfnDrB2yvmk4deIrnMkrGT07JdM5U>&redirect_uri=https://client.example.org/cb/example.com" }'

Execute curl.exe as follows (message #13).Make sure to replace API Key, API Secret, Client ID, Client Secret and Code by your own values generated in the previous steps.

curl.exe -s -X POST https://api.authlete.com/api/auth/token `
-u '<API Key e.g. 10723797812772>:<API Secret e.g. ekYoYTI84qZcpe6bXGzDwduQ1fGBYxJT8K8Tnwd7poc>' `
-H 'Content-Type: application/json' `
-d '{ \"clientId\": \"<Client ID e.g. 12800697055611>\", \"clientSecret\": \"<Client Secret e.g. dcDHEXr_tXNi7QdIMXLSXpXAy_j7Cr4C4LT2xAukQcW_09E2Ag1jTBdwpQrG-HBxflPF4Bz_Nb9Zd_ySAxOs6A>\", \"parameters\": \"grant_type=authorization_code&code=<Code e.g. GrYz5vtk6VaF0jxfnDrB2yvmk4deIrnMkrGT07JdM5U>&redirect_uri=https://client.example.org/cb/example.com\" }'

Se a solicitação for apropriada, Authlete faz a seguinte resposta (mensagem #14).

{
   "accessTokenExpiresAt" : 1558627889220,
   "refreshTokenDuration" : 864000,
   "clientId" : 12818600553323,
   "accessToken" : "-g5ZJDAfpTQAqR9mdnAfhv0zuCe3SUrKJ2_859zI1Ow",
   "refreshToken" : "4PwVTovcwMgnNJbsH-BzeQj5a8nelOi0iEIswex-ueE",
   "accessTokenDuration" : 86400,
   "clientIdAliasUsed" : false,
   "refreshTokenExpiresAt" : 1559405489220,
   "grantType" : "AUTHORIZATION_CODE",
   "subject" : "testuser01",
   "action" : "OK",
   "responseContent" : "{\"access_token\":\"-g5ZJDAfpTQAqR9mdnAfhv0zuCe3SUrKJ2_859zI1Ow\",\"refresh_token\":\"4PwVTovcwMgnNJbsH-BzeQj5a8nelOi0iEIswex-ueE\",\"scope\":null,\"token_type\":\"Bearer\",\"expires_in\":86400}",
   "resultCode" : "A050001",
   "type" : "tokenResponse",
   "resultMessage" : "[A050001] The token request (grant_type=authorization_code) was processed successfully."
}

Preste atenção a três pares de teclas/valores na resposta; resultMessage, action e responseContent.

  • resultMessage fornece resultado legível por humanos do processamento da solicitação. (Veja também Interpretando os códigos de resultado da Authlete)
  • action indica o que o servidor de autorização deve fazer em seguida. O valor nesta resposta é OK, o que significa que o servidor de autorização deve fazer uma resposta de token de volta ao cliente.
  • responseContent é suposto ser o conteúdo da resposta do servidor de autorização.

Espera-se que o servidor de autorização faça a seguinte resposta ao cliente (mensagem nº 15).

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token":"-g5ZJDAfpTQAqR9mdnAfhv0zuCe3SUrKJ2_859zI1Ow",
  "refresh_token":"4PwVTovcwMgnNJbsH-BzeQj5a8nelOi0iEIswex-ueE",
  "scope":null,
  "token_type":"Bearer",
  "expires_in":86400
}

Finalmente, o servidor de autorização criou com sucesso os tokens e forneceu-os ao cliente. Ao aproveitar as APIs da Authlete, o servidor de autorização não precisa implementar lógica complicada para avaliar paramters na solicitação de autorização/token, e fazer respostas adequadas para essas solicitações com o método correto.

Solicitação de API (introspecção de token de acesso)

Na maioria dos casos, o cliente faria uma solicitação com o token de acesso ao servidor de recursos que fornece APIs (mensagem #16). O servidor de recursos deve avaliar a validade do token, recuperar informações sobre o usuário e o cliente relacionados ao token e determinar como responder à solicitação de API. Authlete fornece /auth/introspection API para tal propósito. Ele verifica a validade do token e fornece as informações acima.

Certifique-se de substituir <API Key>, <API Secret> e <Token> por seus próprios valores gerados na etapa anterior.

Execute curl command as follows (message #13). Make sure to replace API Key, API Secret and Token by your own values generated in the previous steps.

curl -s -X POST https://api.authlete.com/api/auth/introspection \
-u '<API Key e.g. 10723797812772>:<API Secret e.g. ekYoYTI84qZcpe6bXGzDwduQ1fGBYxJT8K8Tnwd7poc>' \
-H 'Content-Type: application/json' \
-d '{ "token": "<Token e.g. 7FfwOnGjVHwxXhs2Wr67XV1-ZhQaoy3ctKcGkLyKxuY>" }'

Execute curl.exe as follows (message #13). Make sure to replace API Key, API Secret and Token by your own values generated in the previous steps.

curl.exe -s -X POST https://api.authlete.com/api/auth/introspection `
-u '<API Key e.g. 10723797812772>:<API Secret e.g. ekYoYTI84qZcpe6bXGzDwduQ1fGBYxJT8K8Tnwd7poc>' `
-H 'Content-Type: application/json' `
-d '{ \"token\": \"<Token e.g. 7FfwOnGjVHwxXhs2Wr67XV1-ZhQaoy3ctKcGkLyKxuY>\" }'

Se a solicitação for apropriada, Authlete faz a seguinte resposta (mensagem #18).

{
   "resultMessage" : "[A056001] The access token is valid.",
   "refreshable" : true,
   "clientIdAliasUsed" : false,
   "existent" : true,
   "resultCode" : "A056001",
   "expiresAt" : 1558627889000,
   "responseContent" : "Bearer error=\"invalid_request\"",
   "clientId" : 12818600553323,
   "action" : "OK",
   "usable" : true,
   "sufficient" : true,
   "subject" : "testuser01",
   "type" : "introspectionResponse"
}

O servidor de recursos seria capaz de encontrar um monte de informações, como prazo de validade do token (expiresAt), identificador do usuário que aprovaram o acesso (subject), identificador do cliente (clientId). Então é suposto determinar como responder ao Solicitação de API (mensagem nº 19).

Conlusion

Neste tutorial, pudemos confirmar como usar APIs Authlete para implementar o fluxo de concessão de código de autorização no servidor de autorização.

Próximos passos

Vamos nos aprofundar em Authlete jogando com as seguintes características.