Configurer l’authentification mTLS pour une application

Explique comment configurer l’authentification mTLS pour une application.

Apprenez à configurer l’authentification mTLS pour une application à l’aide de la Management API et de l’Auth0 Dashboard.

Auth0 Dashboard

Vous pouvez utiliser l’Auth0 Dashboard pour configurer mTLS pour une application afin d’activer l’authentification mTLS de l’application 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 Credentials.

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

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

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

   • Attribuer un certificat existant à l’application
   • Ajouter un nouveau certificat en le téléversant

Management API

Utilisez la Management API Auth0 pour configurer mTLS pour une application.

Les exemples suivants utilisent $management_access_token, ou un jeton d’accès de la Management API. Ce jeton 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é de l’application lors de l’authentification mTLS. Toutefois, les certificats auto-signés présentent les limitations suivantes

• Les certificats autosignés ne sont pas acceptés par certains fournisseurs de services 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 de mTLS auto-signé, vous devez créer un nouveau certificat d’application 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 de le transmettre à Auth0. Par exemple, remplacez les sauts de 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 une nouvelle application

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

• $client_name: le nom de la nouvelle application
• $credential_name: le nom de la clé publique
• $credential_certificate: le contenu de $certificate_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 une application.

Mettre à jour une application existante

Vous pouvez mettre à jour une application existante pour qu’elle accepte l’authentification d’application mTLS en supprimant toute valeur dans le champ token_endpoint_auth_method et en ajoutant des valeurs dans le champ client_authentication_methods.

Une fois que vous avez configuré votre application pour mTLS, vous ne pourrez plus vous authentifier à l’aide du Secret client tant que vous n’aurez pas configuré token_endpoint_auth_method de façon à ne plus utiliser mTLS. Pour en savoir plus, consultez Rétablir l’utilisation d’un Secret client pour une application.

Créer la ressource d’informations d’identification

Après avoir généré un certificat, créez la ressource d’informations 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 d’accréditation dans la réponse, que vous devrez associer à l’application.

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

Associer les informations d’identification à l’application et désactiver token_endpoint_auth_method

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

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

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, le Secret client ne sera plus accepté et les applications devront s’authentifier via mTLS.

Pour en savoir plus, consultez la documentation de l’API Mettre à jour une application.

​

Certificats signés par une autorité de certification

Contrairement aux certificats auto-signés générés par l’application et sans 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 tels qu’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 d’application transmis aux DN enregistrés.

Générer un certificat

La méthode de génération d’un certificat d’application signé par une AC dépend fortement de l’infrastructure à clé publique et n’entre pas dans le cadre de ce document. Nous recommandons de générer au moins une paire de clés RSA de 2048 bits.

Créer une nouvelle application

Pour créer une application, effectuez un appel POST au point de terminaison /clients avec la charge utile suivante :

• $client_name: le nom de la nouvelle application
• $credential_name: le nom de la clé publique
• $credential_certificate : le contenu de $certificate_pem produit 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 sujet. Le DN du sujet doit correspondre au Distinguished Name (DN) extrait des certificats d’application envoyés lors de la négociation 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 pourra faire correspondre le DN du sujet est de téléverser le fichier PEM complet.

La requête POST suivante crée une nouvelle application 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 une application.

Mettre à jour une application existante

Si vous ne souhaitez pas créer une nouvelle application pour utiliser mTLS, vous pouvez mettre à jour une application existante afin qu’elle accepte l’authentification d’application 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 application pour mTLS, vous ne pourrez plus vous authentifier à l’aide du Secret client, à moins de configurer token_endpoint_auth_method afin de ne plus utiliser mTLS. Pour en savoir plus, consultez Reconfigurer une application pour utiliser un Secret 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 :

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 Distinguished Name (DN) extrait des certificats d’application envoyés lors de la négociation mTLS.

L’exemple de code suivant crée la ressource d’informations d’identification à l’aide du DN 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"
}'

Quelle que soit la méthode utilisée, n’oubliez pas que l’ID d’accréditation renvoyé dans la réponse est nécessaire pour associer l’accréditation à l’application.

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

Associer les informations d’identification à l’application et désactiver token_endpoint_auth_method

Bien que nous ayons créé les informations d’identification, nous ne les avons pas encore associées à l’application.

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 terminée, l’application ne pourra être authentifiée qu’avec mTLS.

Pour en savoir plus, consultez la documentation de l’API Mettre à jour une application.

​

Rétablir une application pour utiliser un Secret client

Pour rétablir la configuration de votre application afin qu’elle s’authentifie à 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 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 en savoir plus, consultez la documentation de l’API Mettre à jour une application.

​

En savoir plus

• S’authentifier avec mTLS
• Mettre en place le Customer Edge
• Configurer l’authentification mTLS pour un locataire