Configurer l’authentification mTLS pour un client

Décrit comment configurer l’authentification mTLS pour un client.

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

Auth0 Dashboard

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

1. Naviguez vers 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 Credentials (Identifiants)

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

   • mTLS avec un certificat autosigné, ou
   • mTLS avec un certificat signé par l’autorité de certification

5. Une fois que vous avez sélectionné le type de certificat que vous préférez, vous pouvez :

   • Attribuer un identifiant (certificat) existant dans l’application du client
   • Ajouter un nouvel identifiant en téléversant un certificat

Management API

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

Les exemples suivants spécifient $management_access_token, ou un jeton d’accès de Management API. Il doit être remplacé par un jeton d’accès contenant au moins les permissions suivantes :

• 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 récupération d’un jeton d’accès avec les permissions requises, lisez 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 limitations suivantes

• Les certificats auto-signés ne sont pas acceptés par certains fournisseurs de cloud comme Amazon.
• Pour garantir la stabilité de notre plateforme, Auth0 limite les clients à deux certificats enregistrés.

Générer un certificat

Pour pouvoir être authentifié à l’aide d’un certificat 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"

Si vous utilisez cURL ou wget, le certificat PEM doit être échappé en JSON avant d’être transmis à Auth0. Par exemple, remplacez une nouvelle ligne par \r\n :

-----BEGIN PRIVATE KEY-----\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 PRIVATE KEY-----

Créer un nouveau client

Pour créer un nouveau client, faites un appel POST au 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 de $certificate_pemgé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 plus d’information, consultez la documentation sur l’API Créer un client.

Mettre à jour 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 pas vous authentifier au moyen du secret client à moins de configurer token_endpoint_auth_method pour qu’il arrête d’utiliser mTLS. Pour en savoir plus, lisez Revenir à un client pour utiliser un secret client.

Créer la ressource d’identification

Une fois que vous avez 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 identifiant d’identification dans la réponse dont vous aurez besoin pour associer l’identifiant au client.

Pour plus d’information, consultez la documentation sur l’API Créer un identifiant de client.

Associer les identifiants au client et désactiver token_endpoint_auth_method

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

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

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 requête terminée, un Secret Client ne sera plus accepté et les clients devront s’authentifier en utilisant mTLS.

Pour plus d’information, consultez la documentation sur l’API Mettre à jour un client.

​

Certificats signés par l’autorité de certification

Contrairement aux certificats auto-signés qui sont générés par le client et n’ont pas de 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 autorité de certification sont le seul type de certificat accepté par certains fournisseurs de cloud comme Amazon.

Les certificats signés par une autorité de certification 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 nom distinctif (DN) commun. Lors de l’utilisation de certificats signés par une autorité de certification, 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 autorité de certification dépend fortement de l’infrastructure de clés publiques et dépasse le cadre du présent document. Nous recommandons de générer une paire de clés RSA d’au minimum 2048 bits.

Créer un nouveau client

Pour créer un client, faites un appel POST au 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 de $certificate_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 nom distinctif (DN) du sujet. Le DN du sujet doit correspondre au nom distinctif (DN) extrait des certificats du client envoyés au cours de l’établissement de liaison mTLS.

L’extraction du DN du sujet peut varier d’un écosystème à l’autre. La manière la plus fiable de garantir que le serveur d’autorisation fera correspondre le DN du sujet est de téléverser l’intégralité du fichier PEM.

La requête POST suivante crée un nouveau client avec le ND (Nom Distinctif) 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 plus d’informations, consultez la documentation sur l’API Créer un client.

Mettre à jour un client existant

Si vous ne souhaitez pas créer un nouveau client pour utiliser mTLS, vous pouvez mettre à jour un client existant pour qu’il accepte l’authentification client mTLS. Cela implique de supprimer toute valeur dans le champ token_endpoint_auth_method et de créer des valeurs dans le champ client_authentication_methods.

Une fois que vous avez configuré votre client pour mTLS, vous ne pourrez pas vous authentifier au moyen du secret client à moins de configurer token_endpoint_auth_method pour qu’il arrête d’utiliser mTLS. Pour en savoir plus, lisez Revenir à un client pour utiliser un secret client.

Créer la ressource d’identification

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

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 nom distinctif (DN) du sujet. Le nom distinctif (DN) du sujet doit correspondre au nom distinctif (DN) extrait des certificats du client envoyés au cours de l’établissement de liaison mTLS.

L’exemple de code suivant crée la ressource d’identification en utilisant le ND du sujet :

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

Que vous utilisiez l’une ou l’autre méthode, n’oubliez pas que l’ID d’identification renvoyée dans la réponse est nécessaire pour associer l’identification au client.

Pour plus d’information, consultez la documentation sur l’API Créer un identifiant de client.

Associer les identifiants au client et désactiver token_endpoint_auth_method

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

Pour ce faire, mettez à jour client_authentication_methods en effectuant la requête PATCH suivante au point de terminaison /clients. Dans la même requête, définissez token_endpoint_auth_method à 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 effectuée, le client ne pourra être authentifié qu’en utilisant mTLS.

Pour plus d’information, consultez la documentation sur l’API Mettre à jour un client.

​

Faire revenir un client à l’utilisation d’un secret client

Pour restaurer la configuration de votre client afin qu’il s’authentifie à l’aide d’un secret client, désactivez client_authentication_methods et activez à nouveau 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 secret client :

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 plus d’information, consultez la documentation sur l’API Mettre à jour un client.

​

En savoir plus

• Authentification avec mTLS
• Configurer le réseau de périphérie client
• Configurer l’authentification mTLS pour un locataire