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).

É necessário ter uma API Identity cadastrada para utilizar o fluxo Password de OAuth. Você pode ver mais sobre esse fluxo aqui.

Funcionamento

Quando uma app chama uma API vinculada a uma API Identity, ocorre o seguinte: ao requerir um access token pelo fluxo Password, uma requisição é enviada para a API Identity, que trata a chamada e a envia pra o endpoint de autenticação.

Se o backend que faz a validação das credenciais solicitar mais informações além de username e password, é possível utilizar interceptors no fluxo da API Identity para compor um corpo com as informações solicitadas. Por exemplo, é possível recuperar os dados dos extra fields de uma app e incluí-los no corpo.

Uma API comum pode estar associada a mais de uma API Identity, e uma app pode estar associada a mais de uma API. Nesses casos, o serviço de autorização fará requisições para cada API Identity associada, uma a uma. Caso a senha seja válida para alguma API Identity, ele deixará de executar as requisições restantes. Se a senha não for válida para nenhuma Identity, não será permitido criar um access token.

Quando a API Identity fizer uma requisição ao endpoint de autenticação, o conteúdo que for retornado será repassado para a requisição de access token no fluxo Password, permitindo mais possibilidades na autenticação de senhas. Caso a chamada para a API Identity retorne um campo no corpo com a chave extraInfo, o conteúdo desse campo estará presente no extraInfo do access token gerado.

Criando uma API Identity

Para a criação de uma nova API Identity, selecione a opção CREATE API IDENTITY no canto inferior direito da página APIs (no menu que surge ao posicionar o cursor sobre o botão flutuante +).

A página de construção de API será aberta e você deverá preencher as informações necessárias ao longo das diferentes etapas, como no caso de uma API comum:

O API Destination (que você configura clicando no ícone icon backend

dentro da etapa Flows) deverá ser o endpoint onde será executada a verificação de username e senha.

Diferente de APIs comuns, a API Identity possui a etapa Identity, na qual é possível selecionar APIs que utilizam os interceptores OAuth e/ou Access Token Validation com a opção Password habilitada.

Feito isso, publique sua API normalmente depois de todas as etapas de criação e ela estará pronta para uso.

Exemplo de configuração e uso

Para que o processo de configuração e uso da API Identity fique mais fácil, nosso time de Suporte criou um artigo com um exemplo. Você pode acessá-lo aqui.

Thanks for your feedback!

EDIT

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