Accès des applications aux API : autorisations client

Gérez les applications qui peuvent accéder à vos API et les permissions qu’elles détiennent à l’aide d’autorisations client pour les flux délégués par l’utilisateur et machine à machine.

Dans Auth0, vous pouvez contrôler la façon 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 accorde à 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 de permissions, comme des scopes 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’autorisation client. Pour savoir comment définir et gérer les autorisations client, consultez Créer une autorisation client.

​

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

Lorsque vous configurez la politique d’accès des applications d’une API sur require_client_grant, seules les applications pour lesquelles une autorisation client est définie peuvent obtenir un jeton d’accès à l’API. L’autorisation client détermine les permissions 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 lorsque vous configurez la politique d’accès des applications d’une API.

​

Exemple : API de médias sociaux

Pour illustrer comment les autorisations client appliquent le principe du moindre privilège, supposons que vous disposiez d’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 read:posts et write:posts.

Cette autorisation client sert maintenant de limite maximale stricte. Même si l’API de médias sociaux comporte 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

Dans les cas d’accès utilisateur et d’accès client, les autorisations client définissent l’ensemble final des autorisations 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 applicatif 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 autorisations machine-à-machine.
• Lorsque vous définissez subject_type sur user, vous définissez ses autorisations 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 informations d’identification du 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 autorisations 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 autorisations maximales que l’application peut demander à l’API. Les autorisations finales dans le jeton d’accès émis à l’application au nom de l’utilisateur correspondent à l’intersection des autorisations : Demandées par l’application Autorisées par l’autorisation client Autorisées par les politiques de contrôle d’accès basé sur les rôles pour l’utilisateur Auxquelles l’utilisateur final a consenti, le cas échéant. Pour en savoir plus sur les flux d’accès délégué par l’utilisateur, consultez Flux d’authentification et d’autorisation. Les flux d’accès délégué par l’utilisateur n’incluent pas le Client Credentials Flow.

Vous pouvez modifier les scopes finaux accordés par le serveur d’autorisation à l’application ou à l’utilisateur à l’aide de Actions.

​

Attributs du autorisation client

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

Attribut	Description
id	Identifiant unique du autorisation client.
audience	Identifiant unique de l’API à laquelle le autorisation client s’applique.
client_id	ID unique de l’application à laquelle l’accès est accordé.
scopes	Tableau de chaînes représentant les permissions 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 spécifié que pour les flux d’accès délégué par l’utilisateur.
subject_type	Type d’accès à l’application autorisé par le 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, ce qui correspond au Client Credentials Flow.
allow_all_scopes	Booléen. Indique si tous les scopes définis pour l’API sont autorisés pour l’application. Pour cette API, les scopes définis ultérieurement sont automatiquement autorisés.
organization_usage	Détermine comment l’application peut utiliser Organizations lorsqu’elle accède à l’API au moyen du Client Credentials Flow. Les valeurs possibles sont : deny, allow ou require. Pour en savoir plus sur les paramètres d’Organization, consultez Organizations for M2M Applications: Define Organization Behavior.
allow_any_organization	Détermine si l’application peut accéder à n’importe quelle Organization lorsqu’elle utilise le Client Credentials Flow. Pour en savoir plus sur les paramètres d’Organization, consultez Organizations for M2M Applications: Define Organization Behavior.

​

Créer une autorisation client

Vous pouvez créer :

• Permissions par application : appliquez des permissions granulaires à chaque application de votre tenant.
• Autorisation par défaut pour les applications tierces : appliquez des permissions par défaut à toutes les applications tierces de votre tenant.

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

​

Permissions par application

Auth0 Dashboard

Pour configurer les permissions par application dans l’Auth0 Dashboard :

1. Accédez à Dashboard > Applications > APIs et sélectionnez l’API pour laquelle vous souhaitez configurer l’accès des applications.
2. Allez à l’onglet Settings et faites défiler 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 est 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 est 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 permissions 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. Allez à l’onglet Application Access.
3. Faites défiler jusqu’à l’application, sélectionnez Edit, puis Grant Access pour User-Delegated Access et/ou Client Access. Sélectionnez ensuite les permissions souhaitées.
4. Sélectionnez Save.

Management API

Effectuez une requête POST vers le 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"
}'

​

autorisation par défaut pour les applications tierces

Les applications tierces exigent 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 tiers par défaut utilise l’attribut default_for au lieu d’un client_id. Vous pouvez aussi définir des permissions par application en créant une autorisation client avec un client_id précis. Lorsque les deux existent pour la même API, les permissions par application ont préséance.

Les API système (la Management API, My Account API et d’autres) ne prennent pas en charge les autorisations client tiers par défaut. Les applications tierces ne peuvent pas obtenir d’accès aux API système.

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

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

Auth0 Dashboard

Pour configurer les permissions par défaut pour les applications tierces à l’aide de l’Auth0 Dashboard :

1. Accédez à Dashboard > Applications > APIs et sélectionnez l’API pour laquelle vous souhaitez configurer l’accès de l’application.
2. Allez à l’onglet Settings et faites défiler la page jusqu’à Default Permissions for Third-Party Applications.
   • Configurez User-Delegated Access et/ou Client Access à Unauthorized, Authorized ou All.
     • Unauthorized : aucune permission n’est autorisée.
     • Authorized : sélectionnez les permissions voulues.
     • All : inclut les permissions existantes et futures.
3. Sélectionnez Save.

Management API

Faites une requête POST au endpoint /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"
}'

Paramètre	Type	Description
default_for	String	Indique si cette autorisation s’applique automatiquement à certains types d’applications. Définissez-la sur third_party_clients pour vous assurer que toutes les applications tierces ont 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	Une liste de permissions (scopes) autorisées dans le cadre de cette autorisation.
subject_type	String	Définit le type d’accès de l’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 token associé à un utilisateur final. client : utilisé pour l’accès machine à machine, comme le Client Credentials Flow.

​

Mettre à jour une autorisation client

Pour mettre à jour une autorisation client existante, effectuez une requête PATCH vers /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, envoyez une requête DELETE à /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 page 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'

​

Pour en savoir plus

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