SSO Configuration (Settings)¶
Availability: marketed as Pro and Enterprise · Admin-scoped
See the Tier & Scope Matrix for why "marketed" and "enforced" differ here.
Organization admins can register and manage single sign-on providers directly from Settings > Identity > SSO Provider, without an administrator editing environment variables. Both OIDC and SAML 2.0 are supported, and one of each can be active at the same time.
Two ways to configure sign-in
Authentication Setup documents the AUTH_* environment variables the console container reads. The Settings-based registry described here is the self-service alternative: configuration is stored (encrypted where it is secret), versioned, and validated before it can go live. A provider activated here drives sign-in on its own - no environment variable is needed for it.
Where to find it¶
Go to Settings > Identity > SSO Provider. The table lists every provider defined for your organization with a badge showing its protocol.
Choosing a protocol¶
The provider form starts with a Protocol switch:
| Protocol | Use when |
|---|---|
| OIDC | Your IdP offers OpenID Connect (Okta, Auth0, Entra ID, Keycloak, Google Workspace) |
| SAML | Your IdP offers SAML 2.0 only, or your organisation standardises on SAML |
One OIDC provider and one SAML provider can be active at the same time. The "only one active" rule applies per protocol, not per organization.
Registering an OIDC provider¶
| Field | Description |
|---|---|
| Display name | Label shown to admins managing the config (e.g. Okta (Production)) |
| Issuer URL | Your IdP's OIDC issuer (e.g. https://your-tenant.okta.com) |
| Client ID | OAuth client ID registered with your IdP |
| Client secret | OAuth client secret. On edit, leave blank to keep the current one |
| Claim mappings | Rows mapping your IdP's claim names to VirtualSutra's fields (e.g. a groups claim for Teams auto-membership) |
Registering a SAML provider¶
The console itself is the Service Provider. No extra software is deployed and nothing is proxied through a third party.
1. Create the provider and fill in the IdP side¶
| Field | Description |
|---|---|
| Display name | Label shown on the sign-in button and in the admin table |
| IdP Metadata | Either paste the metadata URL your IdP publishes, or switch to the XML tab and drag-and-drop the metadata .xml file. One or the other - not both |
| IdP Entity ID | Your IdP's entity ID, e.g. https://idp.example.com/entity |
| SP Entity ID | The identifier you choose for this console, e.g. https://console.example.com/saml. You will paste the same value into your IdP as the Audience URI |
| IdP Signing Certificate | The IdP's signing certificate in PEM form (-----BEGIN CERTIFICATE----- … -----END CERTIFICATE-----). Assertions are verified against this |
| NameID Format | Email Address, Persistent, Transient or Unspecified - must match what your IdP sends |
| SP Signing Key | Optional. A private key used to sign outgoing authentication requests. Leave blank unless your IdP requires signed requests. On edit, leave blank to keep the current one |
| Claim Mapping | Attribute names your IdP sends for email, name and groups (see below) |
2. Copy the ACS URL into your IdP¶
Once the provider is saved, the form shows a read-only ACS URL with a copy button. That is the Assertion Consumer Service URL your IdP posts the assertion to:
Give your IdP administrator:
| IdP setting | Value |
|---|---|
| ACS / Reply URL | The ACS URL copied from the form |
| Audience URI / SP Entity ID | Exactly what you entered in SP Entity ID |
| Binding | HTTP-POST |
| NameID format | The one selected in the form |
| Signed assertions | Required - and give us the signing certificate |
3. Map attributes¶
SAML has no conventional attribute names, so the Claim Mapping rows tell VirtualSutra which attribute to read:
| VirtualSutra field | What happens |
|---|---|
email | Read from the mapped attribute. If it is absent, email or mail are tried, then the NameID only when the NameID format is Email Address. A sign-in with no usable email is rejected - it is never guessed |
name | Read from the mapped attribute; falls back to the email address |
groups | Read from the mapped attribute (default attribute name groups). Accepts a multi-value attribute or a comma-separated string. Feeds Teams membership exactly as the OIDC groups claim does |
4. Test, then activate¶
Click Test Connection. For a SAML provider this fetches and parses the IdP metadata and shows you:
- the resolved SSO endpoint and SLO endpoint,
- a certificate-validity badge -
Valid until <date>, or a warning such asExpires in 12 days.
Activate stays disabled until a test passes. If you change the metadata source, entity IDs, certificate or signing key afterwards, the provider drops back to Draft and the previous test's resolved endpoints are discarded - re-test before activating again.
Versions¶
Every save creates a new version. A version history drawer shows prior configurations and lets you diff or restore an earlier one, the same as Connections. Secrets are never shown - the drawer only tells you whether a credential was set and whether it changed between versions.
Status lifecycle¶
| Status | Meaning |
|---|---|
| Draft | Saved but not yet validated. Activation is refused |
| Verified | Passed Test Connection for this version |
| Active | Verified and turned on - one per protocol per organization |
For an OIDC provider, Test Connection validates the issuer URL and the JWKS document it points to: it confirms the discovery document's own issuer matches what you configured and that the JWKS endpoint returns at least one signing key.
Editing the issuer, client ID or client secret of an already-active OIDC provider - or the metadata, entity IDs, certificate or key of a SAML one - resets its status back to Draft.
Deactivating and deleting¶
Deactivate turns a provider off without deleting its configuration or version history. Delete removes it permanently.
Related
- Authentication Setup: the environment-variable-based alternative
- Teams: automatic team membership from the
groupsclaim/attribute