Single Sign-On

Your App on SSO

Learn how to adopt SSO into your existing authentication strategy

If you’ve built or used a web app in the last decade you’ve probably used the OAuth 2.0 specification. If you’ve ever clicked “Sign in with Twitter” or built an integration to allow users to sign in with Google, that’s OAuth. It’s a popular protocol that’s enabled application developers to register and sign in users easily, while allowing web users to use a single service for their identity - rather than remembering passwords for hundreds of apps, users can sign in with Facebook, and need only to use their Facebook credentials.

WorkOS loves OAuth so much that we offer a service that allows your application to implement an OAuth authorization flow for Enterprise users; an OAuth flow that supports multiple SSO Identity Providers that would otherwise require you to build multiple SAML integrations.

Once you complete our set-up guide for WorkOS SSO you'll have written all the code required for implementing the WorkOS OAuth authorization flow. That is the only server side code you need to write to handle signing in users. But for each enterprise customer, you need to do a little bit more configuration than a typical OAuth setup. WorkOS makes it easy for you or your Enterprise customer to perform this extra bit of configuration - your team can manage SSO Connections on the WorkOS dashboard, or you can embed WorkOS.js in your application’s account settings page, allowing the Enterprise IT admin to configure the SSO connection themselves.

Once your team configures an SSO connection via the WorkOS dashboard, or your Enterprise customer does so via WorkOS.js, you’re ready to start signing in users for that Enterprise. This presents new user experience challenges as you start to consider the actual mechanics of signing into your application. Enterprise users will want to sign in to your application in two ways - via an Identity Provider Initiated flow, and by visiting your application’s website directly, called a Service Provider initiated flow.

Identity Provider Initiated Sign On

SSO Identity Providers typically offer an application dashboard that shows an Enterprise employee all of the applications they have access to. Okta offers a browser extension that provides a quicker way to see and sign in to the applications to which an Enterprise user has access.

Identity Provider Initiated sign on attempts describe when an Enterprise user clicks on your application from one of these places. WorkOS and applications that implement the WorkOS SSO OAuth flow will support Identity Provider Initiated sign in requests gracefully by default. If you’ve implemented the integration correctly, and properly configured the SSO connection for the specific Enterprise, those Enterprise users can start logging in to your app by clicking on it from their IdP dashboard. These users will be sent to your default redirect_uri with a code parameter that you exchange for a WorkOS SSO Profile.

You may at this point decide you’re ready for production, but WorkOS would advise that you consider the user experience of Enterprise users who come directly to your website wanting to use your application, and application developers typically do support this mode of sign in. Only allowing Identity Provider Initiated flows requires users to always go through their dashboard, something users may forget. It may also make it harder for users to bookmark your application if your sessions are short-lived.

Service Provider Initiated Sign On

If you do decide to allow your Enterprise users to sign in to your application from your own website (your application is the “Service Provider”), you have a few UX options, but one aspect is absolutely crucial - you must obtain an enterprise user’s domain in order to sign them in via WorkOS SSO.

If you followed the WorkOS SSO set-up guide, we had you hardcode in your application as the Enterprise user’s domain. Behind the scenes, WorkOS configured an SSO connection with the FooCorp Okta instance, allowing you to test your integration code prior to onboarding a real Enterprise customer. In a production environment with real Enterprise customers, you need to replace with the domain of the user who wants to sign in. Here are a few approaches we’ve seen to making this work.

Subdomain your tenants

One approach you can take would be to serve your application at a subdomain per tenant. Slack is one web application that does this. When you visit and click on the Sign In button, you’re taken to this page:

Slack Login

If we consider FooCorp here, a FooCorp employee would enter foo-corp into the input, and we can imagine that Slack, on their own back end, looks up foo-corp in their database, and on the next page offers the user the various methods their organization may use for signing in.

How might this work in an application integrating WorkOS SSO? When the user submits a form like this, or visits you need to also look up the acme subdomain in your own database, determine the full domain for that account, and then use that domain to create a WorkOS SSO authorization_url where you redirect this user.

Sign in with SSO

A second approach would be to put a link or button on your login page for Sign in with SSO. One thing to keep in mind here is what Daniel Burka coined the NASCAR Problem - where a cluster of 3rd party branded buttons creates both visual noise and confusion on behalf of the user.

Cypress takes this approach, but is careful to only offer a couple of sign in options that are relevant to their user base:

Cypress Login

Clicking the Single Sign-On link takes you here:

Cypress SSO

Once again, you could implement this approach in your own application, but the crucial aspect remains the same - you need to gather a domain. You can have a user submit their email address in that input and you must separate out the domain, or you can simply ask for domain. You then use the domain to create a WorkOS SSO authorization_url where you redirect this user. You’ll still need to maintain your own record of which domains use WorkOS SSO for authentication, and which use your existing authentication strategies.

Separate Email / Password fields

A third option is to separate your login forms into steps or pages. WorkOS takes this approach in its own dashboard application, and this approach seems to be gaining traction as the SaaS industry matures and more developers begin to offer SSO.

The crucial aspect again is that you must collect an Enterprise user’s domain, and use that to create a WorkOS authorization_url. This approach allows you to use the same form for your SSO Enterprise users and the users who use email and password to sign in to your application.

You again must maintain a reference of which domains use which authentication strategy, and when a user submits their email address, separate the domain, and use your mapping to either show the user a password field, or redirect them immediately to the WorkOS authorization_url if they are an Enterprise user.

Let’s take a look at the login screens of two of the world’s most influential tech companies. Notice anything missing?

Google and Apple Login

There is no password input when you first visit these pages. Both Google and Apple have separated their login process to two steps. You must first enter your email or username, and then these companies determine how to log you in. Each company now supports Single Sign-On using other Identity Providers, even if a vast majority of their users will log in with email and password.

What else?

We’d love to hear about other experiences you’ve come across on the web or what approach you yourself are taking in your application. We’re always trying to deliver the best experience for Developers, so we’re curious to learn from you too! In the future, WorkOS may even offer some tools or APIs that help you handle this, but in the meantime, go get your Enterprise users signing in and using your app!