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
- 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.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Google Cloud project.
- Enable Identity Platform, and add the Client SDK to your app. See the Quickstart to learn how.
Configuring the provider
Go to the Identity Providers page in the Google Cloud console.
Go to the Identity Providers pageClick Add a Provider, and select SAML from the list.
Enter the following details:
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.
).The provider's Entity ID.
The provider's SAML SSO URL.
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-----
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.
Add your app to the list of Authorized Domains. For example, if your app's sign-in URL is
https://example.com/login
, addexample.com
.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.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
:
REST
Before using any of the request data, make the following replacements:
project-id
: the ID for the Google Cloud projectprovider-id
: the SAML provider ID
HTTP method and URL:
PATCH https://identitytoolkit.googleapis.com/admin/v2/projects/project-id/inboundSamlConfigs/provider-id?updateMask=idpConfig.signRequest
Request JSON body:
{ "idp_config": { "sign_request": true } }
To send your request, expand one of these options:
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:
Create a
SAMLAuthProvider
instance with the provider ID you configured in the previous section. The provider ID must start withsaml.
.Web version 9
import { SAMLAuthProvider } from "firebase/auth"; const provider = new SAMLAuthProvider("saml.myProvider");
Web version 8
const provider = new firebase.auth.SAMLAuthProvider('saml.myProvider');
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. // ... });
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. // ... });
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);
Web version 8
firebase.auth().signInWithRedirect(provider);
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. // ... });
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. // ... });
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:
Web version 9
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. // ... });
Web version 8
auth.currentUser.linkWithPopup(provider).then((result) => { // Accounts successfully linked. var credential = result.credential; var user = result.user; // ... }).catch((error) => { // Handle Errors here. // ... });
What's next
- Signing in users with OIDC
- Showing a custom domain during sign in
- Managing OIDC and SAML providers programmatically