Signing in users with SAML

This document shows you how to use Identity Platform to sign in users with a Security Assertion Markup Language (SAML) 2.0 provider.

Before you begin

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. Enable Identity Platform, and add the client SDK to your app. See the Quickstart to learn how.

Configuring the provider

1. Go to the Identity Providers page in the Google Cloud console.
   Go to the Identity Providers page
   

2. Click Add a Provider, and select SAML from the list.

3. Enter the following details:

   1. The Name of the provider. This can be the same as the provider ID, or a custom name. If you enter a custom name, click Edit next to Provider ID to specify the ID (which must begin with saml.).

   2. The provider's Entity ID.

   3. The provider's SAML SSO URL.

   4. The certificate used for token-signing on the provider. Make sure to include the start and end strings. For example:

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

4. Under Service provider, enter the Entity ID of your app. This is typically your app's URL. On your SAML identity provider, this is referred to as the audience.

5. Add your app to the list of Authorized Domains. For example, if your app's sign-in URL is https://example.com/login, add example.com.

6. If necessary, customize the callback URL for your app. This is commonly called the Assertion Consumer Service (ACS) URL by SAML identity providers.

   Using the default callback URL reduces the complexity of validating the SAML response. If you customize this flow, make sure the Identity Platform callback URL for your project is configured on your SAML identity provider. This usually looks something like https://[PROJECT-ID].firebaseapp.com/__/auth/handler. See Customizing an authentication handler to learn more.

7. Click Save.

Provider required elements

Identity Platform expects the <saml:Subject> and <saml:NameID> elements in responses from the provider. If you don't define values for these elements when configuring your provider, the SAML assertion fails.

Signing requests

You can increase the security of your authentication requests by signing them.

To sign requests, first enable signed requests for your identity provider by calling inboundSamlConfigs.patch(), and setting idp_config.sign_request to 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

You must use the REST API to enable signed requests; using the Google Cloud console or Google Cloud CLI is not supported.

The response is an InboundSamlConfig object, which includes an array of SpCertificate. Configure the value of the X509 certificate with your SAML identity provider so it can validate the signature of your requests.

Signing in users

When you sign a user in, the client SDK handles the authentication handshake, then returns ID tokens containing the SAML attributes in their payloads. To sign a user in and get attributes from the SAML provider:

1. Create a SAMLAuthProvider instance with the provider ID you configured in the previous section. The provider ID must start with saml..

   Web version 9

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

   Web version 8

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

2. Start the sign in flow. You can choose to either use a popup or a redirect.

   Popup

   Web version 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

   Web version 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

   Redirect

   To redirect to a sign-in page, call signInWithRedirect():

   Web version 9

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

   Web version 8

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

   Then, call getRedirectResult() to get the results when the user returns to your app:

   Web version 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

   Web version 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. Retrieve the user attributes associated with the SAML provider from the ID token using the firebase.sign_in_attributes claim. Make sure to verify the ID token using the Admin SDK when you send it to your server.

   The ID token includes the user's email address only if it is provided in the NameID attribute of the SAML assertion from the identity provider:

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

   This is populated in the Firebase-issued ID token and in the UserInfo object.

Currently, only service-provider initiated SAML flows from the client SDK are supported.

Linking user accounts

If a user has already signed in to your app using a different method (such as email/password), you can link their existing account to the SAML provider using linkWithPopup() or linkWithRedirect(): For example we can link with a Google account:

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

What's next

• Signing in users with OIDC
• Showing a custom domain during sign in
• Managing OIDC and SAML providers programmatically