Single sign-on (SSO)

Connect your identity provider over SAML 2.0 or OpenID Connect so your team signs in to varsafe with its company accounts.

Single sign-on works with Okta, Microsoft Entra ID, Google Workspace, OneLogin and any other provider that supports either protocol. People on your company’s email domain then sign in through your provider, and a new colleague who signs in that way joins your team automatically, with the least access.

Setting up takes three steps: give your identity provider varsafe’s values, give varsafe your identity provider’s details, then verify your email domain. Sign-ins go to your identity provider once the domain is verified.

Where SSO lives

On the Teams page, expand your team and open the Enterprise SSO section, then click Configure SSO. The section shows (Configured) once a configuration exists. On the Developer plan it shows Upgrade to Team instead.

Each team has one SSO configuration, for one email domain.

Set up OpenID Connect

OpenID Connect is the default choice, and the simplest with most modern providers.

https://api.varsafe.dev/auth/sso/callback/<provider-id>

varsafe reads the discovery document at every sign-in, over https, from public addresses only.

Set up SAML 2.0

Entity ID (audience URI):      https://api.varsafe.dev/auth/sso/saml2/sp/<provider-id>
ACS URL (single sign-on URL):  https://api.varsafe.dev/auth/sso/saml2/sp/acs/<provider-id>

Both setups require https addresses, and refuse URLs that point at private, loopback or link-local addresses.

Verify your domain

Verification proves your team controls the email domain, and it is what switches SSO on: without it any team could claim acme.com and capture its sign-ins. It uses a DNS TXT record, in the Domain verification panel of your saved configuration.

_varsafe-challenge.acme.com   TXT   "varsafe-verify=<token>"

• A record verifies for 7 days. After that the panel says it expired: click Get a new record and replace the TXT value. Get a new record always replaces the token, so a stale or cached record cannot be replayed.
• Keep the record published. varsafe checks it about once a day to confirm your team still controls the domain.
• One team per domain. If another team has already verified the domain, verification fails with Another team has already verified acme.com rather than moving the domain.
• Changing the domain resets verification.

How your team signs in

Once SSO is enabled and the domain verified:

1. A member types their work email on the varsafe sign-in page.
2. varsafe recognizes the domain and shows Continue with SSO.
3. They sign in at your identity provider and come back to varsafe signed in.

The email your identity provider returns must be on the verified domain; a sign-in for any other address is refused. Subdomains do not match: eu.acme.com is not acme.com.

New colleagues join automatically. Someone who has no varsafe account yet gets one on their first SSO sign-in and is added to your team as a Viewer, the least-privileged role that can read secrets. Raise their role from the team’s member list when they need more. If your team has reached its member limit they can still sign in, but are not added to the team.

Existing accounts keep their sign-in. SSO does not sign in to an account that already exists with the same email address, yours included: the sign-in page says so, and the person signs in the way they already do. To try SSO, use an address on your domain that has no varsafe account yet. Invite existing people to your team as usual.

SSO is offered, not enforced. Members on your domain can still choose Use password instead, and any other sign-in method they have set up keeps working. To control access, manage team membership and roles; removing or deactivating someone in varsafe takes effect whatever your identity provider says.

Manage SSO

• Change it. Edit configuration opens the same form in place; Save changes sends only what you changed. The client secret is never shown: leave it empty to keep it, and enter it again to change the client ID or discovery URL.
• Know when your identity provider needs updating. Changing the issuer, the client ID, the discovery URL, the SAML entry point or the identity provider’s entity ID gives the configuration a new provider ID, so the panel says The values your identity provider needs changed with this edit and shows the new ones. Give them to your identity provider: until then its sign-ins fail. Replacing the SAML signing certificate keeps them.
• Turn it off or on. Disable SSO stops routing sign-ins to your identity provider and keeps the configuration; Enable SSO restores it. The badge shows Enabled or Disabled.
• Remove it. Remove asks Delete SSO config?; Confirm deletes the configuration permanently. Members who only ever signed in through SSO will need another way to sign in.

Configuring, changing, verifying and removing SSO are recorded in the team’s audit log.

Troubleshooting

SAML sign-in fails

• The ACS URL or Entity ID does not match. Copy both again from Values for your identity provider. SAML responses must go to the /saml2/sp/acs/ address; an identity provider posting anywhere else gets an error.
• Clocks disagree. varsafe accepts up to 5 minutes of clock difference with your identity provider. Beyond that, sync the provider’s clock with NTP.
• The assertion has no validity window. varsafe refuses assertions without NotBefore and NotOnOrAfter conditions.
• The signature uses SHA-1. varsafe refuses SHA-1 signatures. Switch the application to SHA-256.
• The certificate expired or was replaced. Paste the current one with Edit configuration. During a rollover, paste both.

The certificate is not in PEM format

If your provider gave you a .cer or .der file, convert it:

openssl x509 -inform DER -in cert.cer -out cert.pem

Paste the whole file, including the BEGIN and END lines.

OpenID Connect sign-in fails

• Check that the redirect URI in your provider ends with your current provider ID. It changes when you change the issuer, client ID or discovery URL, and when SSO is configured again.
• Check the Issuer URL matches the issuer in the discovery document exactly, trailing slash included.
• Open the discovery URL in a browser: it must load over https and return JSON, and every address it lists must be an https address too.
• Check the client ID and secret were copied whole.

A member is not offered SSO

• The domain must be verified; see Verify your domain.
• SSO must be Enabled, not just configured.
• The member’s email must be on exactly the configured domain.
• The team’s Team subscription must be active.

Messages you may see

If your own email address is not confirmed yet, varsafe asks you to confirm it before you configure SSO.