API Identity

API Identity es un tipo de API que creamos solo para facilitar la autenticación a través del flujo Password de OAuth.

En primer lugar, vamos a entender mejor qué es el flujo Password:

Flujo Password de OAuth

En el flujo Password, el nombre de usuario y la contraseña de un usuario final, almacenados en un servicio externo, se utilizan para generar el token de acceso necesario para enviar peticiones a una API.

La operación sigue el siguiente diagrama (fuente: 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)   |               |
+---------+                                  +---------------+

Es decir, el usuario informa de su nombre de usuario y contraseña al cliente, que los pasa al servidor de autorización en una petición POST que conduce a la generación de un token de acceso. En respuesta a esto, el servidor de autorización envía un token de acceso que ahora se puede usar para enviar peticiones a la API.

¿Cuándo usarlo?

Dado que el flujo Password establece que el nombre de usuario y la contraseña del usuario se comparten con el cliente, es más común usarlo para permitir el acceso a otras aplicaciones del mismo servicio, pero no a aplicaciones de terceros (en este caso, flujos más seguros, como Authorization Code, son preferibles).

Ahora, la cuestión más importante:

¿Cómo entra la API Identity en el flujo que acabamos de describir?

Cuando se envía una llamada POST para la generación de tokens via Password a la API OAuth, ella identifica la API Identity vinculada a la API a través de la app que se introduce en el header Authorization. El nombre de usuario y la contraseña deben estar presentes en el cuerpo de la petición. A continuación, la API OAuth envía una llamada a la API Identity para validar el nombre de usuario y la contraseña, lo que Identity hace llamando al enpoint de autenticación que tiene registrado. Si la información es válida, la API Identity responde positivamente a la API OAuth, que genera el token necesario para acceder a la API. En caso contrario, el token no se genera.

Un detalle importante: es posible vincular varias APIs Identity a la misma API. Así, en este flujo de autenticación, OAuth llamará a cada una de las APIs Identity vinculadas, desde la más reciente a la más antigua, y tan pronto como el nombre de usuario y la contraseña sean validados, detendrá la validación y responderá positivamente a OAuth. Si se llama a todas las APIs Identity y no se valida el nombre de usuario y la contraseña, no se genera el token. Este funcionamiento de la API Identity permite al Manager concentrar los servidores de autenticación internos para sus APIs.

En resumen, pues, tenemos este flujo (con un ejemplo de llamada a dos APIs Identity):

Todas las APIs que requieren el flujo Password para generar y validar tokens de acceso deben estar vinculadas a una API Identity (este vínculo se realiza en el registro de la API Identity). Esta API y la API Identity deben implementarse en el mismo entorno. Aparte de eso, para que la API Identity pueda controlar las llamadas para la generación de tokens, debe implementarse en el mismo entorno que el flujo POST/access-token (es decir, en el mismo entorno que la API OAuth, que viene con el Manager).

Es necesario tener una API Identity registrada para utilizar el flujo Password de OAuth. Puede ver más sobre este flujo aquí.

Funcionamiento

Cuando una aplicación llama una API asociada a una API Identity, ocurre lo siguiente: al requerir un access token del tipo Password, será realizada una petición para la API Identity, que tratará la llamada y la envirará para el endpoint de autenticación.

Si el backend que valida las credenciales solicita más información, además del nombre de usuario y contraseña, es posible usar interceptores en el flujo de la API Identity para componer un cuerpo con la información solicitada. Por ejemplo, es posible recuperar datos de los extra fields de una aplicación e incluirlos en el cuerpo.

Una API común puede estar asociada a más de una API Identity, y una aplicación (app) puede estar asociada a más de una API. En estos casos, el servicio de autorización enviará peticiones a cada API Identity asociada, una a una. En el caso que la contraseña sea válida en alguna API Identity, él dejará de ejecutar las restantes. En el caso que en ninguna API Identity la contraseña sea válida, no será permitido crear un access token.

Cuando la API Identity realiza una solicitud al endpoint, el contenido que se devuelve se pasará a la solicitud de access token en el flujo Password, permitiendo más posibilidades en la autenticación de contraseñas. En el caso que la llamada para la API Identity retorne un campo en el cuerpo con la clave extraInfo, el contenido de este campo estará presente en el extraInfo del access token generado.

Cómo crear una API Identity

Para la creación de una nueva API Identity, seleccione la opción CREATE API IDENTITY en la esquina inferior derecha de la pantalla APIs (en el menú que aparece al colocar el cursor en el botón flotante +)).

Será abierta la página de construcción de APIs y deberán ser llenadas todas las informaciones necesarias, así como cuando se crea una API común:

El destino (API Destination, que se establece al hacer clic en el ícono icon backend

en la sección Flows) deberá ser el endpoint que ejecutará la verificación de username y contraseña.

Diferente de APIs comunes, la API Identity posee el campo Identity, donde es posible seleccionar APIs que utilizan los interceptores OAuth y/o Access Token Validation con la opción Password habilitada.

Hecho esto, su API puede ser publicada de forma normal después de todos los pasos de creación y estará lista para ser utilizada.

Ejemplo de configuración y uso

Para facilitar el proceso de configuración y uso de la API Identity, nuestro equipo de Soporte ha creado un artículo con un ejemplo. Puede acceder a él aquí.^[1]

1. Este artículo estará disponible en español pronto.

Thanks for your feedback!

EDIT

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