Skip to main content

Enterprise 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), with automatic user provisioning via SCIM 2.0 and role assignment through group mappings.

info

SSO requires Admin role in your Plexicus organization. Configuration changes are audited in Settings → Organization → Audit Log.

Supported Protocols & Providers​

SAML 2.0​

  • Best for: Enterprise organizations with mature identity infrastructure
  • Supported Providers:
    • Okta (step-by-step guide below)
    • Azure AD / Entra ID (step-by-step guide below)
    • Google Workspace (SAML via admin console)
    • Ping Identity, OneLogin, Keycloak, and any SAML 2.0-compliant IdP
  • Features:
    • XML metadata auto-upload to IdP or manual endpoint registration
    • Attribute-based Just-in-Time (JIT) user provisioning
    • Certificate rotation with staging window (zero-downtime IdP cert updates)
    • SP-initiated (user clicks "Sign in with SSO") and IdP-initiated flows (admin portal links)
    • Signing & encryption options (assertions, responses, metadata)

SAML Bindings: HTTP-POST (default, recommended) and HTTP-Redirect (supported).

OIDC (OpenID Connect)​

  • Best for: SaaS and modern cloud-native identity platforms
  • Supported Providers:
    • Okta (via OIDC app)
    • Azure AD / Entra ID (via app registration)
    • Google Workspace (via OAuth app)
    • Auth0, Cognito, Keycloak, and any OpenID Connect provider
  • Features:
    • OAuth 2.0 authorization code flow + PKCE (default-enabled for security)
    • Auto-discovery via OIDC metadata endpoints (.well-known/openid-configuration)
    • ID token + access token handling
    • Refresh token support (standard OIDC)

Default Scopes: openid, email, profile. Customizable per provider.

SSO Configuration Modes​

Choose the enforcement level that matches your organization's security posture:

ModeUser BehaviorWhen to Use
Coexist (default)Login page offers both SSO and password optionsGradual rollout; testing SSO before enforcement
SSO PreferredSSO tab shown first; users can fall back to passwordNear-enforcement; flexibility for edge cases
SSO EnforcedOnly SSO available; password login disabledFull enterprise lockdown (requires successful dry-run within 24 hours)
warning

Before enabling SSO Enforced: Run a successful dry-run validation (see Validate Configuration) to confirm your IdP setup works. Misconfiguration can lock out admins. Use Break-Glass Access to recover.

SAML 2.0 Configuration​

Plexicus acts as a SAML 2.0 Service Provider (SP). Your identity provider must support SAML 2.0 and allow you to register applications.

Plexicus SAML Service Provider Details​

When configuring your IdP, use these Plexicus-side values:

SettingValue
SP Entity IDhttps://api.plexicus.ai/ (or custom domain for self-hosted)
Assertion Consumer Service (ACS) URLhttps://api.plexicus.ai/auth/sso/{client_slug}/acs
Single Logout Service (SLO) URLhttps://api.plexicus.ai/auth/sso/{client_slug}/sls
NameID Formaturn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
Metadata URLhttps://api.plexicus.ai/auth/sso/{client_slug}/metadata
SAML BindingHTTP-POST (default); HTTP-Redirect supported
Signature RequirementsAssertions signed (required); response signing optional

Replace {client_slug} with your organization's unique slug (you can customize this in Settings → Authentication → SSO → Configure → Slug Settings).

Setup: Okta​

Okta Step 1: Create SAML 2.0 Application​

  1. Log in to your Okta admin console.
  2. Go to Applications → Applications → click Create App Integration.
  3. Select SAML 2.0 as the sign-in method.
  4. Click Create.

Okta Step 2: Configure SAML Settings​

  1. Enter App name (e.g., "Plexicus").
  2. In Configure SAML section, enter:
    • Single sign on URL: https://api.plexicus.ai/auth/sso/{client_slug}/acs
    • Audience URI (SP Entity ID): https://api.plexicus.ai/
    • Name ID format: Email (or unspecified)
    • Application username: Email
  3. Leave Response and Assertion signing defaults unless your security policy requires signed responses.

Okta Step 3: Attribute Mapping​

  1. In Attribute Statements, add:

    • email → user.email
    • given_name → user.firstName
    • family_name → user.lastName
    • groups → appuser.groups (if using group-based role assignment)

  2. Optionally set Group Attribute Statements to map Okta groups to Plexicus roles (see Group-to-Role Mapping below).

Okta Step 4: Retrieve IdP Metadata​

  1. In the Sign On tab, scroll to SAML Signing Certificates.
  2. Click View IdP Metadata (or copy the metadata URL).
  3. Keep this metadata URL or XML file — you'll use it in Plexicus.

Okta Step 5: Finalize in Plexicus​

  1. In Plexicus, go to Settings → Authentication → SSO.
  2. Click Setup → Okta (if available) or Generic SAML 2.0.
  3. Choose import method:
    • Paste Metadata XML (recommended) — Copy IdP metadata XML and paste it. Plexicus auto-extracts entity ID, SSO URL, and certificate.
    • Enter Metadata URL — Provide the Okta metadata URL; Plexicus fetches and validates it.
    • Manual Entry — Enter values individually.
  4. Proceed to Attribute Mapping and Validation.

Setup: Azure AD / Entra ID​

Azure AD Step 1: Create Enterprise Application​

  1. Log in to Azure Portal → go to Azure Active Directory → Enterprise Applications.
  2. Click New application → Create your own application.
  3. Name it (e.g., "Plexicus"), select Integrate any other application you don't find in the gallery, and click Create.

Azure AD Step 2: Configure SAML​

  1. Go to Single sign-on → select SAML.
  2. In Set up Single Sign-On with SAML section, click Edit on Basic SAML Configuration:
    • Identifier (Entity ID): https://api.plexicus.ai/
    • Reply URL (Assertion Consumer Service URL): https://api.plexicus.ai/auth/sso/{client_slug}/acs
    • Sign on URL: https://api.plexicus.ai/auth/sso/{client_slug}/login
    • Relay State (optional): leave blank
  3. Click Save.

Azure AD Step 3: User Attributes & Claims​

  1. In the SAML-based sign-on page, edit User Attributes & Claims:
  2. Ensure these claims exist:
    • email — required; source user.mail or user.userprincipalname
    • given_name — source user.givenname
    • family_name — source user.surname
    • groups (optional) — source user.groups (requires premium, or use on-premises groups)
  3. Click Save.

Azure AD Step 4: Download Certificate & Metadata​

  1. In SAML Signing Certificate section, download the Certificate (Base64).
  2. Also copy the App Federation Metadata URL (you'll use it in Plexicus).

Azure AD Step 5: Finalize in Plexicus​

  1. In Plexicus, go to Settings → Authentication → SSO.
  2. Click Setup → Azure AD (if available) or Generic SAML 2.0.
  3. Recommended: Use Enter Metadata URL and paste the App Federation Metadata URL from Azure.
  4. Alternatively, manually enter:
    • IdP Entity ID — Azure AD's Entity ID (shown in SAML config)
    • IdP SSO URL — Azure's Login URL (shown in SAML config)
    • IdP X.509 Certificate — Paste the downloaded Base64 certificate (including -----BEGIN CERTIFICATE-----)
  5. Proceed to Attribute Mapping and Validation.

Setup: Generic SAML 2.0 (Any IdP)​

For identity providers not listed above, follow this generic workflow:

Generic Step 1: Register Plexicus in Your IdP​

In your IdP's admin console, create a new SAML 2.0 application with:

  • SP Entity ID: https://api.plexicus.ai/
  • ACS URL: https://api.plexicus.ai/auth/sso/{client_slug}/acs
  • SLO URL (optional): https://api.plexicus.ai/auth/sso/{client_slug}/sls
  • NameID Format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

Generic Step 2: Retrieve IdP Metadata​

Export the IdP's SAML metadata (usually an XML file or URL) and save it.

Generic Step 3: Configure Plexicus​

  1. Go to Settings → Authentication → SSO → Configure → Generic SAML 2.0.
  2. Option A (Recommended): Paste the IdP metadata XML directly. Plexicus parses:
    • IdP Entity ID
    • IdP SSO URL
    • IdP X.509 Certificate
  3. Option B: If metadata is unavailable, manually enter:
    • IdP Entity ID — Unique identifier from your IdP
    • IdP SSO URL — Login endpoint URL
    • IdP X.509 Certificate — Public certificate in PEM format (including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----)
    • IdP SLO URL (optional) — Logout endpoint

Generic Step 4: Proceed to Validation​

Once entered, test the configuration (see Validate Configuration below).

Attribute Mapping​

By default, Plexicus maps SAML attributes to user fields as follows:

Plexicus FieldDefault SAML AttributeCustomizable
Email (required)emailYes
First Namegiven_nameYes
Last Namefamily_nameYes
Groups (for role mapping)groupsYes

To customize attribute mappings:

  1. In Settings → Authentication → SSO → Advanced Settings, click Attribute Mapping.
  2. For each field, enter the SAML attribute name your IdP sends.
    • Example: If your IdP sends email as emailAddress instead of email, update the mapping.
  3. Click Save.
note

The email attribute is required and must be a valid email address. If missing or malformed, user provisioning fails.

Group-to-Role Mapping​

Automatically assign Plexicus roles based on IdP group membership at login (requires SSO + JIT provisioning).

Prerequisites​

  • SSO is configured (SAML or OIDC)
  • Your IdP supports group assertions (most enterprise IdPs do)
  • Groups attribute is mapped in Attribute Mapping

Setup Group Mapping​

  1. Go to Settings → Authentication → SSO → Advanced Settings → Group Role Mappings.
  2. Click Add Mapping:
    • IdP Group Name — Exact group name from your IdP (e.g., security-team, developers)
    • Plexicus Role — Select a built-in or custom role (see Roles & RBAC)
  3. Repeat for each group/role pair.
  4. Click Save.

Behavior​

  • When a user logs in via SSO for the first time, Plexicus checks their IdP groups.
  • If their group matches a mapping, they are assigned the corresponding Plexicus role automatically.
  • Existing users who already have a role keep their manually assigned role; group mapping does not override.
  • If a user is in multiple groups with different role mappings, the first match (by order in the list) is applied.

Example: Okta + Plexicus Role Mapping​

Okta GroupPlexicus RolePermissions
security-teamCyberoperManage integrations, policies, analytics
developersDeveloperView findings, create remediations
adminsAdminFull organizational access

Validate Configuration​

Before activating SSO, always run a dry-run validation:

  1. Go to Settings → Authentication → SSO → Validate Configuration.
  2. Plexicus performs:
    • Certificate/key verification
    • IdP endpoint connectivity (metadata fetch, if URL provided)
    • Attribute mapping validation (against IdP metadata)
    • Signature algorithm compatibility
  3. Review the validation report:
    • ✅ Success: All checks passed. Safe to proceed to Activate SAML.
    • ⚠️ Warning: Non-critical issues (e.g., optional SLO URL missing). May proceed.
    • ❌ Error: Critical issue. Fix before activation (see Troubleshooting below).
warning

To enable SSO Enforced mode, validation must pass and be completed within the last 24 hours. Once enabled, enforce mode cannot be reversed without a new successful validation.

OIDC (OpenID Connect) Configuration​

Plexicus acts as an OIDC Relying Party (RP) / client and supports the OAuth 2.0 authorization code flow with PKCE enabled by default.

Setup: Okta OIDC​

Okta Step 1: Create OIDC Application​

  1. Log in to your Okta admin console.
  2. Go to Applications → Applications → click Create App Integration.
  3. Select OIDC - OpenID Connect as the sign-in method.
  4. Click Create.

Okta Step 2: Configure App Integration​

  1. Enter App integration name (e.g., "Plexicus OIDC").
  2. Under Grant type, ensure Authorization Code is checked (and optionally Refresh Token).
  3. In Sign-in redirect URIs, add: 
    https://api.plexicus.ai/auth/sso/{client_slug}/oidc/callback
  4. Leave Sign-out redirect URIs empty (or add https://api.plexicus.ai/).
  5. Click Save.

Okta Step 3: Retrieve Credentials & Metadata​

  1. In the app's General tab, copy:
    • Client ID
    • Client Secret (click Show)
  2. Note the Okta domain (e.g., dev-12345.okta.com).
  3. The Discovery URL is: https://dev-12345.okta.com/.well-known/openid-configuration

Okta Step 4: Finalize in Plexicus​

  1. In Plexicus, go to Settings → Authentication → SSO.
  2. Click Setup → Okta (OIDC) or Generic OIDC.
  3. Enter:
    • Discovery URL: https://<your-okta-domain>/.well-known/openid-configuration
    • Client ID: From Okta
    • Client Secret: From Okta (never share this; kept encrypted in Plexicus)
    • Scopes (optional): Default openid email profile is recommended
  4. Proceed to Attribute Mapping and Validation.

Setup: Azure AD / Entra ID OIDC​

Azure AD Step 1: Create App Registration​

  1. Log in to Azure Portal → Azure Active Directory → App registrations.
  2. Click New registration.
  3. Enter Name (e.g., "Plexicus OIDC").
  4. Under Supported account types, select your organization type.
  5. In Redirect URI, select Web and enter: 
    https://api.plexicus.ai/auth/sso/{client_slug}/oidc/callback
  6. Click Register.

Azure AD Step 2: Retrieve Credentials​

  1. In the app overview, copy:
    • Application (client) ID
    • Directory (tenant) ID
  2. Go to Certificates & secrets → Client secrets → New client secret.
  3. Copy the Value (secret itself; not the ID).

Azure AD Step 3: Configure Permissions​

  1. Go to API permissions.
  2. Ensure these permissions are granted:
    • openid, email, profile (delegated, granted for Microsoft Graph)
  3. Grant admin consent.

Azure AD Step 4: Get Discovery URL​

The Discovery URL for Azure AD is:

https://login.microsoftonline.com/{directory_tenant_id}/.well-known/openid-configuration

Replace {directory_tenant_id} with your Tenant ID from Step 2.

Azure AD Step 5: Finalize in Plexicus​

  1. In Plexicus, go to Settings → Authentication → SSO.
  2. Click Setup → Azure AD (OIDC) or Generic OIDC.
  3. Enter:
    • Discovery URL: https://login.microsoftonline.com/{tenant_id}/.well-known/openid-configuration
    • Client ID: Application (client) ID
    • Client Secret: From Certificates & secrets
    • Scopes (optional): Default openid email profile is sufficient; add groups if using group-based role assignment
  4. Proceed to Attribute Mapping and Validation.

Setup: Generic OIDC (Any Provider)​

For providers like Auth0, Cognito, Google, or other OpenID Connect-compliant providers:

Generic Step 1: Retrieve Provider Metadata​

From your OIDC provider's admin console, find the Discovery URL (also called OIDC metadata endpoint):

  • Auth0: https://<your-domain>.auth0.com/.well-known/openid-configuration
  • Cognito: https://cognito-idp.<region>.amazonaws.com/<user_pool_id>/.well-known/openid-configuration
  • Google: https://accounts.google.com/.well-known/openid-configuration

Generic Step 2: Register Plexicus Redirect URI​

In your provider's app settings, add the Redirect URI:

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

Generic Step 3: Create Credentials​

Create an application and note:

  • Client ID
  • Client Secret
  • Discovery URL
  • Supported scopes (typically openid, email, profile, optionally groups)

Generic Step 4: Configure in Plexicus​

  1. Go to Settings → Authentication → SSO → Configure → Generic OIDC.
  2. Enter:
    • Discovery URL
    • Client ID
    • Client Secret
    • Scopes (comma-separated, optional; defaults to openid,email,profile)
  3. Click Validate Configuration to verify connectivity.
  4. If validation passes, click Activate OIDC.

PKCE Security (Default Enabled)​

PKCE (Proof Key for Code Exchange) is enabled by default on all OIDC flows. It adds extra protection against authorization code interception (mitigates desktop/mobile app vulnerabilities and man-in-the-middle attacks on the callback).

You do not need to configure PKCE manually — Plexicus handles it transparently. For details, see OIDC PKCE & Security.

Attribute Mapping (OIDC Claims)​

By default, Plexicus maps OIDC claims to user fields as:

Plexicus FieldDefault OIDC ClaimCustomizable
Email (required)emailYes
First Namegiven_nameYes
Last Namefamily_nameYes
Groups (for role mapping)groupsYes

To customize claim mappings:

  1. In Settings → Authentication → SSO → Advanced Settings, click Attribute Mapping.
  2. For each field, enter the claim name your provider sends (e.g., if Auth0 uses email_verified instead of email, map accordingly).
  3. Click Save.
note

Your OIDC provider must include the mapped claims in the ID token. If a claim is missing, user provisioning will fail or the field will be empty.

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 global.required.secrets.breakGlassSecretKey="your-secret-key" \
  --set global.required.secrets.ssoRelayStateSecret="your-relay-state-secret" \
  --set global.required.secrets.ssoEncryptionKey="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 2.0 User Provisioning (Enterprise)​

info

SCIM provisioning is available on the Enterprise plan (SaaS) or all tiers (self-hosted).

SCIM 2.0 fully complies with RFC 7644. It allows automatic user and group provisioning from your IdP, eliminating manual invites and keeping Plexicus memberships synchronized with your IdP.

Generate SCIM Bearer Token​

  1. Go to Settings → Authentication → SSO → SCIM Tokens.
  2. Click Create Token.
  3. Configure:
    • Token Name (e.g., "Okta SCIM")
    • Expiration (default: 1 year; set to custom if desired)
  4. Click Generate.
  5. Copy the token immediately — it is displayed only once. Store it securely (e.g., in your IdP's secret manager).

Configure SCIM in Your IdP​

Once the token is generated, configure your IdP's SCIM connector:

SettingValue
Base URLhttps://api.plexicus.ai/scim/v2
Bearer TokenToken from step above (keep confidential)
AuthenticationBearer token auth (no username/password)

Okta SCIM Configuration​

  1. In your Okta SAML/OIDC app, go to the Provisioning tab.
  2. Click Configure API Integration.
  3. Enable API Integration and select SCIM 2.0.
  4. Enter:
    • SCIM connector base URL: https://api.plexicus.ai/scim/v2
    • Unique identifier field for users: email
  5. Click Authenticate with Plexicus or enter the bearer token manually.
  6. Click Save.
  7. Go to To App → Enable Create Users and Update User Attributes as needed.
  8. In Attribute Mappings, ensure:
    • email → Okta email (required)
    • givenName → Okta firstName
    • familyName → Okta lastName

Azure AD SCIM Configuration​

  1. In your Azure app registration, go to the Provisioning tab.
  2. Set Provisioning Status to On.
  3. Configure Admin Credentials:
    • Tenant URL: https://api.plexicus.ai/scim/v2
    • Secret Token: Paste the SCIM Bearer Token
  4. Click Test Connection to verify.
  5. Go to Mappings and ensure attribute mappings match (email, name, etc.).
  6. Click Save and Start provisioning if ready.

Generic SCIM Setup​

For other IdPs (Auth0, Cognito, custom systems), provide:

  • Base URL: https://api.plexicus.ai/scim/v2
  • Authentication: Bearer token (in Authorization: Bearer <token> header)
  • Standard SCIM 2.0 endpoints:
    • POST /scim/v2/Users — Create user
    • GET /scim/v2/Users — List users
    • PATCH /scim/v2/Users/{id} — Update user
    • DELETE /scim/v2/Users/{id} — Delete user

Supported SCIM Operations​

Plexicus SCIM 2.0 supports:

OperationEndpointBehavior
Create userPOST /UsersCreates Plexicus account with email, name, groups
List usersGET /UsersReturns all provisioned users (paginated)
Get userGET /Users/{id}Returns user details
Update userPUT /Users/{id} or PATCH /Users/{id}Updates email, name, active status, groups
Deactivate userPATCH /Users/{id} with active: falseDisables user access (doesn't delete account)
Delete userDELETE /Users/{id}Soft-delete; user account marked inactive
List groupsGET /GroupsReturns provisioned groups
Create groupPOST /GroupsCreates group in Plexicus

SCIM Token Rotation​

Tokens expire after 1 year (or custom expiration set at creation). To rotate without service interruption:

  1. Go to Settings → Authentication → SSO → SCIM Tokens.
  2. Click the token name → Rotate.
  3. A new token is generated; the old token remains valid for 7 days (grace period).
  4. Update your IdP's SCIM configuration with the new token immediately.
  5. After 7 days, the old token is revoked automatically.

To revoke a token immediately (e.g., if compromised):

  1. Go to Settings → Authentication → SSO → SCIM Tokens.
  2. Click the token → Delete.
  3. The token is invalidated immediately; update your IdP SCIM config urgently.

Certificate & Secret Rotation​

SAML Certificate Rotation (IdP Certificates)​

When your IdP rotates its signing certificate, you have two options in Plexicus:

Option 1: Stage + Promote (Recommended for Zero Downtime)​

  1. Go to Settings → Authentication → SSO → Advanced Settings.
  2. Click Stage New Certificate.
  3. Paste the new IdP X.509 certificate.
  4. Plexicus now accepts both the old and new certificates for 7 days (staging window).
  5. Once your IdP completes the rotation on their end, click Promote.
  6. The new certificate becomes primary; old certificate is archived.

Option 2: Immediate Replacement​

  1. Go to Settings → Authentication → SSO → Advanced Settings.
  2. Click Replace Certificate and paste the new certificate.
  3. Immediately switch to new certificate — old one is discarded.
  4. Use this only if your IdP has already rotated and old cert is no longer in use (risking login failures if IdP still sends old cert).

Clock Skew Tolerance​

Plexicus allows ±120 seconds of clock drift when validating SAML signatures. If you experience "signature invalid" errors despite correct certificates, check:

  • IdP server time (NTP sync)
  • Plexicus server time (NTP sync)
  • IdP certificate validity period (not yet valid or expired)

OIDC Client Secret Rotation​

Your OIDC provider may require periodic secret rotation for security compliance:

  1. In your OIDC provider's console (Okta, Azure, Auth0), generate a new client secret.
  2. Go to Settings → Authentication → SSO.
  3. Click Edit OIDC Configuration.
  4. Update Client Secret with the new value.
  5. Click Save.
  6. Test login immediately to confirm the new secret works.
  7. Once verified, you can revoke the old secret in your provider (optional grace period).
warning

The old secret remains valid until you explicitly revoke it in your provider. Plexicus uses only the most recent secret you provide.

Break-Glass Emergency Admin Recovery​

If SSO is misconfigured and admins cannot log in, use break-glass access to regain control.

SaaS Break-Glass Recovery​

  1. On the login page, click Cannot access your account?.
  2. Enter an admin email and complete the password recovery flow.
  3. Set a temporary password and log in.
  4. Go to Settings → Authentication → SSO and fix the misconfiguration.
  5. Once fixed, re-enable SSO.

If step 1 is unavailable or SSO Enforced is blocking all logins, contact Plexicus support at support@plexicus.ai with:

  • Organization email
  • Proof of admin access
  • Description of the issue

Self-Hosted Break-Glass Recovery​

Self-hosted deployments have a dedicated break-glass mechanism using Helm secrets:

helm upgrade plexicus ./helm-chart \
  --set global.required.secrets.breakGlassSecretKey="your-secret-key"

To use break-glass:

  1. Access your Kubernetes cluster where Plexicus is running.
  2. Retrieve the break-glass secret from your Helm values or Kubernetes secrets: 
    kubectl get secret plexicus-secrets -o jsonpath='{.data.sso-break-glass-secret}' | base64 -d
  3. Visit the break-glass endpoint (internal use only): 
    POST https://<your-plexicus-domain>/internal/sso/break-glass/{client_id}
    X-Break-Glass-Secret: <secret-key>
  4. This generates a temporary admin token granting access to Settings → Authentication → SSO.
  5. Fix the configuration and re-enable SSO.
warning

Never share the break-glass secret. Treat it like a root password and store it in your secrets manager.

Troubleshooting & Error Reference​

SSO Login Errors​

"SSO not available" (HTTP 404)​

Cause: The organization slug is incorrect, SSO is not configured, or SSO is not activated.

Resolution:

  1. Verify the login URL slug matches your organization (e.g., https://app.plexicus.ai/?sso-slug=your-org).
  2. In Settings → Authentication → SSO, confirm SSO is in one of these states:
    • Configured & Activated (SAML or OIDC tab shows active configuration)
    • Not in "Draft" state
  3. If slug is custom, ensure it matches exactly (case-sensitive).
  4. Check Settings → Organization → Audit Log for recent SSO configuration changes.

Note: For security, Plexicus returns the same 404 error whether the slug doesn't exist or SSO isn't configured — preventing tenant enumeration attacks.

SAML Errors​

Error: "SAML signature validation failed" or "Invalid assertion signature"

Cause: The IdP's certificate doesn't match, is expired, or the assertion isn't signed.

Resolution:

  1. Verify the IdP X.509 Certificate in Settings → Authentication → SSO → Advanced Settings:
    • Should be in PEM format (starts with -----BEGIN CERTIFICATE-----)
    • Not DER or P12 format
    • Not expired (check certificate validity: openssl x509 -in cert.pem -noout -dates)
  2. Check IdP configuration:
    • Ensure Sign Assertions is enabled (not just sign responses)
    • Verify Plexicus ACS URL matches IdP settings exactly
  3. Clock skew: Both IdP and Plexicus servers must have accurate time (NTP sync):
    • ntpdate -q <ntp-server> to check Plexicus time
    • Check IdP time in admin console
    • Plexicus allows ±120 seconds drift; increase if needed via SAML_CLOCK_SKEW_SECONDS env var

For Okta: Download the latest certificate from Applications → App → Sign On → SAML Signing Certificates.

For Azure AD: Download the latest certificate from Single sign-on → SAML Signing Certificate → Certificate (Base64).

Error: "SAML assertion already consumed" (HTTP 400)

Cause: Replay attack detected. The same assertion was used twice.

Resolution:

  • This is a security feature (deduplication). Normally shouldn't occur in production.
  • Clear the browser's cookies and try logging in again.
  • If the error persists, contact Plexicus support.

Error: "Cannot deduplicate IdP-initiated assertion: missing identifier" (HTTP 400)

Cause: IdP-initiated SAML login (from IdP portal) is missing the assertion message ID.

Resolution:

  1. Ensure your IdP is sending message ID in SAML assertions.
  2. For Okta: Verify the SAML app configuration has correct binding settings.
  3. For Azure AD: Ensure the SAML app is sending signed assertions with IDs.
  4. Test SP-initiated flow instead: Direct users to your login page (not IdP portal).

Error: "Link token not found or expired" or "Link token payload invalid" (HTTP 404 / 400)

Cause: Account linking session expired or token corrupted.

Resolution:

  • Account linking tokens are valid for 15 minutes.
  • Start the linking process again: Settings → Authentication → SSO → Link Account.
  • If error persists, clear cookies and retry.

OIDC Errors​

Error: "OIDC state mismatch" or "OIDC state not found or expired" (HTTP 400)

Cause:

  • OIDC state parameter doesn't match (CSRF defense)
  • Session expired (10-minute window)
  • Cookies were cleared between redirect and callback

Resolution:

  1. Clear all cookies for api.plexicus.ai and try again.
  2. Verify the Redirect URI in your OIDC provider exactly matches: 
    https://api.plexicus.ai/auth/sso/{client_slug}/oidc/callback
    (No trailing slash, exact case, exact slug)
  3. Check browser console (F12 → Network → look for callback request):
    • Confirm state parameter is present in callback URL
    • Confirm it's a valid UUID/base64 string
  4. If using Redis, verify Redis connectivity (shown in Plexicus logs).
  5. PKCE is always enabled for security; cannot be disabled.

Error: "Invalid ID token" or "ID token validation failed" (HTTP 401)

Cause: ID token signature is invalid, expired, or claims are malformed.

Resolution:

  1. Verify Discovery URL is correct and accessible:
    • For Okta: https://<your-domain>.okta.com/.well-known/openid-configuration
    • For Azure: https://login.microsoftonline.com/{tenant_id}/.well-known/openid-configuration
    • Test in browser to confirm it returns JSON with signing keys.
  2. Verify Client ID and Client Secret are correct (copy from IdP, no extra spaces).
  3. Check token expiration (ID tokens are typically valid for 1 hour).
  4. Verify the IdP's signing certificate is up-to-date.

User Provisioning Errors​

Error: "User not found" or "User provisioning failed" at login

Cause:

  • Email attribute is missing or malformed
  • JIT provisioning is disabled but user doesn't exist in Plexicus
  • Email attribute doesn't match Attribute Mapping settings

Resolution:

  1. Check Attribute Mapping in Settings → Authentication → SSO → Advanced Settings:
    • Verify Email is mapped to the correct claim/attribute from your IdP
    • Example: If Okta sends mail, not email, update the mapping
  2. Verify IdP is sending the email attribute in the SAML/OIDC response:
    • For Okta: In app Attribute Statements, ensure email → user.email
    • For Azure: In app User Attributes & Claims, ensure email claim is present
    • For OIDC: Verify email is in the scopes and returned in ID token
  3. Check that email value is a valid format (not null, empty, or malformed).
  4. If JIT is disabled, pre-create users in Settings → Organization → Team or enable JIT.

Error: "SCIM user creation failed" or "422 Unprocessable Entity" (SCIM)

Cause: SCIM user payload is malformed or required fields are missing.

Resolution:

  1. Verify SCIM token is valid and not expired:
    • Go to Settings → Authentication → SSO → SCIM Tokens
    • Check Expiration date
    • Rotate if near expiry
  2. Check IdP's SCIM attribute mappings:
    • email must be present and valid
    • givenName and familyName should be mapped (optional but recommended)
  3. Verify IdP SCIM request includes required SCIM schema:
    • schemas: ["urn:ietf:params:scim:schemas:core:2.0:User"]
  4. Check Plexicus logs for detailed SCIM error:
    • kubectl logs -f <plexicus-pod> | grep scim (self-hosted)

Configuration Validation Errors​

Error: "Validation failed: Certificate not found" or "Invalid metadata URL"

Cause: Metadata URL is unreachable or certificate is malformed.

Resolution:

  1. Test metadata URL in browser:
    • curl https://your-idp/.well-known/openid-configuration (OIDC)
    • Verify it returns valid JSON
  2. Ensure certificate is in valid PEM format:
    • Starts with -----BEGIN CERTIFICATE-----
    • Ends with -----END CERTIFICATE-----
    • No extra whitespace or characters
    • If copied from IdP UI, check for HTML entities like &lt; or &gt;
  3. For self-hosted, verify DNS/firewall allows outbound HTTPS to IdP.

SSO Mode Errors​

Error: "Cannot enable SSO Enforced without a successful validation"

Cause: Dry-run validation hasn't been completed or is older than 24 hours.

Resolution:

  1. Go to Settings → Authentication → SSO → Validate Configuration.
  2. Review the validation report — fix any errors or warnings.
  3. Once validation passes, the Activate as Enforced button becomes available.
  4. Enforce mode requires a validation within the last 24 hours — periodically re-validate.

Self-Hosted Specific Errors​

Error: "Break-glass secret invalid" (self-hosted)

Cause: The break-glass secret doesn't match what's configured in Helm.

Resolution:

  1. Verify the secret was set during Helm install: 
    kubectl get secret plexicus-sso -o jsonpath='{.data.break-glass-secret}' | base64 -d
  2. Ensure the X-Break-Glass-Secret header in the break-glass request matches exactly.
  3. If lost, re-run Helm install/upgrade with the secret.

Getting Help​

If none of the above resolve your issue:

  1. Check Plexicus Logs:

    • SaaS: Contact Plexicus support
    • Self-Hosted: kubectl logs -f deployment/plexicus-fastapi | grep -i sso

  2. Gather Diagnostic Info:

    • SSO protocol (SAML or OIDC)
    • Identity provider name and version
    • SSO mode (Coexist/Preferred/Enforced)
    • Last configuration change (from Audit Log)
    • Exact error message and HTTP status code

  3. Contact Plexicus Support:

    • Email: support@plexicus.ai
    • Include the diagnostic info above
    • For SAML: Attach an anonymized SAML assertion (remove user data)

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​