Hanko Custom Provider Guide:About Hanko:Hanko is a modern open source authentication solution and the fastest way you integrate passkeys, 2FA, SSO, and more—with full control over your data. Move between self-hosted and Hanko Cloud anytime. No lock-in. Just Auth how it should be: secure, user friendly, and fully yours.What This Guide Covers: This guide explains how to connect a custom OAuth or OpenID Connect provider that isn’t
one of Hanko’s built-in social providers.Prerequisites:
Alongside its built-in social providers (Apple, Discord, GitHub, Google, LinkedIn, Microsoft), Hanko can connect to
any OAuth 2.0 or OpenID Connect (OIDC) provider you configure yourself.
- Active Hanko project
- Client credentials (client ID and secret) from your provider
- Your provider’s endpoint URLs, or confirmation it supports OIDC discovery
- Register Hanko’s redirect URL with your provider
- Create a custom connection in Hanko Cloud
- Configure discovery or manual endpoint URLs
Adding a custom provider
- Log in to Hanko Cloud and select your project.
- Navigate to
Settings > Social connectionsand scroll toCustom connections. - Note the
Redirect URLshown at the top of the connection form, and register it as an allowed redirect/callback URL with your provider - this step happens on your provider’s side, not Hanko’s. - Click
New connectionand provide:- A
Connection name. - The
Client IDandClient secretobtained from your provider. Scopes, a comma-separated list to request from the provider (openidis the minimum required if the provider is OIDC).
- A
- Click
Save.
Discovery vs. manual endpoints
If your provider implements OIDC discovery, leaveUse OIDC discovery enabled and provide only the Issuer - the base URL identifying the service, without the
/.well-known/openid-configuration path suffix - and Hanko fetches the rest of the provider’s configuration from
its discovery document. Otherwise (including for any plain OAuth 2.0 provider, which has no discovery document by
definition), disable Use OIDC discovery and provide the Authorization endpoint, Token endpoint, and Userinfo endpoint
directly.
Optional settings
PromptandACR valuesare passed through to the provider’s authorization request as-is - Hanko doesn’t validate them, so check your provider’s documentation for which values it actually supports.promptcontrols whether the provider forces re-authentication or consent; the OIDC spec definesnone,login,consent, andselect_accountas common values, though support varies by provider.acr_valuesrequests a specific authentication context and has no standard set of values - it’s entirely provider-defined.Allow linkinglets a user authenticating through this provider link to an existing Hanko account with the same email address - see Account provisioning and linking for how this works and the security trade-off involved.
Attribute and custom claim mapping
A custom provider’s own claims can be mapped onto Hanko’s standard profile fields (see Attribute mapping) and onto any custom claims you’ve declared for your project (see Custom claims) - both are configured directly on the same connection form.Since a non-OIDC (plain OAuth) provider’s userinfo response doesn’t necessarily conform to OIDC standard claim
names, attribute mapping is often required, not just optional, for such providers.