# Add a custom OAuth provider as a social connection

**Before you start**

- [A Clerk application is required.](https://clerk.com/docs/getting-started/quickstart/setup-clerk.md)
- [An OIDC identity provider is required.](https://openid.net/specs/openid-connect-core-1_0.html)

Clerk allows you to configure custom OpenID Connect (OIDC) compatible authentication providers for your application. This guide walks you through the steps to set up a custom OAuth provider.

## Configuration

1. In the Clerk Dashboard, navigate to the [**SSO connections**](https://dashboard.clerk.com/~/user-authentication/sso-connections) page.
2. Select **Add connection** and select **For all users**.
3. Select the **Custom provider** tab.
4. Fill in the following fields:
   - **Name**: The provider name (visible to users)
   - **Key**: A unique identifier for the provider (cannot be changed after creation)
   - **Discovery Endpoint**: The OIDC discovery endpoint URL of your provider
     - Alternatively, select **Manual configuration** to set up provider endpoints manually
   - **Client ID**: Obtained from your provider
   - **Client Secret**: Obtained from your provider
5. **Optional:** If you're configuring a provider for a native or mobile app, a single-page application (SPA), or another public client that can't securely store a client secret, enable the **Use PKCE** toggle. [PKCE (Proof Key for Code Exchange)](https://datatracker.ietf.org/doc/html/rfc7636) is a recommended best practice for modern OAuth clients. Once enabled, Clerk will use the Authorization Code with PKCE flow for authentication with that provider. Learn more about [PKCE](https://clerk.com/docs/guides/configure/auth-strategies/oauth/how-clerk-implements-oauth.md#public-clients-and-pkce).
6. Select **Add connection**. You will be redirected to the connection's configuration page.

The provider is now configured but not yet enabled. On the connection's configuration page, find the **Authorized redirect URLs** to configure in your provider's settings. From there, you can enable the provider from the top of the page by selecting the **Enable connection** toggle.

> If you didn't enable PKCE during creation, select the connection and enable the **Use PKCE** toggle under the **SSO** tab.

## Attribute mapping

If your provider returns claims in a non-standard format:

1. Go to the provider's details page.
2. Under **Attribute mapping**, configure the mapping to match your provider's claim format.

### Tips

- For fields like **Email address verified**, set default values for missing claims.
- If the provider returns a claim but you don't want to set it, leave the mapping field empty.
- If you set a user info URL, it takes priority over the ID Token for claim retrieval.

## Handling edge cases

Sometimes [attribute mapping](#attribute-mapping) isn't enough to get a provider working. For example, the call to the **User info URL** might require additional credentials or API calls. In these instances you should implement a proxy between Clerk and the provider to handle these transformations. The proxy will then be set as the **User info URL**.

The proxy receives the request from Clerk (which contains an `Authorization` header) and should return a JSON object which you can use for attribute mapping.

### Example: Hono with Cloudflare Workers

1. Initialize a new [Hono + Cloudflare Workers](https://hono.dev/docs/getting-started/cloudflare-workers) project

2. Implement your proxy logic, e.g. making an additional API call. Here's a minimal example:

   filename: src/index.ts

   ```ts
   import { Hono } from 'hono'

   const app = new Hono()

   app.get('/', async (c) => {
     const authorization = c.req.header('authorization')

     const userRes = await fetch('https://api.com/user', {
       headers: {
         'Content-Type': 'application/json',
         Authorization: authorization,
         'api-key': 'some-api-key',
       },
     })

     const user = await userRes.json()

     return c.json({
       uuid: user.uuid,
       avatar_url: user.avatar,
       name: user.name,
       username: user.username,
       slug: user.id.slug,
     })
   })

   export default app
   ```

3. Deploy your proxy

4. Set the URL of the deployed Cloudflare worker as the **User info URL**

5. Map the returned claim format of the proxy to the respective attributes in the **Attribute mapping** section

## References

- [OpenID Connect Specification](https://openid.net/specs/openid-connect-core-1_0.html)
- [OAuth 2.0 Framework](https://oauth.net/2/)

---

## Sitemap

[Overview of all docs pages](https://clerk.com/docs/llms.txt)