OIDC auth
Configure generic OIDC providers (Okta/Auth0/Azure AD/Keycloak, etc.) for a self-hosted server.
Happier can be configured with one or more OIDC provider instances. This is intended for enterprise/self-hosting deployments where GitHub isn’t the desired identity provider.
What standard is supported?
Happier’s “custom provider” support is OpenID Connect (OIDC) 1.0 using OAuth 2.0 Authorization Code Flow with PKCE.
- OIDC discovery is required (
/.well-known/openid-configurationunder yourissuer) - The provider must support code exchange at the token endpoint
id_tokenclaims are used as the primary identity profile; optional/userinfocan be enabled- Optional refresh tokens can be stored (encrypted) for offboarding re-checks
- Optional: a headless machine can trade a JWT access token from the provider for a Happier token (see Token exchange for headless machines)
If you need SAML, the recommended approach is to use your IdP’s “OIDC app” or a SAML→OIDC bridge (Okta/Auth0/Azure AD/Keycloak, etc.), and configure Happier using the OIDC options below.
Config sources
You can configure providers via either:
AUTH_PROVIDERS_CONFIG_PATH(recommended): path to a JSON file on the serverAUTH_PROVIDERS_CONFIG_JSON: a JSON string (useful for simple deployments)
JSON schema (v1)
The config must be a JSON array. Each entry defines one provider instance:
[
{
"id": "okta",
"type": "oidc",
"displayName": "Acme Okta",
"issuer": "https://acme.okta.com/oauth2/default",
"clientId": "…",
"clientSecret": "…",
"redirectUrl": "https://YOUR_SERVER/v1/oauth/okta/callback",
"scopes": "openid profile email",
"httpTimeoutSeconds": 30,
"claims": {
"login": "preferred_username",
"email": "email",
"groups": "groups"
},
"allow": {
"usersAllowlist": ["alice", "bob"],
"emailDomains": ["example.com"],
"groupsAny": ["engineering", "platform"],
"groupsAll": ["employees"]
},
"fetchUserInfo": false,
"storeRefreshToken": false,
"tokenExchange": {
"allowedClientIds": ["…"]
},
"ui": {
"buttonColor": "#111111",
"iconHint": "okta"
}
}
]Notes:
idbecomes the provider id used in policy (AUTH_SIGNUP_PROVIDERS=okta) and in the callback URL (/v1/oauth/:provider/callback).issuermust point at the provider’s OIDC issuer URL (discovery uses/.well-known/openid-configuration).- Make sure your OIDC app is configured to allow the exact
redirectUrl. clientSecretcan be replaced byclientSecretEnv, the name of an environment variable that holds the secret. See Client secret from an environment variable.scopesdefaults toopenid profile emailand must includeopenid.httpTimeoutSeconds(default30, clamp 1–120): timeout (seconds) for OIDC discovery and subsequent HTTP requests made by the OIDC client configuration.claimslets you map where to read the provider login/email/groups from (defaults shown above).allowrestricts eligibility (all comparisons are lowercased):usersAllowlist: matches against the provider login claim.emailDomains: allowsuser@domainonly ifdomainmatches.groupsAny: user must be in at least one group.groupsAll: user must be in all groups.
fetchUserInfo(defaultfalse): if enabled, the server fetches/userinfoand merges it into the identity profile.storeRefreshToken(defaultfalse): if enabled, the server stores an encrypted refresh token and uses refresh flows for periodic eligibility re-checks (offboarding) without requiring users to reconnect.tokenExchange(default: absent, exchange off): lets machines trade an access token for a Happier token. See Token exchange for headless machines.uiprovides optional UI hints only (no security impact).
Client secret from an environment variable
clientSecretEnv is available in development source and has not yet been released.
Set clientSecretEnv instead of clientSecret when the provider config lives in non-secret deployment values (Helm values, a compose file, a ConfigMap) and the secret comes from a secret manager:
[
{
"id": "okta",
"type": "oidc",
"displayName": "Acme Okta",
"issuer": "https://acme.okta.com/oauth2/default",
"clientId": "…",
"clientSecretEnv": "OKTA_CLIENT_SECRET",
"redirectUrl": "https://YOUR_SERVER/v1/oauth/okta/callback"
}
]export OKTA_CLIENT_SECRET='…' # or inject it into the server environment from your secret store- The server reads the variable from its own environment when it loads the provider config.
- A literal
clientSecretwins when both fields are set. An empty or invalid literal remains an error; it does not fall back to the variable. - The variable name is trimmed; the secret value is preserved as supplied.
- If the named variable is unset, empty, or whitespace-only, the config is invalid: the server registers none of the configured OIDC providers and reports
auth_providers_config_invalidundercapabilities.auth.misconfiginGET /v1/features, naming the variable without exposing its value. It never starts a provider with an empty secret.
Group overage / external claims
Some providers (notably Microsoft Entra ID / Azure AD) may omit groups from tokens and instead return an “overage” pointer (e.g. _claim_names/_claim_sources). If you configure groupsAny/groupsAll, Happier will fail closed when it detects group overage (treating the user as ineligible) unless it can read groups from the configured claim source (for example by enabling fetchUserInfo and mapping claims.groups appropriately).
Enabling OIDC signup / login enforcement
Example: Okta-only signup + Okta required for ongoing access:
AUTH_ANONYMOUS_SIGNUP_ENABLED=false
AUTH_SIGNUP_PROVIDERS=okta
AUTH_REQUIRED_LOGIN_PROVIDERS=okta
AUTH_PROVIDERS_CONFIG_PATH=/etc/happier/auth-providers.jsonKeyless OIDC login (optional, enterprise)
Happier can also use an OIDC provider as a keyless login method (no device keys), when enabled by feature env vars.
This is intended for enterprise deployments and is usually paired with plaintext storage mode. See:
Minimum prerequisites (example for provider id okta):
HAPPIER_FEATURE_ENCRYPTION__STORAGE_POLICY=optional|plaintext_only
HAPPIER_FEATURE_E2EE__KEYLESS_ACCOUNTS_ENABLED=1
HAPPIER_FEATURE_AUTH_OAUTH__KEYLESS_ENABLED=1
HAPPIER_FEATURE_AUTH_OAUTH__KEYLESS_PROVIDERS=oktaTo allow OIDC sign-in to create a new keyless/plain account on first login:
HAPPIER_FEATURE_AUTH_OAUTH__KEYLESS_AUTO_PROVISION=1Notes:
- Keyless OIDC login is separate from keyed OIDC signup. You can enable either or both.
HAPPIER_FEATURE_ENCRYPTION__DEFAULT_ACCOUNT_MODEcontrols only the default for keyed accounts underoptional; it does not gate keyless provisioning.- On
HAPPIER_FEATURE_ENCRYPTION__STORAGE_POLICY=optional, the client may offer a choice on first login (E2EE vs plaintext) when the provider is enabled for both keyed provisioning and keyless auto-provisioning.
Keyless authentication does not supply keys for historical encrypted Machines. Development clients can use plain Machine control when the server explicitly supports it; that format and token-only client support are unreleased. Converting encrypted Machine history still requires its genuine old keys.
Auto-redirect (OIDC-only deployments)
If an OIDC provider is your only supported login/signup flow, you can enable auto-redirect so users don’t have to tap the button:
HAPPIER_FEATURE_AUTH_UI__AUTO_REDIRECT_ENABLED=1
HAPPIER_FEATURE_AUTH_UI__AUTO_REDIRECT_PROVIDER_ID=<providerId>
AUTH_ANONYMOUS_SIGNUP_ENABLED=0Token exchange for headless machines
A machine that already holds a user's access token from your IdP can trade it for a Happier token on that user's account, with no browser and no pairing step. Dev-box platforms that keep a per-user IdP token in each workspace (for example a Coder external auth) use this to attach a new workspace to its owner's account.
What you need first:
- Keyless OIDC login enabled for the provider (above). The exchange only signs in to keyless/plain accounts.
- The user has signed in to Happier through this provider at least once. The exchange never creates an account.
- An OAuth client in your IdP that issues the machine's access tokens. It can be Happier's own client or a separate one, provided its
/userinforeturns the samesubas the user's Happier login. Providers using pairwise subject identifiers can return different subjects for separate client sectors; those tokens returnnot-linkedeven if the user has already signed in to Happier.
Turn it on per provider by listing the clients whose tokens may be exchanged:
"tokenExchange": {
"allowedClientIds": ["0oa1exampleclient"],
"clientIdClaim": "cid",
"subjectClaim": "uid"
}allowedClientIds(required): OAuth client ids, compared exactly. An empty or missing list leaves the exchange off.clientIdClaim(optional): the access-token claim naming the client. When unset, Happier readsclient_id(RFC 9068), thenazp. For Okta JWT access tokens with acidclient claim, setclientIdClaimtocid.subjectClaim(defaultsub): the access-token claim that must equal thesubreturned by/userinfo. For Okta JWT access tokens whosesubis the login and whoseuidmatches the/userinfosubject, setsubjectClaimtouid.
Allowlisting a client trusts anyone who obtains one of its accepted bearer tokens to sign in to the user's linked Happier account. This includes APIs that receive those tokens: the client claim identifies who requested the token, not who presents it, and this exchange does not restrict aud. The Happier token can remain valid after the IdP token expires. Use a dedicated client and token flow where every token recipient is trusted with that access; a dedicated client alone does not prevent replay by its token recipients.
Verify these claim names against tokens from your configured issuer. Okta treats org authorization server access-token contents as opaque and may change their format. This exchange requires a readable JWT with the configured client and subject claims; an org token format change can therefore disable exchange even while browser login still works. The token is validated by Okta's own /userinfo endpoint, rather than by local signature validation.
The machine then calls:
curl -fsS -X POST "https://YOUR_SERVER/v1/auth/external/<providerId>/token-exchange" \
-H 'content-type: application/json' \
-d "{\"accessToken\":\"$IDP_ACCESS_TOKEN\"}"
# {"success":true,"token":"…"}How the server checks the token:
- It reads the client claim from the token's JWT payload and refuses clients that are not allowed. Opaque (non-JWT) access tokens are refused.
- It sends the token to the provider's
/userinfoendpoint. The provider rejects a token that is expired, revoked, or whose payload was edited, because the signature no longer matches. - It requires the
/userinfosubto equal the token'ssubjectClaim. - It looks up the account already linked to that
subfor this provider. - It refuses end-to-end encrypted accounts and applies the same login eligibility check every authenticated request gets (disabled accounts,
AUTH_REQUIRED_LOGIN_PROVIDERS, offboarding).
The access token must be a JWT and must carry the openid scope, or /userinfo refuses it.
| Status | error | Meaning |
|---|---|---|
| 401 | invalid-token | Not a JWT, rejected by /userinfo, or subject mismatch |
| 403 | token-exchange-disabled | No tokenExchange.allowedClientIds, or keyless login is off for this provider |
| 403 | client-not-allowed | The token's client is not in allowedClientIds |
| 403 | account-disabled, provider-required, not-eligible | The account fails login eligibility |
| 404 | not-linked | No account is linked to this identity yet; sign in once through the app |
| 409 | restore-required | The linked account is end-to-end encrypted |
| 502 | upstream_error | The IdP could not be reached |
Limits:
- The Happier token does not expire with the IdP token. Revocation works as for any other Happier token: disable the account or rely on offboarding checks.
- The response carries only an API token, no content key. Development-source CLI credentials can be token-only, but the CLI has no command that consumes an exchanged token yet. Historical encrypted content still requires its genuine old key.
- Requests share the
oauthExternal.authParamsper-IP rate limit (see Rate limits).
Step-by-step: add a new OIDC provider
- Pick a provider id (lowercase), e.g.
okta/auth0/entra. - In your IdP admin console, create an OIDC application:
- Grant type: Authorization Code
- Enable PKCE
- Add redirect URI:
https://YOUR_SERVER/v1/oauth/<providerId>/callback
- Put the provider config in
AUTH_PROVIDERS_CONFIG_PATH(preferred) orAUTH_PROVIDERS_CONFIG_JSON:- Set
issuer,clientId,clientSecret(orclientSecretEnv), andredirectUrlexactly (must match step 2).
- Set
- Enable it in policy:
- Allow signup via this provider:
AUTH_SIGNUP_PROVIDERS=<providerId> - Make it mandatory for ongoing access:
AUTH_REQUIRED_LOGIN_PROVIDERS=<providerId> - Disable anonymous signup if desired:
AUTH_ANONYMOUS_SIGNUP_ENABLED=false
- Allow signup via this provider:
- Make sure the client app can return from OAuth:
- Web (required unless you use
https://cloud.happier.dev): setHAPPIER_WEBAPP_URL(orHAPPIER_WEBAPP_OAUTH_RETURN_URL_BASE) - Mobile deep link: set
HAPPIER_WEBAPP_OAUTH_RETURN_URL_BASEand allow the scheme viaHAPPIER_OAUTH_RETURN_ALLOWED_SCHEMES(e.g.myapp) - Desktop (unreleased server fix): the bundled
tauri://localhostorigin is trusted by default; no additional allowed-schemes setting is needed. Bundled desktop origins, including Windows'http://tauri.localhost, return to the app's own OAuth route at its root, independently of the relay's UI prefix. KeepHAPPIER_WEBAPP_URLpointing to your web client for browser sign-in. Other custom return schemes still requireHAPPIER_OAUTH_RETURN_ALLOWED_SCHEMES.
- Web (required unless you use
- Validate:
- Restart the server (so it picks up env / config changes).
- Open the Happier app and confirm the new sign-in option appears on the welcome/login screen.
- If it doesn’t, double-check the redirect URL, issuer URL, and that
AUTH_SIGNUP_PROVIDERS/AUTH_REQUIRED_LOGIN_PROVIDERSreference the same provider id. (For troubleshooting, you can also inspectGET /v1/features.)
Note on “optional” web app URL env vars:
HAPPIER_WEBAPP_URL/HAPPIER_WEBAPP_OAUTH_RETURN_URL_BASEare only “optional” if you are using the hosted client athttps://cloud.happier.dev.- If you are self-hosting the web app, or using a local dev web UI, you must set one of these so the server can redirect back to your client after OAuth.
Troubleshooting:
- If you get redirected to
https://cloud.happier.deveven after settingHAPPIER_WEBAPP_URL, the server likely rejected your configured return URL as unsafe. For local web dev, usehttp://localhost:PORTorhttp://*.localhost:PORT(or usehttps://).
“Custom providers” beyond OIDC
At the moment, “custom providers” are supported via OIDC configuration (no plugin system for arbitrary protocols). If you need a non-OIDC provider, it must be implemented as a new provider module in the server and UI (similar to the built-in GitHub provider).