OAuth / OIDC Setup

Overview

• What is OIDC: OpenID Connect (OIDC) is an identity layer built on OAuth2 that lets users authenticate with an external identity provider (IdP).
• Why 3DKenji uses it: enable Single Sign-On (SSO) so you don’t have to manage user passwords on the homelab server.
• Compatibility: 3DKenji supports any OIDC-compliant provider (Authentik, Keycloak, Okta, Auth0, Cloudflare Access, etc.).
• Configuration model: OAuth settings are stored in the 3DKenji database from the admin settings screen after your first admin account is created.

Refer to the API reference for endpoints: docs/api-reference.md.

First-Time Setup Flow

1. Start 3DKenji with local auth only.
2. Create the first admin user through the normal setup or registration flow.
3. Sign in as that admin.
4. Open the admin settings page at /admin/settings.
5. Paste your OIDC provider details into the OAuth / OIDC section and save.
6. Test login with /api/v1/auth/oauth/oidc/authorize.

This is the required setup path for homelab installs.

Authentik Setup (step-by-step)

This walkthrough uses Authentik 2024.x and homelab-friendly examples. Replace auth.example.com and 3dkenji.example.com with your hosts.

1. Log into Authentik admin → Applications → Providers → Create Provider.
2. Choose OAuth2 / OpenID Connect Provider.
3. Provider configuration:
   • Name: 3DKenji (display name for administrators)
   • Authorization grant type: Authorization Code (do not use implicit)
   • Client type: Confidential
   • Client ID: either auto-generated by Authentik or set to a recognizable value (copy this value)
   • Client Secret: generate and copy the secret (store securely)
   • Redirect URIs: add https://3dkenji.example.com/api/v1/auth/oauth/oidc/callback
   • Signing Key: ensure you have a signing key compatible with RS256 (Authentik issues JWKs; 3DKenji validates signatures via the provider JWKS endpoint)
   • Scopes: openid email profile
4. Create an Application in Authentik:
   • Name: 3DKenji
   • Slug: 3dkenji
   • Provider: select the provider created above
   • (Optional) UI fields like icon or description.
5. Note the Issuer URL from the provider or application page. Example:

https://auth.example.com/application/o/3dkenji/

1. In 3DKenji, open /admin/settings and fill in the OAuth / OIDC Configuration form:
   • Enable OAuth / OIDC sign-in: checked
   • Provider Slug: oidc
   • Issuer URL: https://auth.example.com/application/o/3dkenji/
   • Client ID: <from Authentik>
   • Client Secret: <from Authentik>
   • Callback URL: https://3dkenji.example.com/api/v1/auth/oauth/oidc/callback
   • Scopes: openid email profile
   • Mark auth cookie as Secure: checked if you are serving 3DKenji over HTTPS
2. Save the form. The client secret is stored encrypted in the database.
3. Test: visit https://3dkenji.example.com/api/v1/auth/oauth/oidc/authorize in your browser. You should be redirected to Authentik’s login page and back to 3DKenji after authentication.

Other OIDC Providers (quick notes)

• Keycloak: create a client with confidential access, set redirect URI as above, enable openid scope.
• Okta/Auth0: create an application, use the issuer URL from the application details, ensure openid email profile scopes are allowed.
• Cloudflare Access: vendor-specific issuer paths; ensure the .well-known/openid-configuration URL resolves and use the provided client credentials.
• Generic: 3DKenji expects a valid /.well-known/openid-configuration at the issuer URL.

Account Linking Behavior

• If the OIDC provider returns an email that matches an existing local account, the OIDC identity is automatically linked on first login.
• If no local match exists, a new account is created with a NULL local password (OIDC-only account).
• To manually link an existing logged-in account, call POST /api/v1/auth/oauth/{provider}/link which returns an authorize_url to complete linking.
• To unlink a provider use DELETE /api/v1/auth/oauth/{provider}/unlink — unlinking requires a local password to already be set on the account to prevent lockout.

Account Creation via OIDC

• New accounts created via OIDC have no local password by default.
• The account username is derived from the preferred_username claim when present; otherwise a safe slug is generated.

Admin Recovery Path (critical for homelab operators)

Warning: If your primary admin account is OIDC-only and the identity provider becomes unavailable, you may lose administrative access. Set a local recovery password immediately after enabling OIDC.

1. If you already have a local password for an admin account, you can always authenticate with POST /api/v1/auth/admin/recovery-login using username/password.
2. If an admin account was created via OIDC (no local password):
   • Log in once via OIDC (if provider is reachable) and obtain your JWT cookie/session.
   • Call POST /api/v1/auth/admin/set-local-password with your JWT to set a local password.
   • After setting a local password you can use the recovery login even if the IdP becomes unreachable.
3. Best practice: immediately set a local recovery password for the primary admin after enabling OIDC.

Security Considerations

• PKCE (S256) is enforced for authorization flows to mitigate interception attacks.
• ID tokens are validated for issuer, audience, expiry, and signature using the provider’s JWKS endpoint.
• OAuth state values are single-use and expire after 5 minutes.
• Set Mark auth cookie as Secure in admin settings when serving 3DKenji over HTTPS so cookies are marked secure.
• Client secrets and tokens are never logged by the service.
• Saved OAuth client secrets are encrypted before being stored in the database, using a key derived from SECRET_KEY.
• Do not rotate SECRET_KEY casually. If you change it, you must re-enter saved OAuth client secrets because bcrypt is not suitable here: password hashes are one-way, while OAuth client secrets must be decryptable for token exchange.

Troubleshooting

• “OAuth is not enabled”: open /admin/settings, enable OAuth / OIDC, and save the form.
• “Unknown OAuth provider”: confirm the saved Provider Slug matches the {provider} in the URL; default is oidc.
• Redirect URI mismatch: the provider’s registered redirect must exactly match the saved Callback URL.
• “Invalid or expired state”: authorization timed out (>5 minutes) — retry the login flow.
• “Invalid ID token”: check that the provider JWKS endpoint is reachable and the signing key matches (RS256 expected for Authentik by default).
• Admin recovery 401/403: 401 = wrong password or no local password set; 403 = account isn’t an admin.
• “OAuth configuration incomplete”: required fields are missing from the admin settings form, or the stored secret can no longer be decrypted because SECRET_KEY changed.

Runtime Configuration Reference

Variable	Default	Required	Description
SECRET_KEY	dev-secret-key in dev examples	yes	Used for JWT signing and for deriving the encryption key that protects stored OAuth client secrets. Keep it stable.

Saved Database Settings

These values are configured in /admin/settings and stored in the app_settings table:

Setting	Required When Enabled	Description
enabled	yes	Turns OAuth / OIDC sign-in on or off.
provider_name	yes	Provider slug used in URLs, usually oidc.
issuer_url	yes	Provider issuer URL exposing .well-known/openid-configuration.
client_id	yes	OAuth client ID from the provider.
client_secret	yes	OAuth client secret, stored encrypted in the database.
callback_url	yes	Redirect URI registered with the provider.
scopes	no	Space-separated scopes, usually openid email profile.
cookie_secure	no	Marks auth cookies as Secure when HTTPS is in use.

---

If something here doesn’t match your provider UI, open the provider’s application/client settings and verify the issuer, client credentials, and redirect URIs. If you need help with a specific provider, include the provider name and a sanitized copy of the .well-known/openid-configuration JSON.