Launch Checklist

Make sure you're ready to take your app to production.

Prepare your SSO integration for production with this checklist of required steps and best practices.

Implement complementary enterprise features

Integrate the WorkOS Admin Portal to enable users to onboard and set up SSO themselves.
Integrate the WorkOS Directory Sync API for automatic user updating, provisioning, and deprovisioning.

Before you start

This document offers guidance on integrating Single Sign-On with the standalone API into an existing auth stack. Consider AuthKit as a complete authentication platform that leverages Single Sign-On functionality out of the box, following best practices.

Create an IP Allowlist

WorkOS makes use of Cloudflare to ensure security and reliability of all operations. To create a list of allowed IP addresses for redirect requests, use the IP Ranges listed in the Cloudflare documentation.

Go-live checklist

Implement an SSO UI/UX. See the guide for ideas – UI/UX Best Practices for IdP & SP-Initiated SSO

Test the end-to-end SSO experience in your Staging environment.

Unlock your Production environment by adding your billing information

Only enterprise connections in your Production environment will be charged. OAuth connections in Production will be free.

Set your Production Client’s ID and API Key as environment variables

Secure your Production Project’s API key

Configure production redirect URI(s) in your Product Project. Verify the default redirect URI is correct

Ensure the application can receive redirects from WorkOS. Depending on the network architecture, allowlist incoming redirect traffic from api.workos.com if necessary.

Add Connections for your customers in the Production Environment

Frequently asked questions

How should an application handle the first time a user authenticates using WorkOS?

If a user is authenticating to the application for the first time via SSO and does not have an account, implement just-in-time provisioning to create a user when authentication is complete.

Alternatively, leverage Directory Sync to pre-provision users with API endpoints or webhooks. In this case, the user will already exist in the application when they authenticate for the first time.

Can SSO authentication be added for a current user in an application?

If a user is authenticating to the application via SSO but already has an account (with username/password for example), “upgrade” them to SSO. The emails are usually the same for both methods of authentication, so match on email address. Once SSO via WorkOS is enabled, restrict users to sign in with only SSO.

How does WorkOS manage user attributes from an identity provider?

WorkOS normalizes user attributes to provide known values such as id, email,firstName, and lastName.

Is the user attribute mapping configurable in WorkOS?

Yes. For example, the http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname attribute may contain the user email rather than the surname as the attribute name suggests. In these edge cases, WorkOS identifies any attributes that are misconfigured and recommends correct mapping in the “Attribute Mapper” section of the “Connection info” page.

What does the “Allow Profiles Outside Organization” option do?

By default, WorkOS restricts user profiles for SAML Connections to profiles that have email domains that are in the set of User Email Domains on the Organization.

Enabling this option removes this restriction and allows user profiles with any email address to sign in through Connections under this Organization.

If this option is enabled, the returned email attribute on user profiles cannot be exclusively trusted as a verified email address. Instead, use the organization_id or connection_id to verify that the profile belongs to whom it claims.

What does “There are 0 profiles awaiting reconciliation” refer to?

This refers to the number of user profiles that have inconsistent attribute mappings, and that need to be updated in order to successfully authenticate.

How do I integrate WorkOS SSO with my native mobile application?

For mobile applications, implement SSO authentication as follows:

Generate the authentication URL and route the user to a browser or browser fragment in order to authenticate.
The end user authenticates via the native UI of their IdP within that browser.
Upon successful authentication, deep-link the user back into your native application.