mirror of
https://github.com/rcourtman/Pulse.git
synced 2026-04-28 19:41:17 +00:00
a92a53fb98
- Update OIDC.md docs to show correct URL path (/?show_local=true, not /login) - Hide "Enter your credentials" subtitle when local login is hidden Related to #750
69 lines
3.1 KiB
Markdown
69 lines
3.1 KiB
Markdown
# 🔐 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:
|
|
```bash
|
|
export LOG_LEVEL=debug
|
|
# Restart Pulse
|
|
```
|
|
Logs will show discovery, token exchange, and claim parsing details.
|