Pulse/docs/OIDC.md

🔐 OIDC Single Sign-On

Enable Single Sign-On (SSO) with providers like Authentik, Keycloak, Okta, and Azure AD.

🚀 Quick Start

1. Configure Provider: Create an OIDC application in your IdP.
   • Redirect URI: https://<your-pulse-domain>/api/oidc/callback
   • Scopes: openid, profile, email
2. Enable in Pulse: Go to Settings → Security → Single sign-on (OIDC).
3. Enter Details:
   • Issuer URL: The base URL of your IdP (e.g., https://auth.example.com/application/o/pulse/).
   • Client ID & Secret: From your IdP.
4. Save: The login page will now show a "Continue with Single Sign-On" button.

Tip

: To hide the username/password form and only show the SSO button, set PULSE_AUTH_HIDE_LOCAL_LOGIN=true in your environment. You can still access the local login by appending ?show_local=true to the URL (e.g., https://your-pulse-instance/?show_local=true).

⚙️ Configuration

Setting	Description
Issuer URL	The OIDC provider's issuer URL. Must match the iss claim in tokens.
Client ID	The application ID from your provider.
Client Secret	The application secret.
Redirect URL	Auto-detected. Override only if running behind a complex proxy setup.
Scopes	Space-separated scopes. Default: openid profile email.
Claim Mapping	Map email, username, and groups to specific token claims.

Access Control

Restrict access to specific users or groups:

• Allowed Groups: Only users in these groups can login. Requires the groups scope/claim.
• Allowed Domains: Restrict to specific email domains (e.g., example.com).
• Allowed Emails: Allow specific email addresses.

📚 Provider Examples

Authentik

• Type: OAuth2/OpenID (Confidential)
• Redirect URI: https://pulse.example.com/api/oidc/callback
• Signing Key: Must use RS256 (create a certificate/key pair if needed).
• Issuer URL: https://auth.example.com/application/o/pulse/

Keycloak

• Client ID: pulse
• Access Type: Confidential
• Valid Redirect URIs: https://pulse.example.com/api/oidc/callback
• Issuer URL: https://keycloak.example.com/realms/myrealm

Azure AD

• Redirect URI: https://pulse.example.com/api/oidc/callback (Web)
• Issuer URL: https://login.microsoftonline.com/<tenant-id>/v2.0
• Note: Enable "ID tokens" in Authentication settings.

🔧 Troubleshooting

Issue	Solution
invalid_id_token	Issuer URL mismatch. Check logs (LOG_LEVEL=debug) to see the expected vs. received issuer.
unexpected signature algorithm "HS256"	Your IdP is signing with HS256. Configure it to use RS256.
Redirect Loop	Check X-Forwarded-Proto header (must be https) and cookie settings.
Self-Signed Certs	Mount your CA bundle to /etc/ssl/certs/oidc-ca.pem and set OIDC_CA_BUNDLE.

Debugging

Enable debug logs to trace the OIDC flow:

export LOG_LEVEL=debug
# Restart Pulse

Logs will show discovery, token exchange, and claim parsing details.