Easy and secure identity for the enterprise

Overview

SSO made EASIE

EASIE SSO (single sign-on) is a way for applications to provide enterprise-grade SSO through a multi-tenant OpenID provider, with initial support for Google and Microsoft OIDC. It is designed to be an easier alternative to SAML SSO.

A complete implementation of EASIE SSO includes:

  1. Enrollment based on a user's email domain
  2. Mandatory sign-in through Google or Microsoft OIDC
  3. Just-in-time provisioning during sign-in
  4. Automatic deprovisioning and session revocation

Importantly, EASIE SSO works primarily over OpenID Connect endpoints and eliminates the usual back-and-forth associated with SAML SSO:

  1. No additional configuration in Google Workspace or Microsoft Entra
  2. No need to share credentials, like a one-off OIDC client secret or SAML metadata file

This makes EASIE SSO the easiest way for enterprises to adopt full-featured SSO.

Specification
Updated: 2024-11-20

1. Initial setup

EASIE SSO can either be setup by application administrators or directly by the enterprise if the application provides a self-serve flow.

In either case, the application MUST accurately verify two pieces of information:

  1. The email domain used by the enterprise
  2. The multi-tenant IdP used by the enterprise (Google or Microsoft)

It is important to verify this information with an authorized party within the enterprise, usually a member of the IT department.

If an application provides a self-serve flow to setup EASIE SSO, it is critical to prompt the user with a challenge to verify their authority. Self-serve TLS certificate authorities have developed several challenge types that are acceptable for EASIE. For example, you may reference Let's Encrypt to develop a suitable challenge.

2. Account provisioning

EASIE SSO does not currently support a mechanism for continuously syncing users in the enterprise's directory. In turn, there is currently no way to provision accounts proactively, before a user visits the application.

Instead, accounts MUST be provisioned just-in-time, when a user with the email domain is seen for the first time. All account creation flows MUST be updated to force users with an enterprise email domain to verify through its respective IdP.

After an account is provisioned, the application is responsible for determining which enterprise resources are immediately accessible to the new user. Resource access is out of scope for EASIE SSO.

3. Forcing SSO

After a domain is enrolled in EASIE SSO, the application MUST force all users with that email domain (new or existing) to authenticate through the enterprise's choice of multi-tenant IdP.

As with any enterprise SSO implementation, it is critical to ensure that EASIE SSO users cannot bypass authentication through the IdP. If a user attempts to authenticate another way, they should either be forwarded directly to the multi-tenant IdP, or they should receive an error directing them there.

Below is a list of common techniques that attackers have used to try bypassing authentication through the IdP:

  1. Using the "forgot password" mechanism instead of the primary sign-in form.
  2. Using a different IdP. For example, using "Sign in with Microsoft" when the account should be required to use "Sign in with Google."
  3. Adding a phone, and using the phone to sign in instead of email.
  4. Adding a second email, and using the second email to sign in instead of the enteprise email.

The above examples are not intended to be exhaustive. Ultimately, it is the responsability of the application to ensure that no bypasses exist.

4. Mitigating tenant crossover vulnerabilities

When operating SSO through a multi-tenant IdP instead of a single-tenant IdP, additional protections MUST be added to prevent tenant-crossover attacks.

Below is an example of a tenant-crossover attack:

  1. Consider an IdP with two tenants: AcmeInc and EvilCorp.
  2. AcmeInc has enrolled in EASIE SSO and uses acme.com as their email domain.
  3. EvilCorp creates a user in their tenant with attacker@acme.com as its email. This is possible because multi-tenant IdPs may not strictly define which domains are allowed in which tenant.
  4. The attacker accesses the application, and signs in through the multi-tenant IdP, but via the EvilCorp tenant instead of the AcmeInc tenant.

Since the EvilCorp user has a acme.com email domain, it is easy for the application to mistakenly handle it as a AcmeInc user, and potentially grant unauthorized access to AcmeInc resources.

To prevent this attack, the application MUST verify that the user authenticated through the correct tenant within the multi-tenant IdP. While multi-tenant IdPs do make this information available, it is unfortunately not standardized, and protections must be implemented provider-by-provider.

Below is specific guidance for Google and Microsoft:

  1. Google: verify that the hd claim in the OIDC ID token matches the enterprise email domain. This claim contains the domain of the tenant that the user verified through. For more information, please see Google's OIDC claim reference.
  2. Microsoft: verify that the xms_edov claim in the OIDC ID token is set to true. This claim indicates that the tenant has verified ownership of the email domain that the user is presenting. For more information, please see Microsoft's OIDC claim reference.

5. Automatic deprovisioning and session revocation

The application MUST detect user deprovisioning when it occurs, revoke any active sessions, and prevent new sessions from being created.

Although OpenID Connect does not define a standard way to detect that deprovisioning has occurred, both Google and Microsoft make it possible through endpoints for reading user profile information:

  1. Google: First, refresh the access token if it is expired. If this fails, the user has been deprovisioned. Next, request the UserInfo endpoint as determined from the Discovery document. If it fails with a 401 status code, the user has been deprovisioned.
  2. Microsoft: First, refresh the access token if it is expired. If this fails, the user has been deprovisioned. Next, request the Microsoft Graph REST API Get User endpoint. If the request errors with a 401 status code (error codes Authorization_IdentityDisabledor Authorization_IdentityNotFound), the user has been deprovisioned.

If a user is actively visiting the application, the application MUST detect deprovisioning within 10 minutes of the deprovisioning occurring, then must revoke their sessions immediately. This should be accomplished by polling the user profile endpoints while the user is active.

If a user is not actively visiting the application, the application MUST detect that deprovisioning has occurred immediately upon revisiting, and then must revoke their sessions immediately.

Security

Security of EASIE SSO

The primary security difference between EASIE SSO and traditional SSO (using SAML or OIDC) is that EASIE SSO depends on a multi-tenant identity provider, while traditional SSO depends on a single-tenant identity provider.

Relying on a multi-tenant provider increases the risk that a user from one tenant will mistakenly be granted access to the resources of another tenant. EASIE SSO addresses this concern in the section on mitigating tenant crossover vulnerabilities.

Otherwise, EASIE SSO provides the same primary benefits you'd expect from traditional SSO, like automatic provisioning and deprovisioning, and forced authentication through the identity provider.

Please contact easie@clerk.dev with any security questions, or to responsibly disclose any security concerns with EASIE SSO specification.

Future plans

This is an ongoing effort

There is much more that we'd like to incorporate into EASIE SSO, including:

  1. A mechanism for deprovisioning that leverages a webhook instead of polling
  2. A mechanism for applications to easily discover which users in an organization are authorized to administer SSO settings, possibly leveraging a /.well-known entry
  3. A mechanism for applications to easily discover which users in an organization are authorized to administer SSO settings - ideally leveraging a OIDC scope for directory syncing
  4. Support for additional workforce identity providers. Please note that we are limited to solutions that offer a multi-tenant OIDC provider, and this currently excludes many popular providers, including Okta and Rippling

If you would like to contribute to EASIE's continued development, please contact easie@clerk.dev

Credits

EASIE SSO is a small extension to the secure, robust, and widely-adopted OpenID specifications.

It would not be possible with the without the incredible work by the OpenID Foundation.

The EASIE SSO specification was created by Clerk, which builds developer tools for authentication. EASIE SSO is offered alongside SAML SSO in Clerk's product.