Signer et chiffrer les requêtes SAML

Décrit le scénario de configuration particulier permettant de signer et de 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 dans le protocole SAML. Dans cet article, vous trouverez des configurations propres à certains scénarios, présentées selon deux cas d’utilisation :

• Auth0 comme fournisseur de services SAML (par exemple, une connexion SAML)
• Auth0 comme fournisseur d’identité SAML (par exemple, une application configurée avec le SAML Web App addon)

​

Auth0 en tant que fournisseur de services SAML

Ces scénarios s’appliquent lorsqu’Auth0 est le fournisseur de services SAML, ce qui signifie qu’Auth0 se connecte à un fournisseur d’identité SAML en créant une connexion SAML.

​

Signer la requête d’authentification SAML

Si Auth0 est le fournisseur de services SAML, vous pouvez signer la requête d’authentification qu’Auth0 envoie à l’IdP comme suit :

1. Accédez à Auth0 Dashboard > Authentication > Enterprise, puis sélectionnez SAML.
2. Sélectionnez le nom de la connexion à afficher.
3. Repérez Sign Request et activez son commutateur.
4. Téléchargez le certificat sous le commutateur Sign Request, puis remettez-le à l’IdP afin qu’il puisse valider la signature.

​

Activer/désactiver l’encodage deflate

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 effectuer une requête PATCH au point de terminaison Update a Connection de la Management API et définir l’option deflate à false.

La mise à jour de l’objet options d’une connexion remplace l’intégralité de l’objet options. Pour conserver les options de connexion existantes, récupérez l’objet options actuel et ajoutez-y de 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 tenant pour signer les requêtes SAML (lorsque la bascule Sign Request est activée). Vous pouvez aussi fournir votre propre paire de clés publique/privée pour signer les requêtes provenant d’une connexion donnée.

Vous pouvez générer votre propre certificat et votre clé privée à l’aide de cette commande :

openssl req -x509 -nodes -sha256 -days 3650 -newkey rsa:2048 -keyout private_key.key -out certificate.crt

Il n’est pas possible de modifier, dans l’interface utilisateur du Dashboard, la clé utilisée pour signer les requêtes de la connexion; vous devrez donc utiliser le point de terminaison Update a Connection de la Management API v2 et ajouter une propriété signing_key à l’objet options, comme dans l’exemple de charge utile ci-dessous.

La mise à jour de l’objet options d’une connexion remplace l’objet options au complet. 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
		  "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-----"
			}
    }
	}
}

Pour savoir comment obtenir la clé privée et le certificat au format de chaîne JSON à utiliser dans la charge utile, consultez utiliser des certificats et des clés sous forme de chaînes.

​

Recevoir des réponses d’authentification SAML signées

Si Auth0 est le fournisseur de services SAML, toutes les réponses SAML de votre fournisseur d’identité doivent être signées afin d’indiquer qu’elles n’ont pas été altéré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 important ce certificat dans votre connexion Auth0 :

1. Accédez à Auth0 Dashboard > Authentication > Enterprise, puis sélectionnez SAML.
2. Sélectionnez le nom de la connexion à consulter.
3. Repérez X509 Signing Certificate, puis téléversez le certificat.
4. Sélectionnez Save Changes.

Auth0 peut accepter une réponse signée pour l’assertion, la réponse ou les deux.

​

Recevoir des assertions d’authentification SAML chiffrées

Si Auth0 est le fournisseur de services SAML, il peut devoir recevoir des assertions SAML chiffrées d’un fournisseur d’identité. Pour ce faire, vous devez fournir à l’IdP le certificat de clé publique du tenant. 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 tenant.

Utilisez les liens suivants pour obtenir le certificat de 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 dernier profil d’algorithmes pour déchiffrer les assertions SAML.

• Si l’assertion est chiffrée au moyen d’un algorithme qui ne figure pas dans la liste, elle sera rejetée par Auth0.

• Si votre IdP ne prend pas en charge un algorithme de la liste, vous pouvez utiliser le paramètre algorithm_exceptions pour remplacer le profil de sécurité. Auth0 recommande d’utiliser le dernier profil d’algorithmes pour déchiffrer les assertions SAML.

Pour préciser un profil différent ou utiliser un algorithme non répertorié, vous devez mettre à jour la connexion au moyen 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 options d’une connexion, la nouvelle configuration remplace entièrement l’objet options. Pour conserver les options de connexion précédentes, récupérez l’objet options existant et ajoutez-y de 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": [
        // Vous pouvez déroger au profil de sécurité pour utiliser un algorithme moins sécurisé, par exemple :
		// "http://www.w3.org/2001/04/xmlenc#aes128-cbc",
		// "http://www.w3.org/2001/04/xmlenc#aes256-cbc",
		// "http://www.w3.org/2001/04/xmlenc#tripledes-cbc"
	  ]
    }
  }
}

​

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 tenant 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.

La modification de la paire de clés utilisée pour chiffrer et déchiffrer les requêtes dans la connexion ne peut pas être effectuée dans l’interface utilisateur du Dashboard. 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 illustré dans l’exemple de charge utile ci-dessous.

La mise à jour de l’objet options d’une connexion remplace l’objet options au complet. Pour conserver les options de connexion existantes, récupérez l’objet options actuel et ajoutez-y de 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 l’utiliser pour signer la réponse SAML.

​

Auth0 comme fournisseur d’identité SAML

Ce scénario s’applique lorsqu’Auth0 agit comme fournisseur d’identité SAML pour une application. Dans le Dashboard, cela correspond à une Application pour laquelle le SAML Web App Addon est activé.

​

Signer les réponses/assertions SAML

Si Auth0 est le fournisseur d’identité SAML, il signe les assertions SAML avec la clé privée du tenant et fournit au fournisseur de services la clé publique ou le certificat nécessaire pour valider la signature.

Pour signer les assertions SAML :

1. Accédez à Auth0 Dashboard > Applications, puis sélectionnez le nom de l’application à afficher.
2. Faites défiler jusqu’au bas de la page Settings, sélectionnez Show Advanced Settings, puis la vue Certificates.
3. Sélectionnez Download Certificate, puis le format dans lequel vous souhaitez recevoir votre certificat de signature.
4. Envoyez votre certificat au fournisseur de services.

Par défaut, Auth0 signe l’assertion SAML dans la réponse. Pour signer plutôt la réponse SAML :

1. Accédez à Auth0 Dashboard > Applications, puis sélectionnez le nom de l’application à afficher.

2. Sélectionnez la vue Addons.

3. Sélectionnez SAML2 Web App pour afficher ses paramètres, puis repérez le bloc de code Settings.

4. Repérez la clé "signResponse". Supprimez les marques de commentaire (ou ajoutez-la, au besoin), puis définissez sa valeur à true (la valeur par défaut est false). La configuration devrait ressembler à ceci :

   {
     [...], // autres paramètres
     "signResponse": true
   }
   

​

Changer la clé de signature pour les réponses SAML

Par défaut, Auth0 utilise la paire de clés privée/publique attribuée à votre tenant pour signer les réponses SAML ou les assertions. Dans certains cas très précis, vous pourriez vouloir fournir votre propre paire de clés. Vous pouvez le faire à l’aide d’une règle comme celle-ci :

/**
* Handler qui sera appelé lors de l'exécution d'un flow 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 du login.
*/
exports.onExecutePostLogin = async (event, api) => {

    // remplacer par l'ID de l'application pour laquelle le SAML Web App Addon 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 IdPs nécessitant 
    // des certificats personnalisés, vous aurez une instruction "if" pour chacun.  
    if (event.client.client_id === samlIdpClientId) {

    // fournissez 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 : 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);

  }
  };

Pour savoir comment convertir les fichiers de clé privée et de certificat en chaînes de caractères que vous pouvez utiliser dans une règle, consultez utiliser des certificats et des clés sous forme de chaînes.

​

Effectuer la rotation de la clé de signature du tenant

• Auth0 signe les assertions et les réponses SAML à l’aide de la clé de signature de votre tenant. La rotation de cette clé aura une incidence sur tous les fournisseurs de services qui valident les signatures à l’aide du certificat auquel ils font confiance.
• Les fournisseurs de services qui ne font pas confiance au nouveau certificat rejetteront les réponses signées par Auth0, et leurs utilisateurs ne pourront pas se connecter.

Pour en savoir plus sur la rotation des clés de signature, consultez Faire la rotation des clés de signature.

La possibilité de configurer les fournisseurs de services SAML pour qu’ils fassent confiance au certificat next avant d’effectuer la rotation dépend de la capacité de chacun à gérer plus d’un certificat de signature de fournisseur d’identité à la fois.

Avant d’effectuer la rotation, récupérez le certificat NEXT IN QUEUE :

1. Accédez à Dashboard > Paramètres > Clés de signature et faites défiler jusqu’à Liste des clés valides.
2. Repérez la clé valide NEXT IN QUEUE.
3. Sélectionnez Télécharger le certificat de signature dans le menu à points de suspension (…).

Vous pouvez également envoyer une requête GET au point de terminaison Obtenir toutes les clés de signature d’application de la Management API; la réponse comprend le champ "cert" d’une clé valide dont "next": true.

Fournisseurs de services qui prennent en charge plusieurs certificats de signature

Pour assurer l’absence d’interruption de service, de nombreux fournisseurs de services peuvent accepter plusieurs certificats de signature IdP. Ajoutez le certificat valide next au certificat actuel afin que les deux soient approuvés simultanément lorsque Auth0 commencera à l’utiliser.

1. Téléversez le certificat suivant vers le fournisseur de services en tant que certificat de signature approuvé supplémentaire. Ne supprimez pas et ne remplacez pas encore le certificat actuel.
2. Confirmez que le fournisseur de services répertorie les certificats actuel et suivant comme approuvés.
3. Une fois que chaque fournisseur de services approuve les deux certificats, effectuez la rotation de la clé. Ne supprimez l’ancien certificat de vos fournisseurs de services qu’après avoir confirmé que les connexions réussissent.

Fournisseurs de services qui ne prennent en charge qu’un seul certificat de signature

Certains fournisseurs de services n’acceptent qu’un seul certificat de signature de fournisseur d’identité à la fois. Vous devez coordonner la rotation de la clé de signature avec ces fournisseurs de services pendant la même fenêtre de maintenance.

1. Coordonnez-vous avec le fournisseur de services pour planifier le changement pendant une période de faible trafic ou une fenêtre de maintenance.
2. Effectuez la rotation de la clé de signature dans Auth0 et remplacez le certificat approuvé du fournisseur de services par le certificat suivant à des moments aussi rapprochés que possible. Entre ces deux actions, les connexions par l’intermédiaire de ce fournisseur de services échoueront lors de la validation de la signature.
3. Une fois que le fournisseur de services possède le nouveau certificat, vérifiez que les connexions réussissent.

Consultez votre fournisseur de services pour déterminer s’il peut prendre en charge plusieurs certificats de signature ou un seul, puis planifiez en conséquence.

​

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 la signature :

1. Téléchargez le certificat du fournisseur de services contenant la clé publique.

2. Accédez à Auth0 Dashboard > Applications, puis sélectionnez le nom de l’application pour l’afficher.

3. Sélectionnez la vue Addons.

4. Sélectionnez SAML2 Web App pour afficher ses paramètres, puis repérez le bloc de code Settings.

5. 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 sélectionner l’algorithme utilisé pour chiffrer les assertions. Auth0 recommande d’utiliser aes256-gcm pour un niveau de sécurité supérieur.

Vous devez obtenir le certificat et la clé publique du fournisseur de services. Si vous n’avez obtenu que le certificat, vous pouvez en extraire la clé publique à l’aide de 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.pem

Une fois que vous avez les fichiers du certificat et de la clé publique, vous devez les convertir en chaînes de caractères pour les utiliser dans une Action. L’Action se présentera comme suit :

exports.onExecutePostLogin = async (event, api) => {

// cette 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é) : un chiffrement authentifié qui assure à la fois la confidentialité et l’intégrité. Il résiste aux attaques par oracle sur la 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 tenant.

Pour le transport de clé, 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 uniforme après ce changement, nous vous recommandons de passer à aes256-gcm :

1. Vérifiez que votre fournisseur de services SAML prend en charge aes256-gcm et communiquez avec lui pour obtenir du soutien si ce n’est pas le cas.
2. Définissez l’algorithme de chiffrement dans le code de votre Action avec api.samlResponse.setEncryptionAlgorithm("aes256-gcm");.

​

En savoir plus

• utiliser des certificats et des clés sous forme de chaînes