Make sure you’re ready to take your app to production.
This document offers guidance to integrate Single Sign-On with our standalone API into your existing auth stack. You might also want to look at User Management, a complete authentication platform that leverages Single Sign-On functionality out of the box, following best practices.
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 redirect requests, you can use the IP Ranges listed in the Cloudflare documentation.
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.
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.
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.
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.
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.
This refers to the number of user profiles that have inconsistent attribute mappings, and that need to be updated in order to successfully authenticate.
When it comes to mobile applications, our typical advice in implementing SSO authentication goes like this: