Learn how to configure a new generic OIDC connection.
Each SSO Identity Provider requires specific information to create and configure a new connection. Often, the information required to create a connection will differ by Identity Provider.
WorkOS provides the Redirect URI. It’s readily available in your connection Settings in the WorkOS Dashboard. The Redirect URI is the location an Identity Provider redirects its authentication response to.
In order to integrate you’ll need the Client ID, Client Secret, as well as the Discovery Endpoint.
Normally, this information will come from the organization's IT Management team when they set up your application’s OpenID Connect configuration in their Identity Provider admin dashboard. But, should that not be the case during your setup, here’s how to obtain them.
For SSO to properly function with your Identity Provider, you’ll need to create and configure your OpenID Connect application to support the authorization code grant type and have the redirect URI from WorkOS listed as your login redirect URI.
family_name claims to the user ID token in your OIDC provider settings. These claims map to the
last_name attributes in the user profile returned by WorkOS. If the
given_name claim is not available, the
name claim will be mapped to the
first_name attribute instead. For many providers, these claims are included by default, but for other providers you will need to add these claims.
Users can automatically be assigned roles within your application by sending their group memberships. To enable this, set up a group attribute statement following the guidance below.
This feature is currently in beta, contact customer support for more information.
groups claim to the user ID token in your OIDC provider settings. This claim should map to a user's group membership.
After creating an OpenID Connect application, a Client ID and Client Secret will be provisioned for you by your Identity Provider. Enter these in your Connection Settings in the WorkOS Dashboard.
Your Identity Provider’s Discovery Endpoint contains important configuration information. Enter this in your connection Settings in the WorkOS Dashboard. Your Connection will then be verified and good to go!
The OIDC discovery endpoint will always end with
/.well-known/openid-configuration as described in the OpenID Provider Configuration Request documentation.
You can confirm that the discovery endpoint is correct by entering it in a browser window. If there is a JSON object with metadata about the connection returned, the endpoint is correct.