SAML messages - FaceSign SAML IdP

The examples use synthetic service-provider values and omit most XML Signature detail. Use live metadata and actual wire messages for integration testing.

AuthnRequest

Send an unsigned SAML 2.0 AuthnRequest. This example omits correlation input, so a registration without correlation Attribute mappings returns its default transient NameID.

<samlp:AuthnRequest
  xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
  xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
  ID="_request-001"
  Version="2.0"
  IssueInstant="2026-08-11T12:00:00Z"
  Destination="https://idp.facesign.dev/api/saml/sso"
  AssertionConsumerServiceURL="https://sp.example.invalid/saml/acs"
  ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST">
  <saml:Issuer>https://sp.example.invalid/saml/metadata</saml:Issuer>
  <samlp:NameIDPolicy
    Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient" />
</samlp:AuthnRequest>

See Configure for binding, size, timing, correlation-input, and requested-context rules.

Optional correlation input

An exact SP registration may accept login_hint as an alternative to XML Subject. This is a bilateral compatibility extension carried beside SAML, not a field inside the AuthnRequest. For HTTP-Redirect, send it once in the query beside SAMLRequest and optional RelayState:

GET https://idp.facesign.dev/api/saml/sso?SAMLRequest=<url-encoded-deflated-base64>&RelayState=synthetic-state&login_hint=test.user%40example.invalid

For HTTP-POST, send the same named fields in the form body. A hint on the POST URL is rejected. Duplicate SAMLRequest, RelayState, or login_hint fields return HTTP 400 invalid_request, even when their values agree. Encode a literal plus as %2B; otherwise URL or form decoding turns + into a space. FaceSign trims and validates Subject NameID and login_hint identically. An empty or whitespace-only hint is absent. If both inputs are present, the trimmed values must agree; FaceSign then uses the Subject and preserves its supported format. Different values return invalid_request. A mapped SP with neither input returns subject_required before verification starts. The extension is disabled by default. It requires a separate exact-SP opt-in in addition to the unsigned correlation-echo policy. A nonempty hint without both permissions returns subject_echo_disabled.

Success response

A successful response contains one Assertion. FaceSign signs the root Response and nested Assertion separately. This sample is abridged.

<samlp:Response
  xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
  xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
  xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
  ID="_response-001"
  Version="2.0"
  IssueInstant="2026-08-11T12:00:00Z"
  Destination="https://sp.example.invalid/saml/acs"
  InResponseTo="_request-001">
  <saml:Issuer>https://idp.facesign.dev/api/saml/metadata</saml:Issuer>
  <ds:Signature>...root Response signature...</ds:Signature>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
  </samlp:Status>
  <saml:Assertion ID="_assertion-001" Version="2.0" IssueInstant="2026-08-11T12:00:00Z">
    <saml:Issuer>https://idp.facesign.dev/api/saml/metadata</saml:Issuer>
    <ds:Signature>...nested Assertion signature...</ds:Signature>
    <saml:Subject>
      <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:transient">
        facesign-session:session_example_001
      </saml:NameID>
      <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <saml:SubjectConfirmationData
          Recipient="https://sp.example.invalid/saml/acs"
          InResponseTo="_request-001"
          NotOnOrAfter="2026-08-11T12:05:00Z" />
      </saml:SubjectConfirmation>
    </saml:Subject>
    <saml:Conditions NotBefore="2026-08-11T12:00:00Z" NotOnOrAfter="2026-08-11T12:05:00Z">
      <saml:AudienceRestriction>
        <saml:Audience>https://sp.example.invalid/saml/metadata</saml:Audience>
      </saml:AudienceRestriction>
    </saml:Conditions>
    <saml:AuthnStatement AuthnInstant="2026-08-11T12:00:00Z" SessionIndex="_session-001">
      <saml:AuthnContext>
        <saml:AuthnContextClassRef>
          urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified
        </saml:AuthnContextClassRef>
      </saml:AuthnContext>
    </saml:AuthnStatement>
    <saml:AttributeStatement>
      <saml:Attribute Name="facesign.verdict"><saml:AttributeValue>verified_human</saml:AttributeValue></saml:Attribute>
      <saml:Attribute Name="facesign.sessionId"><saml:AttributeValue>session_example_001</saml:AttributeValue></saml:Attribute>
      <saml:Attribute Name="facesign.coercionScore"><saml:AttributeValue>0.05</saml:AttributeValue></saml:Attribute>
      <saml:Attribute Name="facesign.deepfakeResistanceScore"><saml:AttributeValue>0.92</saml:AttributeValue></saml:Attribute>
      <saml:Attribute Name="facesign.repudiationArtifactPresent"><saml:AttributeValue>false</saml:AttributeValue></saml:Attribute>
    </saml:AttributeStatement>
  </saml:Assertion>
</samlp:Response>

Denial response

A completed non-pass or analysis failure may return a signed denial. It has no Assertion, NameID, or attributes. Only the root Response is signed.

<samlp:Response
  xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
  xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
  xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
  ID="_response-deny-001"
  Version="2.0"
  IssueInstant="2026-08-11T12:00:00Z"
  Destination="https://sp.example.invalid/saml/acs"
  InResponseTo="_request-002">
  <saml:Issuer>https://idp.facesign.dev/api/saml/metadata</saml:Issuer>
  <ds:Signature>...root Response signature...</ds:Signature>
  <samlp:Status>
    <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Responder">
      <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:AuthnFailed" />
    </samlp:StatusCode>
    <samlp:StatusMessage>Verification did not pass</samlp:StatusMessage>
  </samlp:Status>
</samlp:Response>

Treat any non-Success response as a failed sign-in.

Released attributes

The table below is the fixed success-attribute contract. Separately configured correlation Attributes are conditional and are described after the table.

Attribute	Current success value	How to use it
`facesign.verdict`	`verified_human`	The only verdict currently released in a success assertion. A non-pass has no assertion.
`facesign.sessionId`	String	Correlation identifier for support and audit.
`facesign.coercionScore`	Decimal string from 0 to 1	Bounded deployed verification output. It is not a calibrated probability or an independent authorization signal.
`facesign.deepfakeResistanceScore`	Decimal string from 0 to 1	Bounded deployed verification output with the same caveat.
`facesign.repudiationArtifactPresent`	Literal string `"false"`	Reserved. Do not branch on it. It does not claim that a signed recording was retained.

By default, success uses a transient facesign-session:<sessionId> NameID. An approved isolated sandbox may instead echo an effective identifier from AuthnRequest Subject or a separately enabled login_hint. For one exact SP, a mapping may duplicate that same value into one or two configured correlation Attributes on success. The mechanism remains inactive until the exact per-SP list of Attribute Name and NameFormat behaviors is configured; omitted NameFormat must be an explicitly agreed behavior. A mapped SP requires one approved effective identifier before verification starts. The echoed NameID and optional Attributes are caller-supplied correlation data, not FaceSign proof of workforce identity.

Correlation input	Success NameID value	Success NameID Format
XML Subject NameID	Validated, trimmed Subject value	Preserved supported Subject format, or SAML 1.1 `unspecified` when omitted
`login_hint` only	Validated, trimmed hint	Supported concrete `NameIDPolicy` format when requested; canonical `urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified` when the policy is omitted or unspecified
Equal Subject and hint	Validated Subject value	Preserved supported Subject format

Every configured correlation Attribute contains the same value as NameID. Its Attribute NameFormat remains the exact registered behavior. A denial contains none of these fields. The FaceSign-owned live loopback uses the reserved .invalid synthetic Subject loopback.user@example.invalid with NameID Format urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress and proves the following two Attributes in FaceSign’s durable default correlation profile, both with SAML Attribute NameFormat urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified:

Conditional loopback Attribute	Value
`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name`	Same synthetic value as NameID
`http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress`	Same synthetic value as NameID

This is an exact-SP loopback fixture, not a default attribute release or evidence that an external SP accepts these fields. FaceSign must separately register an external SP’s exact one-or-two-item mapping before those conditional Attributes can appear there.

Signature profile

The deployed build emits RSA-SHA256 signatures, SHA-256 digests, and exclusive XML canonicalization. On success, it signs the root Response and nested Assertion separately. On denial, it signs only the root Response; there is no Assertion. Trust the current X.509 certificate from the live metadata. Do not pin a certificate copied from an example or sample response. Incoming AuthnRequests remain unsigned.

Validation checklist

Read Status first

Continue only when the top-level status is Success. Treat any non-Success response as a failed sign-in, and reject a non-success response that contains an Assertion.

Validate the required signatures

On success, validate the root Response signature and nested Assertion signature against the certificate in FaceSign metadata. On denial, validate the root Response signature.

Correlate the request

Match InResponseTo on the Response and bearer confirmation data to an outstanding request.

Check where and when it applies

Validate Destination, Recipient, Audience, NotBefore, and both NotOnOrAfter values. Apply the receiving SP’s documented clock-skew policy.

Reject duplicates durably

Store accepted Response and Assertion IDs in a durable duplicate store and reject reuse.

Validate RelayState separately

Use RelayState only to resume application state. It is not identity or authentication evidence.

Replay and fallback responsibilities

InResponseTo provides correlation, but it does not prevent replay by itself. FaceSign reserves each accepted AuthnRequest ID for its exact SP for 10 minutes. The receiving SP still must consume each outstanding request once and durably reject duplicate Response and Assertion IDs. A signed Responder/AuthnFailed is an authenticated non-success. A pre-flow HTTP error and an unreachable or late flow may produce no usable SAML response. The integrator owns fallback for each case. None may be converted to Success or treated as a valid step-up.

​AuthnRequest

​Optional correlation input

​Success response

​Denial response

​Released attributes

​Signature profile

​Validation checklist

​Replay and fallback responsibilities