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

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 this flow, the end user’s username and password are stored in an external service and used to generate the access token required to send requests to an API.

The operation is illustrated in 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)   |               |
+---------+                                  +---------------+

The user provides their username and password to the client, which passes them to the authorization server in a POST request asking for an access token. In response, the authorization server sends back an access token that can be used to make API requests.

When to use it?

Because the Password flow requires the user’s username and password to be shared with the client, it is more commonly used to allow access to different applications of the same service, but not to third-party applications. In this case, more secure flows like the Authorization Code flow are preferable.

API Identity in the OAuth Password flow

When a POST request is sent to the OAuth API to generate a token via Password, it identifies the linked Identity API through the app specified in the Authorization header. The username and password information must be present in the request body. The OAuth API then sends a call to the Identity API to validate the username and password. The Identity API does this by calling the authentication endpoint registered in it. If the information is valid, the Identity API responds positively to the OAuth API, which generates the token required to access the API. Otherwise, the token is not generated.

It is possible to link multiple APIs Identity to the same API. In this authentication flow, the OAuth calls each linked APIs Identity in order from the newest to the oldest. As soon as the username and password are validated, it stops validation and responds positively to the OAuth. If all APIs Identity are called and the username and password are not validated, the token is not generated. This allows the Manager to centralize internal authentication servers for your APIs.

In summary, the flow looks like this (with an example of calling two APIs Identity):

Any API that requires the Password flow to generate and validate access tokens must be linked to at least one API Identity. This linkage is made when registering the API Identity.
The API and the API Identity must be deployed in the same environment.
For the API Identity to handle token generation calls, it is important that it is deployed in the same environment as the POST /access-token flow. That is, in the same environment as the OAuth API, which is already created in your Manager.

How to configure an API Identity?

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

Check more details about the functioning of API Identity and how to configure it.

Additional information

Required calls to obtain access tokens through the Password flow.
If you want to read more about the differences between OAuth flows, visit The OAuth 2.0 Authorization Framework.

Thanks for your feedback!

EDIT

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