OpenID Connect
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.
To create an OpenID Connect (OIDC) connection, you’ll need four pieces of information: a Redirect URI, a Client ID, a Client Secret, and a Discovery Endpoint.
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.
Add the sub, email, given_name, and family_name claims to the user ID token in your OIDC provider settings. These claims map to the idp_id, email, first_name, and 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.
With identity provider role assignment, users can receive roles within your application based on their group memberships. To return this information in the attribute statement, add the groups claim to the user ID token in your OIDC provider settings. This claim should map to a user’s group membership.
Finish role assignment set-up by navigating to the Connection page in the Organization section of the WorkOS Dashboard. Create connection groups referencing the group IdP ID. Then, assign roles to connection groups so users in those groups will automatically be granted roles within your application.
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.