Authorization Code Flow

El tipo de concesión del authorization code se utiliza para obtener acceso a
access tokens y refresh tokens.
El caso de uso en el que se emplea es cuando una aplicación quiere acceder a recursos de un usuario que están
protegidos en un resource server.
Con este flow el dueño del recurso puede dar acceso a dicha aplicación teniendo conocimiento sobre el alcance que la misma tendrá sobre
su información.

Dado que se trata de un flujo basado en redirecciones, la aplicación debe ser capaz de
interactuar con el user-agent del propietario del recurso (normalmente un navegador web) y capaz de recibir solicitudes entrantes (mediante redirección)
desde el servidor de autorización o auth sever.

¿Cómo funciona?

El siguiente es un diagrama del flujo Authorization Code con la explicación correspondiente de cada paso.

oauth2_flow

1 - La aplicación solicita llevar adelante una acción

Desde el frontend de la aplicación se solicita a su backend llevar adelante una acción sobre recursos protegidos.
Para esto es necesario que la aplicación tenga un access token válido.

2 - Solicitud de un token de acceso

El backend de la aplicación recibe la petición del frontend y redirige al usuario hacia el  formulario de login del servidor de autenticación
con el siguiente formato.

Ejemplo:

GET /oauth/authorize?
response_type=code
&redirect_uri=https://www.miapp.com/callback
&client_id=c4b76a47-f603-4ce4-858b-4a042b57ce87
&scope=api_orders_post HTTP/1.1
Host: {{base_url}}

Donde:

client_id
Es el identificador único y público de la aplicación.
response_type
Debe ser “code”
redirect_uri
Es la URI la que está preparada para recoger la respuesta de esta petición. Debe estar previamente registrada y asociada a la aplicación en el auth server.
scope
Es el alcance que quiere obtener la aplicación sobre los recursos protegidos del usuario
Acepta un "*" o "api_orders_post" como se ve en el ejemplo.
base_url
Consultar en la sección Ambientes/Auth Server

3 - Validación de credenciales en el auth server

El servidor de autorización solicita un usuario y un password vía un formulario web (autenticación) al dueño del recurso.

4 - Formulario de consentimientos.

Si las credenciales ingresadas en el paso anterior fueron correctas se informa al usuario cuales son
los scopes a los que la aplicación está intentando acceder.

5 - Respuesta con code.

El usuario da su consentimiento y el servidor redireccionará a la url que se informo en el parámetro redirect_uri junto con el code obtenido.

Ejemplo de redirección al backend de la aplicación:

https://www.miapp.com/callback
?code=examplecode

6 - Solicitud de un token de acceso.

Con el code el backend de la aplicación podrá realizar la petición de un token de acceso al auth server.

Ejemplo de redirección:

POST /oauth/token HTTP/1.1
Host: {{base_url}}
Content-Type: application/json
Content-Length: 217

{
    "grant_type": "authorization_code",
    "client_id": "{{client_id}}",
    "client_secret": "{{client_secret}}",
    "code": "{{code}}",
    "redirect_uri":"https://www.miapp.com/callback"
}

Donde:

base_url
Consultar en la sección Ambientes/Auth Server
grant_type
Es “authorization_code”.
redirect_uri
Debe ser la URI que se usó para solicitar el code.
code
Es el código que nos permitirá recoger el token.
client_id
Es el identificador público de la aplicación.
client_secret
Es la clave secreta de la aplicación relacionada al identificador público de la misma.

7 - Respuesta con token de acceso mediante el code.

El auth server valida el code junto con las credenciales de aplicación.
De ser correcta la información responde con el access token.

Ejemplo:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Content-Length: 1335

{
"token_type":"Bearer",
"expires_in":1625152988,
"access_token":"xxxxxxxxxxxxx",
"refresh_token":"xxxxxxxxxxxxx"
}

Donde:

token_type
Es el formato del access_token.
expires_in
Es el tiempo que el access_token tendrá vigencia para su uso hasta quedar expirado.
access_token
Es un JWT que se usa para autorizar las peticiones a la API del resource server.
refresh_token
Es un token que sirve para conseguir un nuevo access_token cuando el mismo haya expirado.

8 - Solicitud de acceso a recursos protegidos mediante access token.

La aplicación realiza una accion una acción en el resource server sobre recursos protegidos utilizando el access token.

Ejemplo de petición con access token:

GET /api/example HTTP/1.1
Host: http://resource-server.com
Authorization: Bearer {{access_token}}

9 - Respuesta del resource server a la aplicación.

El resource server responde con status code correspondiente.
Si es el caso también tendrá información en body referida a la acción que se llevó adelante o el recurso consultado.

10 - Presentación de información.

La aplicación resuelve la petición presentando la información correspondiente.

Aclaraciones importantes.

Bajo ningún punto se recomienda que credenciales de aplicación y tokens de acceso estén alojados del lado del cliente el cual sea de acceso público.
Tanto las credenciales de aplicación como los tokens deben estar alojados en un backend server side siendo este el único responsable de tener conocimiento sobre este tipo de información.
Todas las peticiones al Auth server y al Resource server deben ser siempre host to host.