Everything I Wish I Had Known about Enterprise SSO | Part II

Single sign-on (SSO) is critical for Enterprise products. It offers security benefits to the client company and an enhanced user experience for the end user. However, there is sometimes a conflict between security and ease of use. Balancing these sometimes-conflicting goals is an important part of defining SSO for your application. Once SSO is on the product roadmap, creating a detailed spec is the first step to to achieve both of these goals.

In our last post, we covered the technical research that goes into building SSO for Enterprise, and this post will detail the product specification best practices that are required to create a compelling, yet secure, user experience. This list might seem long, but we’ve included many things you’ll need for a robust implementation. While most of the tips are table-stakes for a releasable enterprise SSO feature, we’ve added some :sparkles: Bonus tips :sparkles: as well to uncover the extra mile.

New user registration or sign-up

Skip email verification once you have SSO setup.

Because SSO enables you to verify emails on the spot, you no longer need to send verification emails or confirm accounts. This helps shorten the account creation process, but that also means redoing or significantly changing your current setup.

Use just-in-time provisioning to increase product adoption.

Just-in-time (JIT) provisioning (based on domain whitelisting for example) minimizes the manual work, eliminates wait-time, and achieves the ultimate aim of SSO by directly propagating the customer’s user accounts management directly through into the app.This requires automating the process that creates a new account and granting the correct permissions to that new user.

Consider your pricing model when choosing your provisioning method.

The permissions model for your application and even the pricing model will impact how the sign-up process is designed. If a customer wants fine-grained access control for their users within the app, then manual account creation or approval is necessary. If the pricing is per-seat, then blanket domain-whitelisting may not be the right approach.

Sign-in

Highlight your preferred sign-in process in the user interface.

It is important to decide which takes precedence, manual sign in (user enters username and password) or SSO.

For example, Medium leads with SSO and buries the option for email and password in a link, whereas Heroku takes the opposite approach.

Medium Sign In Page

Heroku Sign In Page

Ask for user input when supporting multiple Identity Providers.

When supporting multiple Identity Providers (Google Sign-in, GitHub, OneLogin, Ping Identity, etc.), ask the user for their email address or unique account URL to determine the correct Identity Provider. While offering buttons for each provider is the most direct approach, it can clutter the UI and assumes the user knows which provider their company uses. This is often not true—think of a Google Apps user whose company also uses Okta.

Pagerduty SSO Sign In Page

Use cookies to reduce the user’s signing-in steps.

To reduce manual input, use a long-lifetime cookie that specifies which Identity Provider a user is affiliated with. The next time they login, send them directly to the authentication page. If they have an active session with the Identity Provider, they will be signed in without any extra steps. Their experience will stay the same as if they had actually stayed logged into your app.

Redirect new users to sign-up flow while maintaining the authenticated state.

While obvious in retrospect, many SSO implementers forget the scenario where a new user accidentally tries to sign in via SSO (instead of signing up). In this case, redirect the user to the sign-up flow while maintaining the authenticated state through the sign-up process. Putting them through the authentication flow twice is like being that credit card customer support rep who asks for identity verification after the caller has already spent 18 minutes punching in the numbers in the automated system.

Logging out

Ask the users whether they’d like to be logged out of their Identity Provider as well.

When a user logs out of the application, they can either be logged out of the Identity Provider, or not. User expectations can be varied in this case. The options are to either prompting the user to make a choice upon logging out or making it an admin option for organizations.

Don’t risk unauthorized access by keeping authentication sessions verified for too long.

The longer the session persists, the more opportunity there is for an account that has been revoked with the Identity Provider to still access to the application.

Identity provider flow

Support all the Identity Providers your customers need.

Enterprises will often not even consider products that do not support their SSO Identity Providers.

:sparkles: Bonus tip: Don’t overlook the permissions-grant page.

This is an oft-overlooked page in product design. However, this is where the user grants the application permissions so it is important it inspires trust. Some key elements are—the product image (this should be the correct size and high resolution) and the content of the drop-down menu. The correct user email address needs to populate here as well.

Google Auth with Details

:sparkles: Bonus tip: Whitelist the app with SSO Identity Providers

A lesser-known fact is that applications can often be white-listed with SSO Identity Providers, allowing the user to skip the permissions-grant page altogether. For example, in the case of Google Apps Whitelisting the customer’s admin can configure settings to allow an app direct access without interrupting the user with the permissions-grant page. This is the pinnacle of the SSO experience: a brand new user can arrive at the app via a deep-link and start using it with exactly one click. Magic.

Multiple sign-in options

Give customers the option to force SSO as the only sign-in option.

This can be a gating feature. Enterprise customers often want to force SSO as the only sign-in mechanism because of easier user management. If an employee is no longer at a company, SSO makes it easy to revoke access.

Specify the process for resolving a user signing in via multiple SSO Identity Providers or manually.

Often a user will forget they signed up manually or via SSO and try the other option. When using a globally unique identifier, such as email, to identify users, automatically merging new accounts with the same email address would create the best user experience.

:sparkles: Bonus tip: Allow customer admins to bypass SSO with a username and password.

This is relevant when a company forces SSO for their employees. If SSO breaks or the client switches providers, then the admin needs to be able to log in and change configurations in their organization settings to indicate the new provider. Otherwise, everyone is locked out.

User management

:sparkles: Bonus tip: Allow the application to connect with the client’s user management directory for advanced controls.

The client’s user management directories offer metadata, such as access level or role in the company. Once connected to the application, they can be used to create whitelists and blacklists or level-based access.

Provide non-SSO guest accounts.

The majority of users from an Enterprise customer will come through their SSO with emails on the customer’s domain. Inevitably, however, the customer will want to grant access via other means for users outside of their domain, such as external consultants.


There are many considerations when building an SSO feature for Enterprise customers. The above is a list of the best practices we found useful when spec’ing out our implementation. It is by no means an exhaustive list but should serve as a guiding document which can help uncover more questions that need to be answered for a truly comprehensive spec. And once you’re there, it’s time to build. Good luck!

Everything I Wish I Had Known About Enterprise SSO

Single sign-on (SSO) makes it easy for users to get started with an application. For enterprise applications, support for SSO is critical: many corporate security policies require that all applications must use approved SSO methods. While the experience of using SSO is simple, its specification is anything but simple. It’s easy to get lost in a sea of jargon: OAuth 1.0, 1.0a, 2.0, SAML, JWT, OpenID, OpenID Connect, JIT, and tokens: bearer tokens, refresh tokens, access tokens, authorization tokens, skeeball tokens. Standards documents are too specific to allow you to generalize, and content from vendors is designed to make you think it’s all too complicated to do yourself. When I was tasked with building SSO for LightStep, I spent days researching. Below are some lessons that I hope will save you time and headaches. It boils down to knowing your market, your vocabulary, your standards, and your platform.

Know your market

This is both the most important and most time consuming task before designing your application’s SSO. All other considerations are moot if you don’t understand the ways (there can be more than one) your customers are already managing their accounts. It is worth probing a bit deeper than simply asking “What do you use for SSO?” because you may discover that there are multiple options available.

Important questions to consider:

Do they use Gmail or Google Apps? Does everyone in the company have an account with Github using their work email address?
Do they have a vendor for Single Sign-on such as Okta, OneLogin, or Ping Identity? Do they have an LDAP/Active Directory server or other internally managed Identity Provider?
How do they log in and manage user accounts with their other SaaS vendors?

Know your vocabulary

There is a lot of jargon in SSO standards, tutorials, and documentation, including the ways of referring to the parties in an SSO transaction. Sometimes the same term is used with different meanings! For example, I have seen Service Provider used to refer to at least two distinct roles in the authentication transaction.

These are the three most important concepts in SSO:

  • The User (or Principal or Client) is the individual whose identity is being verified so that you can grant them access to your application.
  • Your application is the Service Provider (or Consumer or Relying Party), which uses a third-party to verify the User’s credentials.
  • The Identity Provider (or Server or OpenID Connect Provider) is the authority responsible for verifying the identity of the User and furnishing claims or assertions of the User’s credentials to the Service Provider.

Know your standards

There are many shared authentication and authorization schemes and standards, though the term “standard” is often used loosely. Some sound a lot alike but are actually quite different. Here are the important standards used in Enterprise SSO:

  • SAML: Security Assertion Markup Language is an XML-based data format and protocol for user authentication. SAML has been around the longest, and it is more common in larger enterprises. Even companies such as Google that have embraced newer standards still support SAML-based workflows for SSO.
  • OpenID: OpenID 1.0 and 2.0 are obsolete standards for maintaining a digital identity with an Identity Provider, which would verify your identity to other websites, also known as Service Providers. They have been replaced by OpenID Connect.
  • OpenID Connect is the latest standard authentication protocol and data format from OpenID. It was originally based on the design of Facebook Connect and has now been embraced by Google and other large providers of user authentication. The standard relies on the OAuth 2.0 protocol for the User to grant the Service Provide access to their identity data, and JSON Web Tokens (JWT) to package identity and other claims in the token payload.
  • OAuth 1.0a was deprecated in favor of OAuth 2.0 but is still in use by large companies, including Twitter. Revision A was released to close security holes in the original standard. It is considered more secure but more difficult to implement than its successor, OAuth 2.0.
  • OAuth 2.0 is the current OAuth standard as of this writing. OAuth 2.0 introduced a wider variety of data flows to support clients beyond the standard in-browser web application. OAuth 2.0 also removed the requirement for the client to encrypt the request, falling back on the built-in encryption of https communication. Even with the updated protocol, OAuth is an authorization scheme, not an authentication scheme. When you use OAuth for authentication, you are using it to get authorizationfrom the User to access their credentials stored with the Provider, and you are trusting the provider to have verified those credentials.

Know your platform

Many of these standards and protocols were developed with a focus on the canonical web app in a browser. If your application does not fit that mold, you may have fewer choices of how you implement SSO.

  • Mobile: Mobile Apps do not have access to the stored cookies in the phone’s web browser when making http requests in a webview, but these cookies are how Identity Providers maintain the logged-in state of the User. Without that state, the mobile app may be able to use the credentials from the Identity Provider, but the User will have to log in again for each new app, taking you from single sign-on to everytime sign-on. Newer protocols, such as OpenID Connect, are working to support native mobile applications without this limitation through NAPPS support. NAPPS provides capabilities that enable the application to register a custom callback URL to support a flow from the app into and back out of the core system web browser.
  • Single-page apps: The standard SSO authentication flows involve at least one communication step between the application’s server and the Identity Provider, but in a single-page app you may want to avoid the server altogether. Even if you don’t, you may not want to go through losing the application state through the standard redirect-based approach. This is where the alternative flows for OAuth 2.0 and OpenID Connect come in. You need to be even more careful when implementing the serverless flows, since the entire flow is happening in client-side JS and you don’t have the out-of-band server-to-server channel to exchange secure credentials. For this reason, big Identity Providers such as Google want you to use their JS toolkits.

I hope you found the distillation of my research on SSO useful. If there’s anything I missed, feel free to add to it in the comments and I will add it to the post and attribute it to you. Now that you have a solid foundation of SSO in enterprise, the next step is product design. Good luck!