SAML 2.0 IdP

What Is SAML?

SAML (Security Assertion Markup Language) is a protocol that lets one system vouch for a user’s identity to another system. It’s the standard that most enterprise Single Sign-On (SSO) relies on — when an employee logs into a corporate portal and gets access to a dozen internal tools without signing in again, SAML is usually doing the work behind the scenes.

The protocol has two roles:

• The Identity Provider (IdP) is the system that knows who the user is and can prove it. It authenticates the user and sends a signed statement (“assertion”) to the application.
• The Service Provider (SP) is the application that needs to know who the user is — a corporate intranet, a SaaS platform, a government portal.

IDToken Seal acts as the Identity Provider. When an enterprise application asks “who is this user?”, IDToken Seal authenticates them with the standard passwordless flow (code + face verification) and sends back a signed SAML assertion with the user’s verified identity.

When Would I Use This?

SAML integration makes sense when you’re connecting IDToken Seal to systems that already speak SAML — and many enterprise systems do:

• Corporate SSO gateways — the organization already has an SSO portal that federates access to internal tools via SAML. Adding IDToken Seal as an IdP replaces password-based login without changing any of the downstream applications.
• SaaS platforms — services like Salesforce, ServiceNow, or Workday support SAML federation. Configuring them to trust IDToken Seal means employees authenticate with their identity credential instead of a password.
• Government portals — many government systems use SAML for citizen authentication. IDToken Seal can provide document-verified identity through the existing SAML infrastructure.

If you’re building a new application and have a choice of protocol, OpenID Connect or direct JWT integration are simpler to implement. SAML is the right choice when the consuming system already requires it.

How It Works

From the user’s perspective, nothing changes — they see the same code confirmation and face verification they use for any IDToken Seal login. The difference is in what happens after authentication: instead of a JWT, the server produces a signed XML assertion and sends it to the enterprise application.

1. The user tries to access a SAML-protected application (the SP)
2. The SP redirects the user to IDToken Seal with a SAML AuthnRequest
3. IDToken Seal runs the standard authentication flow — OTP displayed, mobile push, code confirmation, face verification
4. After authentication succeeds, IDToken Seal builds a signed SAML assertion containing the user’s verified identity claims (filtered by the SP’s registered scopes)
5. The assertion is POSTed back to the SP, which grants access

What the SP Receives

The SAML assertion contains the same verified identity claims as any other IDToken Seal integration — just formatted as SAML attributes instead of JWT claims. Selective disclosure applies identically: only the scopes the user consented to share appear in the assertion.

The SP can also enforce a minimum trust level. If the user’s credential doesn’t meet the required assurance level (e.g., the SP requires Level 3 / eIDAS High, but the user enrolled at Level 2), the authentication is rejected before any identity data is shared.

Assertions are signed (RSA-SHA256 or ECDSA-SHA256) and optionally encrypted (AES-256-CBC + RSA-OAEP), depending on the SP’s requirements.

Logout

IDToken Seal supports Single Logout (SLO) — when a user logs out of one application, the logout propagates:

• SP-initiated: the application sends a LogoutRequest, IDToken Seal invalidates the session and returns a signed LogoutResponse
• IdP-initiated: IDToken Seal can trigger logout across all active SP sessions

---

Technical Reference

The sections below cover endpoints, assertion structure, attribute mapping, SP configuration, and NameID formats. This is the implementation detail for developers integrating a SAML Service Provider with IDToken Seal.

SAML Endpoints

Metadata

GET /saml/metadata

Returns the IdP’s SAML 2.0 metadata (IDPSSODescriptor) for SP configuration.

Includes:

• Entity ID
• Signing certificate
• Encryption certificate (if configured)
• SSO bindings (HTTP-Redirect and HTTP-POST)
• SLO bindings
• Supported NameID formats: persistent, transient, emailAddress

Single Sign-On (HTTP-Redirect)

GET /saml/sso

Receives an AuthnRequest via HTTP-Redirect binding.

Query Parameters

Parameter	Description
SAMLRequest	Deflated + Base64 encoded AuthnRequest
RelayState	Optional relay state to preserve through the flow

Single Sign-On (HTTP-POST)

POST /saml/sso

Receives an AuthnRequest via HTTP-POST binding.

Form Fields

Field	Description
SAMLRequest	Base64 encoded AuthnRequest
RelayState	Optional relay state

Single Logout

GET /saml/slo

Receives a LogoutRequest via HTTP-Redirect binding.

POST /saml/slo

Receives a LogoutRequest via HTTP-POST binding.

Attribute Mapping

The assertion maps IDToken Seal identity claims to SAML attribute OIDs:

IDToken Seal Claim	SAML Attribute OID	Name
tokenId	1.3.6.1.4.1.51528.3.1	IDToken Seal Token ID
givenName	2.5.4.42	Given Name
familyName	2.5.4.4	Family Name
dateOfBirth	1.3.6.1.4.1.51528.3.2	Date of Birth
nationality	1.3.6.1.4.1.51528.3.3	Nationality
trustLevel	1.3.6.1.4.1.51528.3.4	Trust Level

Custom Attribute Mapping

SPs can define custom attribute name overrides in their registration:

{
  "attribute_map": {
    "givenName": "FirstName",
    "familyName": "LastName",
    "tokenId": "UserID"
  }
}

NameID Formats

Format	Value
persistent	The user’s tokenId (stable across sessions)
transient	Random UUID (unique per session)

AuthnContext

The AuthnContextClassRef reflects the trust level:

Trust Level	AuthnContext
1-2	MobileTwoFactorUnregistered
3	MobileTwoFactorContract

Service Provider Registration

Each Service Provider is registered with the following configuration:

Field	Description
entity_id	SP’s unique SAML entity identifier
acs_url	Where to POST the SAML Response
slo_url	Single Logout endpoint (optional)
signing_cert_pem	SP’s cert for verifying AuthnRequest signatures
encrypt_assertions	Whether to encrypt assertions (AES + RSA-OAEP)
required_trust_level	Minimum trust level for this SP (1, 2, or 3)
attribute_map	Custom attribute name overrides

SLO Flow Detail

1. SP sends a LogoutRequest with the user’s NameID and optional SessionIndex
2. IDToken Seal invalidates the Redis session (if SessionIndex provided)
3. IDToken Seal returns a LogoutResponse via HTTP-Redirect binding