Social connections (OAuth)
Before you start
Social connections, also known as OAuth connections in Clerk, allow users to gain access to your application by using their existing credentials from an Identity Provider (IdP), like Google or Microsoft. For example, if you enable Google as a social provider, then when a user wants to sign in to your application, they can select Google and use their Google account to sign in.
The easiest way to add social connections to your Clerk app is by using prebuilt views. If you need more control, you can build a custom OAuth flow with the Clerk API.
Enable a social connection
Development instances
For development instances, Clerk uses pre-configured shared OAuth credentials and redirect URIs to make the development flow as smooth as possible. This means that you can enable most social providers without additional configuration.
To enable a social connection:
- In the Clerk Dashboard, navigate to the SSO connections page.
- Select the Add connection button, and select For all users.
- Select the provider you want to use.
Production instances
For production instances, you will need to configure the provider with custom OAuth credentials. See the list of supported providers below for provider-specific setup instructions.
Configure additional OAuth scopes
Each OAuth provider requires a specific set of scopes that are necessary for proper authentication with Clerk. These essential scopes are pre-configured and automatically included by Clerk. They typically include permissions for basic profile information and email access, which are fundamental for user authentication and account creation.
In addition to the core scopes, you can specify additional scopes supported by the provider. These scopes can be used to access additional user data from the provider.
To add additional OAuth scopes, when you are enabling a new social connection, enable Use custom credentials. The Scopes field will appear.
Request additional OAuth scopes after sign-up
Clerk allows you to request additional OAuth scopes even after a user has signed up.
Apply the .userProfileOAuthConfig(_:) modifier to the UserProfileView or UserButton view, with any additional OAuth scopes you would like per provider. The user will be prompted to reconnect their account on their user profile page.
Use the following tabs to see how to add additional OAuth scopes to the UserProfileView and UserButton views.
UserProfileView()
.userProfileOAuthConfig([
.init(provider: .google, additionalScopes: ["foo", "bar"]),
.init(provider: .github, additionalScopes: ["qux"]),
])UserButton()
.userProfileOAuthConfig([
.init(provider: .google, additionalScopes: ["foo", "bar"]),
.init(provider: .github, additionalScopes: ["qux"]),
])Add a social connection after sign-up
For each social provider, you can disable the option to sign up and sign in to your application using the provider. This is useful when you want users to connect their OAuth account after authentication — for example, when your application needs to read a user's GitHub repository data but doesn't require GitHub for sign-in.
To configure the option for users to sign up and sign in with a social provider:
- In the Clerk Dashboard, navigate to the SSO connections page.
- Select the social provider you want to configure.
- Enable or disable Enable for sign-up and sign-in.
- Save the changes.
Once signed in, a user can connect to additional social providers without going through another sign-up. The Account Portal shows which providers a user has connected and which they can still connect to on their user profile page.
If you use prebuilt views, the UserProfileView lets users manage their connections. For a custom UI, build a custom OAuth flow with the Clerk API.
Allowlist OAuth redirect URLs
In addition to enabling a social connection in the Clerk Dashboard, native applications require allowlisting the redirect URLs used during the OAuth flow.
Clerk ensures that security critical nonces are passed only to allowlisted URLs when the SSO flow is completed in native browsers or webviews. For maximum security in your production instances, you need to allowlist your custom redirect URLs via the Clerk Dashboard or the Clerk Backend API.
To allowlist a redirect URL via the Clerk Dashboard:
- In the Clerk Dashboard, navigate to the Native applications page.
- Scroll down to the Allowlist for mobile SSO redirect section and add your redirect URLs.
Sign in with Apple
You can use Sign in with Apple to offer a native authentication experience in your iOS, watchOS, macOS or tvOS apps.
Instead of the typical OAuth flow that redirects through a browser, you can use Apple's native authentication and send the resulting ID token and authorization code to Clerk. Clerk verifies the user against the information Apple provides.
For additional information on using Sign in with Apple in your iOS app, see the dedicated guide.
Supported social providers
Clerk provides a wide range of social providers to ease your user's sign-up and sign-in processes. Select a provider to learn how to configure it for your Clerk app.
Apple
Add Apple as an authentication provider for your Clerk app.
Atlassian
Add Atlassian as an authentication provider for your Clerk app.
Bitbucket
Add Bitbucket as an authentication provider for your Clerk app.
Box
Add Box as an authentication provider for your Clerk app.
Coinbase
Add Coinbase as an authentication provider for your Clerk app.
Discord
Add Discord as an authentication provider for your Clerk app.
Dropbox
Add Dropbox as an authentication provider for your Clerk app.
Add Facebook as an authentication provider for your Clerk app.
GitHub
Add GitHub as an authentication provider for your Clerk app.
GitLab
Add GitLab as an authentication provider for your Clerk app.
Add Google as an authentication provider for your Clerk app.
HubSpot
Add HubSpot as an authentication provider for your Clerk app.
Hugging Face
Add Hugging Face as an authentication provider for your Clerk app.
LINE
Add LINE as an authentication provider for your Clerk app.
Linear
Add Linear as an authentication provider for your Clerk app.
Add LinkedIn as an authentication provider for your Clerk app.
Microsoft
Add Microsoft as an authentication provider for your Clerk app.
Notion
Add Notion as an authentication provider for your Clerk app.
Slack
Add Slack as an authentication provider for your Clerk app.
Spotify
Add Spotify as an authentication provider for your Clerk app.
TikTok
Add TikTok as an authentication provider for your Clerk app.
Twitch
Add Twitch as an authentication provider for your Clerk app.
Vercel
Add Vercel as an authentication provider for your Clerk app.
X/Twitter v2
Add X (Twitter v2) as an authentication provider for your Clerk app.
Xero
Add Xero as an authentication provider for your Clerk app.
Don't see the provider you're looking for? You can configure a custom OIDC-compatible provider or request a new one.
Feedback
Last updated on