Firebase has support for SAML. That support works, and is secure. But many folks run into a few problems:

1. Firebase makes onboarding new customers a manual process for you and your customer. It’s also confusing for you and your customer, because Firebase’s docs do not explain how to onboard customers at all.

   SAML intrinsically requires that you give your customer some SAML settings, and then they give you some settings. Firebase’s SAML docs don’t at all explain where your customer is supposed to put the settings you give them. In fact, Firebase’s docs don’t even clarify that one of the settings — “Your app’s Entity ID” — is something you need to assign. The docs make no mention of the “ACS URL” (which Firebase calls a “callback URL”, a term your customers will not understand) at all — a setting that SAML can never work without.

2. Relatedly, it’s very confusing how to test or dogfood your SAML support.

You can use SSOReady to take away these problems — you’ll find this article and the rest of our docs to be explicit, clear, and detailed. SSOReady’s self-serve setup UI automates SAML onboarding for you, and gives your customers a best-in-class experience.

SSOReady integrates into Firebase as a custom OIDC provider. You can add SAML support to your Firebase application in an afternoon.

Getting started with SSOReady

This guide will take you through:

1. Basic concepts. How Enterprise SSO / SAML works at a high level, and how SSOReady will help you implement it in your Firebase application.
2. Code implementation. What you’ll need to build, and how to use SSOReady’s Firebase integration.
3. Onboarding customers. SAML requires both you and your customer do setup. SSOReady automates your end of the equation, and this section describes what instructions you’ll give to your customers.

SSOReady is just an authentication middleware layer. SSOReady doesn’t “own” your users, and it doesn’t require you to use any particular tech stack, although this article assumes Firebase. That’s on purpose — it makes onboarding easier for you, and it forces us to keep earning your business in the long run, because churning is easier.

Basic concepts

“Enterprise SSO” is mostly a synonym for a protocol called SAML. It’s a way for a company to easily let their employees log into all their software products, including your product.

At smaller companies, employees use username+password or “Log in with Google” to sign into your product. At larger companies, employees instead expect to use services like Okta or Microsoft Entra (formerly “Azure AD”) to do sign-in. Those sign-ins happen using the SAML protocol.

SSOReady makes it way easier to implement SAML. SSOReady’s OAuth-over-SAML functionality makes SAML fit into existing OAuth-based applications, so you can use SSOReady as a custom OIDC provider in your Firebase app. From your code’s perspective, SSOReady will seem like an ordinary custom OIDC provider. Under the hood, and from your customer’s perspective, it will actually be a SAML login, with all the benefits that brings for your customer.

We’ll cover how to create a custom Firebase OIDC provider in Setting up Firebase. We’ll then see the code you need to write in Code implementation. We’ll cover the setup work you’ll need to do inside SSOReady’s webapp in Setting up SSOReady. We’ll cover the settings you’ll give and ask for in Onboarding customers.

Setting up Firebase

SSOReady can act as a Firebase OpenID Connect (“OIDC”) provider. To set up SSOReady’s integration with Firebase, follow these steps:

With that, both Firebase and SSOReady are configured. Your next step is to add a bit of code to tell Firebase to do a SAML-based login using SSOReady.

Code implementation

From here, you’ll use Firebase’s sign-in flows for OIDC connectors. You’ll want to use the “Pop-up flow”, because Firebase’s “redirect flow” doesn’t work with modern browsers.

You need to pass an organizationExternalId custom OAuth parameter. How you get that value is covered in Setting up SSOReady later on this page.

Putting it all together, typically you’ll write Firebase code that looks like this:

1
import { getAuth, signInWithPopup, OAuthProvider } from "firebase/auth";
2
3
const provider = new OAuthProvider("oidc.ssoready-saml");
4
provider.setCustomParameters({
5
  organizationExternalId: "..." // see "Setting up SSOReady" for what you put here
6
})
7
8
const auth = getAuth();
9
await signInWithPopup(auth, provider)

From here, SSOReady and Firebase will automatically integrate together to log users into your system over SAML.

If you want to get the user’s SAML email address, you can get that from the current user like so:

1
const auth = getAuth();
2
const samlEmail = auth.currentUser.providerData
3
    .find(({ providerId }) => providerId === "oidc.ssoready-saml")
4
    .uid

Setting up SSOReady

Setting up Firebase breezed through creating something called an “environment” and a “SAML OAuth Client”. In Code implementation, there was one missing detail (organizationExternalId) that you need to implement SSOReady. This section explains what’s going on with those.

1. What is an SSOReady environment? An environment is how you tell SSOReady where your Firebase app lives.
2. What is an SSOReady SAML OAuth Client? A SAML OAuth Client belongs to an environment. It’s an adapter that makes SAML look like OAuth.
3. How do I get organizationExternalId? You create an organization in an environment, where you can choose an external ID convenient for you.

This section will step you through how you’ll do all of this setup in SSOReady’s webapp. As a prerequisite step, you’ll need to sign up to SSOReady. It’s free and anyone can sign up, even with a personal email.

Creating environments

To create an environment, go here. You’ll typically create one environment per Firebase project. Environments require a “Redirect URL”, but if you only ever use SAML-over-OAuth, its value is never used. When you’re integrating SSOReady with Firebase, what matters is the environment’s OAuth Redirect URI.

Firebase calls the SSOReady OAuth Redirect URI a “callback URL”. Its value should be something like:

https://your-firebase-project-name.firebaseapp.com/__/auth/handler

Set your environment’s OAuth Redirect URI to the Firebase callback URL.

Creating SAML OAuth clients

SAML and OAuth are different protocols, but SSOReady’s SAML OAuth Clients act as bridge between the two. They look to the outside world like a normal OAuth client, but under the hood they wrap SAML to carry out an OAuth flow.

SAML OAuth Clients are scoped to an environment. When viewing an environment in the app, click “API Keys” on the left navbar. Then click “Create SAML OAuth Client”. A popup will show you your new SAML OAuth client’s secret (it starts with ssoready_oauth_client_secret_...). That’s the “Client secret” you’ll input into Firebase

After clicking “View SAML OAuth Client” on that popup, you’ll also see the client’s ID (it starts with saml_oauth_client_...). That’s the “Client ID” you’ll input into Firebase.

Creating organizations

An organization corresponds to a corporate customer of yours. If you sold your product to Apple, Nvidia, and Amazon, you’d have three organizations in SSOReady: one each for Apple, Nvidia, and Amazon.

Organizations belong to an environment. When viewing an environment in the app, the “Create organization” button creates a new organization. Organizations have two properties worth highlighting:

• An optional external ID, which you can assign. If you’re selling multi-tenant B2B software, you probably already have a concept that closely matches an SSOReady organization — usually, this is something named a “team”, “workspace”, “company”, or something similar. When creating an SSOReady organization, use your product’s counterpart to an organization ID as the external ID.

  You’ll provide the external ID as the organizationExternalId in your code implementation.

• A set of domains. If you expect Apple’s employees will log in to your product from @apple.com and @shazam.com email addresses, then put apple.com and shazam.com here. SSOReady will enforce that users’ SAML logins come from these domains.

Creating SAML connections

A SAML connection holds onto SAML-related settings. In “Onboarding customers”, you’ll be providing and asking for settings. Those settings all live on an SSOReady SAML connection.

SAML connections belong to an organization. When viewing an organization in the app, the “Create SAML connection” button creates a new SAML connection. Beyond the SAML-related settings covered in “Onboarding customers”, SAML connections have one setting of note: whether they are primary.

Each organization has up to one primary SAML connection. In your code implementation, you provide an organizationExternalId. SSOReady will use that organization’s primary SAML connection to initiate the login.

Onboarding customers

In Basic concepts, we mentioned that you and your customer need to exchange details about each other before you can do SAML logins. This process happens offline — there’s no coding involved.

You have to go through this process each time a new company wants to set up SAML. It’s inherent to how SAML was designed.

With SSOReady, you have two options for onboarding customers onto SAML — that is, exchanging SAML-related settings with them. You can:

1. Use SSOReady’s self-serve setup links. You give your customers a link, where they can set up SAML on their own. It’s a slick experience for your customers, and they’ll get set up in minutes. We recommend this approach.
2. Give your customers instructions yourself, over email/slack/Zoom/etc.

If you go with option (2), be advised that SAML identity providers (e.g. Okta, Microsoft Entra, Google Workspace, etc.) don’t use the same terminology for these identical details. To deal with that, we’ve prepared a separate set of documentation for you to follow depending on what identity provider your customer uses:

• Okta
• Google Workspace
• Microsoft Entra (aka Microsoft Azure Active Directory, Microsoft Azure AD)
• JumpCloud
• Ping Identity

In all cases, you’re ultimately going to:

1. Give your customers an “SP Entity ID” and “SP ACS URL”. SSOReady’s webapp gives you both.
2. Ask your customers for an “IDP Entity ID”, “IDP Redirect URL”, and “IDP Certificate” which you input into SSOReady.

Once you have all those details, you’ll be ready to accept SAML logins!