O que é e como configurar 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

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

O funcionamento é como mostra 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)   |               |
+---------+                                  +---------------+

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

Quando utilizá-lo?

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

API Identity no fluxo de Password OAuth

Quando uma chamada POST é enviada para a API OAuth para gerar token via Password, ela identifica a API Identity vinculada à API por meio da app informada no header Authorization. Username e senha devem estar presentes no corpo da requisição. A API OAuth realiza uma requisição à API Identity para validar o username e senha, utilizando o endpoint de autenticação registrado nela. Se as informações forem válidas, a API Identity responde positivamente à API OAuth, que gera o token necessário para acessar a API. Caso contrário, o token não é gerado.

É possível vincular várias APIs Identity a uma mesma API. Nesse fluxo de autenticação, a OAuth chama cada uma das Identity vinculadas, da mais nova para a mais antiga. Assim que username e senha forem validados, ela interrompe a validação e responde positivamente à API OAuth.

Se todas as APIs Identity forem chamadas e username e senha não forem validados, o token não é gerado. Isso permite que o Manager concentre os servidores de autenticação internos para suas APIs.

Resumidamente, temos este fluxo (com um exemplo de chamada a duas APIs Identity):

Toda API que requer o fluxo Password para gerar e validar access tokens deve estar vinculada a pelo menos uma API Identity. Essa vinculação é feita no cadastro da API Identity.
A API e a API Identity devem estar implantadas no mesmo ambiente.
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 há um passo extra no caso da Identity, em que precisamos vinculá-la à API que irá requerer access tokens gerados pelo fluxo Password.

Veja mais detalhes sobre o funcionamento das APIs Identity como configurá-la.

Informações adicionais

Chamadas necessárias para obter access tokens pelo fluxo Password.
Se quiser ler mais sobre as diferenças entre os 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]