Acceso de las aplicaciones a las API: Client Grants

Obtén información sobre Client Grants

En Auth0, puedes controlar cómo las aplicaciones acceden a tus API mediante políticas de acceso de aplicaciones a las API y client grants.

Un client grant proporciona acceso granular de una aplicación a una API. Asocia:

• Una API identificada por su audience o identificador único.
• Una aplicación identificada por su client_id.
• Una lista de permisos, como alcances y/o authorization_details_types, que la aplicación puede solicitar para la audiencia especificada.

Para obtener más información sobre la lista de atributos que puedes definir en un client grant, consulta Atributos de client grant. Para obtener información sobre cómo definir y administrar client grants, consulta Crear client grant.

​

Políticas de acceso de aplicaciones a la API y client grants

Cuando configuras la política de acceso de aplicaciones de una API como require_client_grant, solo las aplicaciones que tengan definido un client grant pueden obtener un token de acceso para la API. El client grant establece los permisos máximos que una aplicación puede solicitar a la API, conforme al principio de mínimo privilegio. Por ello, Auth0 recomienda usar require_client_grant al configurar la política de acceso de aplicaciones de una API.

​

Ejemplo: API de redes sociales

Para ilustrar cómo los client grants aplican el principio de privilegio mínimo, supongamos que tiene una API de redes sociales con los permisos read:posts, write:posts, read:friends y delete:posts. Crea una aplicación y define un client grant con los permisos read:posts y write:posts.

Este client grant ahora actúa como un límite estricto. Aunque la API de redes sociales tenga otros permisos, su aplicación nunca podrá solicitar ni obtener read:friends o delete:posts.

​

Acceso delegado por el usuario vs. acceso del cliente

Tanto en el acceso de usuario como en el acceso de cliente, los client grants definen el conjunto final de permisos que controlan el acceso de una aplicación a una API. El atributo subject_type del client grant determina el tipo de acceso de la aplicación que se permite para una API.

Una aplicación puede tener hasta dos client grants para una sola API:

• Cuando establece subject_type en client, define sus permisos de máquina a máquina.
• Cuando establece subject_type en user, define sus permisos para actuar en nombre del usuario.

La siguiente tabla explica cómo los client grants controlan el acceso de las aplicaciones a las API según el flujo del tipo de acceso:

Tipo de acceso	Atributo subject_type	Descripción
Acceso con credenciales de cliente (acceso de máquina a máquina)	Establezca subject_type en client.	El client grant autoriza directamente a la aplicación a acceder a la API en su propio nombre, en lugar de hacerlo en nombre del usuario final. Los permisos que define en el client grant son los que la aplicación está autorizada a recibir en el token de acceso.
Acceso delegado por el usuario	Establezca subject_type en user.	El client grant define los permisos máximos que la aplicación puede solicitar a la API. Los permisos finales del token de acceso emitido a la aplicación en nombre del usuario son la intersección de los permisos: Solicitados por la aplicación Permitidos por el client grant Permitidos por las políticas de control de acceso basado en roles para el usuario Autorizados por el usuario final, si corresponde. Para obtener más información sobre los flujos de acceso delegado por el usuario, consulte Flujos de autenticación y autorización. Los flujos de acceso delegado por el usuario no incluyen el flujo de credenciales del cliente.

Puede modificar los alcances finales otorgados por el Servidor de autorización a la aplicación o al usuario mediante Actions.

​

Atributos del client grant

Un client grant tiene varios atributos que puede definir para configurar el acceso de la aplicación a las API mediante la Auth0 Management API:

Atributo	Descripción
id	Identificador único del client grant.
audience	Identificador único de la API a la que corresponde el client grant.
client_id	El id único de la aplicación a la que se le concede acceso.
scopes	Una matriz de cadenas que representa los permisos que la aplicación puede solicitar.
authorization_details_types	Una matriz de cadenas que representa tipos de datos de autorización enriquecidos que la aplicación puede solicitar. Este atributo solo se puede especificar para flujos de acceso delegados por el usuario.
subject_type	El tipo de acceso de aplicación que permite el client grant: user: se usa para acceso delegado por el usuario, que corresponde a todos los flujos que generan un token asociado a un usuario final. client: se usa para acceso de máquina, que corresponde al flujo de credenciales del cliente.
allow_all_scopes	Booleano. Indica si se permiten para la aplicación todos los alcances definidos en la API. En el caso de la API, los alcances que se definan en el futuro se permitirán automáticamente.
organization_usage	Determina cómo puede usar la aplicación las organizaciones al acceder a la API mediante el flujo de credenciales del cliente. Los valores posibles son deny, allow o require. Para obtener más información sobre la configuración de la organización, lea Organizaciones para aplicaciones M2M: definir el comportamiento de la organización.
allow_any_organization	Determina si la aplicación puede acceder a cualquier organización al usar el flujo de credenciales del cliente. Para obtener más información sobre la configuración de la organización, lea Organizaciones para aplicaciones M2M: definir el comportamiento de la organización.

​

Crear client grant

Puede crear:

• Permisos por aplicación: Aplique permisos granulares a cada aplicación de su inquilino.
• Permisos predeterminados para aplicaciones de terceros: Aplique permisos predeterminados a todas las aplicaciones de terceros de su inquilino.

Cuando ambos están configurados para la misma API, los permisos por aplicación prevalecen sobre los permisos predeterminados para aplicaciones de terceros.

​

Permisos por aplicación

Auth0 Dashboard

Para configurar los permisos por aplicación con Auth0 Dashboard:

1. Vaya a Dashboard > Applications > APIs y seleccione la API para la que quiere configurar el acceso de la aplicación.
2. Vaya a la pestaña Settings y desplácese hacia abajo hasta Application Access Policy.
   • Configure User-Delegated Access como No apps allowed, Per-app authorization o All apps allowed.
     • No apps allowed: Ninguna aplicación puede obtener un token de acceso para la API.
     • Per-app authorization: Solo las aplicaciones con un client grant definido pueden obtener un token de acceso para la API.
     • All apps allowed: Cualquier aplicación de su inquilino puede obtener un token de acceso para la API.
   • Configure Client Access como Per-app authorization o All apps allowed.
     • Per-app authorization: Solo las aplicaciones con un client grant definido pueden obtener un token de acceso para la API.
     • All apps allowed: Cualquier aplicación de su inquilino puede obtener un token de acceso para la API.
3. Seleccione Save para guardar la configuración de Application Access Policy.

Para los permisos por aplicación, debe autorizar el acceso a la API individualmente para cada aplicación.

1. Vaya a Applications > APIs y seleccione la API.
2. Vaya a la pestaña Application Access.
3. Desplácese hasta la aplicación, seleccione Edit y luego Grant Access para User-Delegated Access y/o Client Access. Después, seleccione los permisos que desee.
4. Seleccione Save.

Management API

Realice una solicitud POST al endpoint /client-grants con el siguiente cuerpo de la solicitud:

curl --location 'https://{yourDomain}/api/v2/client-grants' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
--data '{
    "client_id": "{CLIENT_ID}",
    "audience": "https://api.my-service.com",
    "scope": [
        "read:item"
    ],
    "authorization_details_types":["payment"],
    "subject_type": "user"
}'

​

Permisos predeterminados para aplicaciones de terceros

Las aplicaciones de terceros siempre requieren un client grant explícito para acceder a cualquier API, incluso cuando la política de acceso de la API está configurada en Allow All. Para simplificar la administración si tiene muchas aplicaciones de terceros o usa Dynamic Client Registration, configure grants o permisos predeterminados que se apliquen automáticamente a todas las aplicaciones de terceros.

Un client grant predeterminado para terceros usa el atributo default_for en lugar de client_id. También puede definir permisos por aplicación creando un client grant con un client_id específico. Cuando ambos existen para la misma API, los permisos por aplicación tienen prioridad.

Las API del sistema (la Management API, My Account API y otras) no admiten client grants predeterminados para terceros. No es posible conceder a aplicaciones de terceros acceso a las API del sistema.

Los atributos default_for y client_id son mutuamente excluyentes. Cada client grant debe especificar exactamente uno de ellos.

Para obtener información sobre cómo configurar políticas de acceso a API para aplicaciones de terceros, consulte Configurar aplicaciones de terceros.

Auth0 Dashboard

Para configurar permisos predeterminados para aplicaciones de terceros con Auth0 Dashboard:

1. Vaya a Dashboard > Applications > APIs y seleccione la API para la que desea configurar el acceso de las aplicaciones.
2. Vaya a la pestaña Settings y desplácese hacia abajo hasta Default Permissions for Third-Party Applications.
   • Configure User-Delegated Access y/o Client Access como Unauthorized, Authorized o All.
     • Unauthorized: No se permite ningún permiso.
     • Authorized: Seleccione los permisos que correspondan.
     • All: Incluye los permisos actuales y futuros.
3. Seleccione Save.

Management API

Haga una solicitud POST al endpoint /api/v2/client-grants con el siguiente cuerpo de solicitud:

cURL

curl --request POST \
    --url 'https://YOUR_DOMAIN/api/v2/client-grants' \
    --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
    --header 'Content-Type: application/json' \
    --data '{
        "default_for": "third_party_clients",
        "audience": "https://api.example.com",
        "scope": ["read:items", "write:items"],
        "subject_type": "user"
}'

Parámetro	Tipo	Descripción
default_for	String	Especifica si este grant se aplica automáticamente a determinados tipos de aplicaciones. Establézcalo en third_party_clients para garantizar que todas las aplicaciones de terceros tengan acceso a esta API de forma predeterminada.
audience	String	El identificador único (URI) de la API para la que se crea el grant.
scope	Array	Una lista de permisos (alcances) permitidos como parte de este grant.
subject_type	String	Define el tipo de acceso de la aplicación permitido para la API: user: Se usa para el acceso delegado por el usuario, que corresponde a flows que generan un token asociado a un usuario final. client: Se usa para acceso de máquina a máquina, como el flujo de credenciales del cliente.

​

Actualizar el client grant

Para actualizar un client grant existente, realiza una solicitud PATCH a /client-grants/{id}:

curl --location --request PATCH 'https://{yourDomain}/api/v2/client-grants/{CLIENT_GRANT_ID}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
--data '{
    "scope": [
        "read:item",
        "update:item"
    ],
    "authorization_details_types":["payment", "credits_transfer"]
}'

​

Eliminar client grant

Para eliminar un client grant, realiza una solicitud DELETE a /client-grants/{id}:

curl --location --request DELETE 'https://{yourDomain}/api/v2/client-grants/{CLIENT_GRANT_ID}' \
--header 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}'

​

Obtener client grants

También puede consultar y paginar la colección client-grants mediante parámetros como client_id, audience o subject_type:

curl --request GET \
--url 'https://{yourDomain}/api/v2/client-grants?subject_type=user&audience=https%3A%2F%2Fapi.my-service.com' \
--header 'Authorization: Bearer {YOUR_MANAGEMENT_API_TOKEN}' \
--header 'Accept: application/json'

​

Más información

• Políticas de acceso a la API para aplicaciones
• Tipos de concesión de aplicaciones
• Aplicaciones de terceros
• Configurar aplicaciones de terceros