Signing in users with SAML  |  Identity Platform Documentation  |  Google Cloud (2024)

• Home
• Identity Platform
• Documentation
• Guides

This document shows you how to use Identity Platform to sign in users with aSecurity 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 theQuickstart tolearn 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 toProvider 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 toinclude 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 istypically your app's URL. On your SAML identity provider, this isreferred to as the audience.

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

   See Also

   Understanding SAML | Okta DeveloperHow SAML Authentication Works?Configure Auth0 as SAML Identity ProviderSSO assertion requirements - Google Workspace Admin Help

6. If necessary, customize the callback URL for your app. This iscommonly called the Assertion Consumer Service (ACS) URL by SAMLidentity providers.

   Using the default callback URL reduces the complexity of validating the SAMLresponse. If you customize this flow, make sure the Identity Platformcallback 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 handlerto 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 bycalling 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 theGoogle Cloud console or Google Cloud CLI is not supported.

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

Signing in users

When you sign a user in, the Client SDK handles the authenticationhandshake, then returns ID tokens containing the SAML attributes in theirpayloads. To sign a user in and get attributes from the SAML provider:

1. Create a SAMLAuthProviderinstance with the provider ID you configured inthe previous section. The provider ID must start with saml..

   See Also

   Set up your own custom SAML app

   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 { 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

   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 IDtoken using the firebase.sign_in_attributes claim. Make sure to verify theID 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 theNameID 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 SDKare 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