Skip to main content
Velor
← Docs

For IT admins

SAML SSO setup.

Velor supports SAML 2.0 SSO with any compliant IdP. Below is the end-to-end flow: copy Velor’s SP values into your IdP, paste the IdP metadata URL back into Velor, enforce a domain, and optionally make SSO mandatory org-wide.

Step 01

Prerequisites

  • Velor workspace owner. Only an owner can configure SSO. The settings page lives at /dashboard/settings/sso.
  • Admin access to your IdP (Okta, Microsoft Entra ID, Google Workspace, OneLogin, JumpCloud, or any SAML 2.0 IdP).
  • A corporate email domain. SSO is bound to an email domain (for example acme.com). Public domains (gmail.com, outlook.com) are not accepted — every user whose email matches the configured domain will be routed through SSO. You can only configure a domain you have an address in: the owner setting it up must be signed in as someone@that-domain, and a domain can be claimed by one workspace at a time. Before you can turn on Enforce, you prove you control the domain with a DNS TXT record (step 5). If you need a domain released or moved between workspaces, contact us.
  • An IdP metadata URL served over HTTPS. Velor fetches it server-side and validates SSL. Metadata XML upload is also supported if your IdP does not expose a public URL.

Step 02

Velor SP (Service Provider) values

Your IdP needs three values from Velor to issue assertions. They are identical for every Velor customer (Velor is the SP, your IdP is the authority). The exact strings are shown in your workspace at Settings → Single Sign-On; copy from there to avoid transcription mistakes.

Assertion Consumer Service (ACS) URL

https://<velor-auth-host>/auth/v1/sso/saml/acs

SP Entity ID / Audience URI

https://<velor-auth-host>/auth/v1/sso/saml/metadata

SP metadata XML

https://<velor-auth-host>/auth/v1/sso/saml/metadata

<velor-auth-host> is shown on your SSO settings page. The same SP endpoints serve every customer — which org a sign-in resolves to is decided by the email-domain binding you set in step 4.

NameID format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress. Required attribute: email (the user’s corporate email address). Optional: name.

Step 03

Configure your IdP

Pick your IdP below. Each path ends with you holding an IdP metadata URL that you’ll paste into Velor in step 4.

Okta

  1. Admin Console → Applications → Create App Integration → SAML 2.0.
  2. Single sign-on URL: paste Velor's ACS URL. Audience URI: paste Velor's Entity ID.
  3. Name ID format: EmailAddress. Application username: Email.
  4. Attribute Statements: add `email` mapped to user.email (and optionally `name` mapped to user.displayName).
  5. After save, open the Sign-On tab and copy the Identity Provider metadata URL.

Microsoft Entra ID (Azure AD)

  1. Microsoft Entra Admin Center → Enterprise applications → New application → Create your own application.
  2. Pick 'Integrate any other application you don't find in the gallery (Non-gallery)'.
  3. Single sign-on → SAML. Identifier (Entity ID): paste Velor's Entity ID. Reply URL (ACS): paste Velor's ACS URL.
  4. User attributes & claims: ensure `emailaddress` is mapped to user.mail (or user.userprincipalname).
  5. Step 3 of the SAML config shows the App Federation Metadata URL — copy it.

Google Workspace

  1. Admin Console → Apps → Web and mobile apps → Add app → Add custom SAML app.
  2. Download Google IdP metadata (or grab the IdP metadata URL on the next screen).
  3. ACS URL and Entity ID: paste from Velor's SSO settings page.
  4. Name ID format: EMAIL. Name ID: Basic Information > Primary email.
  5. Attribute mapping: map `email` to Primary email. Save and enable for the org units who get Velor access.

OneLogin / JumpCloud / generic SAML

  1. Create a new SAML 2.0 application.
  2. ACS / Recipient URL and Audience / Entity ID: paste from Velor's SSO settings page.
  3. NameID format: emailAddress.
  4. Add an `email` attribute mapped to the user's corporate email.
  5. Publish a metadata URL (or download the XML) — you'll paste this into Velor in step 4.

Step 04

Connect your IdP to Velor

  1. In Velor, go to Settings → Single Sign-On.
  2. Paste your IdP’s metadata URL (or upload the XML if your IdP doesn’t expose a URL). Velor fetches and parses the metadata server-side, with SSRF protection that blocks private and loopback addresses.
  3. Set the email domain that should use this IdP (for example acme.com). Multiple domains for the same org can be configured — contact us if you need that.
  4. Save. The provider is registered with Velor’s auth backend and shown as Configured — disabled.

Step 05

Test and enforce

Test with one user first, then enforce org-wide once you’re confident.

  1. Have a user from the domain visit /login on Velor and enter their corporate email. Velor detects the SSO-bound domain and redirects to your IdP for sign-in.
  2. After a successful IdP round-trip, Velor receives the SAML assertion at the ACS URL, exchanges it for a session, and lands the user on the dashboard.
  3. Once the test succeeds, flip Enable on. Users on the configured domain can now sign in via SSO from /login at any time.
  4. Before you can enforce, verify the domain: on the SSO settings page, under Domain ownership, choose Show DNS record, add the TXT record at your DNS host, then choose Check record. Without this, Enforce is refused with “Cannot enable SSO enforcement until your domain is verified”.
  5. Optional but recommended for production: Enforce. This blocks password and OAuth sign-in for anyone whose email matches the configured domain, so the IdP becomes the only path in. The same refusal covers the routes that would otherwise issue a session without touching your IdP: a magic link, a password reset, and accepting an invitation. Each tells the person to sign in through your IdP instead.

Enforcement does not apply to existing members from different domains (for example, a contractor on a personal Gmail who was previously invited). Add their domain to your IdP or remove their access from the team page.

Enforcement applies when someone signs in. A session that already existed when you switched it on is ended the next time that person loads the dashboard, not at the moment you flip the setting. To cut someone off immediately, remove them from Settings → Team.

Step 06

SCIM 2.0 provisioning

SCIM lets your IdP push user create / update / deactivate events to Velor automatically. Without SCIM, teammates are added by invitation and you must manually remove them in Velor when they leave.

  1. In Velor, go to Settings → SCIM Provisioning and generate a SCIM token. Tokens are shown once at creation — copy it immediately to your IdP.
  2. In your IdP, point the provisioning endpoint at https://app.velorplatforms.com/api/scim/v2. Use Bearer <token> for authentication. The same URL is shown on the SCIM Provisioning page itself.
  3. Supported operations: create user, update user (name, email, active flag), deactivate user. Group sync is not currently supported — role assignment stays in Velor.
  4. SCIM can only create users whose address is on the email domain configured for your SSO connection. Create requests for any other domain are refused, so set the domain before turning provisioning on.

Step 07

Troubleshooting

  • “Email domain already in use.” Another Velor workspace has registered this domain. Email support@velorplatforms.com with the domain and we’ll resolve the conflict.
  • “Metadata URL is not reachable.” The URL must be HTTPS and resolve to a public IP. Velor blocks internal hostnames and private ranges. If your IdP only exposes metadata behind a VPN, upload the XML instead.
  • “Missing email attribute.” The assertion did not include an email claim. Add the attribute mapping in your IdP (step 3) and re-test.
  • User landed on /login instead of /dashboard. The session exchange failed silently. Check your browser’s network tab for the call to /auth/callback; the response body identifies which validation step failed.
  • Enforce mode locked you out. If you enforced SSO and your IdP is misconfigured, the workspace owner can recover via a signed admin link. Email support@velorplatforms.com from the owner’s registered email.

Need help with your IdP?

We’ll happily get on a call with your IT team to walk through the setup live, or run through it asynchronously by email. Most customer SAML configurations are working within a single business day from first contact.