Skip to main content
Custom OIDC lets you bring any OpenID Connect-compliant identity provider - Okta, Auth0, Keycloak, Microsoft Entra ID, Ping, Zitadel, or your own - as a sign-in option, even if it isn’t one of Hexclave’s built-in providers. Hexclave handles the OAuth flow, OIDC discovery, and account linking; you supply the issuer URL and client credentials.
Custom OIDC providers require a Team plan or above. Because you’re always using your own credentials, there are no shared development keys for custom OIDC.

​
How it works

You give Hexclave an issuer URL, and Hexclave fetches the provider’s configuration from its OIDC discovery document (<issuer>/.well-known/openid-configuration) to find the authorization, token, and userinfo endpoints. User profiles are mapped from standard OIDC claims (sub, name / preferred_username, email, email_verified, picture). You can add multiple custom OIDC providers, each identified by a unique provider ID that you choose.

​
Integration Steps

1

​
Choose a provider ID

Pick a unique ID for this provider, for example my-okta. You’ll use it in the callback URL and in your sign-in code.Provider IDs may contain lowercase letters, numbers, hyphens, and underscores only, and can’t match a built-in provider name (like google or github).
2

​
Create an OIDC app with your identity provider

In your identity provider’s admin console, create a new OIDC / OAuth2 web application and set its redirect (callback) URL to:
Replace YOUR_PROVIDER_ID with the ID you chose in the previous step. For local development, use http://localhost:8102/api/v1/auth/oauth/callback/YOUR_PROVIDER_ID.Then collect:
  • Issuer URL - the base URL of your provider (e.g. https://your-idp.example.com). It must support OIDC discovery.
  • Client ID and Client Secret from the app you just created.
3

​
Add the provider in Hexclave

  1. On the Hexclave dashboard, select Auth Methods in the left sidebar.
  2. Click Add Custom OIDC.
  3. Fill in the form:
    • Provider ID - the ID you chose (e.g. my-okta)
    • Display Name - a human-readable label (e.g. My Identity Provider)
    • Issuer URL - your provider’s issuer URL
    • Client ID and Client Secret - from your provider
    • Scopes (optional) - space-separated OAuth scopes. Defaults to openid email profile.
  4. Click Add Provider.
After it’s created, choose Configure on the provider’s row to view the exact Redirect URL Hexclave generated, and confirm it matches what you registered with your identity provider.
4

​
Trigger sign-in from your app

Custom OIDC providers are not rendered automatically by the prebuilt sign-in buttons, so start the flow yourself with signInWithOAuth, passing your provider ID:
Custom OIDC providers don’t appear in the default <SignIn /> / <SignUp /> provider buttons. Add your own button that calls signInWithOAuth("<your-provider-id>") (or build a fully custom sign-in UI).

​
Connecting accounts

Custom OIDC also works as a connected account. To link a custom OIDC provider to an already signed-in user, call linkConnectedAccount with the same provider ID:
For non-shared providers like custom OIDC, you can also request additional scopes and retrieve access tokens to call your provider’s APIs on the user’s behalf.

​
Need More Help?