Procéder à la connexion des utilisateurs avec SAML

Ce document explique comment utiliser Identity Platform pour connecter des utilisateurs avec un fournisseur SAML (Security Assertion Markup Language) 2.0.

Avant de commencer

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

6. Activez Identity Platform et ajoutez le SDK client à votre application. Pour savoir comment procéder, consultez le guide de démarrage rapide.

Configurer le fournisseur

1. Accédez à la page Fournisseurs d'identité dans la console Google Cloud.
   Accéder à la page "Fournisseurs d'identité"
   

2. Cliquez sur Ajouter un fournisseur, puis sélectionnez SAML dans la liste.

3. Saisissez les informations suivantes :

   1. Le nom du fournisseur. Il peut s'agir de l'ID du fournisseur ou d'un nom personnalisé. Si vous saisissez un nom personnalisé, cliquez sur Modifier à côté de ID de fournisseur pour spécifier l'ID (qui doit commencer par saml.).

   2. ID d'entité du fournisseur.

   3. L'URL SSO SAML du fournisseur

   4. Certificat utilisé pour la signature des jetons sur le fournisseur. Veillez à inclure les chaînes de début et de fin. Exemple :

      -----BEGIN CERTIFICATE-----
      MIICajCCAdOgAwIBAgIBADANBgkqhkiG9w0BAQ0FADBSMQswCQYDVQQGEwJ1czEL
      ...
      LEzc1JwEGQQVDYQCwsQMSBDAF0QAB0w9GikhqkgBNADABIgABIwAgOdACCjaCIIM
      -----END CERTIFICATE-----
      

4. Sous Fournisseur de services, saisissez l'ID d'entité de votre application. Il s'agit généralement de l'URL de votre application. Sur votre fournisseur d'identité SAML, il s'agit de l'audience.

5. Ajoutez votre application à la liste des Domaines autorisés. Par exemple, si l'URL de connexion de votre application est https://example.com/login, ajoutez example.com.

6. Si nécessaire, personnalisez l'URL de rappel de votre application. Les fournisseurs d'identité SAML le nomment généralement l'URL du service ACS (Assertion Consumer Service).

   L'utilisation de l'URL de rappel par défaut réduit la complexité de la validation de la réponse SAML. Si vous personnalisez ce flux, assurez-vous que l'URL de rappel d'Identity Platform pour votre projet est configurée sur votre fournisseur d'identité SAML. Elle se présente généralement sous la forme https://[PROJECT-ID].firebaseapp.com/__/auth/handler. Pour en savoir plus, consultez la section Personnaliser un gestionnaire d'authentification.

7. Cliquez sur Enregistrer.

Éléments obligatoires pour le fournisseur

Identity Platform attend les éléments <saml:Subject> et <saml:NameID> dans les réponses du fournisseur. Si vous ne définissez pas de valeurs pour ces éléments lorsque vous configurez votre fournisseur, l'assertion SAML échoue.

Signer les requêtes

Vous pouvez renforcer la sécurité de vos requêtes d'authentification en les signant.

Pour signer des requêtes, commencez par activer les requêtes signées pour votre fournisseur d'identité en appelant inboundSamlConfigs.patch() et en définissant idp_config.sign_request sur true :

PATCH https://identitytoolkit.googleapis.com/admin/v2/projects/project-id/inboundSamlConfigs/provider-id?updateMask=idpConfig.signRequest

{
  "idp_config": {
    "sign_request": true
  }
}

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: project-id" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://identitytoolkit.googleapis.com/admin/v2/projects/project-id/inboundSamlConfigs/provider-id?updateMask=idpConfig.signRequest"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "project-id" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://identitytoolkit.googleapis.com/admin/v2/projects/project-id/inboundSamlConfigs/provider-id?updateMask=idpConfig.signRequest" | Select-Object -Expand Content

Vous devez utiliser l'API REST pour activer les requêtes signées. La console Google Cloud ou Google Cloud CLI ne sont pas compatibles.

La réponse est un objet InboundSamlConfig, qui comprend un tableau de SpCertificate. Configurez la valeur du certificat X509 avec votre fournisseur d'identité SAML afin qu'il puisse valider la signature de vos requêtes.

Procéder à la connexion des utilisateurs

Lorsque vous connectez un utilisateur, le SDK client gère le handshake d'authentification, puis renvoie des jetons d'ID contenant les attributs SAML dans leurs charges utiles. Pour connecter un utilisateur et obtenir les attributs du fournisseur SAML, procédez comme suit :

1. Créez une instance SAMLAuthProvider avec l'ID de fournisseur que vous avez configuré à la section précédente. L'ID du fournisseur doit commencer par saml..

   Version Web 9

   import { SAMLAuthProvider } from "firebase/auth";
   
   const provider = new SAMLAuthProvider("saml.myProvider");
   auth_saml_provider_create.js

   Version Web 8

   const provider = new firebase.auth.SAMLAuthProvider('saml.myProvider');
   saml.js

2. Démarrez le flux de connexion. Vous pouvez choisir d'utiliser un pop-up ou une redirection.

   Fenêtre pop-up

   Version Web 9

   import { getAuth, signInWithPopup, SAMLAuthProvider } from "firebase/auth";
   
   const auth = getAuth();
   signInWithPopup(auth, provider)
     .then((result) => {
       // User is signed in.
       // Provider data available from the result.user.getIdToken()
       // or from result.user.providerData
     }).catch((error) => {
       // Handle Errors here.
       const errorCode = error.code;
       const errorMessage = error.message;
       // The email of the user's account used.
       const email = error.customData.email;
       // The AuthCredential type that was used.
       const credential = SAMLAuthProvider.credentialFromError(error);
       // Handle / display error.
       // ...
     });
   auth_saml_signin_popup.js

   Version Web 8

   firebase.auth().signInWithPopup(provider)
     .then((result) => {
       // User is signed in.
       // Identity provider data available in result.additionalUserInfo.profile,
       // or from the user's ID token obtained from result.user.getIdToken()
       // as an object in the firebase.sign_in_attributes custom claim
       // This is also available from result.user.getIdTokenResult()
       // idTokenResult.claims.firebase.sign_in_attributes.
     })
     .catch((error) => {
       // Handle / display error.
       // ...
     });
   saml.js

   Rediriger

   Pour rediriger vers une page de connexion, appelez signInWithRedirect():

   Version Web 9

   import { getAuth, signInWithRedirect } from "firebase/auth";
   
   const auth = getAuth();
   signInWithRedirect(auth, provider);
   auth_saml_signin_redirect.js

   Version Web 8

   firebase.auth().signInWithRedirect(provider);
   saml.js

   Appelez ensuite getRedirectResult() pour obtenir les résultats lorsque l'utilisateur revient à votre application:

   Version Web 9

   import { getAuth, getRedirectResult, SAMLAuthProvider } from "firebase/auth";
   
   const auth = getAuth();
   getRedirectResult(auth)
     .then((result) => {
       // User is signed in.
       // Provider data available from the result.user.getIdToken()
       // or from result.user.providerData
     })
     .catch((error) => {
       // Handle Errors here.
       const errorCode = error.code;
       const errorMessage = error.message;
       // The email of the user's account used.
       const email = error.customData.email;
       // The AuthCredential type that was used.
       const credential = SAMLAuthProvider.credentialFromError(error);
       // Handle / display error.
       // ...
     });
   auth_saml_signin_redirect_result.js

   Version Web 8

   firebase.auth().getRedirectResult()
     .then((result) => {
       // User is signed in.
       // Provider data available in result.additionalUserInfo.profile,
       // or from the user's ID token obtained from result.user.getIdToken()
       // as an object in the firebase.sign_in_attributes custom claim
       // This is also available from result.user.getIdTokenResult()
       // idTokenResult.claims.firebase.sign_in_attributes.
     }).catch((error) => {
       // Handle / display error.
       // ...
     });
   saml.js

3. Récupérez les attributs utilisateur associés au fournisseur SAML à partir du jeton d'ID en utilisant la revendication firebase.sign_in_attributes. Veillez à valider le jeton d'ID à l'aide du SDK Admin lorsque vous envoyez ce jeton à votre serveur.

   Le jeton d'ID n'inclut l'adresse e-mail de l'utilisateur que si elle est fournie dans l'attribut NameID de l'assertion SAML du fournisseur d'identité:

   <Subject>
     <NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">test@email.com</NameID>
   </Subject>
   

   Il est renseigné dans le jeton d'ID émis par Firebase et dans l'objet UserInfo.

Actuellement, seuls les flux SAML initiés par le fournisseur de services à partir du SDK client sont compatibles.

Associer des comptes utilisateur

Si un utilisateur s'est déjà connecté à votre application à l'aide d'une méthode différente (adresse e-mail/mot de passe, par exemple), vous pouvez associer son compte existant au fournisseur SAML à l'aide de linkWithPopup() ou linkWithRedirect() : Par exemple, nous pouvons associer un compte Google:

import { getAuth, linkWithPopup, GoogleAuthProvider } from "firebase/auth";
const provider = new GoogleAuthProvider();

const auth = getAuth();
linkWithPopup(auth.currentUser, provider).then((result) => {
  // Accounts successfully linked.
  const credential = GoogleAuthProvider.credentialFromResult(result);
  const user = result.user;
  // ...
}).catch((error) => {
  // Handle Errors here.
  // ...
});
auth_link_with_popup.js

auth.currentUser.linkWithPopup(provider).then((result) => {
  // Accounts successfully linked.
  var credential = result.credential;
  var user = result.user;
  // ...
}).catch((error) => {
  // Handle Errors here.
  // ...
});
link-multiple-accounts.js

Étape suivante

• Procéder à la connexion des utilisateurs avec OIDC
• Afficher un domaine personnalisé lors de la connexion
• Gérer les fournisseurs OIDC et SAML par programmation