SAML 2.0 IdP

The IDToken Auth Server can act as a SAML 2.0 Identity Provider (IdP), translating passwordless IDToken authentication into SAML assertions for enterprise Service Providers.

This enables organizations to integrate IDToken with existing SAML-based applications (e.g., corporate SSO, SaaS platforms) without modifying them.

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.

SSO Flow

When a SAML SP sends an AuthnRequest to IDToken:

The SP redirects the user to /saml/sso with an AuthnRequest
IDToken parses and validates the AuthnRequest (issuer, ACS URL, signature)
The standard IDToken auth flow runs (OTP + mobile confirmation)
After authentication, IDToken builds a signed SAML Assertion
The assertion is POSTed to the SP’s Assertion Consumer Service (ACS) URL

SAML Assertion

The assertion contains IDToken identity claims mapped to SAML attribute OIDs:

Attribute Mapping

IDToken Claim	SAML Attribute OID	Name
`tokenId`	`1.3.6.1.4.1.51528.3.1`	IDToken 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 Configuration

Each registered Service Provider is defined by the following fields:

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

Single Logout (SLO)

IDToken supports SP-initiated Single Logout:

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