Skip to content

TaskView is a self-hosted project and task management platform focused on clarity, ownership, and control. TaskView is built for teams that want a transparent, self-hosted alternative to SaaS task managers.

doc: sso

Nikolai Gimanb24f829a6be5
diff --git a/docs/2.features/11.sso.md b/docs/2.features/11.sso.md
new file mode 100644
index 0000000..5d94d28
--- /dev/null
+++ b/docs/2.features/11.sso.md
@@ -0,0 +1,161 @@
+---
+title: SSO (Single Sign-On)
+description: Configure SAML 2.0 or OpenID Connect SSO for your organization. Users authenticate through your corporate identity provider (Okta, Azure AD, Google Workspace, Keycloak) and get automatic access to TaskView.
+navigation:
+ icon: i-lucide-shield-check
+---
+
+SSO lets your organization's members sign in to TaskView using your corporate identity provider (IdP). Supported protocols: **SAML 2.0** and **OpenID Connect (OIDC)**.
+
+## How it works
+
+1. User enters their email on the TaskView login page (SSO tab)
+2. TaskView looks up the email domain (e.g. `company.com`) and finds the matching SSO config
+3. User gets redirected to your IdP (Okta, Azure AD, etc.)
+4. User authenticates at the IdP
+5. IdP redirects back to TaskView with identity proof
+6. TaskView creates an account (if new) and logs the user in
+
+Users who sign in via SSO are automatically added to the organization that owns the SSO config.
+
+## Setting up SSO
+
+Go to your organization's settings → **SSO** tab. You need the **admin** or **owner** role.
+
+### SAML 2.0
+
+**Required fields:**
+
+| Field | Description |
+|-------|-------------|
+| Provider name | Display name shown in the UI (e.g. "Okta", "Azure AD") |
+| Email domain | The domain used for routing (e.g. `company.com`). One domain = one SSO config |
+| IdP SSO URL | Your IdP's SAML endpoint where login requests are sent |
+| SP Entity ID | TaskView's identifier. Can be any string, must match what you configure in your IdP |
+| IdP Certificate | Your IdP's public signing certificate (base64, without BEGIN/END headers) |
+| ACS URL (Callback) | The URL where your IdP sends SAML responses. Shown after creating the config - copy it to your IdP |
+
+**Using Metadata URL (recommended):**
+
+Instead of filling fields manually, paste your IdP's metadata URL and click **Sync**. This auto-fills the IdP SSO URL, Certificate, and Logout URL from the metadata XML.
+
+Example metadata URLs:
+- Okta: `https://your-org.okta.com/app/xxx/sso/saml/metadata`
+- Azure AD: `https://login.microsoftonline.com/{tenant}/federationmetadata/2007-06/federationmetadata.xml`
+- Keycloak: `http://your-keycloak/realms/{realm}/protocol/saml/descriptor`
+
+SP Entity ID is not filled from metadata - you set it yourself. It must match between TaskView and your IdP.
+
+### SAML signature requirements
+
+TaskView **requires** that your IdP signs SAML Assertions. Without a valid signature, authentication will be rejected.
+
+**IdP configuration:**
+
+| Setting | Required value |
+|---------|---------------|
+| Sign assertions | **ON** (required) |
+| Sign documents (response) | **ON** (required) |
+
+TaskView validates the assertion signature. The document (response) signature provides additional transport-level integrity. Both should be enabled for maximum security.
+
+> **Note:** If you encounter "Invalid signature" errors with both signatures enabled, verify that your IdP certificate is correct. Re-sync from metadata URL if needed.
+
+**Request signing (enterprise, optional):**
+
+For environments that require signed AuthnRequests, you can provide an SP signing key pair. Generate it with:
+
+```bash
+openssl req -x509 -newkey rsa:2048 -keyout sp-key.pem -out sp-cert.pem -days 3650 -nodes -subj "/CN=taskview"
+```
+
+Paste `sp-key.pem` contents into **SP Private Key** and `sp-cert.pem` into **SP Certificate** in TaskView. Upload `sp-cert.pem` to your IdP so it can verify the signature.
+
+When signing keys are provided, TaskView signs AuthnRequests with **RSA-SHA256**.
+
+### OpenID Connect (OIDC)
+
+**Required fields:**
+
+| Field | Description |
+|-------|-------------|
+| Provider name | Display name (e.g. "Google Workspace", "Keycloak OIDC") |
+| Email domain | The domain used for routing (e.g. `company.com`) |
+| Issuer URL | Your IdP's OIDC issuer URL. Used for auto-discovery of endpoints |
+| Client ID | OAuth client ID from your IdP |
+| Client Secret | OAuth client secret from your IdP |
+| Callback URL | The URL where your IdP redirects after authentication. Shown after creating the config |
+
+Example issuer URLs:
+- Google: `https://accounts.google.com`
+- Azure AD: `https://login.microsoftonline.com/{tenant}/v2.0`
+- Keycloak: `http://your-keycloak/realms/{realm}`
+
+TaskView uses **PKCE (S256)** for the authorization code exchange. Your IdP must support the authorization code grant with PKCE.
+
+## Email domain routing
+
+:::callout{icon="i-lucide-alert-triangle" color="warning"}
+Each SSO config is bound to an **email domain**. One domain can only have one SSO config - this is enforced at the database level.
+:::
+
+When a user enters `[email protected]` on the SSO login tab, TaskView checks if domain `company.com` has a configured SSO provider. If yes - redirect to IdP. If no - show an error.
+
+## User provisioning
+
+When a user authenticates via SSO for the first time:
+1. A TaskView account is created automatically (with a random password - they'll only use SSO)
+2. A personal workspace is created for them
+3. They are added to the SSO config's organization with the **member** role
+
+For existing users (already registered with the same email), SSO login links their account - no new account is created, data is preserved.
+
+## Replay attack protection (SAML)
+
+TaskView stores SAML AuthnRequest IDs in a PostgreSQL table (`saml_request_cache`) and validates the `InResponseTo` field in SAML responses. Each request ID can only be used once. This prevents replay attacks even in multi-instance deployments behind a load balancer.
+
+Request IDs expire after 5 minutes.
+
+## API endpoints
+
+### Public
+
+| Method | URL | Description |
+|--------|-----|-------------|
+| GET | `/module/sso/providers?domain={domain}` | Check if SSO is configured for a domain |
+| GET | `/module/sso/login/{configId}` | Initiate SSO login (redirects to IdP) |
+| GET/POST | `/module/sso/callback/{configId}` | Handle IdP callback |
+
+### Admin (requires authentication + org admin role)
+
+| Method | URL | Description |
+|--------|-----|-------------|
+| GET | `/module/sso/admin/metadata?url={metadataUrl}` | Parse SAML metadata XML from URL |
+| GET | `/module/sso/admin/configs?organizationId={id}` | List SSO configs for an organization |
+| POST | `/module/sso/admin/configs` | Create SSO config |
+| PATCH | `/module/sso/admin/configs/{configId}` | Update SSO config |
+| DELETE | `/module/sso/admin/configs/{configId}` | Delete SSO config |
+
+## Database tables
+
+| Table | Purpose |
+|-------|---------|
+| `tv_auth.sso_configs` | SSO provider configurations (SAML/OIDC settings per organization) |
+| `tv_auth.sso_identities` | Links between TaskView users and their external SSO identities |
+| `tv_auth.saml_request_cache` | SAML request ID cache for replay attack prevention |
+
+## Troubleshooting
+
+**"SSO not configured" when entering email** - No SSO config exists for this email domain. Create one in organization settings.
+
+**"Invalid requester" (SAML)** - SP Entity ID in TaskView doesn't match Client ID in your IdP. They must be identical.
+
+**"Invalid signature" (SAML)** - IdP Certificate in TaskView is wrong or outdated. Re-sync from metadata URL or copy the certificate from your IdP's metadata XML.
+
+**"Invalid document signature" (SAML)** - The document (response) signature validation failed. Verify the IdP certificate is correct and re-sync from metadata URL.
+
+**"Failed to initiate SSO login" (OIDC)** - Issuer URL is wrong, or the IdP is unreachable. Verify the URL by opening `{issuer}/.well-known/openid-configuration` in a browser.
+
+**"Invalid parameter: redirect_uri" (OIDC)** - Callback URL in TaskView doesn't match "Valid redirect URIs" in your IdP. Copy the callback URL from TaskView's SSO settings and add it to your IdP.
+
+**User logged in as wrong person** - The IdP has an active session for another user. This is normal SSO behavior - the IdP controls sessions, not TaskView. Use a different browser or incognito window to test with a different user.