Signer et chiffrer les requêtes SAML

Pour augmenter la sécurité de vos transactions, vous pouvez signer ou chiffrer à la fois vos demandes et vos réponses dans le protocole SAML. Dans cet article, vous trouverez des configurations pour des scénarios spécifiques, séparés en deux cas d’utilisation :

• Auth0 en tant que fournisseur de services SAML (par exemple, une connexion SAML)

• Auth0 en tant que fournisseur d’identité SAML (par exemple, une application configurée avec le module complémentaire SAML Web App)

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

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

1. Naviguez vers Auth0 Dashboard > Authentification > Entreprise, et sélectionnez SAML.

2. Sélectionnez le nom de la connexion à afficher.

3. Localisez Signer la requête et activez-le.

4. Téléchargez le certificat sous la bascule Signer la requête et fournissez-le à l’IdP pour qu’il puisse valider la signature.

Par défaut, les demandes d’authentification SAML sont envoyées via HTTP-Redirect et utilisent l’encodage deflate, qui place la signature dans un paramètre de requête.

Pour désactiver l’encodage deflate, vous pouvez effectuer un appel PATCH au point de terminaison Mettre à jour une connexion de Management API et définir l’option deflate sur false.

La mise à jour de l’objet options pour une connexion remplace l’ensemble de l’objet options. Pour conserver les options de connexion précédentes, récupérez l’objet options existant et ajoutez-y de nouvelles clés/valeurs.

Point de terminaison : https://{yourDomain}/api/v2/connections/{yourConnectionId}

Charge utile :

{
	{ 
		"options" : {
			[...], // all the other connection options
		  "deflate": false
	}
}

Par défaut, Auth0 utilise la clé privée du locataire pour signer les requêtes SAML (lorsque la bascule Signer la requête est activée). Vous pouvez également fournir votre propre paire de clés privée/publique pour signer les demandes provenant d’une connexion spécifique.

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

La modification de la clé utilisée pour signer les demandes dans la connexion ne peut pas être effectuée dans l’interface utilisateur du Tableau de bord. Vous devrez donc utiliser le point de terminaison Mettre à jour une connexion de Management API v2 et ajouter une propriété signing_key à l’objet options, comme indiqué dans l’exemple de charge utile ci-dessous.

La mise à jour de l’objet options pour une connexion remplace l’ensemble de l’objet options. Pour conserver les options de connexion précédentes, récupérez l’objet options existant et ajoutez-y de nouvelles clés/valeurs.

Point de terminaison : https://{yourDomain}/api/v2/connections/{yourConnectionId}

Charge utile :

{
	{ 
		"options" : {
			[...], // all the other connection options
		  "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 formatés en tant que chaîne JSON à utiliser dans la charge utile, consultez Utilisation de certificats, de clés et de chaînes.

Si Auth0 est le fournisseur de services SAML, toutes les réponses SAML de votre fournisseur d’identité doivent être signées pour indiquer qu’elles n’ont pas été modifiées par un tiers non autorisé.

Vous devrez configurer Auth0 pour valider les signatures des réponses en obtenant un certificat de signature du fournisseur d’identité et en chargeant le certificat du fournisseur d’identité dans votre connexion Auth0 :

1. Naviguez vers Auth0 Dashboard > Authentification > Entreprise, et sélectionnez SAML.

2. Sélectionnez le nom de la connexion à afficher.

3. Localisez le Certificat de signature X509, et téléversez le certificat.

4. Sélectionnez Enregistrer les modifications.

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

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

• CER

• PEM

• PEM brut

• PKCS#7

• Empreinte numérique

Télécharger le certificat dans le format demandé par l’IdP.

Comme indiqué ci-dessus, Auth0 utilisera par défaut la paire de clés privée/publique de votre locataire pour gérer le chiffrage. 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 duTableau de bord, vous devrez donc utiliser le point de terminaison Mettre à jour une connexion de 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 pour une connexion remplace l’ensemble de l’objet options. Pour conserver les options de connexion précédentes, récupérez l’objet options existant et ajoutez-y de nouvelles clés/valeurs.

Point de terminaison : https://{yourDomain}/api/v2/connections/{yourConnectionId}

Charge utile :

{
	{ 
		"options" : {
			[...], // all the other connection options
		  "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 lorsque Auth0 est le fournisseur d’identité SAML pour une application. Celle-ci est représentée dans le Dashboard par 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/le certificat nécessaire pour valider la signature.

Pour signer les assertions SAML :

1. Allez sur Auth0 Dashboard > Applications, et sélectionnez le nom de l’application à afficher.

2. Faites défiler jusqu’au bas de la page Paramètres, sélectionnez Afficher les paramètres avancés et sélectionnez l’affichageCertificats

3. Sélectionnez Télécharger le certificat et sélectionnez le format dans lequel vous souhaitez recevoir votre certificat de signature.

4. Envoyer votre certificat au fournisseur de services.

Par défaut, Auth0 signe l’assertion SAML dans la réponse. Pour signer la réponse SAML à la place :

1. Naviguez vers Auth0 Dashboard > Applications, et sélectionnez le nom de l’application à afficher.

2. Sélectionnez l’affichage Modules complémentaires.

3. Sélectionnez Application Web SAML2 pour afficher ses paramètres, et localisez le bloc de code Paramètres .

4. Localisez la clé "signResponse". Décommentez-la (ou ajoutez-la, si nécessaire), puis donnez-lui la valeur true (la valeur par défaut est false). La configuration devrait ressembler à ceci :

   {
     [...], // other settings
     "signResponse": true
   }

   Was this helpful?

   Yes /No

Par défaut, Auth0 utilise la paire de clés privée/publique attribuée à votre locataire pour signer les réponses ou assertions SAML. Pour des scénarios très spécifiques, vous pouvez souhaiter fournir votre propre paire de clés. Vous pouvez le faire avec une règle comme celle-ci :

/**
* Handler that will be called during the execution of a PostLogin flow.
*
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {PostLoginAPI} api - Interface whose methods can be used to change the behavior of the login.
*/
exports.onExecutePostLogin = async (event, api) => {

    // replace with the ID of the application that has the SAML Web App Addon enabled
      // for which you want to change the signing key pair.
      const samlIdpClientId = 'YOUR_SAML_APP_CLIENT_ID';

    // only do this for the specific client ID.  If you have multiple IdPs that require 
    // custom certificates, you will have an "if" statement for each one.  
    if (event.client.client_id === samlIdpClientId) {

    // provide your own private key and certificate here  
    // see https://auth0.com/docs/authenticate/protocols/saml/saml-sso-integrations/work-with-certificates-and-keys-as-strings 
    // for formatting instructions basically you start with a PEM format certificate and
    // replace the line enedings with "\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 transformer les fichiers de clé privée et de certificat en chaînes que vous pouvez utiliser dans une règle, consultez Utilisation de certificats, de clés et de chaînes.

Si Auth0 est le fournisseur d’identité SAML, il peut recevoir des demandes signées avec la clé privée du fournisseur de services. Auth0 utilise la clé publique/le certificat pour valider la signature.

Pour configurer la validation de la signature :

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

2. Naviguez vers Auth0 Dashboard > Applications, et sélectionnez le nom de l’application à afficher.

3. Sélectionnez l’affichage Modules complémentaires.

4. Sélectionnez Application Web SAML2 pour afficher ses paramètres, et localisez le bloc de code Paramètres .

5. Localisez la clé "signingCert". Décommentez-la (ou ajoutez-la, si nécessaire), puis définissez sa valeur en fonction du certificat que vous avez téléchargé depuis le fournisseur de services. La configuration devrait ressembler à ceci :

   {
     [...], // other settings
     "signingCert": "-----BEGIN CERTIFICATE-----\nMIIC8jCCAdqgAwIBAgIJObB6jmhG0QIEMA0GCSqGSIb3DQEBBQUAMCAxHjAcBgNV\n[..all the other lines..]-----END CERTIFICATE-----\n"
   }

   Was this helpful?

   Yes /No

Si Auth0 est le fournisseur d’identité SAML, vous pouvez utiliser des Actions pour chiffrer les assertions SAML qu’il envoie.

Vous devez obtenir le certificat et la clé publique auprès du fournisseur de services. Si vous n’avez que le certificat, vous pouvez dériver la clé publique en utilisant openssl. En supposant que le fichier de certificat soit nommé certificate.pem, vous pouvez exécuter :

openssl x509 -in certificate.pem -pubkey -noout > public_key.pem

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

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

// this Action sets a specific public key to encrypt the SAML assertion generated from 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);
  }
};

Les algorithmes suivants sont utilisés :

• AES256 pour le chiffrement d’assertion

• RSA-OAEP (y compris MGF1 et SHA1) pour le transport des clés

• Utilisation de certificats et de clés sous forme de chaînes de caractères