Single Sign-On (SSO)
Curiosity Workspace integrates with external identity providers so users sign in with their existing corporate accounts. SSO is also the supported way to enforce MFA, conditional access, and group-based authorization in front of a workspace.
Supported providers
| Provider | Protocol | Guide |
|---|---|---|
| Microsoft Entra ID (formerly Azure AD) | OAuth 2.0 / OIDC | Microsoft Entra ID |
| Google Workspace | OAuth 2.0 / OIDC | Google Sign-In |
| Okta | OIDC | Okta |
| Auth0 | OIDC | Auth0 |
| Generic SAML 2.0 | SAML | The /api/saml/ endpoints handle SAML; configure under Settings → SSO → SAML |
Choosing a provider
| If your users live in… | Use… | Notes |
|---|---|---|
| Microsoft 365 / Entra ID | Microsoft Entra ID | Map Entra groups to Workspace teams. |
| Google Workspace | Google Sign-In | Optionally restrict to your Google domain. |
| Okta universal directory | Okta | OIDC; SAML also supported. |
| Auth0 | Auth0 | OIDC; useful as a federation broker for multiple upstream IdPs. |
| Other (PingFederate, Keycloak, ADFS, …) | SAML 2.0 | Use the generic SAML configuration. |
General configuration shape
Every SSO provider follows the same three-step flow:
- Register the workspace as an application in the identity provider.
- Set the redirect URI in the IdP to the workspace's callback path.
- Paste the IdP-issued credentials (Client ID, Client Secret, Tenant ID, etc.) into the workspace under Manage → Settings → Accounts → Single Sign-On.
Redirect URI format
The redirect URI always follows this exact shape:
{MSK_PUBLIC_ADDRESS}/api/{provider}sso/completed-login-attempt
Where {provider} is one of microsoft, google, okta, auth0. For example:
https://workspace.example.com/api/microsoftsso/completed-login-attempt
https://workspace.example.com/api/googlesso/completed-login-attempt
For SAML, the callback is https://workspace.example.com/api/saml/acs.
Exact match
The redirect URI registered with the IdP must match byte-for-byte, including the scheme, hostname, port, and trailing path. If MSK_PUBLIC_ADDRESS is not set, the workspace will generate redirect URIs against its internal hostname — which won't match what's registered in your IdP.
Group mapping (ReBAC)
The full power of SSO comes from mapping IdP groups to Workspace teams (_AccessGroup nodes). When a user signs in:
- The IdP returns the user's group memberships in the token.
- The workspace creates a
_Usernode if it doesn't exist. - The workspace adds the user to the matching teams via
_MemberOfedges. - Search and graph queries automatically respect those memberships through ReBAC.
Configure group mapping under Settings → SSO → Group Mapping after the basic OIDC/SAML flow is working.
Session management
| Setting | Description | Recommended |
|---|---|---|
| Session duration | How long a session remains active before re-authentication | 8 hours for interactive users, 1 hour for admins |
| Inactivity timeout | Automatic logout on idle | 30 minutes for shared environments |
| Token rotation | Rotate refresh tokens on use | Enabled |
Security recommendations
- Enforce MFA in your IdP — every account, with no carve-outs for service accounts.
- HTTPS-only for the workspace; never disable
MSK_USE_HSTSonce it's on. - Audit log — forward authentication events to your SIEM. See Monitoring.
- Least privilege — map IdP groups to the most restrictive workspace teams that still allow the user's tasks.
- Disable the local admin account after onboarding administrators via SSO.
Common troubleshooting
| Symptom | Likely cause |
|---|---|
| "Redirect URI mismatch" on the IdP | MSK_PUBLIC_ADDRESS doesn't match the URI registered with the IdP (trailing slash, http vs https, port). |
| Login succeeds on the IdP but fails on the workspace | Client secret typo, wrong tenant ID, or expired secret. |
| Login succeeds but the user lands without permissions | Group mapping isn't configured, or the IdP isn't including group claims in the token. |
| Login worked yesterday, fails now after a restart | MSK_JWT_KEY was autogenerated and changed on restart; set it explicitly. |
| Loop between IdP and workspace | Cookies blocked, or the workspace hostname differs between the IdP redirect and what the browser sees. |
For symptom-first debugging, see Troubleshooting → SSO.
Next steps
- Pick a provider and follow the matching guide.
- Wire group mapping under Settings → SSO → Group Mapping.
- Confirm ReBAC is working: as a test user, search for content owned by a team you're not in and verify it's absent.