SSO with Okta

• Okta admin access to your org’s Okta tenant
• Vectis admin role — this is configured from Admin → SSO
• Your Vectis instance URL (e.g. https://your-workspace.mspvectis.com)

1. In Okta, go to Applications → Applications → Create App Integration. Choose OIDC — OpenID Connect and Web Application.
2. Under Sign-in redirect URIs, paste the OIDC redirect URI shown on the Vectis SSO page. It’ll look like https://your-workspace.mspvectis.com/api/auth/callback/sso-oidc.
3. Assign the application to the Okta groups who should be allowed to sign in to Vectis. If your org has a single Vectis-ops group, use that; otherwise, use an Everyone assignment and rely on Vectis’s domain allowlist for the gate.
4. After the app is created, copy the Client ID, Client Secret, and Okta domain (e.g. dev-12345.okta.com).
5. Back in Vectis, open Admin → SSO. Pick OpenID Connect (OIDC), paste the Client ID and Client Secret, and for Issuer URL enter https://dev-12345.okta.com. Leave the endpoint overrides blank — Vectis auto-discovers them.
6. Add the email domains that should use SSO to Allowed Email Domains, then hit Test Connection. A successful test shows the Okta discovery document; failures surface the specific error.
7. Toggle Enable SSO, save, and open a private window to verify the IdP login round-trip before turning on enforcement.

1. In Okta, go to Applications → Create App Integration and choose SAML 2.0.
2. For Single sign-on URL (ACS), paste the SAML ACS URL shown on the Vectis SSO page. It’ll end in /api/auth/sso/saml/callback.
3. For Audience URI (SP Entity ID), either use the same ACS URL or set a custom value and enter that value into Vectis’s SP Entity ID field.
4. Under Attribute Statements, map email to user.email and displayName to user.displayName. Okta’s default email NameID format works too.
5. After Okta shows the app’s Sign On tab, click View SAML setup instructions. Copy the Identity Provider Single Sign-On URL and X.509 Certificate.
6. In Vectis Admin → SSO, pick SAML 2.0. Paste the Okta sign-on URL into SSO Entry Point URL and the full -----BEGIN CERTIFICATE----- block into IdP Certificate. Save — Vectis re-wraps the cert into canonical PEM and encrypts it at rest.

Once Enforce SSO is on, every user on your allowed domains MUST sign in via Okta. If Okta has an outage or your config breaks, no-one can get in. The recovery path is a break-glass admin — an account that keeps Vectis password + MFA sign-in even when enforcement is on, and is scoped to ONLY the SSO settings page (no customers, tickets, billing, or other admin surface).

Add one from the Break-glass admin accounts card on the SSO settings page. A dedicated mailbox (e.g. sso-recovery@yourdomain.com) is the recommended pattern. Read more about roles & permissions →

• “domain not allowed” — the email coming back from Okta isn’t in the allowed-domains list. Check that the Okta attribute statement sends user.email, not user.login.
• “signature verification failed” (SAML) — the IdP cert pasted into Vectis doesn’t match what Okta is using to sign. Re-copy the X.509 cert from Okta’s Sign On tab.
• Clock skew — SAML assertions have tight NotBefore / NotOnOrAfter windows. If your Vectis host drifts more than 5 minutes, all SAML logins fail. NTP is the fix.