Federation Overview

Federation allows your organization to connect external identity providers (IdPs) to VeraID, enabling users to sign in with their existing corporate credentials. VeraID supports both inbound OIDC and inbound SAML federation, with automatic domain-based routing and just-in-time (JIT) user provisioning.

How federation works

1. A user navigates to your VeraID-protected application.
2. VeraID identifies the user’s domain (from their email address or a domain hint).
3. VeraID routes the authentication request to the appropriate external IdP based on domain-to-IdP mapping.
4. The user authenticates at the external IdP.
5. The external IdP returns an assertion (SAML) or tokens (OIDC) to VeraID.
6. VeraID validates the response, creates or updates the local user (JIT provisioning), and issues a VeraID session.

---

Inbound OIDC federation

Connect an external OIDC-compliant identity provider (Okta, Auth0, Entra ID, Google Workspace, etc.) to VeraID.

Configuration

curl -X POST https://app.veraid.io/api/v1/federation/oidc \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate Okta",
    "discoveryUrl": "https://company.okta.com/.well-known/openid-configuration",
    "clientId": "0oa1b2c3d4e5f6g7h8",
    "clientSecret": "okta_client_secret_value",
    "scopes": ["openid", "email", "profile", "groups"],
    "domains": ["company.com", "subsidiary.com"],
    "jitProvisioning": {
      "enabled": true,
      "defaultGroups": ["employees"],
      "defaultRoles": ["user"],
      "attributeMapping": {
        "firstName": "given_name",
        "lastName": "family_name",
        "email": "email",
        "department": "department",
        "groups": "groups"
      }
    }
  }'

Response:

{
  "id": "fed_oidc_abc123",
  "name": "Corporate Okta",
  "protocol": "oidc",
  "discoveryUrl": "https://company.okta.com/.well-known/openid-configuration",
  "domains": ["company.com", "subsidiary.com"],
  "status": "active",
  "callbackUrl": "https://app.veraid.io/api/v1/federation/oidc/fed_oidc_abc123/callback",
  "createdAt": "2026-03-26T10:00:00Z"
}

Setting up the external IdP

After creating the federation connection, configure the external IdP with the callback URL:

1. In the external IdP (e.g., Okta), create a new OIDC application.
2. Set the redirect URI to the callbackUrl returned by VeraID:

   https://app.veraid.io/api/v1/federation/oidc/{federationId}/callback

3. Copy the client ID and client secret from the external IdP into the VeraID federation configuration.
4. Ensure the external IdP issues the required scopes (openid, email, profile).

OIDC claim mapping

Map claims from the external IdP’s ID token to VeraID user attributes:

External Claim	VeraID Attribute	Description
sub	externalId	Unique identifier at the external IdP
email	email	User email address
given_name	firstName	First name
family_name	lastName	Last name
groups	groups	Group memberships (if available)
picture	avatarUrl	Profile photo URL

---

Inbound SAML federation

Connect an external SAML 2.0 identity provider to VeraID.

Configuration via metadata URL

curl -X POST https://app.veraid.io/api/v1/federation/saml \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate ADFS",
    "metadataUrl": "https://adfs.company.com/federationmetadata/2007-06/federationmetadata.xml",
    "domains": ["company.com"],
    "nameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
    "attributeMapping": {
      "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
      "firstName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
      "lastName": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
      "groups": "http://schemas.xmlsoap.org/claims/Group"
    },
    "jitProvisioning": {
      "enabled": true,
      "defaultGroups": ["employees"],
      "defaultRoles": ["user"]
    }
  }'

Configuration via metadata upload

If the external IdP does not expose a metadata URL, upload the metadata XML directly:

curl -X POST https://app.veraid.io/api/v1/federation/saml \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Corporate ADFS",
    "metadataXml": "<EntityDescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" entityID=\"http://adfs.company.com/adfs/services/trust\">...</EntityDescriptor>",
    "domains": ["company.com"],
    "jitProvisioning": {
      "enabled": true,
      "defaultGroups": ["employees"]
    }
  }'

Response:

{
  "id": "fed_saml_def456",
  "name": "Corporate ADFS",
  "protocol": "saml",
  "entityId": "http://adfs.company.com/adfs/services/trust",
  "domains": ["company.com"],
  "status": "active",
  "spMetadataUrl": "https://app.veraid.io/api/v1/federation/saml/fed_saml_def456/metadata",
  "acsUrl": "https://app.veraid.io/api/v1/federation/saml/fed_saml_def456/acs",
  "createdAt": "2026-03-26T10:00:00Z"
}

Setting up the external IdP

Configure the external SAML IdP with VeraID’s SP metadata:

1. Import VeraID’s SP metadata URL into the external IdP:

   https://app.veraid.io/api/v1/federation/saml/{federationId}/metadata

2. Or manually configure:
   • ACS URL: https://app.veraid.io/api/v1/federation/saml/{federationId}/acs
   • Entity ID: https://app.veraid.io/api/v1/federation/saml/{federationId}
   • NameID Format: emailAddress
3. Configure attribute release rules to include the mapped attributes.

---

Domain-to-IdP routing

Domain routing determines which external IdP handles authentication for users from a specific email domain.

How routing works

1. User enters their email address (e.g., jane@company.com).
2. VeraID extracts the domain (company.com).
3. VeraID looks up the federation connection mapped to company.com.
4. The user is redirected to the matching external IdP.

Managing domain mappings

Each federation connection specifies one or more domains in the domains field. A domain can only be mapped to one federation connection at a time.

# List all domain mappings
curl -X GET https://app.veraid.io/api/v1/federation/domains \
  -H "Authorization: Bearer kd_live_your_api_key"

Response:

{
  "data": [
    {
      "domain": "company.com",
      "federationId": "fed_oidc_abc123",
      "federationName": "Corporate Okta",
      "protocol": "oidc",
      "verified": true
    },
    {
      "domain": "subsidiary.com",
      "federationId": "fed_oidc_abc123",
      "federationName": "Corporate Okta",
      "protocol": "oidc",
      "verified": true
    },
    {
      "domain": "partner.com",
      "federationId": "fed_saml_def456",
      "federationName": "Partner ADFS",
      "protocol": "saml",
      "verified": true
    }
  ]
}

Domain verification

Before a domain can be used for federation routing, it must be verified:

1. Navigate to Settings > Organization > Domains.
2. Add the domain.
3. Verify ownership by adding a DNS TXT record:

   _veraid-verification.company.com TXT "veraid-verify=abc123def456"

4. Click Verify. VeraID checks the DNS record and marks the domain as verified.

Caution

Unverified domains cannot be used for federation routing. This prevents an attacker from claiming a domain they do not control and intercepting authentication traffic.

---

JIT provisioning

Just-in-time (JIT) provisioning automatically creates VeraID user accounts when users authenticate through a federated IdP for the first time.

Configuration options

Setting	Default	Description
enabled	false	Enable JIT provisioning for this federation connection
defaultGroups	[]	Groups to assign to JIT-provisioned users
defaultRoles	["user"]	Roles to assign to JIT-provisioned users
attributeMapping	Standard mapping	Map external IdP attributes to VeraID fields
updateOnLogin	false	Update user attributes from the IdP on every login
requireEmailVerification	true	Only provision users with verified email addresses

Attribute sync on login

When updateOnLogin is enabled, VeraID updates the local user profile with the latest attributes from the external IdP on every authentication. This keeps directory data in sync without requiring SCIM:

{
  "jitProvisioning": {
    "enabled": true,
    "updateOnLogin": true,
    "attributeMapping": {
      "firstName": "given_name",
      "lastName": "family_name",
      "department": "department",
      "groups": "groups"
    }
  }
}

Note

JIT provisioning creates users in the ACTIVE state. If you need users to go through an approval workflow before gaining access, disable JIT provisioning and use SCIM-based provisioning with manual approval in the admin UI.

---

Managing federation connections

Listing connections

curl -X GET https://app.veraid.io/api/v1/federation \
  -H "Authorization: Bearer kd_live_your_api_key"

Testing a connection

curl -X POST https://app.veraid.io/api/v1/federation/{federationId}/test \
  -H "Authorization: Bearer kd_live_your_api_key"

Disabling a connection

curl -X PATCH https://app.veraid.io/api/v1/federation/{federationId} \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "status": "disabled" }'

When a federation connection is disabled, users from its mapped domains fall back to VeraID’s built-in authentication methods (password, passkey, etc.).

Deleting a connection

curl -X DELETE https://app.veraid.io/api/v1/federation/{federationId} \
  -H "Authorization: Bearer kd_live_your_api_key"

Caution

Deleting a federation connection does not delete the JIT-provisioned users. Those users remain in the VeraID directory and can continue to authenticate using VeraID’s built-in methods.

---

Next steps

OIDC Provider

Use VeraID as an OIDC provider for your own applications. OIDC Guide

Conditional Access

Enforce policies based on federation source and authentication context. Conditional Access

User Directory

Manage users and groups provisioned via federation. Directory Guide