Accès des applications aux API : autorisations client

Découvrez les autorisations client

Dans Auth0, vous pouvez contrôler la manière dont les applications accèdent à vos API à l’aide des politiques d’accès des applications aux API et des autorisations client.

Une autorisation client permet d’accorder à une application un accès précis à une API. Elle associe :

• Une API identifiée par son audience ou son identifiant unique.
• Une application identifiée par son client_id.
• Une liste d’autorisations, comme des portées d’accès et/ou des authorization_details_types, que l’application est autorisée à demander pour l’audience indiquée.

Pour en savoir plus sur la liste des attributs que vous pouvez définir dans une autorisation client, consultez Attributs d’une autorisation client. Pour savoir comment définir et gérer des autorisations client, consultez Créer une autorisation client.

​

Politiques d’accès des applications aux API et autorisations client

Lorsque vous configurez la politique d’accès des applications d’une API avec require_client_grant, seules les applications pour lesquelles une autorisation client a été définie peuvent obtenir un jeton d’accès à l’API. L’autorisation client établit les autorisations maximales qu’une application peut demander à l’API, conformément au principe du moindre privilège. Par conséquent, Auth0 recommande d’utiliser require_client_grant lors de la configuration de la politique d’accès des applications d’une API.

​

Exemple : API de médias sociaux

Pour illustrer comment les autorisations client s’inscrivent dans le principe du moindre privilège, supposons que vous ayez une API de médias sociaux avec les autorisations suivantes : read:posts, write:posts, read:friends et delete:posts. Vous créez une application et définissez une autorisation client avec les autorisations suivantes : read:posts et write:posts.

Cette autorisation client sert maintenant de plafond strict. Même si l’API de médias sociaux comprend d’autres autorisations, votre application ne pourra jamais demander ni obtenir read:friends ou delete:posts.

​

Accès délégué par l’utilisateur vs accès client

Pour l’accès utilisateur et l’accès client, les autorisations client définissent l’ensemble final de permissions qui contrôlent l’accès d’une application à une API. L’attribut subject_type de l’autorisation client détermine le type d’accès d’application autorisé pour une API.

Une application peut avoir jusqu’à deux autorisations client pour une même API :

• Lorsque vous définissez subject_type sur client, vous définissez ses permissions machine à machine.
• Lorsque vous définissez subject_type sur user, vous définissez ses permissions pour agir au nom de l’utilisateur.

Le tableau suivant explique comment les autorisations client contrôlent l’accès des applications aux API selon le type de flux d’accès :

Type d’accès	Attribut subject_type	Description
Accès par identifiants client (accès machine à machine)	Définissez subject_type sur client.	L’autorisation client autorise directement l’application à accéder à l’API en son propre nom plutôt qu’au nom de l’utilisateur final. Les permissions que vous définissez dans l’autorisation client sont celles que l’application est autorisée à recevoir dans le jeton d’accès.
Accès délégué par l’utilisateur	Définissez subject_type sur user.	L’autorisation client définit les permissions maximales que l’application peut demander à l’API. Les permissions finales dans le jeton d’accès délivré à l’application au nom de l’utilisateur correspondent à l’intersection des permissions : Demandées par l’application Autorisées par l’autorisation client Autorisées par les politiques de contrôle d’accès fondé sur les rôles pour l’utilisateur Approuvées par l’utilisateur final, s’il y a lieu. Pour en savoir plus sur les flux d’accès délégué par l’utilisateur, consultez Authentication and Authorization Flows. Les flux d’accès délégué par l’utilisateur n’incluent pas le flux Client Credentials.

Vous pouvez modifier les portées finales accordées par le serveur d’autorisation à l’application ou à l’utilisateur à l’aide d’Actions.

​

Attributs d’une autorisation client

Une autorisation client comporte plusieurs attributs que vous pouvez définir pour configurer l’accès d’une application aux API à l’aide de l’API de gestion Auth0 :

Attribut	Description
id	Identifiant unique de l’autorisation client.
audience	Identifiant unique de l’API à laquelle l’autorisation client s’applique.
client_id	Identifiant unique de l’application à laquelle l’accès est accordé.
scopes	Tableau de chaînes représentant les autorisations que l’application peut demander.
authorization_details_types	Tableau de chaînes représentant les types de données d’autorisation enrichies que l’application peut demander. Cet attribut ne peut être précisé que pour les flux d’accès délégué par l’utilisateur.
subject_type	Type d’accès à l’application permis par l’autorisation client : user : utilisé pour l’accès délégué par l’utilisateur, ce qui correspond à tous les flux qui génèrent un jeton associé à un utilisateur final. client : utilisé pour l’accès machine à machine, ce qui correspond au flux Client Credentials.
allow_all_scopes	Booléen. Indique si toutes les portées définies pour l’API sont autorisées pour l’application. Pour l’API, les portées définies ultérieurement sont automatiquement autorisées.
organization_usage	Détermine comment l’application peut utiliser les organisations lorsqu’elle accède à l’API au moyen du flux Client Credentials. Les valeurs possibles sont : deny, allow ou require. Pour en savoir plus sur les paramètres des organisations, consultez Organizations for M2M Applications: Define Organization Behavior.
allow_any_organization	Détermine si l’application peut accéder à n’importe quelle organisation lorsqu’elle utilise le flux Client Credentials. Pour en savoir plus sur les paramètres des organisations, consultez Organizations for M2M Applications: Define Organization Behavior.

​

Créer une autorisation client

Vous pouvez créer :

• Autorisations par application : Définissez des autorisations granulaires pour chaque application de votre locataire.
• Autorisations par défaut pour les applications tierces : Définissez des autorisations par défaut pour toutes les applications tierces de votre locataire.

Lorsque les deux existent pour la même API, les autorisations par application ont priorité sur les autorisations par défaut pour les applications tierces.

​

Autorisations par application

Tableau de bord Auth0

Pour configurer les autorisations par application à l’aide du tableau de bord Auth0 :

1. Accédez à Dashboard > Applications > APIs et sélectionnez l’API pour laquelle vous souhaitez configurer l’accès des applications.
2. Ouvrez l’onglet Settings et faites défiler la page jusqu’à Application Access Policy.
   • Réglez User-Delegated Access sur No apps allowed, Per-app authorization ou All apps allowed.
     • No apps allowed : Aucune application ne peut obtenir de jeton d’accès pour l’API.
     • Per-app authorization : Seules les applications pour lesquelles une autorisation client a été définie peuvent obtenir un jeton d’accès pour l’API.
     • All apps allowed : Toute application de votre tenant peut obtenir un jeton d’accès pour l’API.
   • Réglez Client Access sur Per-app authorization ou All apps allowed.
     • Per-app authorization : Seules les applications pour lesquelles une autorisation client a été définie peuvent obtenir un jeton d’accès pour l’API.
     • All apps allowed : Toute application de votre tenant peut obtenir un jeton d’accès pour l’API.
3. Sélectionnez Save pour enregistrer les paramètres de Application Access Policy.

Pour les autorisations par application, vous devez autoriser individuellement l’accès à l’API pour chaque application.

1. Accédez à Applications > APIs et sélectionnez l’API.
2. Ouvrez l’onglet Application Access.
3. Faites défiler la page jusqu’à l’application, sélectionnez Edit, puis Grant Access pour User-Delegated Access et/ou Client Access. Sélectionnez ensuite les autorisations voulues.
4. Sélectionnez Save.

API de gestion

Envoyez une requête POST au point de terminaison /client-grants avec le corps de requête suivant :

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"
}'

​

Autorisations par défaut pour les applications tierces

Les applications tierces nécessitent toujours une autorisation client explicite pour accéder à une API, même lorsque la politique d’accès de l’API est définie sur Allow All. Pour simplifier la gestion lorsque vous avez un grand nombre d’applications tierces ou que vous utilisez Dynamic Client Registration, configurez des autorisations ou des permissions par défaut qui s’appliquent automatiquement à toutes les applications tierces.

Une autorisation client tierce par défaut utilise l’attribut default_for plutôt qu’un client_id. Vous pouvez aussi définir des permissions propres à une application en créant une autorisation client avec un client_id précis. Lorsque les deux existent pour la même API, les permissions propres à l’application ont préséance.

Les API système (la Management API, la My Account API, entre autres) ne prennent pas en charge les autorisations client tierces par défaut. L’accès aux API système ne peut pas être accordé aux applications tierces.

Les attributs default_for et client_id s’excluent mutuellement. Chaque autorisation client doit préciser exactement l’un ou l’autre.

Pour savoir comment configurer les politiques d’accès aux API pour les applications tierces, consultez Configure Third-Party Applications.

Tableau de bord Auth0

Pour configurer les permissions par défaut des applications tierces à l’aide du tableau de bord Auth0 :

1. Accédez à Dashboard > Applications > APIs et sélectionnez l’API pour laquelle vous voulez configurer l’accès des applications.
2. Ouvrez l’onglet Settings et faites défiler la page jusqu’à Default Permissions for Third-Party Applications.
   • Réglez User-Delegated Access et/ou Client Access sur Unauthorized, Authorized ou All.
     • Unauthorized : aucune permission n’est accordée.
     • Authorized : sélectionnez les permissions voulues.
     • All : inclut les permissions actuelles et futures.
3. Sélectionnez Save.

Management API

Envoyez une requête POST au point de terminaison /api/v2/client-grants avec le corps de requête suivant :

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"
}'

Parameter	Type	Description
default_for	String	Indique si cette autorisation est appliquée automatiquement à certains types d’applications. Définissez-la sur third_party_clients pour que toutes les applications tierces aient accès à cette API par défaut.
audience	String	L’identifiant unique (URI) de l’API pour laquelle l’autorisation est créée.
scope	Array	La liste des permissions (portées) autorisées dans le cadre de cette autorisation.
subject_type	String	Définit le type d’accès d’application autorisé pour l’API : user : utilisé pour l’accès délégué par l’utilisateur, ce qui correspond aux flux qui génèrent un jeton associé à un utilisateur final. client : utilisé pour l’accès machine à machine, comme le flux Client Credentials.

​

Mettre à jour l’autorisation client

Pour mettre à jour une autorisation client existante, faites une requête PATCH à /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"]
}'

​

Supprimer une autorisation client

Pour supprimer une autorisation client, faites une requête DELETE vers /client-grants/{id} :

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

​

Récupérer les autorisations client

Vous pouvez aussi interroger les collections client-grants et les parcourir par page à l’aide de paramètres comme client_id, audience ou 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'

​

En savoir plus

• Politiques d’accès aux API pour les applications
• Types d’autorisation des applications
• Applications tierces
• Configurer des applications tierces