O que é e como configurar uma API Identity?

O que é uma API Identity?

API Identity é um tipo de API que criamos especificamente para facilitar a autenticação pelo fluxo Password de OAuth.

Primeiro, vamos entender o que é o fluxo Password:

Fluxo Password de OAuth

No fluxo do tipo Password, o username e a senha de um usuário final, armazenados em um serviço externo, são utilizados para gerar o access token necessário para fazer requisições a uma API.

O funcionamento segue o diagrama abaixo (fonte: The OAuth 2.0 Authorization Framework):

+----------+
| Resource |
|  Owner   |
|          |
+----------+
     v
     |    Resource Owner
    (A) Password Credentials
     |
     v
+---------+                                  +---------------+
|         |>--(B)---- Resource Owner ------->|               |
|         |         Password Credentials     | Authorization |
| Client  |                                  |     Server    |
|         |<--(C)---- Access Token ---------<|               |
|         |    (w/ Optional Refresh Token)   |               |
+---------+                                  +---------------+

Ou seja, o usuário informa seu username e senha para o cliente, que os passa para o servidor de autorização em uma chamada POST que pede a geração de um access token. Como resposta dessa chamada, o servidor de autorização envia um access token que, agora, pode ser usado para fazer requisições a API.

Quando utilizá-lo?

Como o fluxo Password estabelece que o username e senha do usuário sejam compartilhados com o cliente, é mais comum utilizá-lo para permitir acesso a aplicações diferentes de um mesmo serviço, mas não a aplicações terceiras (nesse caso, fluxos de mais segurança, como o Authorization Code, são preferíveis).

Agora, a questão mais importante:

Como a API Identity se insere no fluxo que acabamos de descrever?

Quando uma chamada POST para geração de token via Password é enviada para a API OAuth, ela identifica a API Identity vinculada a API por meio da app que é informada no header Authorization. A informação de username e senha deve estar presente no corpo da requisição. A API OAuth envia, então, uma chamada à API Identity para validar username e senha, o que a Identity faz chamando o endpoint de autenticação que está cadastrado nela. Se as informações forem válidas, então a API Identity responde positivamente à API OAuth, que gera o token necessário para ter acesso à API. Caso contrário, o token não é gerado.

Um detalhe importante: é possível vincular várias APIs Identity para uma mesma API. Então, nesse fluxo de autenticação, a OAuth vai chamar cada uma das Identity vinculadas, da mais nova para a mais antiga, e assim que username e senha forem validados, ela interrompe a validação e responde positivamente à OAuth. Se todas as APIs Identity forem chamadas e username e senha não forem validados, o token não é gerado. Essa atuação da API Identity permite com que o Manager concentre os servidores de autenticação internos para as suas APIs.

De forma resumida, então, temos este fluxo (com um exemplo de chamada a duas APIs Identity):

Toda API que requerir o fluxo Password para geração e validação de access token deve estar vinculada a pelo menos uma API Identity (essa vinculação é feita no cadastro da API Identity). Essa API e a API Identity devem estar implantadas no mesmo ambiente. Fora isso, para que a API Identity consiga tratar as chamadas para geração de token, é importante que ela esteja implantada no mesmo ambiente do fluxo POST /access-token (ou seja, no mesmo ambiente da API OAuth, que já vem criada no seu Manager).

Como configurar uma API Identity?

A configuração de uma API Identity segue os mesmos passos de uma API normal. A diferença é que existe um passo extra no caso da Identity, em que precisamos vinculá-la à AAPI que requerirá access tokens gerados pelos fluxo Password.

Veja mais detalhes sobre o funcionamento das API Identity aqui e sobre como configurá-la aqui.

Veja mais

Detalhamos as chamadas necessárias para obter access tokens pelo fluxo Password aqui.
Se quiser ler mais sobre as diferenças entre os diferentes fluxos de OAuth, acesse The OAuth 2.0 Authorization Framework.

Thanks for your feedback!

EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]