Sign InGet Started

Single Sign On

Single Sign-On (SSO) Setup Guide

What is Single Sign-On?

Single Sign-On (SSO) allows your team to access Contextium using your organization's existing identity provider (like Okta, Azure AD, or Google Workspace). Instead of managing separate passwords, users authenticate through your company's login system.

Benefits

  • 🔐 Enhanced Security: Centralized authentication through your identity provider
  • ⚡ Faster Onboarding: New team members get instant access through your directory
  • 🎯 Simplified Management: Add or remove access from one central location
  • 📊 Better Compliance: Meet security requirements with centralized audit logs
  • 🔄 Automatic Provisioning: Users are created automatically on first login

Requirements

  • Plan: Business or Enterprise subscription required
  • Identity Provider: OIDC/OAuth 2.0 compatible provider (Okta, Azure AD, Google Workspace, Auth0, etc.)
  • Role: Workspace Owner or Admin permissions

Quick Start Guide

Step 1: Access SSO Settings

  1. Log in to Contextium as a workspace Owner or Admin
  2. Navigate to Settings → SSO
  3. You'll see the SSO configuration page

If you're not on a Business or Enterprise plan, you'll see an upgrade prompt.

Step 2: Choose Your Provider

Contextium supports all OIDC/OAuth 2.0 compatible providers:

  • Azure AD (Microsoft Entra ID)
  • Okta
  • Google Workspace
  • Auth0
  • Generic OIDC (for other providers)

Select your provider type from the dropdown or choose "Generic OIDC" for any standard OIDC provider.

Step 3: Configure Your Provider

You'll need the following information from your identity provider:

  1. Client ID: Your application's client identifier
  2. Client Secret: Your application's secret key
  3. Issuer/Discovery URL: The OIDC discovery endpoint
  4. Allowed Domains: Email domains that can use SSO (e.g., company.com)

Provider-Specific Setup Guides

Setting Up with Google Workspace

Step 1: Create OAuth 2.0 Client in Google Cloud

  1. Go to Google Cloud Console
  2. Select your project (or create a new one)
  3. Navigate to APIs & Services → Credentials
  4. Click Create Credentials → OAuth 2.0 Client ID
  5. Choose Web application as the application type
  6. Add authorized redirect URI: 
    https://app.contextium.io/api/v1/auth/sso/callback
    (Use your API URL if self-hosting)
  7. Click Create and save your Client ID and Client Secret

Step 2: Configure in Contextium

  1. In Contextium SSO settings, select Google Workspace
  2. Enter your Client ID and Client Secret
  3. Set Issuer URL to: 
    https://accounts.google.com
  4. Add your email domain (e.g., yourcompany.com)
  5. Configure role mappings (optional)
  6. Enable Auto-provision users
  7. Click Save Configuration

Step 3: Test the Connection

  1. Click Test Configuration to verify settings
  2. If successful, toggle Enable SSO
  3. Test login with a user from your domain

Setting Up with Azure AD (Microsoft Entra ID)

Step 1: Register Application in Azure

  1. Go to Azure Portal
  2. Navigate to Azure Active Directory → App registrations
  3. Click New registration
  4. Set application name: Contextium SSO
  5. Set supported account types: Accounts in this organizational directory only
  6. Add Redirect URI (Web): 
    https://app.contextium.io/api/v1/auth/sso/callback
  7. Click Register

Step 2: Configure Application

  1. Copy the Application (client) ID
  2. Go to Certificates & secrets
  3. Click New client secret
  4. Add description and expiry
  5. Copy the secret Value (you won't see it again!)
  6. Go to Token configuration
  7. Add optional claims for email and name

Step 3: Configure in Contextium

  1. In Contextium SSO settings, select Azure AD
  2. Enter your Client ID and Client Secret
  3. Set Issuer URL to: 
    https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0
    Replace YOUR_TENANT_ID with your Azure AD tenant ID
  4. Add your email domain (e.g., company.com)
  5. Set Role Claim Path to roles (if using Azure AD roles)
  6. Configure role mappings
  7. Enable Auto-provision users
  8. Click Save Configuration

Step 4: Test the Connection

  1. Click Test Configuration
  2. Enable SSO after successful test
  3. Test login with an Azure AD user

Setting Up with Okta

Step 1: Create OIDC Application in Okta

  1. Log in to your Okta Admin Console
  2. Go to Applications → Applications
  3. Click Create App Integration
  4. Select OIDC - OpenID Connect
  5. Choose Web Application
  6. Set application name: Contextium SSO
  7. Add Sign-in redirect URI: 
    https://app.contextium.io/api/v1/auth/sso/callback
  8. Choose Controlled access settings
  9. Click Save

Step 2: Configure Application Settings

  1. Copy the Client ID and Client Secret
  2. Go to Assignments tab
  3. Assign users or groups who should have access
  4. (Optional) Go to Sign On tab → OpenID Connect ID Token to add custom claims

Step 3: Configure in Contextium

  1. In Contextium SSO settings, select Okta
  2. Enter your Client ID and Client Secret
  3. Set Issuer URL to: 
    https://YOUR_DOMAIN.okta.com
    Replace YOUR_DOMAIN with your Okta domain
  4. Add your email domain (e.g., company.com)
  5. Set Role Claim Path to groups (if using Okta groups)
  6. Configure role mappings
  7. Enable Auto-provision users
  8. Click Save Configuration

Step 4: Test the Connection

  1. Click Test Configuration
  2. Enable SSO after successful test
  3. Test login with an Okta user

Setting Up with Auth0

Step 1: Create Application in Auth0

  1. Log in to your Auth0 Dashboard
  2. Go to Applications → Applications
  3. Click Create Application
  4. Choose Regular Web Applications
  5. Go to Settings tab
  6. Add Allowed Callback URLs: 
    https://app.contextium.io/api/v1/auth/sso/callback
  7. Copy your Client ID and Client Secret

Step 2: Configure in Contextium

  1. In Contextium SSO settings, select Auth0
  2. Enter your Client ID and Client Secret
  3. Set Issuer URL to: 
    https://YOUR_DOMAIN.auth0.com/
    Replace YOUR_DOMAIN with your Auth0 domain
  4. Add your email domain (e.g., company.com)
  5. Configure role mappings (if using Auth0 roles)
  6. Enable Auto-provision users
  7. Click Save Configuration

Step 3: Test the Connection

  1. Click Test Configuration
  2. Enable SSO after successful test
  3. Test login with an Auth0 user

Setting Up with Generic OIDC Provider

For any other OIDC-compatible provider:

  1. In Contextium SSO settings, select Generic OIDC
  2. Enter your provider's:
    • Client ID
    • Client Secret
    • Issuer/Discovery URL (usually ends with /.well-known/openid-configuration)
  3. Add your email domain
  4. Configure role mappings (if supported)
  5. Enable Auto-provision users
  6. Click Save Configuration
  7. Test and enable

Advanced Configuration

Role Mapping

Map groups or roles from your identity provider to Contextium workspace roles:

Contextium Roles:

  • Admin: Full workspace management access
  • Editor: Can create and edit content
  • Viewer: Read-only access

Example Mapping:

Azure AD Group → Contextium Role
"Engineering-Admins" → Admin
"Engineering-Devs" → Editor
"Engineering-Contractors" → Viewer

Configuration:

  1. Set Role Claim Path to the claim containing groups/roles (e.g., groups, roles)
  2. Configure Role Mappings in JSON format: 
    {
  "admin": ["Engineering-Admins", "IT-Admins"],
  "editor": ["Engineering-Devs", "Product-Team"],
  "viewer": ["Contractors", "Guests"]
}
  3. Set Default Role for users without matching groups

Require SSO

When enabled, users with email addresses in the allowed domains must use SSO and cannot use password login.

To enable:

  1. Configure and test SSO first
  2. Enable the Require SSO toggle
  3. Users with matching domains will be forced to use SSO login

Important: Make sure SSO is working correctly before enabling this option!

Auto-Provisioning

When enabled, users logging in via SSO for the first time will automatically:

  • Get a Contextium account created
  • Be added to the workspace
  • Receive the appropriate role based on role mappings

To disable auto-provisioning:

  1. Uncheck Auto-provision users
  2. Only existing workspace members can log in via SSO
  3. You must manually invite new users first

Security Best Practices

1. Test Before Enabling

Always test your SSO configuration before enabling it for all users:

  • Click Test Configuration button
  • Verify successful authentication
  • Check user attributes are correct
  • Confirm role mapping works as expected

2. Use Specific Domains

Only add email domains your organization owns to Allowed Domains:

  • ✅ Good: yourcompany.com
  • ❌ Bad: gmail.com, outlook.com

3. Rotate Secrets Regularly

  • Update your Client Secret periodically
  • Use your identity provider's secret rotation features
  • Update the secret in Contextium after rotation

4. Monitor Audit Logs

Check the SSO Audit Logs regularly for:

  • Failed login attempts
  • Unusual authentication patterns
  • Blocked access attempts

5. Configure Role Mappings

  • Use least-privilege principle
  • Set a conservative Default Role (Viewer)
  • Only grant Admin/Editor to specific groups

Troubleshooting

Error: "SSO authentication failed"

Possible causes:

  • Incorrect Client ID or Secret
  • Invalid Issuer URL
  • User's email domain not in Allowed Domains
  • Application not assigned to user in IdP

Solutions:

  1. Verify Client ID and Secret are correct
  2. Check Issuer URL format (should include https://)
  3. Confirm user's email domain is in Allowed Domains
  4. Ensure user is assigned to the application in your IdP

Error: "Email domain not allowed"

Cause: User's email domain is not in the Allowed Domains list

Solution:

  1. Go to SSO Settings
  2. Add the user's domain to Allowed Email Domains
  3. Save configuration

Error: "User not found"

Cause: Auto-provisioning is disabled and user doesn't exist

Solutions:

  • Enable Auto-provision users in SSO settings, OR
  • Manually invite the user to the workspace first

Users Can't See Roles/Permissions

Cause: Role mapping not configured correctly

Solutions:

  1. Check Role Claim Path matches your IdP's claim name
  2. Verify group names in Role Mappings match exactly
  3. Check user is a member of the expected group in your IdP
  4. Set appropriate Default Role as fallback

SSO Works But Wrong Role Assigned

Cause: Role mapping configuration issue

Solutions:

  1. Verify the group names in your role mappings match exactly
  2. Check the Role Claim Path (common values: groups, roles, custom.groups)
  3. Review the user's groups in your IdP
  4. Check audit logs to see what groups were received

Getting Help

If you need assistance with SSO setup:

  1. Check Audit Logs: Review recent SSO login attempts in Settings → SSO → Audit
  2. Documentation: Review your identity provider's OIDC documentation
  3. Support: Contact Contextium support with:
    • Identity provider name
    • Error messages from audit logs
    • Steps you've already tried

FAQ

Q: Can I use multiple SSO providers? A: Currently, one SSO provider per workspace is supported.

Q: What happens to existing passwords when SSO is enabled? A: Existing passwords remain active unless you enable "Require SSO". Users can still log in with passwords if SSO is not required.

Q: Can users have both SSO and password login? A: Yes, unless "Require SSO" is enabled. When not required, users can choose either login method.

Q: What happens if SSO goes down? A: If "Require SSO" is not enabled, users can still log in with passwords. Workspace admins can always access the workspace to disable SSO if needed.

Q: Do I need to manually create users? A: No, if auto-provisioning is enabled. Users are automatically created on their first SSO login.

Q: Can I test SSO without affecting my team? A: Yes! SSO is not required by default. You can test with your own account before enabling it for everyone.

Q: Is SSO available on all plans? A: SSO is available on Business and Enterprise plans only. Upgrade your plan to access SSO.

Next Steps

After setting up SSO:

  1. ✅ Test login with your own account
  2. ✅ Enable SSO for your workspace
  3. ✅ Notify your team about the new login option
  4. ✅ (Optional) Enable "Require SSO" after confirming it works
  5. ✅ Monitor audit logs for any issues

Need help? Contact support@contextium.io or visit our Help Center.

Previous
MCP Tokens - Authentication & Security
Next
Social Login