SSO Setup

Verify your work email domain before you wire up an IdP. SSO is bound to a verified domain — without it, Velocity has no safe way to know that jane@acme.com is actually one of your users.

1. Open Org Settings → Domains and click Add domain.
2. Copy the generated velocity-verify=... token.
3. Add it as a DNS TXT record at the apex of the domain you want to claim.
4. Click Check now. Propagation is usually under a minute; we re-check hourly for 24 hours otherwise.

Velocity acts as the SAML Service Provider. You configure Velocity as an app in your IdP, then paste three pieces of metadata back into Velocity.

1. In your IdP, create a new SAML application. Use https://api.aethernaut.ai/sso/saml/acs as the ACS URL and https://api.aethernaut.ai/sso/saml/metadata as the Entity ID.
2. Download the IdP metadata XML.
3. In Velocity, open Org Settings → SSO → SAML and either paste the full XML or fill the three fields directly.

The three fields, if you're wiring it by hand:

• entity_id — the IdP's issuer URL.
• sso_url — the HTTP-POST SSO endpoint users get redirected to.
• signing_cert — the IdP's public x509 cert in PEM form, used to verify SAML assertions.

Click Test connection. We send a real AuthnRequest and parse the response — if anything is wrong (clock skew, wrong cert, mis-mapped NameID) we tell you exactly which field is at fault.

OIDC is faster to wire than SAML because we discover endpoints automatically. You only need three values from your IdP.

1. In your IdP, register Velocity as an OIDC client. Redirect URI: https://api.aethernaut.ai/sso/oidc/callback.
2. Grab the issuer URL, the client_id, and the client_secret.
3. Paste them into Org Settings → SSO → OIDC.

On save, we fetch {issuer}/.well-known/openid-configuration and cache the authorization, token, JWKS, and userinfo endpoints. If your IdP rotates signing keys, we pick that up via the JWKS endpoint automatically — no manual cert swap.

Configuring an IdP doesn't enable it. You attach it to one or more verified domains. Once attached, any user whose email ends in that domain is auto-redirected to your IdP on the login screen — they never see the password field at all.

1. Open Org Settings → SSO → Domain bindings.
2. Select a verified domain.
3. Pick the IdP profile to bind it to. One domain, one IdP.

Once you've tested SSO end-to-end, flip sso_required in Org Settings → Security. Password login is disabled org-wide. The only exception is a single break-glass Manager account, which Velocity preserves so you can recover if your IdP itself goes down.

Okta. Set the Name ID format to EmailAddress and map user.email to NameID. Group claims are optional but useful for role mapping later.

Microsoft Entra ID. Use the “Enterprise application” template, not the legacy app registration. Entra signs assertions with SHA-256 by default; if you switched it to SHA-1 you'll see an assertion-verify failure. Don't.

Google Workspace. OIDC only — Google's SAML support for non-Google apps is awkward. Use the “Web application” OAuth client type and request the openid email profile scopes.

Auth0. Either flavor works. For SAML, make sure “Sign Response” is on (not just “Sign Assertions”) — Velocity verifies both. For OIDC, use the regular web application type, not SPA.