Enabling your web app for SAML with Identity Platform

This guide shows how to enable an existing web application for Security Assertion Markup Language (SAML) 2.0, with Identity Platform. This will include accepting SAML assertions from identity providers (IdP) as a SAML service provider, verifying their contents, and producing a lightweight JWT that you can use in your application to verify authentication and perform authorization.

Before you begin

To enable SAML for your web app, you'll need the following:

  • Access to an application that you want to enable for SAML sign-on.
  • A Google Cloud project for which you're a Project Owner, with billing enabled for the project.
  • Identity Platform enabled for the project.

Configuring an Identity Platform project with your SAML identity provider

  1. Go to the Identity Providers page in the Cloud Console.
    Go to the Identity Providers page
  2. Click Add A Provider.
  3. On the Select a provider drop-down list, select SAML.
  4. Next to Enabled, click the button to enable the provider.
  5. Under Sign-in method, enter the following details:
    1. A Display Name.
    2. Enter the SAML EntityID from your SAML identity provider.
    3. Enter the SAML SSO URL from your SAML identity provider.
  6. Under Certificate, paste the certificate used for token-signing on the identity provider. Make sure to include the START and END CERTIFICATE strings.
  7. Under Service provider, enter the EntityId of your application. This is commonly the URL of your application. On your SAML identity provider, this is referred to as the audience.
    1. If necessary, customize the callback URL for your application. This is commonly the Assertion Consumer Service (ACS) URL in your SAML identity provider.

Note that using the default callback URL can help minimize the complexity of validating the SAML response. When you use this flow, make sure that the Identity Platform callback URL for your project is configured at your SAML identity provider. This is usually in the form of https://<authDomain>/__/auth/handler. For information on customizing the callback URL, see Customizing the Redirect Domain.

The Identity Platform client SDK provides an API that handles the entire SAML authentication handshake. It then returns ID tokens that contain all of the additional SAML attributes in its payload.

Whitelisting your website domain

If you're signing in users to https://www.example.com/login, you will need to add www.example.com to the list of authorized domains in Identity Platform. To do this:

  1. Go to the Identity Platform Settings page in the Cloud Console.
    Go to the Identity Platform Settings page
  2. Under Authorized Domains, click Add Domain.
  3. Add any domains that should be allowed to authenticate your end users.

Identity Platform is now configured to trust assertions from your SAML identity provider.

Configuring your web application

Next, you'll configure your web application to support SAML SSO flows via the client SDK. For more information about the Web SDK, see the docs.

Step 1: Adding the SDK to your application

To add the SDK to your application, follow the steps below:

  1. Go to the Identity Platform Users page in the Cloud Console.
    Go to the Identity Platform Users page
  2. On the top right, click application setup details.
  3. Copy the application setup details into your web application. For example:

       <script src="https://www.gstatic.com/firebasejs/5.5.4/firebase.js"></script>
       <script>
         // Initialize Identity Platform
         var config = {
           apiKey: "...",
           authDomain: "my-app-12345.firebaseapp.com"
         };
         firebase.initializeApp(config);
       </script>
    

Step 2: Handling the sign-in flow with the client SDK

To sign in with a SAML provider, you need to instantiate a SAMLAuthProvider instance using the provider ID that is used to configure the provider in the Cloud Console:

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

When you use this sign-in mechanism, you can configure sign in to use a popup or a redirect flow:

  • To sign in with a popup-window, call signInWithPopup:

      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 via result.user.getIdToken()
          // as an object in the firebase.sign_in_attributes custom claim
          // This is also available via result.user.getIdTokenResult()
          // idTokenResult.claims.firebase.sign_in_attributes.
        })
        .catch((error) => {
          // Handle error.
        });
    
  • To sign in by redirecting to the sign-in page, call signInWithRedirect:

      firebase.auth().signInWithRedirect(provider);
    

After the user completes sign-in and returns to the your application, you can get the sign-in result by calling getRedirectResult:

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

After sign-in is completed, more user attributes that are associated with the SAML provider can be securely retrieved from the user's ID token by checking the firebase.sign_in_attributes claim. When sending the Identity Platform ID token to your server to parse the corresponding claims, make sure you verify the ID token using the Admin SDK.

Currently, only service-provider (SP) initiated SAML flows via the web SDK are supported.

You can also link a SAML provider to an existing user using linkWithPopup or linkWithRedirect. For example, you can link multiple providers to the same user, so they can sign in with either method:

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

// Link with a popup.
firebase.auth().currentUser.linkWithPopup(provider)
      // currentUser.providerData array now has an additional entry for this provider.
    })
    .catch((error) => {
      // Handle error.
    });

Sensitive operations like updating email or adding or modifying a password will require recent sign-in using reauthenticateWithPopup or reauthenticateWithRedirect APIs:

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

// Reauthenticate with a popup.
firebase.auth().currentUser.reauthenticateWithPopup(provider)
    .then((result) => {
      // Get the updated ID token.
      return result.user.getIdTokenResult();
    })
    .then((idTokenResult) => {
      // idTokenResult.authTime should be updated to reflect recent sign-in status.
      // idTokenResult.token has the latest ID token.
    })
    .catch((error) => {
      // Handle error.
    });

Customizing the redirect domain

When you create a project, Identity Platform will provision a unique subdomain for your project powered by Firebase Hosting, like https://my-app-12345.firebaseapp.com. This will also be used as the redirect mechanism for all OAuth, OIDC, and SAML based sign-in operations. Your project name at the FirebaseApp domain will be automatically whitelisted for all supported OAuth/SAML/SAML providers. This means that users will see that URL while signing in to Google, before redirecting back to the application.

To customize the URL to show a domain that you own, follow the steps below:

  1. Use the Firebase Console to connect a custom domain to your project.
  2. Use the Cloud Console to add your custom domain auth.custom.domain.com to the list of authorized domains.
  3. In your identity provider's configuration, update the callback URL from https://my-app-12345.firebaseapp.com/__/auth/handler to https://auth.custom.domain.com/__/auth/handler.
  4. When you initialize your Auth instance, update the authDomain to the custom domain:

       firebase.initializeApp({
         apiKey: '...',
         // Replace the default one with your custom domain.
         // authDomain: 'my-app-12345/firebaseapp.com',
         authDomain: 'auth.custom.domain.com'
       });
    

By completing this guide, your web app is now configured for using SAML with Identity Platform, including sign-in flow and a custom redirect domain.

Was this page helpful? Let us know how we did:

Send feedback about...

Cloud Identity for Customers and Partners Documentation
Need help? Visit our support page.