Single Sign-On
Facilitate greater security, easier account management, and accelerated application onboarding and adoption.
Enable SSO for your AuthKit application. AuthKit handles the SSO routing and API calls automatically when a user’s account is associated with an existing SSO connection.
For a conceptual overview of SSO, see How Single Sign-On Works. For the standalone SSO API without AuthKit, see the SSO Quick Start.
Navigate to the Authentication settings section in the WorkOS Dashboard and enable Single Sign-On:
AuthKit will now automatically detect when a user is attempting to sign in via SSO and redirect them to the appropriate IdP.
Confirm the Single Sign-On integration works correctly by using the Test Identity Provider to simulate login flows end-to-end. The staging environment includes a default Test Organization and active SSO connection configured with the Test Identity Provider.
Log into the WorkOS Dashboard and navigate to the Test SSO page. This page outlines a number of different SSO scenarios and provides all the necessary information to complete the tests.
This is likely the first login flow to test when implementing SSO. The test simulates users initiating authentication from the sign-in page. In this scenario, the user enters their email in the app, gets redirected to the identity provider, and then is redirected back to the application.
This test simulates users initiating authentication from their identity provider. It is a common login flow that developers often overlook. In this scenario, users log in to the identity provider directly, select the application from their list of SSO-enabled apps, and are redirected to the application upon successful authentication.
This test simulates users authenticating with an email domain different from the verified domain of the test organization, example.com. A relevant scenario is authenticating freelance users, whose email domain is not owned by the company.
This test simulates a generic error response from the user’s identity provider. In this scenario, SSO authentication has failed for the user. Below is an example of the error-related parameters passed to the redirect URI in the application.
The Test Identity Provider saves time by providing an out-of-the-box experience compared to the configuration process required with a real identity provider.
If the integration works with the Test Identity Provider, it will work with other identity providers. However, it may be helpful to also learn about the setup process that customers go through on their side, which varies depending on the specific identity provider.
Create an organization in the WorkOS Dashboard. Organizations in WorkOS represent a customer, so creating an organization allows testing the SSO connection the way customers experience it.
Go to the organization and click Invite admin. Select Single Sign-On from the list of features. In the next step, enter an email address to send the setup link to, or click Copy setup link.
The setup link goes to Admin Portal, where customers get the exact instructions for every step needed to enable Single Sign-On with the app.
Integrate Admin Portal directly into the app to enable self-serve setup of Single Sign-On and other enterprise features for users.
To complete the integration, create an account with the identity provider to test with. After signing up with the chosen identity provider, follow the corresponding Admin Portal instructions from the setup link. Once done, start testing the SSO integration with that identity provider.
The setup instructions from the Admin Portal are also available directly in the docs for creating a connection manually:
Build and manage a custom authentication UI via the AuthKit Authentication API.
Examples of building custom UI are also available on GitHub.