OpenID Connect SSO Guide

OpenID Connect SSO Guide

Nutify supports OpenID Connect (OIDC) Single Sign-On while retaining built-in Nutify accounts. Administrators can configure OIDC from the web interface or manage it entirely through container environment variables.

Choose a Configuration Mode

UI-managed mode

This is the default and recommended mode for most installations.

1. Sign in with a local administrator account.
2. Open System -> Authentication.
3. Follow Save, Discover, Browser Test, and Enable.

The client secret is encrypted with SECRET_KEY, API responses are masked, and SSO cannot be enabled before provider discovery and a successful real browser login. Continue with OIDC Guided Setup.

Environment-managed mode

Use this for immutable Docker deployments, secret managers, or infrastructure automation. Set OIDC_CONFIG_SOURCE=environment; the Authentication page shows masked status and cannot modify the configuration. Continue with OIDC Environment Configuration.

The two sources are never merged.

Login Experience

• Local-only installations show the Nutify username/password form directly.
• Dual-mode installations show Sign in with Single Sign-On and Sign in with Nutify account.
• Auto-redirect installations immediately start SSO.
• Emergency local administrator access always bypasses auto-redirect:

https://nutify.example.com/auth/login?local=1

Keep at least one tested local administrator account.

Security Model

• Authorization Code flow with PKCE S256, state, and nonce
• exact discovery/token issuer validation
• matching sub between ID token and UserInfo
• HTTPS issuer and callback in production
• discovery endpoint and JWKS validation before activation
• explicit provider-group authorization by default
• immutable identity binding by provider issuer + subject
• no automatic linking by mutable username or email
• encrypted UI-managed client secret and masked APIs
• OIDC-only accounts cannot gain local passwords or local role overrides
• disabled Nutify accounts remain disabled

If a provider username collides with a local or different OIDC account after Unicode normalization and case folding, login is rejected. An IdP account named admin therefore cannot take over the local administrator.

Authorization Policy

Administrator groups map members to Nutify administrator. User groups map members to normal user. When both match, administrator wins. Comparisons are case-insensitive.

At least one group must be configured unless Allow all authenticated users is explicitly enabled. That setting grants normal-user access to every valid provider identity; configured administrator groups still control elevation.

Provider role/group changes apply at the next login. Provider data never reactivates a disabled Nutify account.

Provider Help

See OIDC Provider Examples for current Authentik, Keycloak, and Microsoft Entra ID terminology and issuer examples.

Dynamic Client Registration

Nutify shows Dynamic client registration only when trusted provider discovery advertises a registration_endpoint. The provider may require a one-time Initial Access Token. Nutify sends that token once and never stores, logs, or returns it.

Dynamic registration is provider-dependent. Manual confidential-client setup remains the universal fallback. See OIDC Security and Troubleshooting.