WorkOS Docs Homepage
Single Sign-On

Going Live

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

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

WorkOS makes use of Cloudflare to ensure security and reliability of all operations. If you are looking to create a list of allowed IP addresses for incoming requests, you can use the IP Ranges listed in the Cloudflare documentation.

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

If a user is authenticating to your application for the first time via SSO and doesn’t have an account, you can implement just-in-time provisioning to create a user when authentication is complete.

You can also leverage Directory Sync to pre-provision users with API endpoints or webhooks. In this case, the user will already be created in your application when they authenticate for the first time.

Can we add SSO authentication for a current user in an application?

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

How does WorkOS manage user attributes from an identity provider?

WorkOS normalizes user attributes so you can expect known values such as id, email,firstName, and lastName. You will still receive all of the attributes sent by your identity provider in the raw_attributes object.

Is the user attribute mapping configurable in WorkOS?

Yes. For example, let’s say the http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname attribute contains the user email rather than the surname as the attribute name suggests. In these edge cases, WorkOS will identify any attributes that are misconfigured and recommend 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, your code can not exclusively trust the returned email attribute on user profiles to be a verified email address. Instead, you must use the organization_id or connection_id in order 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.

For IdP-initiated SSO, what should the RelayState be?

RelayState support for IdP-initiated authentication is currently in invite-only beta, please reach out to WorkOS support if you’d like to use it or learn more about it.