Configurer l’authentification mTLS pour un client

Enregistrez un certificat X.509 auto-signé ou signé par une AC sur une application Auth0 afin d’activer l’authentification client mTLS auprès du serveur d’autorisation.

Apprenez à configurer l’authentification mTLS pour un client avec la Management API et l’Auth0 Dashboard.

Auth0 Dashboard

Vous pouvez utiliser Auth0 Dashboard pour configurer mTLS pour un client afin d’activer l’authentification client mTLS auprès du serveur d’autorisation.

1. Accédez à Auth0 Dashboard > Applications > Applications.

2. Sélectionnez l’application que vous souhaitez utiliser avec mTLS ou créez une nouvelle application.

3. Sélectionnez l’onglet Informations d’identification.

4. Choisissez la méthode d’authentification requise, qui peut être l’une des suivantes :

   • mTLS avec un certificat auto-signé
   • mTLS avec un certificat signé par une autorité de certification

5. Une fois le type de certificat souhaité sélectionné, vous pouvez :

   • Attribuer une information d’identification (certificat) existante à l’application cliente
   • Ajouter une nouvelle information d’identification en téléversant un certificat

Management API

Utilisez l’Auth0 Management API pour configurer mTLS pour un client.

Les exemples suivants utilisent $management_access_token, c’est-à-dire un jeton d’accès à la Management API. Il doit être remplacé par un jeton d’accès qui comprend au moins les scopes suivants :

• create:custom_domains
• read:custom_domains
• create:clients
• update:clients
• update:client_credentials
• update:client_keys
• update:tenant_settings

Pour en savoir plus sur la façon d’obtenir un jeton d’accès avec les scopes requis, consultez Obtenir des jetons d’accès.

​

Certificats auto-signés

Utilisez des certificats auto-signés pour vérifier l’identité du client lors de l’authentification mTLS. Cependant, les certificats auto-signés présentent les limites suivantes :

• Les certificats auto-signés ne sont pas acceptés par certains fournisseurs infonuagiques, comme Amazon.
• Pour assurer la stabilité de notre plateforme, Auth0 n’autorise que deux certificats enregistrés par client.

Générer un certificat

Pour vous authentifier à l’aide du mTLS auto-signé, vous devez créer un nouveau certificat client auto-signé.

L’exemple de code suivant génère un nouveau certificat auto-signé :

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -sha256 -days 365 -nodes -subj "/C=XX/ST=StateName/L=CityName/O=CompanyName/OU=CompanySectionName/CN=CommonNameOrHostname"

Comme le certificat doit être envoyé sous forme de chaîne JSON sur une seule ligne, chaque caractère de saut de ligne littéral du fichier PEM doit être échappé pour JSON avant de le transmettre à Auth0. Remplacez chaque saut de ligne par \n (ou par \r\n si le fichier utilise des fins de ligne Windows). De nombreux outils et bibliothèques HTTP n’effectuent pas cette conversion automatiquement ; vérifiez donc l’échappement avant d’envoyer la requête. Par exemple :

-----BEGIN CERTIFICATE-----\r\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQDDXAVKQo2SUMHH\r\no9ecWYNiL5\/yva5NSj8uQjKoeRAsOIOAyOBTLxgwmno13xZ8VDkcT1cHTlC+2CkE\r\noBII4OUbHPVof+dtknkL+jUBdIPX1QvlGSUbzduZE4hEEQ8zH6w4EAA2VN72Bymn\r\nT8i\/+Tz9Dx6M1nkuXPCwM7sYEuq5OrqT5yVB6KByKKElp\/tauJkHp0st04iGDgl2\r\nFJUt3QJFCFewTDDdGq62otVJxHfouXPmHBQjzf+f1CZy+N0q2z+JGRt44YZq+F9y\r\ne3RWawvv2x3TXgRBLpvIKqf99LoPVdwozHl8QODu52dyelvLQ866XLhAALuMwic\/\r\nbQbolnMpAgMBAAECggEAf6LliekFmezNTmQLgIkzP7kh5XRsJu81bEGv20aNfHbH\r\n5CJZ\/b8tLMQgyIWiqURVs9taXtmaA7YyxmTWo5pb1WUMKWQ3je0+zMaCTxsS8Lau\r\n+NV+2zWaHd8XDnGe3qX43QAHQ3gb294+JqQH4vUyFZwFN7sAnXv3fQevW0Ewvics\r\nOua\/xNa7y5hbJUPZiQjRhO+n+gTEqpfsnPWNlm9hk\/wVnnjKvMfstN4zUbznRAoN\r\nW8TK82tiVWAXW4CjgIBtVRZjTA9x3UOtbhcvNzaTRxc+scCpIpAVuurS+ZIKZdpm\r\nNnhiOk3akpLU3KZrm8C5JQRn8cupY9WkfCiLXbMFAQKBgQD9JfVMv6zDeNvExneR\r\n7fZDIT2UAEhYExwRJwQPyxkVPwev9HBYuuaaknIbomWTkt\/B6Q3k3p6VI4lxhnVl\r\nbkpOYl5UquP3VoVROEJts224hKgVcLw6s+i+lZDOAleNgbN7rj82l4BIu+SEj\/7c\r\nz94hAa\/wRRvsW+QnxF1sZnpY+QKBgQDFj2h8I4noFJk3sbbk3qQdi5+49ibWSuhc\r\nXVpU+0dQ1lRlhXYT9cDMc22HRt8hjXUNRhdpXvOqVaFiBjv9wBsmFyaJO3tOK3uE\r\ndBgD4lF03bnbGI7\/I3DivW\/tyEMS5JXI\/qrpdWor+wR30c5M\/45y2AGpjwnoGf+D\r\nX8SAMzknsQKBgQCrSljuIrBK3+eNAWH821CL4d0h3QMWnW+bZ5QG\/70sNCcGd1bh\r\noy3Qn5EYg81JitNfCUw+dihF7\/LbX0jmZjdfTI5Zqfxw6xlweKnyQrvWY+S8BTlI\r\nW138P4Xo74rAlGeXI7NgRCkojgK1dB3W2cyK9vJOmOSpDRCXm\/Y\/GCRnOQKBgCE\/\r\n75\/lA1LSFK9w8401g32NgEZK92JdnRnehFOFLw2F5RJpEeRuGhLO4oJABVHKUwb2\r\n4v3TA0OJwe2Tiwk8CdWxU8UJA8m2O8WhHGGa94apwpwDWB3MwzUGGQ52BAPsAOGh\r\nKva70jCwwKHB5+zBniHqBO2aq1oq9fwQZCwHcvkhAoGBAIa8QMHNrX7AuCSAeR4\/\r\n\/7XrGU1a4oExz417AYgZOuGaYQAI5BMIjRZZ3JTzO\/QsmkzeS1tFuBlih8li\/t4l\r\nE2TdnKhy376A6QWfbTDkJN6gzFeaMKwe98mOHKeq0KZITGYVTSa2AYH5zaro0Yku\r\nonOH1NdyEKFFgxGLg7wveYUW\r\n-----END CERTIFICATE-----

Créer un nouveau client

Pour créer un nouveau client, effectuez un appel POST vers le point de terminaison /clients avec la charge utile suivante :

• $client_name: le nom attribué au nouveau client
• $credential_name: le nom de la clé publique
• $credential_certificate: le contenu du fichier cert.pem généré à l’étape précédente

curl --location --request POST 'https://$tenant/api/v2/clients' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "$client_name",
  "app_type": "non_interactive",
  "client_authentication_methods": {
    "self_signed_tls_client_auth": {
      "credentials": [{ 
        "name": "$credential_name", 
        "credential_type": "x509_cert", 
        "pem": "$credential_certificate"
      }]
    }
  },
  "jwt_configuration": {
    "alg": "RS256"
  }
}'

Pour en savoir plus, consultez la documentation de l’API Créer un client.

Modifier un client existant

Vous pouvez mettre à jour un client existant pour qu’il accepte l’authentification client mTLS en supprimant toute valeur dans le champ token_endpoint_auth_method et en créant des valeurs dans le champ client_authentication_methods.

Une fois que vous avez configuré votre client pour mTLS, vous ne pourrez plus vous authentifier au moyen du Client Secret, à moins de configurer le token_endpoint_auth_method pour qu’il n’utilise plus mTLS. Pour en savoir plus, consultez Rétablir l’utilisation d’un Client Secret pour un client.

Créer la ressource d’identification

Après avoir généré un certificat, créez la ressource d’identification :

curl --location --request POST 'https://$tenant/api/v2/clients/$client_id/credentials' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "$credential_name", 
  "credential_type": "x509_cert", 
  "pem": "$credential_certificate"
}'

Auth0 renvoie un ID de credential dans la réponse, que vous devrez utiliser pour associer le credential au client.

Pour en savoir plus, consultez la documentation de l’API Créer un jeton d’identification client.

Associer l’identifiant au client et désactiver token_endpoint_auth_method

Les identifiants téléversés ne sont pas automatiquement activés pour l’authentification du client. Vous devez mettre à jour l’authentification du client afin d’utiliser le nouveau certificat client auto-signé.

La requête PATCH suivante définit token_endpoint_auth_method sur null, désactivant ainsi l’authentification par secret client. Elle met également à jour client_authentication_methods avec l’ID d’identifiants :

curl --location --request PATCH 'https://$tenant/api/v2/clients/$client_id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "token_endpoint_auth_method": null, 
  "client_authentication_methods": {
    "self_signed_tls_client_auth": {
      "credentials": [{ "id": $credential.id }]
    }
  }
}'

Une fois cette demande traitée, un Client Secret ne sera plus accepté et les clients devront s’authentifier via mTLS.

Pour en savoir plus, consultez la documentation de l’API Update a client.

​

Certificats signés par une autorité de certification

Contrairement aux certificats auto-signés, qui sont générés par le client et ne disposent d’aucune chaîne de confiance, les certificats signés par une autorité de certification (AC) sont considérés comme plus fiables puisqu’ils sont émis par un tiers de confiance. Les certificats signés par une AC sont le seul type de certificat accepté par certains fournisseurs infonuagiques, comme Amazon.

Les certificats signés par une AC intègrent dans leurs informations d’identité la notion de nom distinctif (DN). Bien que chaque certificat individuel créé par une AC donnée soit unique, ils peuvent partager un DN commun. Lors de l’utilisation de certificats signés par une AC, Auth0 stocke le DN et compare les certificats clients transmis avec les DN enregistrés.

Générer un certificat

La méthode de génération d’un certificat client signé par une AC dépend fortement de l’infrastructure à clés publiques et ne relève pas du cadre de ce document. Nous recommandons de générer au moins une paire de clés RSA de 2048 bits.

Créer un nouveau client

Pour créer un client, effectuez un appel POST vers le point de terminaison /clients avec la charge utile suivante :

• $client_name: le nom du nouveau client
• $credential_name: le nom de la clé publique
• $credential_certificate: le contenu du fichier PEM généré par l’autorité de certification

curl --location --request POST 'https://$tenant/api/v2/clients' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "$client_name",
  "app_type": "non_interactive",
  "client_authentication_methods": {
    "tls_client_auth": {
      "credentials": [{ 
        "name": "$credential_name", 
        "credential_type": "cert_subject_dn", 
        "pem": "$credential_certificate"
      }]
    }
  },
  "jwt_configuration": {
    "alg": "RS256"
  }
}'

Au lieu de transmettre le fichier PEM complet, vous pouvez également transmettre le DN du subject. Le DN du subject doit correspondre au Distinguished Name (DN) extrait des certificats client envoyés lors du handshake mTLS.

L’extraction du DN du sujet peut varier d’un écosystème à l’autre. Le moyen le plus fiable de garantir que le serveur d’autorisation correspondra au DN du sujet consiste à téléverser le fichier PEM complet.

La requête POST suivante crée un nouveau client avec le DN du sujet :

curl --location --request POST 'https://$tenant/api/v2/clients' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "$client_name",
  "app_type": "non_interactive",
  "client_authentication_methods": {
    "tls_client_auth": {
      "credentials": [{ 
        "name": "$credential_name", 
        "credential_type": "cert_subject_dn", 
        "subject_dn": "C=XX\nST=StateName\nL=CityName\nO=CompanyName\nOU=CompanySectionName\nCN=CommonNameOrHostname"
      }]
    }
  },
  "jwt_configuration": {
    "alg": "RS256"
  }
}'

Pour en savoir plus, consultez la documentation de l’API Créer un client.

Modifier un client existant

Si vous ne souhaitez pas créer un nouveau client pour utiliser mTLS, vous pouvez mettre à jour un client existant afin qu’il accepte l’authentification client mTLS. Pour ce faire, supprimez toute valeur dans le champ token_endpoint_auth_method et ajoutez des valeurs dans le champ client_authentication_methods.

Une fois que vous avez configuré votre client pour mTLS, vous ne pourrez plus vous authentifier au moyen du Client Secret, à moins de configurer le token_endpoint_auth_method pour qu’il n’utilise plus mTLS. Pour en savoir plus, consultez Rétablir l’utilisation d’un Client Secret pour un client.

Créer la ressource d’informations d’identification

Une fois que vous avez généré une paire de clés exclusivement pour mTLS, créez la ressource d’informations d’identification. Effectuez la requête POST suivante vers le point de terminaison /clients/$client_id/credentials :

curl --location --request POST 'https://$tenant/api/v2/clients/$client_id/credentials' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "$credential_name", 
  "credential_type": "cert_subject_dn", 
  "pem": "$credential_certificate"
}'

Au lieu de transmettre le fichier PEM complet, vous pouvez transmettre le DN du sujet. Le DN du sujet doit correspondre au nom distinctif (DN) extrait des certificats clients envoyés lors de la poignée de main mTLS.

L’exemple de code suivant crée la ressource d’authentification à l’aide du Subject DN :

curl --location --request POST 'https://$tenant/api/v2/clients/$client_id/credentials' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "$credential_name", 
  "credential_type": "cert_subject_dn", 
  "subject_dn": "C=XX\nST=StateName\nL=CityName\nO=CompanyName\nOU=CompanySectionName\nCN=CommonNameOrHostname"
}'

Quelle que soit la méthode utilisée, n’oubliez pas que l’ID de credential renvoyé dans la réponse est nécessaire pour associer le credential au client.

Pour en savoir plus, consultez la documentation de l’API Créer un jeton d’identification client.

Associer l’identifiant au client et désactiver token_endpoint_auth_method

Bien que nous ayons créé le credential, nous ne l’avons pas encore associé au client.

Pour ce faire, mettez à jour client_authentication_methods en effectuant la requête PATCH suivante vers le point de terminaison /clients. Dans la même requête, définissez token_endpoint_auth_method sur null :

​​

curl --location --request PATCH 'https://$tenant/api/v2/clients/$client_id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "token_endpoint_auth_method": null, 
  "client_authentication_methods": {
    "tls_client_auth": {
      "credentials": [{ "id": $credential.id }]
    }
  }
}'

Une fois cette requête traitée, le client ne peut être authentifié qu’avec mTLS.

Pour en savoir plus, consultez la documentation de l’API Update a client.

​

Rétablir l’utilisation d’un Client Secret pour un client

Pour rétablir la configuration de votre client afin de l’authentifier à l’aide d’un Secret client, désactivez client_authentication_methods et réactivez token_endpoint_auth_method avec la méthode d’authentification souhaitée.

Dans la requête PATCH suivante, définissez token_endpoint_auth_method sur client_secret_post pour réactiver l’authentification par Client Secret :

curl --location --request PATCH 'https://$tenant/api/v2/clients/$client_id' \
  --header 'Authorization: Bearer $management_access_token' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "token_endpoint_auth_method": "client_secret_post",
  "client_authentication_methods": null
}'

Pour en savoir plus, consultez la documentation de l’API Update a client.

​

En savoir plus

• S’authentifier avec mTLS
• Configurer le Customer Edge
• Configurer l’authentification mTLS pour un tenant