Skip to main content
Velor

Enterprise IT guides

Single sign-on (SAML 2.0)

Connect Okta, Microsoft Entra ID, Google Workspace, OneLogin or any SAML 2.0 identity provider; verify your domain; enforce SSO; recover from a lockout.

Who can do this: the workspace owner, from /dashboard/settings/sso (Single Sign-On in Settings). It needs a recent sign-in (within 15 minutes) and, if your workspace requires two-factor, a two-factor session.

1. Give your identity provider Velor's values

On the page, under the setup steps, copy these into a new SAML application at your IdP:

Page fieldGoes in your IdP as
ACS URL (Assertion Consumer Service)the ACS / Single sign-on URL
SP Entity ID / Audience URIthe Entity ID / Audience
SP Metadata URL(if your IdP can import service-provider metadata)

Map the user's email address to a SAML attribute (the default name is email). Your assertion must contain an email claim. If your IdP names the attribute differently, change Email SAML attribute name under Advanced: attribute mapping.

2. Give Velor your identity provider's metadata

Choose the provider (Okta, Microsoft Entra ID, Google Workspace, OneLogin, or Generic SAML 2.0), enter your email domain, and supply the IdP's metadata either as a Metadata URL (must be https:// and publicly reachable) or by choosing Paste XML. Then press Enable SSO (Update SSO when changing an existing setup).

Before anything is registered, Velor reads the metadata and refuses, with a specific message, when:

What is wrongWhat you are told
The URL did not answer"We could not download the metadata from that URL..." and to paste the XML instead
The URL answered with an error statusthe status code
It is not IdP metadata (for example Velor's own metadata)"That is not identity provider SAML metadata"
The metadata has no signing certificate, or it cannot be read (truncated paste)"no signing certificate" / "could not be read"
The signing certificate has expiredthe expiry date, and to download your IdP's current metadata
The certificate is not valid yetthe dates, and to check the IdP

A certificate with fewer than 30 days left is accepted with a warning that names the expiry date. The settings page then shows the certificate's status every time you open it (valid until, expiring, expired, or "could not check" if the metadata cannot be read just now).

3. Verify your domain (required for enforcement)

Under Domain ownership, enter the Domain to verify. Velor shows a TXT record: host _velor-sso.<your domain> and a value that begins velor-sso-verification=. Add it at your DNS provider and press Check record. A domain is only treated as yours for enforcement once the record is found; you cannot enforce SSO on a domain you have not proved you control.

4. Test, then enforce

Sign in from a private window: enter your work email on the sign-in page and continue with SSO. Only when that works, turn on Enforce SSO. With enforcement on, password, magic-link and Google sign-in are refused for addresses on your domain (the owner included), and password-reset links are not sent for it. You can only enable enforcement from an owner address that is itself on the domain.

First-time SSO users are created when they first sign in through your IdP, provided their address is on your verified domain. Status of this feature: first-sign-in provisioning is covered by automated tests; it has not yet been exercised against a live identity provider in production.

When sign-in fails

What the person seesCauseFix
"Your identity provider's signing certificate has expired..."The IdP rotated or lapsed its certificateIT: update the certificate in the SAML app. Owner: paste the new metadata under Single Sign-On
"We could not verify the signature on your identity provider's response..."The certificate it signs with no longer matches the metadata saved in VelorOwner: paste the IdP's current metadata
"Velor could not reach your identity provider's metadata..."The metadata URL is no longer public or is downOwner: paste the metadata XML instead; or retry
"Your SSO sign-in took too long and expired"The sign-in was left openStart again from the sign-in page
"Your identity provider did not send an email address..."The email attribute is not released, or named differentlyIT: release the email attribute; owner: check Email SAML attribute name
"Your organization's single sign-on isn't set up for this account yet..."The domain is not verified, the address is outside it, or the IdP is not the configured oneOwner: verify the domain and invite the person
"Your organization requires SSO..."Enforcement is on and the person tried another methodEnter the work email and continue with SSO

If you are locked out

If enforcement is on and the identity provider is broken (certificate expired, SAML app deleted), nobody on the domain can sign in, owner included. There is deliberately no in-product bypass: a password override for the owner would be a way around the control. The recovery is a Velor operator action: email support from the owner's address; after we verify the owner by a second channel we turn enforcement off (your SSO configuration stays), record who verified and why in your audit log, and tell you. You then paste the corrected metadata, test an SSO sign-in, and re-enable enforcement. Avoid the situation: keep a calendar reminder for the certificate expiry shown on the settings page, and test with enforcement off before turning it on.

Removing SSO

Remove SSO deletes the configuration and the registration with the sign-in provider. Users keep their accounts and can sign in by the other methods.

In the product: /dashboard/settings/sso (sign-in required).