Skip to main content

Single Sign-On (SSO) Setup

Enable your team to log in using your organization's identity provider via SAML 2.0 or OIDC (OpenID Connect). Plexicus supports both protocols for secure, enterprise-grade authentication.

info

SSO requires organization-level permissions to configure. Only team admins can set up or modify SSO settings.

Supported Protocols​

SAML 2.0​

  • Best for: Large enterprises with established SAML infrastructure
  • Providers: Okta, Azure AD, Google Workspace, Ping Identity, OneLogin, and any SAML 2.0-compliant IdP
  • Features:
    • XML metadata exchange for simplified setup
    • Attribute-based Just-in-Time (JIT) user provisioning
    • Certificate rotation for zero-downtime IdP updates
    • SP-initiated and IdP-initiated flows

OIDC (OpenID Connect)​

  • Best for: SaaS providers and modern cloud identity platforms
  • Providers: Auth0, Cognito, Okta, Google Workspace, Azure AD
  • Features:
    • OAuth 2.0 + PKCE (Proof Key for Code Exchange) for secure code flow
    • Dynamic discovery via OIDC metadata endpoints
    • Automatic access token and ID token handling

SSO Configuration Modes​

When you enable SSO, choose how strictly to enforce it:

ModeBehaviorUse Case
Coexist (default)SSO and password login both availableGradual migration; optional adoption
SSO PreferredSSO shown first; fallback to password if neededAlmost-enforced but flexible
SSO EnforcedOnly SSO login available; password login disabledFull enterprise lockdown (requires successful dry-run)
note

To enable SSO Enforced, you must first run a successful dry-run validation within the last 24 hours. This ensures your configuration works before locking out your team.

SAML 2.0 Configuration​

Step 1: Gather Your IdP Information​

From your identity provider's admin dashboard, collect:

  • IdP Entity ID — Unique identifier for your IdP (e.g., https://okta.com/123456)
  • IdP SSO URL — Login endpoint (e.g., https://your-org.okta.com/app/123456/sso/saml)
  • IdP SLO URL (optional) — Single Logout endpoint for session termination
  • IdP X.509 Certificate — Public certificate for signature validation (PEM format)
  • SAML Metadata URL or XML — Auto-discovered alternative to manual entry

Step 2: Register Plexicus as a Service Provider​

In your IdP's admin interface, create a new SAML application with these values:

Entity ID (Issuer):

https://api.plexicus.ai/

Assertion Consumer Service (ACS) URL:

https://api.plexicus.ai/auth/sso/{client_slug}/acs

Replace {client_slug} with your organization's slug (default: your client ID). You can customize this slug in Settings → Authentication → SSO → Configure.

Single Logout Service (SLO) URL (optional):

https://api.plexicus.ai/auth/sso/{client_slug}/sso

NameID Format:

urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Step 3: Configure in Plexicus​

  1. Navigate to Settings → Authentication → SSO.
  2. Click Configure SSO.
  3. Select Generic SAML 2.0.
  4. Enter:
    • IdP Entity ID — from your IdP
    • IdP SSO URL — login endpoint
    • IdP X.509 Certificate — PEM block, including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----
    • SP Entity ID (optional) — defaults to https://api.plexicus.ai/
    • IdP SLO URL (optional) — for logout flows

Step 4: Attribute Mapping​

By default, Plexicus expects:

  • Email → email
  • First Name → given_name
  • Last Name → family_name
  • Groups → groups (for group-based role assignment)

If your IdP uses different attribute names, customize them:

  1. Click Advanced Settings.
  2. Map each attribute to your IdP's claim names.

Example: If your IdP sends email as mail instead of email, update the mapping to mail.

Step 5: Optional — Group-to-Role Mapping​

If your IdP supports group membership, you can auto-assign Plexicus roles based on SAML groups:

  1. In Advanced Settings, add a Group Role Mapping.
  2. Enter:
    • IdP Group — e.g., security-team
    • Plexicus Role — e.g., Developer or a custom role
  3. Users in that IdP group will be auto-assigned the role on first login.

Step 6: Validate and Activate​

  1. Click Validate Configuration (dry-run).
    • Plexicus checks all certificates, endpoints, and attribute mappings.
    • No changes are persisted.
  2. If validation passes, click Activate SAML.
tip

If you receive certificate errors during validation, verify:

  • The certificate is in valid PEM format (not DER or P12)
  • It's not expired
  • It matches your IdP's current signing certificate

OIDC (OpenID Connect) Configuration​

Step 1: Gather Your OIDC Provider Information​

From your OIDC provider's app registration interface, collect:

  • Discovery URL — Auto-discovers metadata (e.g., https://accounts.google.com/.well-known/openid-configuration)
  • Client ID — Your app's ID
  • Client Secret — Your app's secret (kept encrypted; never exposed in logs)
  • Scopes — Default: openid email profile

Step 2: Register Plexicus as an OIDC Client​

In your OIDC provider's admin console, create a new application:

  1. Set Application Type → Web Application
  2. Set Redirect URI to: 
    https://api.plexicus.ai/auth/sso/{client_slug}/oidc/callback
    Replace {client_slug} with your organization's slug.
  3. Do not use http://localhost in production — only https is accepted.
  4. Copy the generated Client ID and Client Secret.

Step 3: Configure in Plexicus​

  1. Navigate to Settings → Authentication → SSO.
  2. Click Configure SSO.
  3. Select Generic OIDC.
  4. Enter:
    • Discovery URL — OIDC metadata endpoint
    • Client ID — from your provider
    • Client Secret — from your provider
    • Scopes (optional) — defaults to openid email profile

Plexicus enables PKCE (Proof Key for Code Exchange) by default. This adds an extra layer of security for the authorization code flow. No manual configuration needed.

Step 5: Attribute Mapping (Optional)​

Similar to SAML, customize how OIDC claims map to Plexicus user fields:

  1. Click Advanced Settings.
  2. Map claims:
    • Email Claim → email (or mail, email_address)
    • First Name Claim → given_name
    • Last Name Claim → family_name
    • Groups Claim → groups (if your provider supports groups)

Step 6: Validate and Activate​

  1. Click Validate Configuration.
  2. If validation passes, click Activate OIDC.

Just-in-Time (JIT) Provisioning​

When SSO is enabled, Plexicus can automatically create user accounts on first login using JIT provisioning.

Configuration​

  1. Navigate to Settings → Authentication → SSO.
  2. Under Advanced Settings, configure:
    • JIT Enabled — Toggle on/off (default: enabled)
    • Default Role — Role assigned to newly provisioned users (default: Developer)

Behavior​

  • When a user logs in via SSO for the first time, Plexicus creates an account with their email and extracted attributes (name, groups).
  • If group-role mapping is configured, the user's IdP group determines their role.
  • Otherwise, the Default Role is assigned.
  • Existing users who link SSO to their account keep their current role.
caution

If JIT is disabled and a user who hasn't been pre-provisioned tries to log in, they'll see a "User not found" error. Pre-invite all users before disabling JIT.

Self-Hosted Deployments​

If running Plexicus self-hosted via Helm, SSO relies on three secrets in your Helm chart:

helm install plexicus ./helm-chart \
  --set sso.breakGlassSecretKey="your-secret-key" \
  --set sso.relayStateSecret="your-relay-state-secret" \
  --set sso.encryptionKey="your-encryption-key"
SecretPurpose
BREAK_GLASS_SECRET_KEYEnables admin break-glass access if SSO is misconfigured (admin-only recovery)
SSO_RELAY_STATE_SECRETHMAC secret for SAML RelayState signing (prevents open-redirect attacks)
SSO_ENCRYPTION_KEYEncrypts OIDC client secrets at rest
warning

Never commit secrets to version control. Use your deployment platform's secret management (e.g., Sealed Secrets, HashiCorp Vault).

For more details, see Self-Hosted Configuration.

SCIM User Provisioning (Enterprise)​

info

SCIM provisioning is available on Scale plan and above.

Use SCIM 2.0 to automatically sync users and groups from your IdP to Plexicus without manual invitations:

  1. Generate a SCIM Bearer Token:

    • Go to Settings → Authentication → SSO → SCIM Tokens.
    • Click Create Token.
    • Copy the token (shown once).

  2. Configure your IdP's SCIM integration:

    • SCIM Base URL: https://api.plexicus.ai/scim/v2
    • Bearer Token: Paste the token from step 1.
    • Endpoints: Map to:
      • /scim/v2/Users (user provisioning)
      • /scim/v2/Groups (group provisioning)

  3. Test the connection in your IdP's admin console.

Token Rotation:

  • Tokens expire after 1 year (customizable at creation).
  • Rotate tokens via Settings → Authentication → SSO → SCIM Tokens → Rotate.
  • Old tokens remain valid for 7 days during the rotation window.

Certificate & Secret Rotation​

SAML Certificate Rotation​

When your IdP rotates its signing certificate:

  1. Go to Settings → Authentication → SSO.
  2. Click Advanced Settings.
  3. Choose Stage or Promote:
    • Stage: Keeps the old certificate active while accepting the new one (dual-cert window, ~7 days).
    • Promote: Immediately switch to the new certificate.

OIDC Client Secret Rotation​

If you need to rotate your OIDC client secret in your provider:

  1. Generate a new secret in your OIDC provider's console.
  2. Go to Settings → Authentication → SSO.
  3. Update the Client Secret with the new value.
  4. Click Save.

Plexicus encrypts and stores the secret securely; it's never logged or exposed.

Troubleshooting​

"SSO not available" error​

  • Verify the client_slug is correct in your login URL.
  • Check that SSO has been activated (not just configured).
  • Confirm the tenant has a valid SSO configuration.

SAML signature validation failed​

  • Ensure the IdP's X.509 certificate is current and in PEM format.
  • Check that your IdP is signing assertions (not just responses).
  • Verify clock skew tolerance: Plexicus allows ±120 seconds by default.

OIDC callback returns "state mismatch"​

  • Clear browser cookies for api.plexicus.ai.
  • Confirm the Redirect URI in your OIDC provider matches exactly: https://api.plexicus.ai/auth/sso/{client_slug}/oidc/callback
  • If using multiple IdPs or testing locally, disable PKCE briefly (not recommended for production).

"User provisioning failed"​

  • Verify the email attribute is correctly mapped and contains a valid email address.
  • If group-role mapping is configured, ensure the IdP group exists and is returned in the response.
  • Check the organization has available user licenses (for SaaS).

SSO Enforced mode requires a dry-run​

  • Run Validate Configuration and wait for success.
  • Activation of SSO Enforced requires a successful dry-run within the last 24 hours.

Best Practices​

  1. Test SSO before enforcement: Use Coexist mode first, then graduate to SSO Preferred or SSO Enforced.
  2. Distribute the login slug: Share your custom SSO login slug (e.g., your-company.plexicus.ai) with your team.
  3. Rotate certificates proactively: Don't wait for IdP certificate expiration; rotate preemptively.
  4. Use group-role mapping: Auto-assign roles via IdP groups to reduce manual team management overhead.
  5. Monitor audit logs: Check Settings → Organization → Audit Log for SSO configuration changes.

SaaS vs Self-Hosted Differences​

FeatureSaaSSelf-Hosted
SAML 2.0✅ Yes✅ Yes
OIDC✅ Yes✅ Yes
SCIM ProvisioningScale+ planIncluded
Custom Slug✅ Yes✅ Yes
Certificate Rotation✅ Yes✅ Yes
Break-Glass RecoveryAdmin onlyVia secrets

Next Steps​