OIDC Guided Setup

OIDC Guided Setup

This guide configures UI-managed Single Sign-On from System -> Authentication. The local Nutify login remains active throughout the process.

1. Prepare the Provider Client

Create a confidential web/OpenID Connect client in the identity provider:

• flow: Authorization Code
• callback: https://nutify.example.com/auth/oidc/callback
• scopes: openid profile email groups
• PKCE: S256 supported
• username claim: normally preferred_username
• groups claim: normally groups

Use the exact callback displayed by Nutify. Reverse-proxy users must enter the public HTTPS callback, not the container address.

2. Save a Draft

Open System -> Authentication and enter:

• exact issuer URL
• Client ID and Client Secret
• public callback URL
• provider name and button label
• username/groups claim names
• one or more administrator/user groups

Expand Claims and access policy for authorization settings. Only select Allow all authenticated users when every provider account should receive normal-user access.

A private/LAN IdP requires Allow a private-network issuer. This is an explicit SSRF boundary exception; link-local and metadata-service addresses remain blocked.

Select Save configuration. Saving does not enable SSO.

3. Discover the Provider

Select Discover provider. Nutify validates:

• the issuer and discovery document match exactly
• Authorization Code flow is advertised
• authorization, token, and JWKS endpoints are valid
• JWKS contains signing keys
• network and HTTPS policy passes

Correct the provider or URL if discovery fails.

4. Test in a Real Browser

Select Test SSO in browser. A separate window completes the provider login, token validation, UserInfo validation, group policy, and callback without creating a Nutify user session.

Any security-sensitive configuration change invalidates this result and disables SSO until the test is repeated.

5. Enable SSO

Enable SSO becomes available only after discovery and browser verification both pass. Enabling it adds the SSO option to the login page.

Test both paths before enabling automatic redirect:

1. sign in through SSO
2. sign out
3. open /auth/login?local=1
4. sign in with the local administrator

Optional Dynamic Registration

If discovery advertises support, Nutify displays a Dynamic Client Registration box. Enter a provider-issued Initial Access Token only when required and select Register Nutify client. Nutify stores only the returned Client ID and encrypted secret; the access token is discarded.

If the box is absent or registration is rejected, create the client manually.

Disable or Reset

• Disable SSO immediately removes SSO from the public login page.
• Delete SSO configuration removes the saved provider settings.
• Existing OIDC-only users remain visible to administrators and keep their immutable identity bindings until the users are deleted.