For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Login
    • Introduction
  • SAML (Enterprise SSO)
    • SAML Quickstart
    • SAML: A technical primer
    • Integrating SAML with your Login UI
    • Handling SAML Logins + JIT Provisioning
  • SCIM (Enterprise Directory Sync)
    • SCIM Quickstart
  • SDKs
    • TypeScript SDK
    • Python SDK
    • Go SDK
    • Java SDK
    • C# SDK
    • Ruby SDK
    • PHP SDK
  • SAML-over-OAuth
    • SAML over OAuth (SAML NextAuth.js integration)
    • SAML for Firebase
  • IDP configuration
    • Enabling self-service configuration for your customers
  • SSOReady concepts
    • Overview
    • Environments
    • Organizations
    • SAML Connections
    • SAML Login Flows
    • SCIM Directories
    • SCIM Users
    • SCIM Groups
    • SCIM Request Logs
  • Management API
    • Management API
  • DummyIDP
    • Testing SAML/SCIM with DummyIDP
  • Self-Hosting
    • Self-Hosting SSOReady
  • API Reference
Login
Logo
On this page
  • Deciding on a user flow
  • Option 1: Explicitly ask for SAML and Organization
  • Option 2: Explicitly ask for SAML, infer organization from email
  • Option 3: Infer “Log in with SAML” from email
  • Identity Provider-initiated flows as an escape hatch
SAML (Enterprise SSO)

Integrating SAML with your Login UI

How to add a "Log in with SAML" flow to your existing login user experience
Was this page helpful?
Previous

Handling SAML Logins and Just-in-Time Provisioning

How to handle SAML logins and implement Just-in-Time (JIT) Provisioning

Next
Built with

This document contains best practices for SAML. You should start with the quickstart first.

One of the more subtle aspects of adding SAML to your product is making it a seamless user experience. This guide will spell out your options, how to decide which one to go with, and how to implement it.

Deciding on a user flow

The essential challenge with adding SAML to your product’s login experience is that you need to figure out two things:

  1. Does this user need to log in over SAML?
  2. If they do need to log in over SAML, which company do they work for?

Every SAML-supporting login experience ultimately is about finding the answer to these two questions.

This document spells out exactly how to implement the three most popular user experiences for supporting “Log in with SAML”.

  1. If you can’t uniquely determine which organization an email belongs to, use Option 1: Explicitly ask for SAML and Organization.
  2. If you can determine this, and you want to have an explicit “Log in with SAML” button on your login page, choose Option 2: Explicitly ask for SAML, infer organization from email.
  3. If you don’t care about having an explicit “Log in with SAML” button, or would prefer to avoid showing that option unless it’s appropriate for a user, then choose Option 3: Infer “Log in with SAML” from email.

Or, as a flowchart / decision tree:

A decision tree for which SAML login UX you should choose.

If you’re just looking for the easiest possible way to add “Log in with SAML” support, that’s Option 1: Explicitly ask for SAML and Organization.

Option 1: Explicitly ask for SAML and Organization

This is the easiest flow to implement, at the cost of being a bit clunkier for your customers. Your users will need to know some sort of unique identifier for their organization inside your product, and you’ll use that identifier as the organizationExternalId to initiate a SAML login.

1

Start with your login page

Your initial login page, before SAML, looks something like this.

Identify the page you’ll want to modify, and in particular figure out where you’d like to add a new button for “Sign in with SAML”. Typically, this goes next to any other login providers you may use, e.g. “Log in with Google”.

2

Add a “Log in with SAML” button

Your login page, now with a "Sign in with SAML" button.

Add a new button that takes the user to the next step of the SAML login process in step (3). Typically, you’ll do this by making the “Sign in with SAML” button a link to a new /login-saml page.

3

Add a SAML login page asking for an organization ID

Your new SAML-specific login page, which asks for an organization ID.

On this new page, you’ll ask your user to input their organization ID.

4

Redirect the user when they click “Log in with SAML”

Create a new endpoint (or GraphQL resolver, RPC method, whatever is easiest for you) on your backend. That endpoint will:

  1. Take the organization ID the user inputted in the above UI,
  2. Call SSOReady’s Get SAML Redirect URL with the given organization ID as the organizationExternalId argument to SSOReady.
  3. Get SAML Redirect URL returns a URL. Redirect your user to that URL.

Option 2: Explicitly ask for SAML, infer organization from email

This flow gives your customers a smooth experience for logging in with SAML, while also letting you explictly offer a “Log in with SAML” button. Users explicitly opt into logging in with SAML, and you infer which company they belong to from the email they input.

1

Start with your login page

Your initial login page, before SAML, looks something like this.

Identify the page you’ll want to modify, and in particular figure out where you’d like to add a new button for “Sign in with SAML”. Typically, this goes next to any other login providers you may use, e.g. “Log in with Google”.

2

Add a “Log in with SAML” button

Your login page, now with a "Sign in with SAML" button.

Add a new button that takes the user to the next step of the SAML login process in step (3). Typically, you’ll do this by making the “Sign in with SAML” button a link to a new /login-saml page.

3

Add a SAML login page asking for an email

Your new SAML-specific login page, which asks for an email.

On this new page, you’ll ask your user to input their email.

4

Redirect the user when they click “Log in with SAML”

Create a new endpoint (or GraphQL resolver, RPC method, whatever is easiest for you) on your backend. That endpoint will:

  1. Take the email the user inputted in the above UI,
  2. Figure out an organization ID from that email. This is going to be specific to exactly how your product assigns users to organizations. For example, if you have one (or a list of) domain(s) tied to every organization, then you might look up an organization by the email’s domain.
  3. Call SSOReady’s Get SAML Redirect URL with the organization ID from the previous step as the organizationExternalId argument to SSOReady.
  4. Get SAML Redirect URL returns a URL. Redirect your user to that URL.

Option 3: Infer “Log in with SAML” from email

This flow lets you avoid having a “Log in with SAML” button on the screen unless it’s appropriate. You automatically detect that SAML needs to happen while the user starts typing their email address.

1

Start with your login page

Your initial login page, before SAML, looks something like this.

Identify the page you’ll want to modify, and in particular figure out where you’d like to add a new button for “Sign in with SAML”. Typically, this goes next to any other login providers you may use, e.g. “Log in with Google”.

2

Create an email-to-SAML-organization lookup endpoint

Create a new endpoint (or GraphQL resolver, RPC method, whatever is easiest for you) on your backend. That endpoint will:

  1. Take a user’s email,
  2. Figure out an organization ID from that email. This is going to be specific to exactly how your product assigns users to organizations. For example, if you have one (or a list of) domain(s) tied to every organization, then you might look up an organization by the email’s domain.
  3. If no organization is found, or if the organization isn’t internally tagged as being enabled for SAML, then return some empty value or some error the frontend knows means “nothing was found”.
  4. If you did find an organization that you’ve internally tagged as having SAML, then use SSOReady’s Get SAML Redirect URL with the organization’s ID as the organizationExternalId argument to SSOReady.
  5. Get SAML Redirect URL returns a URL. Return that URL to your frontend.
3

Look up the user’s email address for a SAML organization

Either on a continuous basis (e.g. every time the email input changes, maybe with debouncing) or whenever the user moves focus away from the email input, send a request to your new enpodint with the inputted email address.

Most of the time, this lookup won’t find anything, especially if the user hasn’t finished typing out the email address. In that case, don’t do anything special.

The email lookup for "jdoe@acmecorp.c" didn't find anything, so nothing special happens.

But when a lookup does succeed, then remove any password inputs or options for other kinds of login methods. Change “Log in” to “Log in with SAML”.

The email lookup for "jdoe@acmecorp.com" found an organization with SAML, so the login button becomes SAML-based.

When a user clicks “Log in with SAML”, redirect them to the URL you got back from your new lookup endpoint from step (2).

Identity Provider-initiated flows as an escape hatch

The options outlined above are the three most common ways SAML login flows are implemented by SaaS businesses.

Sometimes, customers will want special logic. Some large company is going to ask for special logic where acmecorp.com and acmecorp.in email addresses log into the same organization, but using a different SAML connection.

You can acquiesce to such requests, but keep in mind that you can also suggest your customer uses Identity Provider-initiated logins instead.

When you use SSOReady to implement SAML, you get support for Identity Provider-initiated flows for free. Those work by having your customer log into your product directly from their Identity Provider. For example, an Okta-initiated flow consists of clicking on a tile in their Okta with your company’s logo on it.

In most cases, you can use Service Provider-initiated flows, like the ones described on this page, to make SAML logins easy for most customers. For the occasional cases where a customer has very specific needs, they are typically used to having to implement those specific needs using an Identity Provider-initiated flow.