Décrit le cas de configuration particulier pour signer et chiffrer les requêtes SAML
Pour renforcer la sécurité de vos transactions, vous pouvez signer ou chiffrer à la fois vos requêtes et vos réponses avec le protocole . Dans cet article, vous trouverez des configurations pour des scénarios précis, réparties en deux cas d’utilisation :
Auth0 comme fournisseur de services SAML (par exemple, une connexion SAML)
Auth0 comme SAML (par exemple, une application configurée avec le module complémentaire SAML Web App)
Ces scénarios s’appliquent lorsque Auth0 agit comme fournisseur de services SAML, c’est-à-dire lorsqu’Auth0 se connecte à un fournisseur d’identité SAML en créant une connexion SAML.
Par défaut, les requêtes d’authentification SAML sont envoyées par HTTP-Redirect et utilisent l’encodage deflate, ce qui place la signature dans un paramètre de requête.Pour désactiver l’encodage deflate, vous pouvez faire un appel PATCH au point de terminaison Update a Connection de la Management API et définir l’option deflate sur false.La mise à jour de l’objet options d’une connexion remplace l’objet options en entier. Pour conserver les options de connexion existantes, récupérez l’objet options actuel et ajoutez-y les nouvelles paires clé-valeur.Point de terminaison : https://{yourDomain}/api/v2/connections/{yourConnectionId}Charge utile :
{ { "options" : { [...], // toutes les autres options de connexion "deflate": false } }}
Utiliser une clé personnalisée pour signer les requêtes
Par défaut, Auth0 utilise la clé privée du locataire pour signer les requêtes SAML (lorsque l’option Sign Request est activée). Vous pouvez également fournir votre propre paire de clés privée/publique pour signer les requêtes provenant d’une connexion précise.Vous pouvez générer votre propre certificat et votre propre clé privée à l’aide de cette commande :
Il n’est pas possible de modifier, dans l’interface du Dashboard, la clé utilisée pour signer les requêtes pour la connexion. Vous devrez donc utiliser le point de terminaison « Update a Connection » de la v2 et ajouter une propriété signing_key à l’objet options, comme dans l’exemple de payload ci-dessous.La mise à jour de l’objet options d’une connexion remplace entièrement cet objet. Pour conserver les options existantes de la connexion, récupérez l’objet options actuel et ajoutez-y les nouvelles paires clé-valeur.Point de terminaison : https://{yourDomain}/api/v2/connections/{yourConnectionId}Payload :
{ { "options" : { [...], // toutes les autres options de connexion "signing_key": { "key":"-----BEGIN PRIVATE KEY-----\n...{your private key here}...\n-----END PRIVATE KEY-----", "cert":"-----BEGIN CERTIFICATE-----\n...{your public key cert here}...\n-----END CERTIFICATE-----" } } }}
Recevoir des réponses d’authentification SAML signées
Si Auth0 est le fournisseur de services SAML, toutes les réponses SAML provenant de votre fournisseur d’identité devraient être signées afin d’indiquer qu’elles n’ont pas été modifiées par un tiers non autorisé.Vous devrez configurer Auth0 pour valider la signature des réponses en obtenant un certificat de signature auprès du fournisseur d’identité et en chargeant ce certificat dans votre connexion Auth0 :
Recevoir des assertions d’authentification SAML chiffrées
Si Auth0 est le fournisseur de services SAML, il peut devoir recevoir des assertions chiffrées d’un fournisseur d’identité. Pour ce faire, vous devez fournir à l’IdP le certificat de la clé publique du locataire. L’IdP chiffre l’assertion SAML à l’aide de la clé publique et l’envoie à Auth0, qui la déchiffre à l’aide de la clé privée du locataire.Utilisez les liens suivants pour obtenir la clé publique dans différents formats :
Téléchargez le certificat dans le format demandé par l’IdP.
Définir les algorithmes de déchiffrement du contenu
Par défaut, Auth0 prend automatiquement en charge les algorithmes répertoriés dans le plus récent profil d’algorithmes pour déchiffrer les assertions SAML.
Si l’assertion est chiffrée avec un algorithme qui ne figure pas dans la liste, elle sera rejetée par Auth0.
Pour spécifier un profil différent ou utiliser un algorithme qui ne figure pas dans la liste, vous devez mettre à jour la connexion à l’aide du point de terminaison Update a Connection et modifier la propriété assertion_decryption_settings, comme indiqué dans l’exemple de charge utile ci-dessous.Lorsque vous mettez à jour l’objet d’options d’une connexion, la nouvelle configuration remplace l’intégralité de l’objet options. Pour conserver les options existantes de la connexion, récupérez l’objet d’options actuel et ajoutez-y les nouvelles paires clé-valeur.Point de terminaison : https://{yourDomain}/api/v2/connections/{yourConnectionId}
Charge utile :
{ "options": { [...], // toutes les autres options de connexion "assertion_decryption_settings": { "algorithm_profile": "v2026-1", "algorithm_exceptions": [] } }}
Utilisez votre paire de clés pour déchiffrer les réponses chiffrées
Comme indiqué ci-dessus, Auth0 utilisera par défaut la paire de clés privée/publique de votre locataire pour gérer le chiffrement. Vous pouvez également fournir votre propre paire de clés publique/privée si un scénario avancé l’exige.Il n’est pas possible de modifier, dans l’interface du Dashboard, la paire de clés utilisée pour chiffrer et déchiffrer les requêtes pour la connexion. Vous devrez donc utiliser le point de terminaison Update a Connection de la Management API v2 et ajouter une propriété decryptionKey à l’objet options, comme indiqué dans l’exemple de charge utile ci-dessous.La mise à jour de l’objet options d’une connexion remplace l’intégralité de cet objet. Pour conserver les options existantes de la connexion, récupérez l’objet options actuel et ajoutez-y les nouvelles paires clé/valeur.Point de terminaison : https://{yourDomain}/api/v2/connections/{yourConnectionId}Charge utile :
{ { "options" : { [...], // toutes les autres options de connexion "decryptionKey": { "key":"-----BEGIN PRIVATE KEY-----\n...{your private key here}...\n-----END PRIVATE KEY-----", "cert":"-----BEGIN CERTIFICATE-----\n...{your public key cert here}...\n-----END CERTIFICATE-----" } }}
Les métadonnées SAML disponibles pour la connexion seront mises à jour avec le certificat fourni afin que le fournisseur d’identité puisse le récupérer pour signer la réponse SAML.
Ce scénario s’applique lorsqu’Auth0 est le fournisseur d’identité SAML d’une application. Dans le Dashboard, cela correspond à une Application pour laquelle le module complémentaire SAML Web App est activé.
Si Auth0 est le fournisseur d’identité SAML, il signera les assertions SAML avec la clé privée du locataire et fournira au fournisseur de services la clé publique ou le certificat nécessaire pour valider la signature.Pour signer les assertions SAML :
Sélectionnez SAML2 Web App pour afficher ses paramètres, puis repérez le bloc de code Settings.
Repérez la clé "signResponse". Retirez les marques de commentaire (ou ajoutez-la, au besoin), puis définissez sa valeur sur true (la valeur par défaut est false). La configuration devrait ressembler à ceci :
{ [...], // autres paramètres "signResponse": true}
Par défaut, Auth0 utilise la paire de clés privée/publique attribuée à votre locataire pour signer les réponses ou les assertions SAML. Dans certains cas très précis, vous voudrez peut-être fournir votre propre paire de clés. Vous pouvez le faire avec une règle comme celle-ci :
/*** Gestionnaire qui sera appelé lors de l'exécution d'un flux PostLogin.** @param {Event} event - Détails sur l'utilisateur et le contexte dans lequel il se connecte.* @param {PostLoginAPI} api - Interface dont les méthodes peuvent être utilisées pour modifier le comportement de la connexion.*/exports.onExecutePostLogin = async (event, api) => { // remplacer par l'ID de l'application pour laquelle le module complémentaire SAML Web App est activé // et pour laquelle vous souhaitez modifier la paire de clés de signature. const samlIdpClientId = 'YOUR_SAML_APP_CLIENT_ID'; // effectuer cette opération uniquement pour le client_id spécifique. Si vous avez plusieurs IdP nécessitant // des certificats personnalisés, vous aurez une instruction "if" pour chacun. if (event.client.client_id === samlIdpClientId) { // indiquez votre propre clé privée et certificat ici // consultez https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/work-with-certificates-and-keys-as-strings // pour les instructions de mise en forme : vous commencez avec un certificat au format PEM et // remplacez les fins de ligne par "\n" const signingCert = "-----BEGIN CERTIFICATE-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV[..all the other lines..]-----END CERTIFICATE-----\n"; const signingKey = "-----BEGIN PRIVATE KEY-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV[..all the other lines..]-----END PRIVATE KEY-----\n"; api.samlResponse.setCert(signingCert) api.samlResponse.setKey(signingKey); } };
Recevoir des requêtes d’authentification SAML signées
Si Auth0 est le fournisseur d’identité SAML, il peut recevoir des requêtes signées avec la clé privée du fournisseur de services. Auth0 utilise la clé publique ou le certificat pour valider la signature.Pour configurer la validation de signature :
Téléchargez le certificat du fournisseur de services contenant la clé publique.
Sélectionnez SAML2 Web App pour afficher ses paramètres, puis repérez le bloc de code Settings.
Repérez la clé "signingCert". Décommentez-la (ou ajoutez-la, au besoin), puis attribuez-lui comme valeur le certificat que vous avez téléchargé depuis le fournisseur de services. La configuration devrait ressembler à ceci :
{ [...], // autres paramètres "signingCert": "-----BEGIN CERTIFICATE-----\nMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n[..all the other lines..]-----END CERTIFICATE-----\n"}
Envoyer des assertions d’authentification SAML chiffrées
Si Auth0 est le fournisseur d’identité SAML, vous pouvez utiliser Actions pour chiffrer les assertions SAML qu’il envoie. Vous pouvez aussi choisir l’algorithme utilisé pour chiffrer les assertions. Auth0 recommande d’utiliser aes256-gcm pour un niveau de sécurité accru.Vous devez obtenir le certificat et la clé publique auprès du fournisseur de services. Si vous n’avez obtenu que le certificat, vous pouvez extraire la clé publique à l’aide d’openssl. En supposant que le fichier de certificat s’appelle certificate.pem, vous pouvez exécuter :openssl x509 -in certificate.pem -pubkey -noout > public_key.pemUne fois que vous avez obtenu les fichiers de certificat et de clé publique, vous devez les convertir en chaînes de caractères pour les utiliser dans une Action. L’Action ressemblera à ceci :
exports.onExecutePostLogin = async (event, api) => {// cet Action définit une clé publique spécifique pour chiffrer l'assertion SAML générée par Auth0 if ( event.client.client_id === "THE_CLIENT_ID_OF_THE_APP_WITH_THE_SAML_APP_ADDON" ) { const encryptionCert = "-----BEGIN CERTIFICATE-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV[..all the other lines..]-----END CERTIFICATE-----\n"; const encryptionPublicKey = "-----BEGIN PUBLIC KEY-----\nnMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV[..all the other lines..]-----END PUBLIC KEY-----\n"; api.samlResponse.setEncryptionCert(encryptionCert); api.samlResponse.setEncryptionPublicKey(encryptionPublicKey); api.samlResponse.setEncryptionAlgorithm("aes256-gcm"); }};
Auth0 prend en charge les algorithmes suivants pour le chiffrement des assertions :
aes256-gcm(recommandé) : Chiffrement authentifié qui assure à la fois la confidentialité et l’intégrité. Il résiste aux attaques par oracle de validité du format.
aes256-cbc (par défaut) : Il n’offre aucune garantie d’intégrité. Lorsqu’une Action n’utilise pas l’objet api.samlResponse.setEncryptionAlgorithm pour définir l’algorithme de chiffrement, Auth0 utilise par défaut l’algorithme aes256-cbc et consigne un avertissement de dépréciation dans les journaux de votre locataire.
Pour le transport des clés, Auth0 utilise rsa-oaep, y compris les fonctions MGF1 et SHA1.
Auth0 prévoit de remplacer l’algorithme de chiffrement par défaut par aes256-gcm.Pour assurer un comportement cohérent après ce changement, nous vous recommandons de passer à aes256-gcm :
Vérifiez que votre fournisseur de services SAML prend en charge aes256-gcm, et communiquez avec lui pour obtenir de l’assistance si ce n’est pas le cas.
Définissez l’algorithme de chiffrement dans le code de votre Action avec api.samlResponse.setEncryptionAlgorithm("aes256-gcm");.
Authentification
Gérer les utilisateurs
Personnaliser
Auth0 AI
Plateforme