Configurar Rich Authorization Requests (RAR)

Aprenda a configurar Rich Authorization Requests (RAR) para un servidor de recursos.

Con Rich Authorization Requests (RAR), los clientes pueden solicitar y obtener datos de autorización granular de propietarios de recursos, como los usuarios finales, durante el Flujo de código de autorización con Pushed Authorization Requests (PAR) y el Flujo de autenticación de canal secundario iniciado por el cliente.

Rich Authorization Requests usa el parámetro authorization_details. Este parámetro acepta un arreglo JSON de objetos que puede incluir información detallada sobre la autorización solicitada, como los recursos o las acciones específicas a las que el cliente quiere acceder en nombre del usuario.

Puede renderizar los authorization_details solicitados para el usuario de una de estas formas:

• En el navegador, mediante una pantalla de consentimiento personalizada
• En una aplicación móvil al usar notificaciones push con el SDK de Auth0 Guardian o la aplicación Auth0 Guardian

Para configurar Rich Authorization Requests para un servidor de recursos, debe:

1. Registrar tipos de authorization_details para el servidor de recursos.
2. Configurar las políticas de acceso a la API para permitir que su aplicación solicite esos tipos.
3. Establecer la pantalla de consentimiento personalizada para renderizar authorization_details.
4. Opcional: Configurar la política de consentimiento para el servidor de recursos.

​

Registrar tipos de authorization_details

Cada objeto del arreglo JSON debe tener un campo type, que describe la estructura del objeto. Un arreglo authorization_details puede contener varias entradas del mismo type.

​

Aplicación Auth0 Guardian

Si usa la aplicación Auth0 Guardian, el valor del parámetro authorization_details debe tener un solo objeto en el array, y ese objeto debe ajustarse al siguiente esquema de Auth0:

Campo	Descripción	Ejemplo
type	Especifica el tipo de solicitud de autorización: urn:auth0:schemas:authorization-details: El URN de Auth0 indica que la solicitud usará el esquema de Auth0. v1: La versión del esquema. user-profile: Valor proporcionado por el cliente que indica que la solicitud es para información del perfil de usuario.	urn:auth0:schemas:authorization-details:v1:user-profile
instruction	Un mensaje legible para el usuario para que apruebe la solicitud.	Apruebe la solicitud.
properties	Un objeto JSON que contiene los atributos o claim específicos del usuario que se solicitan. Cada clave (por ejemplo, email, full_name) representa un campo concreto del perfil de usuario: display: Un valor booleano que determina si la propiedad debe mostrarse al usuario en el cuadro de diálogo de consentimiento. Si es true, se mostrará; si es false, es una propiedad solo interna que no está pensada para que el usuario la vea. name: El nombre legible para humanos de la propiedad (por ejemplo, “Dirección de correo electrónico”). display_order: Un entero que determina el orden en que las propiedades se mostrarán en el cuadro de diálogo de consentimiento. description: Una explicación breve y opcional del propósito de la propiedad. value: El valor real de la propiedad (por ejemplo, “[e-mail]”, “John Doe”). El tipo de datos puede variar (cadena, entero, booleano, etc.).	"properties": { "stringPropertyForDisplay": { "display": true, "name": "A String:", "display_order": "1", "value": "Value 1"} }

A continuación, se muestra un ejemplo del tipo authorization_details con el esquema de Auth0:

{
    "type": "urn:auth0:schemas:authorization-details:v1:user-profile",
    "instruction": "An instruction to the user",
    "properties": {
        "stringPropertyForDisplay": {
            "display": true,
            "name": "A String:",
            "display_order": 1,
            "value": "Value 1"
        },
        "numericPropertyForDisplay": {
            "display": true,
            "name": "A Number:",
            "display_order": 2,
            "description": "An optional description",
            "value": 100.00
        },
        "booleanPropertyForDisplay": {
            "display": true,
            "name": "A Boolean:",
            "display_order": 3,
            "value": true
        },
        "hiddenProperty": {
            "display": false,
            "value": "This value should not be displayed"
        }
    }
}

​

Otros canales de notificación

El tipo authorization_details no necesita usar el esquema de Auth0 si no estás usando la aplicación Auth0 Guardian. Si muestras authorization_details mediante una pantalla de consentimiento personalizada o tu propia aplicación móvil personalizada con el SDK de Auth0 Guardian, se aplican los siguientes requisitos:

• Máximo de 5 KB
• Debe ser un JSON válido
• Debe ser un array de objetos
• Máximo de 5 entradas en el array
• Cada objeto debe tener una propiedad type (prerregistrada en la API)
• Máximo de 10 propiedades por objeto
• La longitud máxima de los nombres de las propiedades es de 255 caracteres
• La longitud máxima del valor de una propiedad es de 255 caracteres
• Máximo de 5 niveles de objetos anidados
• Los nombres de las propiedades solo pueden contener los siguientes caracteres: a-zA-Z0-9_.-

A continuación se muestra un ejemplo de authorization_details de tipo money_transfer que no usa el esquema de Auth0. Contiene los siguientes campos de objeto:

• instructedAmount: El importe en USD que se transferirá.
• sourceAccount: La cuenta bancaria de origen desde la que se transferirá el dinero.
• destinationAccount: La cuenta bancaria de destino a la que se transferirá el dinero.
• beneficiary: El destinatario de la transferencia de dinero.
• subject: El asunto de la transferencia de dinero.

{
  "type": "money_transfer", 
  "instructedAmount": {"amount": 2500, "currency": "USD"},   
  "sourceAccount": "xxxxxxxxxxx1234", 
  "destinationAccount": "xxxxxxxxxxx9876", 
  "beneficiary": "Hanna Herwitz", 
  "subject": "A Lannister Always Pays His Debts"
}

Debe registrar tipos de authorization_details para un servidor de recursos, lo cual es similar a registrar alcances permitidos. Puede registrar tipos de authorization_details con el Auth0 Dashboard o la Management API.

Auth0 Dashboard

Para agregar authorization_details en el Auth0 Dashboard:

1. Vaya a Auth0 Dashboard > Applications > APIs.
2. Seleccione la pestaña Permissions.
3. En Add an Authorization Details type, puede agregar varios tipos de authorization_details para su servidor de recursos. Introduzca un tipo de authorization_details.
4. Seleccione la opción +Add.

Puede ver los tipos de authorization_details de su servidor de recursos en List of Authorization Details Types:

Management API

Para registrar tipos de authorization_details en un servidor de recursos existente, realice una solicitud PATCH al endpoint Update a resource server.

El siguiente ejemplo de código agrega los tipos payment_initiation y money_transfer a authorization_details para un servidor de recursos:

curl --location --request PATCH 'https://$tenant/api/v2/resource-servers/$resource-server-id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "authorization_details": [{"type": "payment_initiation"}, {"type": "money_transfer"}]
  }'

Para crear un nuevo servidor de recursos con un tipo de authorization_details registrado, realice una solicitud POST al endpoint /resource-servers.

La siguiente solicitud POST crea un nuevo servidor de recursos con el tipo payment_initiation en authorization_details:

curl --location --request POST 'https://$tenant/api/v2/resource-servers' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Payments API",
  "identifier": "https://payments.api/",
  "authorization_details": [{"type": "payment_initiation"}]
  }'

​

Configure las políticas de acceso a la API

Políticas de acceso a la API para aplicaciones controlan qué aplicaciones pueden acceder a sus APIs y qué alcances o tipos de authorization_details tienen permitidos.

Puede consultar la política actual de su API mediante la Management API. Haga una solicitud GET al endpoint Obtener un servidor de recursos y revise la propiedad subject_type_authorization en la respuesta:

curl --location --request GET 'https://$tenant/api/v2/resource-servers/$resource-server-id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json'

La propiedad subject_type_authorization admite valores para client.policy y user.policy:

• Si el valor de la política es allow_all, las aplicaciones o los usuarios pueden solicitar todos los tipos de authorization_details registrados para la API.
• Si el valor de la política es require_client_grant, cada tipo de authorization_details debe estar permitido explícitamente por el client grant de esa aplicación.
• Si el valor de la política es deny_all, ninguna aplicación ni ningún usuario pueden solicitar ninguno de los tipos de authorization_details registrados para la API.

Para obtener más información sobre cómo administrar los client grants de las aplicaciones, consulte Acceso de aplicaciones a las API: Client Grants .

​

Configurar una pantalla de consentimiento personalizada

Puede renderizar los authorization_details de una solicitud de autorización enriquecida en la pantalla de consent. Para ello, configure la pantalla customized-consent con los partials de plantilla adecuados.

Puede configurar la pantalla de consentimiento personalizada con Auth0 CLI o Management API.

​

Auth0 CLI

Para configurar los partials personalizados de consent, ejecute el comando auth0 ul customize con los indicadores adecuados en su terminal:

auth0 ul customize

Para obtener más información, consulte la documentación para personalizar Universal Login de Auth0.

​

Management API

Para configurar los partials personalizados de consent, realiza una solicitud PUT al endpoint /prompts/customized-consent/partials:

curl --location --request PUT "https://$tenant/api/v2/prompts/customized-consent/partials" \
  --header "Authorization: Bearer $management_access_token" \
  --header "Content-Type: application/json" \
  --data '{
    "customized-consent": {
      "form-content": "<div style=\"font-size: 1.3em; font-weight: bold;\">Operation Details</div><hr style=\"margin: 10px 0;\"><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Transaction Type</div><div>{{ transaction.params.authorization_details[0].type }}</div><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Amount</div><div>{{ transaction.params.authorization_details[0].instructedAmount.amount }} {{ transaction.params.authorization_details[0].instructedAmount.currency }}</div><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Recipient</div><div>{{ transaction.params.authorization_details[0].beneficiary }}</div><div style=\"margin-bottom: 20px;\"></div><div style=\"font-weight: bold;\">Destination Account</div><div>{{ transaction.params.authorization_details[0].destinationAccount }}</div><div style=\"margin-bottom: 20px;\"></div>"
    }
  }'

La plantilla de consent personalizada renderiza authorization_details en la siguiente pantalla de consent que Auth0 muestra al usuario final:

En el flujo de notificaciones por correo electrónico con CIBA y RAR, debe personalizar la pantalla de consent para mostrar al usuario las pantallas de aprobación o rechazo:

Para obtener más información sobre cómo personalizar la pantalla de consent, consulte:

• Personalizar las páginas de Universal Login
• Personalizar Universal Login con el editor sin código
• Configurar partials para una pantalla en la documentación de la API

​

Opcional: Configurar la política de consentimiento para el servidor de recursos

La política de consentimiento del servidor de recursos determina si Auth0 almacena los valores de authorization_details y los pone a disposición de las aplicaciones móviles cuando se envía una notificación push.

Consulte el comportamiento de la política de consentimiento estándar de Auth0 para una solicitud que contiene authorization_details:

Flujo	Notificación push enviada	Comportamiento
Cualquiera	No	Se muestra la pantalla de consentimiento personalizada.
Flujo de código de autorización con PAR	Sí	No se muestra ninguna pantalla de consentimiento. El consentimiento debe mostrarse en la aplicación móvil que recibe el desafío de notificación push. Si se usa la aplicación Auth0 Guardian, mostrará automáticamente authorization_details al usuario. Si se usa una aplicación móvil personalizada, authorization_details se puede recuperar mediante el SDK de Auth0 Guardian.
Flujo de autenticación de canal secundario iniciado por el cliente	Sí	Si se usa la aplicación Auth0 Guardian para autorizar la solicitud CIBA, authorization_details se recuperará automáticamente y se mostrará. Si se usa una aplicación móvil personalizada para autorizar la solicitud CIBA, authorization_details se puede recuperar mediante el SDK de Auth0 Guardian. Si la solicitud CIBA se autoriza mediante un enlace web (por ejemplo, desde un correo electrónico), se mostrará la pantalla de consentimiento personalizada. Los clientes pueden optar por activar una notificación push como segundo factor para la solicitud CIBA cuando el usuario la aprueba mediante un enlace web; en ese caso, el comportamiento es el mismo que el anterior. La aplicación Auth0 Guardian vuelve a mostrar automáticamente authorization_details al usuario, mientras que las aplicaciones móviles personalizadas pueden optar por recuperar authorization_details mediante el SDK de Auth0 Guardian.

Los clientes también pueden establecer consent_policy en transactional-authorization-with-mfa, que tiene el siguiente comportamiento:

Flujo	Notificación push enviada	Comportamiento
Flujo de código de autorización con PAR	No	Se muestra la pantalla de consentimiento personalizada.
Flujo de código de autorización con PAR	Sí	No se muestra ninguna pantalla de consentimiento. La solución del cliente debe mostrar el consentimiento en su propia interfaz de usuario. Auth0 asignará un ID único a la solicitud y lo expondrá en la Post-Login Action como event.transaction.linking_id, junto con event.transaction.requested_authorization_details. Si se usa la aplicación Auth0 Guardian, NO se mostrarán authorization_details. Si se usa una aplicación móvil personalizada, la notificación push incluirá linking_id, lo que permitirá a los desarrolladores recuperar authorization_details desde sus propias API si es necesario.
Flujo de autenticación de canal secundario iniciado por el cliente	Cualquiera	El flujo CIBA no es compatible con la política de consentimiento transactional-authorization-with-mfa

Puede configurar la política de consentimiento para un servidor de recursos con el Auth0 Dashboard o la Management API.

Auth0 Dashboard

Configure la política de consentimiento en la configuración de su API mediante el Auth0 Dashboard.

1. Vaya a Auth0 Dashboard > Applications > APIs.
2. Seleccione la pestaña Settings.
3. En Access Settings, elija la política de consentimiento Standard.
4. Guarde los cambios.

Management API

Para establecer la política de consentimiento de un servidor de recursos o una API mediante la Management API, envíe una solicitud PATCH al endpoint Update a resource server. En la solicitud PATCH, establezca consent_policy en standard:

curl --location --request PATCH 'https://$tenant/api/v2/resource-servers/$resource-server-id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{ "consent_policy": "standard" }'