Custom OIDC Providers
Point a Social Connect connection at any OIDC-compliant identity provider — configuration fields, the issuer-trust model, and the account-linking risk specific to third-party IdPs.
Social Connect isn't limited to Google. A connection can point at any OIDC-compliant identity
provider — Okta, Auth0, a self-hosted Keycloak, an enterprise IdP, or anything else that exposes a
standard /.well-known/openid-configuration discovery document. The brokering model is identical to
Sign in with Google: your app still only ever consumes a Hawcx-issued ID
token, and Hawcx still verifies and discards the provider's token server-side.
The connection's name (what you pass to saveSocialConnection and what appears in the
oidc:<name> method id) is just a label — it has no special meaning to Hawcx. What determines trust
is the fields below, in particular issuer_allowlist.
Configuration fields
Set these under Settings → Social Connect → Add connection in the Admin Console.
| Field | Type | Notes |
|---|---|---|
client_id | string | Your OIDC client id at the provider. |
client_secret | string, write-only | Never returned by reads (listSocialConnections reports only has_client_secret: true/false). Omit on update to keep the stored value. |
discovery_url | string (URL) | The provider's /.well-known/openid-configuration document. Fetched server-side. |
redirect_uri | string (URL) | Where the provider redirects after login — normally https://<your-hosted-login-host>/oidc/callback, same convention as Google's setup. |
scopes | string[] | Typically ["openid", "email", "profile"]. |
issuer_allowlist | string[], required, non-empty | The exact issuer URL(s) this connection is allowed to assert. See issuer trust model — this is the field that actually decides whether the connection is safe. |
claims_mapping | object | Remaps which token claim feeds a normalized field (e.g. {"email": "upn"} if your IdP puts the email in a non-standard claim). |
allow_email_linking | boolean, default false | Same semantics as Google account linking — do not enable for an IdP you don't fully trust, see Account-linking below. |
email_verified_required | boolean, default true | Same semantics as Google's setting, but see Account-linking below for why it's a weaker guarantee here. |
pkce_enabled | boolean, default true | Leave on unless your IdP can't support PKCE. |
client_auth_method | string, default client_secret_post | One of client_secret_post, client_secret_basic, client_secret_jwt, private_key_jwt. |
The issuer-trust model
Every login through a Custom OIDC connection is checked by two independent guards before Hawcx trusts the provider's assertion of who the user is:
- Reserved-issuer origin pinning. If a token claims an issuer that matches one of a small,
Hawcx-hardcoded list of well-known providers (Google, Microsoft, Apple, Facebook, GitHub
Actions), the discovery document must actually have been served from that provider's real origin.
A connection cannot claim
iss: https://accounts.google.comfrom a discovery document hosted anywhere else — this holds regardless ofissuer_allowlistand cannot be configured away. issuer_allowlist. For any issuer that is not one of those five reserved values — i.e. any genuinely third-party or self-hosted IdP — this is the only thing pinning trust.issuer_allowlistis mandatory and must be non-empty; set it to the exact issuer URL your IdP's discovery document declares. An empty allowlist causes every login on that connection to fail token verification.
issuer_allowlist is not optional
If you leave issuer_allowlist empty, sign-in will fail for everyone — this is expected, not a
bug. Always set it to your identity provider's issuer URL when you set up the connection.
Account-linking
Only enable allow_email_linking on a Custom OIDC connection if you operate the IdP yourself, or
otherwise fully trust its verification of the emails it asserts. For any third-party or
federated-from-elsewhere IdP, leave it off — new logins will provision a distinct Hawcx user instead
of linking, which is the safe default.
See also
- Account linking: the identity model and linking policy this page assumes.
- Social Connect Reference: normalized claims and the
federated_identitieslink, which apply the same way regardless of provider.
Account Linking
How a Google sign-in maps to a Hawcx user — verified-email linking, the account-takeover guard, JIT provisioning, and the unique (issuer, subject) rule.
Social Connect Reference
Normalized profile claims, the federated_identities link, redirect vs One Tap modes, and the current scope of Sign in with Google via Hawcx.