Enregistrer des applications avec CIMD

Découvrez comment enregistrer des applications avec le Client ID Metadata Document (CIMD).

Pour en savoir plus sur l’enregistrement au moyen du Client ID Metadata Document (CIMD), notamment ses avantages, ses cas d’utilisation et le fonctionnement du CIMD manuel et dynamique, consultez Aperçu du CIMD.

​

Prérequis

Avant d’enregistrer une application au moyen d’un CIMD, assurez-vous de respecter les exigences suivantes :

​

Configuration du locataire et de l’application

Seules les applications tierces peuvent être enregistrées comme clients CIMD :

• Configurer la politique d’accès à l’API : les applications tierces nécessitent des autorisations client explicites pour accéder aux API.
• Promouvoir les connexions au niveau du domaine : rendez les connexions disponibles au niveau du domaine ou du locataire pour authentifier vos utilisateurs, une condition requise pour les applications tierces.
• Profil de compatibilité du paramètre de ressource (facultatif) : pour les clients MCP, nous recommandons d’activer ce profil dans vos paramètres du locataire. Cela permet au serveur d’autorisation de traiter les requêtes propres aux ressources (RFC 8707) en vérifiant le paramètre resource si audience n’est pas fourni.

​

Types de clients pris en charge

Vous pouvez enregistrer les types de clients suivants avec CIMD dans Auth0 :

• Type d’application : il doit s’agir d’une application native ou d’une application Web traditionnelle.
• Application tierce : il doit s’agir d’une application tierce (is_first_party: false), soumise à des contrôles de sécurité renforcés.

​

Méthodes d’authentification prises en charge

Les clients CIMD ne peuvent pas utiliser de méthodes d’authentification fondées sur des secrets symétriques partagés, comme client_secret_post, client_secret_basic ou client_secret_jwt.

Selon que le client est public ou confidentiel, Auth0 prend en charge les méthodes d’authentification suivantes pour les clients CIMD :

• Clients publics :
  • Aucune authentification du client n’est requise au terminal de jeton; définissez token_endpoint_auth_method sur none dans les métadonnées du client
  • Doivent utiliser la clé de preuve pour l’échange de code (PKCE) pour les flux d’autorisation
• Clients confidentiels :
  • Seule l’authentification Private Key JWT est prise en charge; définissez token_endpoint_auth_method sur private_key_jwt dans les métadonnées du client
  • Fournissez un jwks_uri pour héberger les clés publiques. Le jwks_uri doit avoir exactement la même origine (schéma, hôte et port) que l’URL CIMD. Pour en savoir plus, consultez les règles de validation JSON CIMD.

L’authentification Private Key JWT est offerte uniquement aux clients d’entreprise. Pour en savoir plus sur les forfait Enterprise, consultez Pricing ou communiquez avec Auth0 Sales.

Les clients CIMD manuels qui utilisent l’authentification Private Key JWT doivent mettre en place la rotation des clés en générant une nouvelle paire de clés avec un nouveau kid unique.

​

Activer l’enregistrement CIMD

Activez l’enregistrement CIMD à l’aide d’Auth0 Dashboard ou de Management API.

Auth0 Dashboard

• Activer la prise en charge de CIMD : activez le bouton Client ID Metadata Document Registration dans vos paramètres du locataire pour signaler la prise en charge de CIMD dans les métadonnées du serveur d’autorisation Auth0. Les clients peuvent ainsi détecter automatiquement cette fonctionnalité lors de la connexion.
  • Accédez à Settings > Advanced et faites défiler jusqu’à la section Settings.
  • Activez Client ID Metadata Document Registration.
• Prise en charge de l’enregistrement CIMD dynamique : activez le bouton Dynamic CIMD Registration sous Client ID Metadata Document Registration dans vos paramètres du locataire. Lorsque cette option est activée, les nouveaux clients peuvent s’enregistrer eux-mêmes au moyen du CIMD dynamique. Lorsqu’elle est désactivée, les nouveaux clients ne peuvent plus s’enregistrer eux-mêmes de cette façon, mais les clients CIMD dynamiques existants continuent de fonctionner normalement.

Management API

Le bouton Client ID Metadata Document Registration correspond à la propriété client_id_metadata_document_supported, et Dynamic CIMD Registration, à client_id_metadata_document_dynamic_registration_supported, toutes deux sur le terminal PATCH /api/v2/tenants/settings.

client_id_metadata_document_dynamic_registration_supported exige que client_id_metadata_document_supported soit true, et client_id_metadata_document_supported ne peut pas être désactivé tant que client_id_metadata_document_dynamic_registration_supported est true. Dans les deux cas, toute tentative renvoie une erreur 400 Bad Request, par exemple :

{
  "statusCode": 400,
  "error": "Bad Request",
  "errorCode": "validation_error",
  "message": "client_id_metadata_document_dynamic_registration_supported cannot be enabled when client_id_metadata_document_supported is false. Enable client_id_metadata_document_supported in the same request or beforehand."
}

Si votre locataire n’a pas accès à l’enregistrement CIMD dynamique, toute tentative de définir client_id_metadata_document_dynamic_registration_supported renvoie une erreur 403 Forbidden :

{
  "statusCode": 403,
  "error": "Forbidden",
  "errorCode": "not_entitled",
  "message": "Updating the client_id_metadata_document_dynamic_registration_supported setting is not allowed for this tenant."
}

​

Enregistrer des applications avec un CIMD

Lors de la création d’une application dans Auth0, enregistrez-la manuellement au moyen d’un CIMD à l’aide de l’Auth0 Dashboard ou de la Management API.

Lorsque l’enregistrement CIMD dynamique est activé, les applications s’enregistrent elles-mêmes auprès d’Auth0 lors de l’exécution, au moyen de leur URL CIMD. Pour activer l’enregistrement CIMD dynamique, consultez Activer l’enregistrement CIMD.

Auth0 Dashboard

Pour enregistrer une application avec un CIMD manuel à l’aide de l’Auth0 Dashboard :

1. Accédez à Applications > Applications.
2. Sélectionnez Create Application > Import from URL.
3. Entrez l’URL du CIMD. Ensuite, sélectionnez Preview. Auth0 valide l’URL du CIMD selon les règles de validation des URL CIMD.
4. Si l’URL du CIMD est valide, Auth0 charge le CIMD et le valide selon les règles de validation JSON CIMD. Prévisualisez les métadonnées du client et corrigez toute erreur de validation.
5. Sélectionnez Create.

Management API

Pour enregistrer une application avec un CIMD manuel à l’aide de la Management API :

1. Prévisualiser le CIMD : validez l’URL du CIMD et le CIMD avec Auth0
2. Enregistrer le client CIMD : enregistrez l’application comme client CIMD dans Auth0

​

Prévisualiser le CIMD

Pour prévisualiser le CIMD, effectuez une requête POST vers le point de terminaison /api/v2/clients/cimd/preview et transmettez les éléments suivants :

• external_client_id : l’URL du CIMD de l’application

Le point de terminaison /api/v2/clients/cimd/preview charge et valide le external_client_id ainsi que le CIMD à cette URL, ce qui vous permet de prévisualiser les métadonnées du client et toute erreur de validation.

La requête suivante transmet https://mcpserver.example.com/client.json comme external_client_id au point de terminaison /api/v2/clients/cimd/preview :

Auth0 CLI

Vous utilisez l’Auth0 CLI? Si ce n’est pas déjà fait, configurez et authentifiez votre session CLI avant d’exécuter cette commande.

auth0 api post "clients/cimd/preview" \
  --data '{
    "external_client_id": "https://mcpserver.example.com/client.json"
  }'

cURL

curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/clients/cimd/preview' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "external_client_id": "https://mcpserver.example.com/client.json"
  }'

En cas de réussite, Auth0 renvoie une réponse semblable à celle-ci :

{
  "mapped_fields": {
    "external_client_id": "https://mcpserver.example.com/client.json",
    "redirect_uris": ["https://mcpserver.example.com/callback"],
    "client_name": "MCP Tool Server",
    "logo_uri": "https://mcpserver.example.com/logo.png",
    "grant_types": ["authorization_code"],
    "scope": "read write"
  },
  "validation": {
    "valid": true,
    "warnings": [
      "Grant type not supported: 'implicit'",
      "Property not supported: 'nfv_token_signed_response_alg'"
    ]
  }
}

Si un client est déjà enregistré avec le external_client_id que vous avez prévisualisé, la réponse inclut également client_id et external_metadata_created_by :

{
  "mapped_fields": { "..." },
  "validation": { "valid": true, "violations": [], "warnings": [] },
  "client_id": "YOUR_CLIENT_ID",
  "external_metadata_created_by": "client"
}

external_metadata_created_by indique comment le client existant a été enregistré :

Valeur	Description
client	L’application s’est enregistrée dynamiquement au moyen de son URL CIMD lors de l’exécution.
admin	Un administrateur du locataire a enregistré manuellement l’application à partir de son URL CIMD.

​

Enregistrer le client CIMD

Une fois les métadonnées du client vérifiées, effectuez une requête POST vers le point de terminaison /api/v2/clients/cimd/register et transmettez les éléments suivants :

• external_client_id : l’URL du CIMD de l’application

Le point de terminaison /api/v2/clients/cimd/register enregistre l’application CIMD. Si un client CIMD manuel existe déjà avec ce external_client_id, Auth0 met à jour le client existant au lieu d’en créer un nouveau. Si un client CIMD dynamique existe déjà avec ce external_client_id, la requête échoue avec une erreur 409 Conflict.

La requête suivante transmet https://mcpserver.example.com/client.json comme external_client_id au point de terminaison /api/v2/clients/cimd/register :

Auth0 CLI

auth0 api post "clients/cimd/register" \
  --data '{
    "external_client_id": "https://mcpserver.example.com/client.json"
  }'

cURL

curl --request POST \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/clients/cimd/register' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "external_client_id": "https://mcpserver.example.com/client.json"
  }'

En cas de réussite, Auth0 renvoie une réponse semblable à celle-ci :

Location: /api/v2/clients/YOUR_CLIENT_ID
{
  "client_id": "YOUR_CLIENT_ID",
  "mapped_fields": {
    "external_client_id": "https://mcpserver.example.com/client.json",
    "redirect_uris": ["https://mcpserver.example.com/callback"],
    "client_name": "MCP Tool Server",
    "logo_uri": "https://mcpserver.example.com/logo.png",
    "grant_types": ["authorization_code"],
    "scope": "read write"
  },
  "validation": {
    "valid": true,
    "warnings": [
      "Grant type not supported: 'implicit'",
      "Property not supported: 'nfv_token_signed_response_alg'"
    ]
  }
}

​

Actualiser les métadonnées du client

Les clients CIMD manuels et les clients CIMD dynamiques n’actualisent pas les métadonnées du client de la même façon.

Clients CIMD manuels

Pour les clients CIMD manuels, vous pouvez actualiser manuellement les métadonnées du client. Auth0 récupère alors les métadonnées du client à jour à partir du CIMD; vous pouvez ensuite les prévisualiser et les sauvegarder.

Lorsque vous actualisez les métadonnées du client, Auth0 met à jour app_type et grant_types pour qu’ils correspondent aux valeurs du CIMD hébergé. Pour en savoir plus sur les champs CIMD, consultez Règles de validation JSON CIMD.

Dans Auth0 Dashboard :

1. Accédez à Applications > Applications et sélectionnez votre client CIMD.
2. Dans le coin supérieur droit, sélectionnez Refresh Client Metadata (Actualiser les métadonnées du client).
3. Sélectionnez Refresh Preview (Actualiser l’aperçu) pour prévisualiser les plus récentes métadonnées du client dans le CIMD. Examinez les avertissements ou erreurs de validation, le cas échéant.
4. Sélectionnez Sauvegarder.

Clients CIMD dynamiques

Pour les clients CIMD dynamiques, Auth0 récupère automatiquement le document CIMD le plus récent dans les cas suivants :

• Lorsque le client effectue une requête OAuth auprès d’Auth0 lors de la première découverte
• Lorsqu’aucune copie du CIMD n’est en cache
• Lorsqu’un élément de la requête OAuth ne passe pas la validation, par exemple un redirect_uri qui ne correspond pas

Contrairement au CIMD manuel, où un administrateur du locataire examine et approuve les mises à jour des métadonnées, le CIMD dynamique récupère de nouveau, valide et applique automatiquement les métadonnées actualisées et les changements de clés pour chaque locataire qui utilise ce client; aucune intervention n’est requise de la part des locataires.

Les clients fréquemment utilisés sont actualisés périodiquement en arrière-plan avant que leurs données ne deviennent périmées, afin que les utilisateurs actifs ne subissent pas de délai de connexion supplémentaire en attendant la récupération des métadonnées en temps réel. Les clients moins utilisés ne sont actualisés qu’au besoin, de manière réactive.

​

Fréquences d’actualisation distinctes pour les métadonnées et les clés

Les métadonnées CIMD (nom, URI de redirection, etc.) et les clés de connexion (JWKS) s’actualisent selon des calendriers différents, puisque la rotation des clés est beaucoup plus fréquente que la modification des métadonnées. Ainsi, une rotation de clés n’entraîne pas de récupération complète inutile des métadonnées, et inversement.

​

Résolution automatique des clés

Si Auth0 ne trouve pas une clé de connexion (kid) dont il a besoin lors de la validation du jeton, il récupère automatiquement, au besoin, les clés les plus récentes à partir du jwks_uri du client, plutôt que d’exiger une mise à jour manuelle.

​

Gestion des échecs

Si l’URL des métadonnées ou les clés d’un client deviennent temporairement inaccessibles ou invalides, Auth0 espace automatiquement ses tentatives plutôt que de réessayer immédiatement à chaque requête. Si des métadonnées validées sont bien récupérées, mais qu’un élément de la requête demeure invalide, Auth0 rejette cette requête d’autorisation sans récupérer de nouveau le document.

​

Obtenir le client CIMD

Pour obtenir un client CIMD, faites une requête GET vers le terminal /v2/clients/{clientId}, où {clientID} correspond à l’ID client généré par Auth0 attribué au client CIMD :

Auth0 CLI

auth0 api get "clients/YOUR_CLIENT_ID"

cURL

curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/clients/YOUR_CLIENT_ID' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --header 'Content-Type: application/json'

Sinon, transmettez le external_client_id ou l’URL CIMD en paramètre de requête au terminal /v2/clients :

Auth0 CLI

auth0 api get "clients" \
  -q "external_client_id=https://mcpserver.example.com/client.json"

cURL

curl --request GET \
  --url 'https://YOUR_AUTH0_DOMAIN/api/v2/clients?external_client_id=https://mcpserver.example.com/client.json' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --header 'Content-Type: application/json'

Si la requête réussit, Auth0 renvoie une réponse qui contient la configuration du client CIMD avec des champs comme external_client_id, name, callbacks, token_endpoint_auth_method, external_metadata_created_by, external_metadata_status, et plus encore.

​

Statut des métadonnées CIMD

Chaque client CIMD comprend un champ external_metadata_status qui indique si Auth0 a pu résoudre le document de métadonnées hébergé du client :

Valeur	Description
available	Le document de métadonnées a été résolu. Les clients CIMD manuels indiquent toujours available, puisque c’est un administrateur du locataire qui détermine quand les métadonnées sont actualisées. Pour les clients CIMD dynamiques, available reflète la résolution à un moment donné et ne garantit pas que les champs retournés correspondent à la version la plus récente. Auth0 peut fournir une copie des métadonnées mise en cache récemment plutôt que de les récupérer de nouveau à chaque requête.
unavailable	Auth0 n’a pas pu résoudre le document de métadonnées du client, par exemple parce que l’URL CIMD hébergée est temporairement inaccessible ou renvoie un contenu non valide. Tant que le document est indisponible, seuls name et app_type sont retournés, avec leurs dernières valeurs connues (périmées); les autres champs dérivés des métadonnées sont omis. Les requêtes d’authentification pour ce client échouent jusqu’à ce que les métadonnées puissent de nouveau être résolues.

Un client CIMD dynamique dont le statut est external_metadata_status: "unavailable" peut se rétablir de lui-même dès que son URL de métadonnées redevient accessible. Auth0 résout de nouveau les métadonnées automatiquement lors d’une requête d’authentification subséquente, sans aucune intervention manuelle. Si le statut demeure unavailable pendant une période prolongée, envisagez de supprimer le client plutôt que d’attendre indéfiniment.

Pour diagnostiquer le statut des métadonnées CIMD, vous pouvez envoyer une requête POST au terminal /api/v2/clients/cimd/preview. Si l’URL est accessible, mais que le document de métadonnées CIMD n’est pas valide, Auth0 renverra des erreurs de validation.

​

Mettre à jour le client CIMD

Vous pouvez mettre à jour les champs de la base de données Auth0 pour un client CIMD enregistré. La mise à jour du client CIMD dans Auth0 ne met pas automatiquement à jour le CIMD hébergé sur le domaine de l’application.

Vous pouvez uniquement mettre à jour les champs suivants pour les clients CIMD. Les clients CIMD dynamiques font l’objet de restrictions supplémentaires : vous ne pouvez pas mettre à jour app_type, description, grant_types ni name.

Champ	Description
app_type	Le type d’application Auth0. Pour CIMD, cette valeur provient de application_type et se limite à native (pour les applications natives) ou regular_web (pour les applications web).
grant_types	Les types d’octroi OAuth 2.0 autorisés. Pour CIMD, cette valeur se limite à authorization_code et refresh_token. Les autres types sont exclus lors du mappage.
jwt_configuration.alg	L’algorithme utilisé pour signer le ID Token. Comme il s’agit de clients tiers en mode strict, les applications CIMD sont généralement limitées à des algorithmes asymétriques sécurisés comme RS256, RS512 ou PS256.
description	Une description libre du client. Elle est directement mappée à partir des métadonnées CIMD, avec une limite maximale de 140 caractères.
oidc_conformant	Doit être activé pour les clients tiers en mode strict. Cela garantit que le client respecte les spécifications OIDC et, en règle générale, ce champ ne peut pas être modifié pour les clients CIMD.
allowed_origins	Une liste d’URL autorisées pour le Cross-Origin Resource Sharing (CORS). Généralement utilisée par les applications basées sur un navigateur.
web_origins	Une liste d’URL autorisées pour les flux web (p. ex., Silent Authentication).
refresh_token.*	Configuration du comportement du jeton d’actualisation, y compris rotation_type, leeway et divers paramètres de durée de vie. Ces paramètres déterminent combien de temps un jeton d’actualisation demeure valide et s’il est renouvelé lors de son utilisation.
organization_*	Paramètres des flux propres à l’organisation, y compris usage, require_behaviour, discovery_methods et default_organization. Ils déterminent comment le client interagit avec Auth0 Organizations.
client_metadata	Paires clé-valeur arbitraires utilisées pour stocker des renseignements supplémentaires sur le client qui ne correspondent pas aux propriétés Auth0 standard.
require_proof_of_possession	Indique si le client doit fournir une preuve de possession d’une clé, souvent utilisée avec DPoP ou mTLS.

Pour mettre à jour un client CIMD, envoyez une requête PATCH au terminal /v2/clients/{clientId}, où {clientID} est l’ID client généré par Auth0 et attribué au client CIMD :

Auth0 CLI

auth0 api patch "clients/YOUR_CLIENT_ID" \
  --data '{
    "description": "This is my test CIMD client"
  }'

cURL

curl --location --request PATCH \
  'https://YOUR_AUTH0_DOMAIN/api/v2/clients/YOUR_CLIENT_ID' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_MANAGEMENT_API_TOKEN' \
  --data '{
    "description": "This is my test CIMD client"
  }'

​

Considérations relatives à la sécurité

​

Rotation des clés pour les clients CIMD avec l’authentification private_key_jwt

Pour faire la rotation des clés des clients CIMD qui utilisent l’authentification Private Key JWT, générez une nouvelle paire de clés avec un kid nouveau et unique. Si vous faites la rotation de votre clé privée et mettez à jour votre JWKS avec de nouvelles clés sous le même kid, l’enregistrement CIMD d’Auth0 rejettera la nouvelle clé et conservera l’ancienne. Cela garantit que la rotation des clés exige l’ajout explicite de nouvelles clés, plutôt qu’un remplacement silencieux.

Pour les clients CIMD manuels, actualisez l’enregistrement de votre clé dans Auth0 après avoir fait la rotation de vos clés. Pour en savoir plus, consultez Rotation des clés de connexion.

Pour les clients CIMD dynamiques, aucune actualisation manuelle n’est nécessaire : si Auth0 ne trouve pas de clé de connexion (kid) lors de la validation du jeton, il récupère automatiquement les clés les plus récentes à partir du jwks_uri du client.

​

Les informations d’identification ne sont pas prises en charge pour les clients CIMD dynamiques

Un client CIMD dynamique s’authentifie au moyen de clés résolues à partir de son jwks_uri; il ne possède donc aucun enregistrement d’informations d’identification stocké. Toute requête POST envoyée au terminal /v2/clients/{id}/credentials pour un client CIMD dynamique échoue et renvoie l’erreur suivante :

{
  "statusCode": 400,
  "error": "Bad Request",
  "errorCode": "client_credentials_not_supported",
  "message": "Credentials of dynamically registered CIMD clients are resolved from the jwks_uri of their client ID metadata document and cannot be managed through this endpoint."
}

Pour effectuer la rotation des clés d’un client CIMD dynamique, mettez à jour le document jwks_uri hébergé sur son domaine; Auth0 récupère automatiquement les nouvelles clés au besoin. La lecture, la mise à jour et la suppression des informations d’identification d’un client CIMD dynamique ne sont pas bloquées; comme il n’existe aucun enregistrement d’informations d’identification, ces requêtes se comportent comme pour tout client sans informations d’identification (une liste vide, une réponse 404 Not Found pour un identifiant d’information d’identification donné ou une réponse idempotente 204 No Content lors d’une suppression). Cette restriction ne s’applique pas aux clients CIMD manuels ni aux autres types d’application.