SAML for Firebase using a custom OIDC provider
Use SSOReady to add painless SAML support to your product
Firebase has support for SAML. That support works, and is secure. But many folks run into a few problems:
-
Firebase makes onboarding new customers is 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.
-
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:
- Basic concepts. How Enterprise SSO / SAML works at a high level, and how SSOReady will help you implement it in your Firebase application.
- Code implementation. What you’ll need to build, and how to use SSOReady’s Firebase integration.
- 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:
Create an SSOReady SAML OAuth Client
For more details on what you’re setting up in this step, see Creating environments and Creating SAML OAuth Clients in the Setting up SSOReady section.
Sign up to SSOReady, if you haven’t already. It’s free and anyone can sign up, even with a personal email.
Create an environment. You can do so
directly from this page. Choose
any name you like, and choose any Redirect URL — http://localhost
is
fine. Because we’ll be using SAML-over-OAuth, this value won’t be used.
Leave OAuth Redirect URI blank — we’ll get its correct value from Firebase
later.
Create a SAML OAuth Client. You can do so by going to “API Keys” from the left sidebar, and then clicking on “Create SAML OAuth Client”.
A popup now appears. Click on the SAML OAuth Client secret to copy it. Paste that somewhere temporary, you’ll need it in step (3). Click “Done”. You’re now viewing a SAML OAuth Client’s details.
We’re done setting things up on the SSOReady side. Open a new tab, and go to Firebase.
Go to your Firebase app’s “Sign-in method” Settings
Go to your Firebase application in the Firebase console, if you haven’t already.
You can find these settings by clicking on “Build” in the left sidebar, then Authentication. In the top navigation bar, go to the “Sign-in method” tab.
Add a new OpenID Connect provider
Click on “Add a new provider”. Then click on “OpenID Connect”. Then toggle “Enable” to be on. Configure the OIDC provider as follows:
-
Grant type: Keep this value as “Code flow”, which is the default.
-
Name: We recommend “SSOReady SAML”. The provider ID becomes
oidc.ssoready-saml
. If you choose a different name, you’ll need to make sure that you adapt the code in Code implementation to use your provider ID instead ofoidc.ssoready-saml
. -
Client ID: In the SSOReady tab from step (1), you’re looking at the SAML OAuth Client you created. Copy its ID — it starts with
saml_oauth_client_...
— into the Client ID in Firebase. -
Issuer URL: Set this to
https://auth.ssoready.com/v1/oauth
. -
Client secret: In step (1), you copied a SAML OAuth Client secret. Its value starts with
ssoready_oauth_client_secret_...
. Paste that into the Client secret in Firebase.
Click “Next”. Firebase now shows you a Callback URL — it ends in
/__/auth/handler
. Copy that value, and then click “Save”.
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:
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:
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.
- What is an SSOReady environment? An environment is how you tell SSOReady where your Firebase app lives.
- 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.
- 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
You can skip this step if you’ve already followed Setting up Firebase.
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:
Set your environment’s OAuth Redirect URI to the Firebase callback URL.
Creating SAML OAuth clients
You can skip this step if you’ve already followed Setting up Firebase.
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 putapple.com
andshazam.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:
- 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.
- 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:
- Give your customers an “SP Entity ID” and “SP ACS URL”. SSOReady’s webapp gives you both.
- 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!