🔐 OIDC Authentication

SSO via OpenID Connect. Users log in with their existing identity provider.

Setup

Go to Settings → Authentication → Add Provider.

Field	Description
Display Name	Shown on login button
Issuer URL	IdP's discovery URL
Client ID	From your IdP
Client Secret	From your IdP
Redirect URI	Copy this to your IdP
Scope	Usually openid profile

Provider Setup

Microsoft Entra ID (Azure AD)

1. Azure Portal → Microsoft Entra ID → App registrations → New registration
2. Add redirect URI: https://nexterm.yourdomain.com/api/auth/oidc/callback
3. Copy Application (client) ID → Client ID
4. Certificates & secrets → New client secret → copy value → Client Secret
5. Issuer URL: https://login.microsoftonline.com/{tenant-id}/v2.0

Google

1. Google Cloud Console → APIs & Services → Credentials
2. Create Credentials → OAuth client ID → Web application
3. Add redirect URI: https://nexterm.yourdomain.com/api/auth/oidc/callback
4. Issuer URL: https://accounts.google.com

WARNING

Google requires app verification for production. Add test users in OAuth consent screen during dev.

Keycloak

1. Clients → Create client
2. Enable Client authentication
3. Add redirect URI, copy Client Secret from Credentials tab
4. Issuer URL: https://keycloak.yourdomain.com/realms/{realm-name}

Authentik

1. Applications → Providers → Create → OAuth2/OpenID Provider
2. Set redirect URI, copy Client ID/Secret
3. Issuer URL: https://authentik.yourdomain.com/application/o/{application-slug}/

TIP

The trailing slash matters. Check /.well-known/openid-configuration to see the exact issuer value.

Authelia

identity_providers:
  oidc:
    clients:
      - client_id: nexterm
        client_secret: '$pbkdf2-sha512$your-hashed-secret'
        redirect_uris:
          - https://nexterm.yourdomain.com/api/auth/oidc/callback
        scopes: [ openid, profile, email ]

Issuer URL: https://auth.yourdomain.com

Attribute Mapping

Defaults in Advanced Settings:

Field	Claim
Username	preferred_username
First Name	given_name
Last Name	family_name

Troubleshooting

Redirect URI mismatch - Must match exactly. Check trailing slashes, http vs https.

User attributes wrong - Check claim names in your IdP's token and adjust mapping.