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.
TypeScript graphviewkanban-boardnodejsproductivityproject-managementself-hostedtasktask-managementtask-managertodoapp
doc: sso
Nikolai Gimanb24f829a6be5
diff --git a/docs/2.features/11.sso.md b/docs/2.features/11.sso.mdnew file mode 100644index 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.