SAML federation setup

VEREID Auth is both an OpenID Connect provider and a SAML 2.0 Identity Provider. For enterprise customers federating into VEREID — i.e. "let our Okta-managed employees sign in to this VEREID-authenticated B2B app" — VEREID acts as a SAML Service Provider against the customer's IdP. That is the flow this guide covers.

Before you start

You will need:

• An Enterprise plan (SAML is gated on Enterprise).
• Admin access to your IdP (Okta, Azure AD, Google Workspace, Ping, or any SAML 2.0-compliant IdP).
• The VEREID tenant ID you are federating to (developer.vereid.com → Tenant → ID).

Step 1 — Generate the SP metadata

In developer.vereid.com → Auth Apps → New SAML SP:

• Name — your IdP name, e.g. Okta — Acme.
• EntityID — defaults to https://auth.vereid.com/v1/saml/sp/<tenant_id>.
• ACS URL — defaults to https://auth.vereid.com/v1/saml/acs/<tenant_id>.
• NameID format — email (recommended) or persistent.
• Signature algorithm — RSA-SHA256 (default), RSA-SHA512 allowed.

Click Download SP metadata → vereid-sp.xml. This is the file you upload to your IdP.

Step 2 — Configure the IdP

Okta

1. Applications → Create App Integration → SAML 2.0.
2. Name: VEREID Auth. Logo: download from https://vereid.com/brand/icon.png.
3. Single Sign-On URL: the AssertionConsumerService Location from vereid-sp.xml.
4. Audience URI (SP Entity ID): the entityID from vereid-sp.xml.
5. Name ID format: EmailAddress.
6. Attribute Statements (add):
   • email — user.email
   • firstName — user.firstName
   • lastName — user.lastName
7. Save, copy the Identity Provider metadata URL.

Azure AD (Entra)

1. Enterprise applications → New application → Non-gallery.
2. Single sign-on → SAML.
3. Upload vereid-sp.xml via Upload metadata file.
4. Edit User Attributes & Claims: ensure name, email, givenname, surname are present.
5. Download Federation Metadata XML.

Google Workspace

1. Apps → Web and mobile apps → Add custom SAML app.
2. Download IdP metadata immediately.
3. ACS URL + Entity ID from vereid-sp.xml.
4. NameID: Basic Information > Primary email.
5. Attribute mapping: email, first_name, last_name.

Ping Identity

1. Applications → Add → SAML.
2. Upload vereid-sp.xml.
3. Attribute Contract: add email, firstName, lastName.
4. Download IdP metadata.

Step 3 — Upload IdP metadata to VEREID

Back in developer.vereid.com → Auth Apps → <your SAML SP> → Upload IdP metadata, paste the XML or the metadata URL. VEREID extracts the signing certificate and the SSO URL automatically.

Step 4 — Test

curl -sS "https://auth.vereid.com/v1/saml/login/$TENANT_ID?return_url=https://yourapp.com/"

This issues a SAML AuthnRequest, redirects to your IdP, and (on successful login) lands on the ACS URL. VEREID exchanges the assertion for a session and redirects the user to return_url.

For automated regression, use SAMLTrace (browser extension) or vereid saml debug --tenant=$TENANT_ID from the CLI.

Step 5 — Map IdP groups to VEREID roles

If your IdP sends a groups (Okta), memberOf (Azure), or custom group attribute, configure mapping in developer.vereid.com → SSO → Group Mapping:

Mapping runs on every login; group memberships are not cached.

Step 6 — Single Logout (SLO)

Optional but recommended. In developer.vereid.com → SSO → SLO, enable SLO. VEREID will send a LogoutRequest to the IdP on every VEREID logout, and accept LogoutRequest from the IdP to terminate VEREID sessions. SLO is gated on Enterprise.

Step 7 — The verification claim in SAML

Even over SAML, the vereid_verification claim is available — see OIDC claims. It is exposed as a single XML attribute named urn:vereid:verification containing the base64-encoded JSON document. Your IdP-side processing should decode the attribute and parse it as JSON.

import base64, json
raw = assertion.attributes["urn:vereid:verification"]
claim = json.loads(base64.b64decode(raw))
print(claim["tier"], claim["badges"])

Common issues

• InvalidNameIDPolicy — the IdP is configured to send persistent but the SP expects email. Recreate the SP with NameID format = persistent (in step 1).
• InvalidSignature — the IdP rotated its signing cert and metadata is stale. Re-upload IdP metadata.
• AudienceRestriction mismatch — the IdP-side Audience does not match the SP entityID. Copy from vereid-sp.xml exactly.
• Group mapping not applied — the IdP did not send the groups attribute. Verify with SAMLTrace before debugging on our side.

Going further

• OIDC claims — the wire format for vereid_verification.
• Auth product overview — for the non-SAML, OIDC-only path.
• Contact enterprise@vereid.com if you need SCIM provisioning, JIT user creation, or per-IdP custom domains.