SAML 2.0 IdP

VeraID can act as a SAML 2.0 Identity Provider (IdP), enabling your enterprise applications to authenticate users via SAML assertions. This is essential for integrating with legacy applications, SaaS platforms, and enterprise tools that require SAML-based single sign-on.

IdP metadata

Your organization’s SAML IdP metadata is available at:

https://app.veraid.io/api/saml/{orgId}/metadata

This XML document contains the IdP entity ID, SSO endpoint URLs, signing certificates, and supported name ID formats. Most service providers can auto-configure themselves by importing this metadata URL.

---

Registering a Service Provider

You can register service providers (SPs) in two ways: by uploading SP metadata or by manual configuration.

Metadata upload (recommended)

1. Navigate to Settings > Identity Provider > SAML Service Providers.
2. Click Add Service Provider.
3. Choose Upload Metadata and provide either:
   • A metadata URL — VeraID will fetch and parse the SP metadata automatically.
   • A metadata XML file — Upload the SP metadata document directly.
4. Review the parsed configuration (entity ID, ACS URLs, signing certificate).
5. Configure attribute mapping (see below).
6. Click Save.

Via the API (metadata upload)

curl -X POST https://app.veraid.io/api/v1/saml/service-providers \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Salesforce",
    "metadataUrl": "https://login.salesforce.com/saml/metadata/abc123",
    "attributeMapping": {
      "email": "user.email",
      "firstName": "user.firstName",
      "lastName": "user.lastName",
      "department": "user.department",
      "groups": "user.groups"
    }
  }'

Manual configuration

If the SP does not provide a metadata document, configure it manually:

curl -X POST https://app.veraid.io/api/v1/saml/service-providers \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Internal HR Portal",
    "entityId": "urn:hr-portal:production",
    "assertionConsumerServiceUrl": "https://hr.internal.example.com/saml/acs",
    "singleLogoutServiceUrl": "https://hr.internal.example.com/saml/slo",
    "nameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
    "signingCertificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----",
    "encryptAssertions": true,
    "signAssertions": true,
    "signResponse": true,
    "attributeMapping": {
      "email": "user.email",
      "displayName": "user.fullName",
      "role": "user.roles[0]"
    }
  }'

Response:

{
  "id": "sp_abc123",
  "name": "Internal HR Portal",
  "entityId": "urn:hr-portal:production",
  "assertionConsumerServiceUrl": "https://hr.internal.example.com/saml/acs",
  "nameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
  "status": "active",
  "createdAt": "2026-03-26T10:00:00Z"
}

---

SP-initiated SSO

In the SP-initiated flow, the user starts at the service provider, which redirects them to VeraID for authentication:

1. User visits the SP application (e.g., https://hr.internal.example.com).
2. The SP generates a SAML AuthnRequest and redirects the user to VeraID’s SSO endpoint:

https://app.veraid.io/api/saml/{orgId}/sso

3. VeraID authenticates the user (password, passkey, MFA, etc.).
4. VeraID generates a signed SAML assertion and POSTs it to the SP’s Assertion Consumer Service (ACS) URL.
5. The SP validates the assertion and creates a local session.

This is the most common SAML flow and is supported by all SAML-compliant service providers.

---

IdP-initiated SSO

In the IdP-initiated flow, the user starts at VeraID and navigates to a service provider:

1. User logs into VeraID at https://app.veraid.io.
2. User clicks on an application tile in the App Launcher dashboard.
3. VeraID generates an unsolicited SAML assertion and POSTs it to the SP’s ACS URL.
4. The SP validates the assertion and creates a local session.

Enabling IdP-initiated SSO

IdP-initiated SSO must be explicitly enabled per service provider:

curl -X PATCH https://app.veraid.io/api/v1/saml/service-providers/{spId} \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "idpInitiatedSso": {
      "enabled": true,
      "relayState": "https://hr.internal.example.com/dashboard"
    }
  }'

Caution

IdP-initiated SSO does not include a SAML AuthnRequest from the SP, which means the SP cannot verify the InResponseTo field. Some SPs may reject unsolicited assertions for security reasons. Always prefer SP-initiated SSO when possible.

---

Attribute mapping

Attribute mapping defines which user attributes are included in the SAML assertion. You can map standard user fields and custom metadata.

Default attributes

These attributes are always included in the assertion:

SAML Attribute	Source	Format
NameID	user.email (configurable)	Per nameIdFormat setting
email	user.email	String
firstName	user.firstName	String
lastName	user.lastName	String

Custom attribute mapping

Map additional attributes from user profile data, group memberships, or custom metadata:

{
  "attributeMapping": {
    "department": "user.department",
    "title": "user.title",
    "employeeId": "user.metadata.employeeId",
    "groups": "user.groups",
    "roles": "user.roles",
    "costCenter": "user.metadata.costCenter",
    "manager": "user.manager.email"
  }
}

Attribute transformations

Apply transformations to attribute values before including them in the assertion:

Transformation	Example	Description
lowercase	user.email | lowercase	Convert to lowercase
uppercase	user.department | uppercase	Convert to uppercase
prefix	user.groups | prefix("app_")	Add prefix to each value
join	user.roles | join(",")	Join array values with delimiter
regex	user.email | regex("(.+)@.+", "$1")	Extract with regex

---

NameID formats

VeraID supports the following NameID formats:

Format	URI	Description
Email	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress	User’s email address (default)
Persistent	urn:oasis:names:tc:SAML:2.0:nameid-format:persistent	Opaque, stable identifier across sessions
Transient	urn:oasis:names:tc:SAML:2.0:nameid-format:transient	One-time identifier per session
Unspecified	urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified	SP determines interpretation

---

Signing and encryption

Assertion signing

VeraID signs all SAML assertions by default using RSA-SHA256. The signing certificate is included in the IdP metadata document.

Response signing

In addition to assertion signing, you can enable full response signing for SPs that require it:

{
  "signAssertions": true,
  "signResponse": true
}

Assertion encryption

For SPs that support encrypted assertions, enable encryption and provide the SP’s encryption certificate:

{
  "encryptAssertions": true,
  "encryptionAlgorithm": "aes256-cbc"
}

The SP’s encryption certificate is extracted automatically from the SP metadata. For manually configured SPs, provide it in the signingCertificate field.

---

Single Logout (SLO)

VeraID supports SAML Single Logout to terminate sessions across all connected SPs:

• IdP-initiated SLO — When a user logs out of VeraID, logout requests are sent to all active SP sessions.
• SP-initiated SLO — When a user logs out of an SP, the SP sends a logout request to VeraID, which propagates it to all other active SPs.

The SLO endpoint is:

https://app.veraid.io/api/saml/{orgId}/slo

---

Troubleshooting

Common issues

Issue	Solution
SP rejects assertion	Verify clock sync (assertions have a 5-minute validity window). Check that the SP’s entity ID and ACS URL match exactly.
Attributes missing	Review attribute mapping configuration. Ensure the source fields exist on the user profile.
Signature validation fails	Ensure the SP has the latest IdP signing certificate. Certificates rotate every 12 months with a 30-day overlap.
IdP-initiated SSO fails	Verify that idpInitiatedSso.enabled is set to true for the SP. Check the relay state URL.

SAML trace logging

Enable SAML trace logging for debugging:

curl -X PATCH https://app.veraid.io/api/v1/saml/service-providers/{spId} \
  -H "Authorization: Bearer kd_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "traceLogging": true }'

When trace logging is enabled, full SAML request and response XML is captured in the audit log. Disable it after debugging to avoid excessive log volume.

Note

SAML trace logs may contain sensitive user attributes. Ensure access to audit logs is restricted to authorized administrators.

---

Next steps

OIDC Provider

Set up VeraID as an OpenID Connect provider for modern web applications. OIDC Guide

Authentication Methods

Configure how users authenticate — passwords, passkeys, magic links, and social login. Authentication Methods

Federation

Connect external identity providers for enterprise SSO. Federation Guide