---
title: OpenID Connect
description: Learn how to configure a new generic OIDC connection
breadcrumb:
  title: Integrations
  url: /integrations
originalPath: .tmp-workos-clone/packages/docs/content/integrations/oidc.mdx
---

## Introduction

To set up an OpenID Connect (OIDC) connection on behalf of an organization, you'll need the client credentials and the discovery endpoint of their OIDC provider from the organization's IT team.

---

## What WorkOS provides

When setting up an OIDC connection, WorkOS provides one key piece of information in the **Service Provider Details** section for an SSO connection within the [WorkOS Dashboard](https://dashboard.workos.com/):

- [Redirect URI](/glossary/redirect-uri): The endpoint where identity providers send authentication responses after successful login

![The Redirect URI of a OIDC connection in the WorkOS Dashboard.](https://images.workoscdn.com/images/99a7c7d5-50a9-4bff-a3f3-22dc1cfeca58.png?auto=format&fit=clip&q=50)

The **Redirect URI** serves as the destination for authentication responses and must be configured in the organization's identity provider admin dashboard.

---

## What you will need

You will need to obtain three pieces of information from the organization:

- [Client ID](/glossary/client-id): Application identifier from the OIDC provider
- [Client Secret](/glossary/client-secret): Authentication secret for the application
- [Discovery Endpoint](/glossary/discovery-endpoint): Configuration URL containing OIDC metadata

Typically, the organization's IT team will provide these values when they configure your application in their identity provider admin dashboard. However, if you need to guide them through the process, the following sections will help.

---

## (1) Create an application with the identity provider

For SSO to properly function, the organization needs to create and configure an OpenID Connect application in their identity provider that supports the authorization code grant type.

Copy the **Redirect URI** from the WorkOS Dashboard connection settings.

Instruct the organization admin to paste this value as the login redirect URI in their OIDC application configuration. This ensures authentication responses are sent to the correct WorkOS endpoint.

---

## (2) Configure ID token claims

The organization's OIDC provider needs to include specific claims in the user ID token. Instruct them to add the following claims to their OIDC provider settings:

- `sub`: Maps to the `idp_id` attribute in WorkOS user profiles
- `email`: Maps to the `email` attribute in WorkOS user profiles
- `given_name`: Maps to the `first_name` attribute in WorkOS user profiles
- `family_name`: Maps to the `last_name` attribute in WorkOS user profiles

For many providers, these claims are included by default, but some providers require manual configuration.

### Role Assignment (optional)

With [identity provider role assignment](/sso/identity-provider-role-assignment), users can receive roles within your application based on their group memberships. To enable this functionality, instruct the organization to add the `groups` claim to the user ID token in their OIDC provider settings. This claim should map to a list of the user's group memberships.

> Finish role assignment set-up by navigating to the SSO connection page in the **Organizations** section of the [WorkOS Dashboard](https://dashboard.workos.com/). Create SSO groups by referencing the IdP Group ID. Then, assign roles to these SSO groups so group members are automatically granted roles within your application.

---

## (3) Obtain client credentials and discovery endpoint

After the organization creates an OpenID Connect application, their identity provider will provision client credentials and a discovery endpoint.

The discovery endpoint will always end with `/.well-known/openid-configuration` as described in the [OpenID Provider Configuration Request documentation](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationRequest). 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.

In the WorkOS Dashboard, navigate to your connection settings. Paste the **Client ID**, **Client Secret**, and **Discovery Endpoint** values from the organization's IT team into their respective input fields. Click **Update connection**.

![Input the Client ID, Client Secret, and Discovery Endpoint in the WorkOS Dashboard](https://images.workoscdn.com/images/ed603b39-a06e-4c2f-b96f-7cadaa793be4.png?auto=format&fit=clip&q=50)