What is it and how can I configure an API Identity?

What is an API Identity?

API Identity is a type of API that we created just to facilitate authentication via the OAuth Password flow.

First, let’s understand what the Password flow is:

OAuth Password flow

In the Password flow, an end user’s username and password, stored in an external service, are used to generate the access token necessary to send requests to an API.

The operation follows the diagram below (source: 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)   |               |
+---------+                                  +---------------+

That is, the user informs their username and password to the client, who passes them on to the authorization server in a POST request that leads to the generation of an access token. In response to this, the authorization server sends an access token that can now be used to send requests to the API.

When to use it?

Since the Password flow establishes that the user’s username and password are shared with the client, it’s more common to use it to allow access to other applications of the same service, but not to third-party applications (in this case, more secure flows, such as Authorization Code, are preferable).

Now, the central question:

How does the API Identity fit into the flow we just described?

When a POST call is made the API OAuth requiring the generation of a token, the API OAuth identifies the API Identity linked to the API through the app informed in the header Authorization. The username and password must be included in the request body. Then, the API OAuth calls the API Identity to validate the username and password, which the Identity does by calling the authentication endpoint registered in it. If the information is validated, the API Identity answers positively to the API OAuth, which generates the token. Otherwise, the token is not generated.

One important detail: you can link several APIs Identity to the same API. So, in this authentication flow, OAuth will call each of the linked APIs Identity, from the newest to the oldest, and as soon as the username and password are validated, it stops the validation process and responds positively to OAuth. If all APIs Identity are called and the username and password are not validated, the token is not generated. This behaviour of the API Identity allows the Manager to concentrate the internal authentication servers for your APIs.

Briefly, then, we have this flow (with an example in which two APIs Identity are called):

api identity en

Every API that requires the Password flow to generate and validate access tokens must be linked to an API Identity (this link is made in the registration of the API Identity). This API and the API Identity must be deployed to the same environment. Other than that, for the API Identity to be able to handle calls for token generation, it must be deployed in the same environment as the POST / access-token flow (that is, in the same environment as the API OAuth, which comes with your Manager).

How to configure an API Identity?

The configuration of an API Identity follows the same steps as for a normal API. The difference is that there is an extra step in the case of Identity, in which we need to link it to the API that will require access tokens generated with the Password.

See more details on how the API Identity works here and on how to configure it here.

See more

Thanks for your feedback!
EDIT

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