Configure your service provider

FaceSign needs two service-provider values before it can accept an AuthnRequest:

The exact, case-sensitive SP entityID.
The exact HTTPS Assertion Consumer Service (ACS) URL that accepts HTTP-POST responses.

Pilot registration is partner-assisted. FaceSign confirms through your pilot onboarding channel when the exact, case-sensitive entityID and HTTPS POST ACS URL are active. Use an isolated, non-authorizing sandbox for UAT, with synthetic identifiers wherever an identifier is needed.

Open FaceSign IdP metadata

Import the live entityID, signing certificate, SSO bindings, and transient NameID format. Live metadata is authoritative for the current signing certificate.

Configuration at a glance

Setting	Value
IdP entityID	`https://idp.facesign.dev/api/saml/metadata`
SSO endpoint	`https://idp.facesign.dev/api/saml/sso`
SSO profile	SP-initiated SAML 2.0 Web Browser SSO only. IdP-initiated SSO is unsupported.
Request bindings	HTTP-Redirect and HTTP-POST
Response binding	HTTP-POST to the registered ACS. HTTP-Artifact and artifact resolution are unsupported.
AuthnRequest signing	Send unsigned requests. Metadata declares `WantAuthnRequestsSigned="false"`.
Default NameID	Transient, session-scoped `facesign-session:<sessionId>`
Response protection	Success responses include a signed Assertion. Its NameID is integrity-protected by the Assertion signature. Assertions and NameIDs are not encrypted; `EncryptedID` is unsupported.
Single logout	SLO (`SingleLogoutService`) is unsupported.
Response trust	Current X.509 certificate published in live metadata.

FaceSign registers the entityID and HTTPS ACS exactly as supplied. If the request includes AssertionConsumerServiceURL, it must match that ACS. The metadata publishes Redirect and POST SSO endpoints, but responses always use HTTP-POST. For certificate rollover, notification timing and metadata re-import behavior must be agreed during onboarding or UAT.

Supported AuthnRequest profile

The deployed IdP accepts HTTP-Redirect and HTTP-POST requests with these rules:

Field	Deployed rule
`ID`	Required; maximum 160 UTF-8 bytes using letters, digits, `_`, `.`, `:`, or `-`. Emit a fresh unique ID. FaceSign rejects duplicate AuthnRequest IDs for the same SP for 10 minutes.
`Version`	Must be exactly `2.0`.
`IssueInstant`	More than 60 seconds in the future or more than six minutes old is rejected.
`<Issuer>`	Must exactly match the registered entityID.
`Destination`	May be omitted. If present, it must match `https://idp.facesign.dev/api/saml/sso`.
`AssertionConsumerServiceURL`	May be omitted. If present, it must match the registered ACS.
`ProtocolBinding`	May be omitted. If present, it must request HTTP-POST for the response.
`IsPassive`	`true` and `1` are rejected because verification is interactive.
`AssertionConsumerServiceIndex`	Rejected. Use the registered ACS URL or omit the URL.
Encoded `SAMLRequest`	Required exactly once; maximum 256 KiB. Redirect uses raw DEFLATE plus base64 and URL encoding. POST uses plain base64 in the form body.
Decoded or inflated AuthnRequest XML	Maximum 1 MiB.
`RelayState`	Optional and accepted at most once; returned unchanged; maximum 2,048 UTF-8 bytes. The signed Response does not give RelayState SAML integrity protection. Validate it as application state, not identity evidence.
Subject NameID	Optional correlation input. Use at most one Subject containing exactly one plain-text NameID; maximum 256 UTF-16 code units. Use an advertised email, persistent, Windows-domain, Kerberos, or unspecified format, or omit Format. Transient is not accepted for an injected Subject.
`login_hint`	Optional bilateral compatibility extension, not a SAML AuthnRequest field. It is enabled only for an exact SP registration. Send it at most once in the Redirect query or POST form body, never in a POST URL. It uses the same 256-code-unit and character rules as Subject NameID.

The replay reservation is scoped to the exact SP entityID and request ID. It is an inbound guard. The receiving SP still owns durable Response and Assertion replay rejection. Duplicate SAMLRequest, RelayState, or login_hint fields return HTTP 400 invalid_request, even when the repeated values agree. FaceSign never accepts login_hint from a POST URL or combines it with a form hint. The IdP rejects signed AuthnRequests. That includes an embedded XML signature and Redirect or POST signature parameters. If the service provider cannot disable request signing, it is incompatible with the deployed profile.

NameID and correlation input

For a registration without correlation Attribute mappings, a request with no approved correlation input returns a transient, session-scoped NameID. Omit NameIDPolicy, or request transient or unspecified. With approved sandbox correlation echo, the effective identifier can come from either an XML Subject NameID or, when separately enabled for that exact SP, login_hint. FaceSign trims surrounding whitespace, preserves case, and applies the same validation to both sources: the value must be nonempty after trimming, contain no control, invisible, or nonstandard whitespace characters, and contain no more than 256 UTF-16 code units. FaceSign does not Unicode-normalize or decode the value a second time. For Subject input, use an advertised email, persistent, Windows-domain, Kerberos, or unspecified format, or omit Format. Transient is not accepted. The returned NameID format is the Subject format, or SAML 1.1 unspecified when the Subject omits it. For hint-only input, a supported concrete NameIDPolicy format selects the returned NameID format. An omitted or unspecified policy returns canonical SAML 1.1 unspecified. If both inputs are present, their trimmed values must agree; FaceSign then preserves the Subject value and format. A disagreement returns HTTP 400 invalid_request. NameIDPolicy may be omitted, request unspecified, or exactly match a supported returned NameID format. Transient and unknown formats remain invalid for caller-supplied correlation input. SPNameQualifier on NameIDPolicy is not supported. For one exact registered sandbox SP, FaceSign can separately configure a bounded list of one or two correlation Attributes. Each mapping records an exact Attribute Name and exact NameFormat behavior: SAML’s standard uri, basic, or unspecified NameFormat URI, or an explicit agreement to omit NameFormat. Names must be unique. Under the uri NameFormat, the Attribute Name must itself be an absolute URI. On a successful assertion with an effective identifier, every configured Attribute repeats the same value as the returned NameID. The mechanism remains inactive until that exact per-SP list is configured. Once it is configured, a request with neither Subject nor an approved nonempty login_hint is rejected before a FaceSign session starts. The FaceSign-owned live loopback is already configured with the reserved .invalid synthetic Subject loopback.user@example.invalid, NameID Format urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress, and the following two Attributes in FaceSign’s durable default correlation profile, both using SAML Attribute NameFormat urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified:

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

Its ACS validates the exact NameID and both fields. That proves FaceSign’s loopback contract only; it does not enable either Attribute for an external SP.

The echoed NameID and any configured correlation Attributes contain the same unsigned, caller-supplied request input. None is FaceSign identity proof, and none can authorize access.

FaceSign enables unsigned correlation echo separately for each registered SP, and it remains off by default. The non-SAML login_hint compatibility extension requires its own exact-SP opt-in in addition to the echo policy. A nonempty Subject or hint without the applicable opt-in returns subject_echo_disabled. An empty or whitespace-only hint counts as absent. Before enabling echo, agree on a synthetic value such as test.user@example.invalid, the accepted input source, and the expected returned NameID. If the SP reads response Attributes, also agree on the exact one-or-two-item list of Attribute Name and NameFormat behaviors. Omit NameFormat only by explicit agreement. FaceSign emits no correlation Attributes until that exact per-SP list is configured. Never place a real workforce identifier in a public fixture.

Synthetic HTTP-Redirect example

This template shows where the hint belongs:

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

The following dependency-free Node.js example prints a complete Redirect URL with a fresh request ID and IssueInstant. Its SP and ACS are deliberately synthetic and unregistered. Replace them only after FaceSign confirms your exact registration.

import { randomUUID } from 'node:crypto';
import { deflateRawSync } from 'node:zlib';

const xml = `<samlp:AuthnRequest
  xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
  xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
  ID="_request-${randomUUID()}"
  Version="2.0"
  IssueInstant="${new Date().toISOString()}"
  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:1.1:nameid-format:unspecified" />
</samlp:AuthnRequest>`;

const query = new URLSearchParams({
  SAMLRequest: deflateRawSync(Buffer.from(xml)).toString('base64'),
  RelayState: 'synthetic-state',
  login_hint: 'test+uat@example.invalid',
});

console.log(`https://idp.facesign.dev/api/saml/sso?${query}`);

For HTTP-POST, place SAMLRequest, optional RelayState, and optional login_hint in the form body. Do not put login_hint on the POST URL. URL and form decoding treat + as a space, so encode a literal plus sign as %2B (for example, test%2Buat%40example.invalid). URLSearchParams performs that encoding in the example above.

RequestedAuthnContext

Omit RequestedAuthnContext, or send exactly one container with Comparison="exact" and exactly one class reference:

urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified

FaceSign returns that fixed class. Any other requested authentication context is rejected before verification starts. Confirm that the receiving SP accepts this exact value during UAT.

Unsupported features

Signed AuthnRequests.
AssertionConsumerServiceIndex.
IdP-initiated SSO.
SLO and SingleLogoutService.
HTTP-Artifact and artifact resolution.
Encrypted Assertions, encrypted NameIDs, and EncryptedID.
Interactive requests with IsPassive="true" or IsPassive="1".
SPNameQualifier on NameIDPolicy.
Any RequestedAuthnContext other than the exact fixed class described above.

Next, compare your messages with the SAML examples and validation checklist.

Open FaceSign IdP metadata

​Configuration at a glance

​Supported AuthnRequest profile

​NameID and correlation input

​Synthetic HTTP-Redirect example

​RequestedAuthnContext

​Unsupported features

Configuration at a glance

Supported AuthnRequest profile

NameID and correlation input

Synthetic HTTP-Redirect example

RequestedAuthnContext

Unsupported features