Federation
iya-sts can be either end of a federation relationship with a foreign
identity service, in five protocols: SAML 2.0
(Web Browser SSO),
SAML 1.1 (Browser/POST), WS-Federation 1.2 (the passive requestor profile),
OpenID Connect and
OAuth 2.0. As a service provider
it sends a person to a partner and consumes what comes back; as an identity
provider it marks a partner as a federation partner and decides which
attributes are released to it. A partner’s Shared Signals — its CAEP and
RISC events about the people it signs in — are received on its relationship,
and a partner that signs nobody in (a device manager, an HR system) is a
relationship of a sixth protocol, ssf (see A partner’s Shared Signals,
below). Relationships are per trust realm: each
realm has its own register, and a relationship is verified against the
certificate configured in that realm.
It is the one feature in this service that refuses by default — nothing federated happens until somebody configures a relationship, and what a relationship configures is a key.
This page is that bilateral trust. OpenID Federation is a different one: two entities trust a key through a chain of signed statements ending at a Trust Anchor, and that chain does not provision a person or start a session by itself. A SPIFFE federated bundle is a third register (SPIFFE).
Features
One relationship is one direction
A relationship has a role (service-provider — this service consumes — or
identity-provider — this service asserts) and a protocol (saml2,
saml11, wsfed, oidc, oauth2, or ssf for a partner that only sends
Shared Signals, service-provider side only). A partner this service both consumes from
and asserts to is two relationships, because every field differs by
direction: whose endpoints, whose certificate, an inbound attribute mapping or
an outbound release list. A field that belongs to the other direction is
refused by name rather than written and ignored.
Relationships live in the directory under ou=federations, one entry each, and
there are three doors onto that register: the console, the management API and
an ldapmodify.
The endpoints
| Path | What it is |
|---|---|
GET /federation |
what federation is here, every relationship in both directions, and the URL to give each partner |
GET /federation/login/{id} |
start: sends the browser to the partner — an <AuthnRequest>, a SAML 1.1 inter-site transfer URL, wa=wsignin1.0, or an OAuth 2.0 authorization request. Takes ?returnTo= (a path on this service) and ?application= (a hint naming what the person is signing in to, so the relationship can count that pair — checked against the live register before anything is written down) |
GET\|POST /federation/acs/{id} |
finish: the assertion consumer service, the WS-Federation wreply and the OAuth 2.0 redirect_uri, all one path. This is the URL to configure at the partner |
GET /federation/link/{handle} |
where the linking sign-in of link-at-first-sign-in returns: after the person has signed in here as the account the partner named, this records the link and finishes the federated sign-in (#109). Single-use, and it records the link only for a fresh local sign-in as that person |
GET /federation/metadata/{id} |
this service’s own SAML metadata (an SPSSODescriptor) for one SAML partner, unsigned — with its SingleLogoutService on the Redirect and POST bindings and, for SAML 2.0, its encryption key (KeyDescriptor use="encryption", #168). For a WS-Federation partner, an EntityDescriptor with a fed:ApplicationServiceType role, its passive requestor endpoint and its encryption key |
GET\|POST /federation/initiate-login/{id} |
an OpenID Connect relationship’s initiate_login_uri (OpenID Connect Core section 4): a sign-in the partner starts. Off unless fedInitiateLogin is on; iss must be the relationship’s fedPeer; login_hint is passed on; target_link_uri is followed only to a path on this service |
GET /federation/request/{id}/{handle} |
a Request Object by reference, fetched once by the partner (fedRequestObject request_uri) |
GET\|POST /federation/webfinger/{id} |
where a person types an identifier to find their OpenID Provider (fedWebFinger) |
GET /federation/fragment.js |
the one script of the assertion consumer service, for a relationship whose fedResponseMode is fragment: it posts the fragment-encoded answer back to /federation/acs/{id} |
GET /federation/jwks/{id} |
an OpenID Connect relationship’s encryption key as a JWKS (use: enc), what the partner registers to encrypt its ID Token to (#168) |
GET\|POST /federation/slo/{id} |
a partner’s sign-out, in a browser (#167): a SAML 2.0 <LogoutRequest> or <LogoutResponse>, a WS-Federation wsignoutcleanup1.0 or wsignout1.0, and the browser coming back from an OpenID Provider’s end_session_endpoint. The SAML SingleLogoutService, the WS-Federation sign-out URL and the OpenID Connect post_logout_redirect_uri to configure at the partner |
POST /federation/backchannel-logout/{id} |
the OpenID Connect backchannel_logout_uri to register at the partner |
GET /federation/frontchannel-logout/{id} |
the OpenID Connect frontchannel_logout_uri to register at the partner, with frontchannel_logout_session_required |
POST /federation/signals/{id} |
where the partner pushes its Shared Signals (RFC 8935) when the relationship’s stream is a push stream; given to the partner when the stream is created (#373) |
GET /authn/select-idp |
the chooser drawn when an application names several usable partners |
GET /federation/pages.js |
the script that draws /federation and what the login and linking paths say when they refuse (#580) |
In a trust realm every path is under /realm/{id}.
/federation, and what /federation/login/{id} and
/federation/link/{handle} say when they will not go on, run as a script in
the browser (since #580): each answers a small document, with the status it
always had, that loads /federation/pages.js, which draws the page in the
browser’s language — a refusal’s reason in English. A browser with scripts
blocked is told it needs them, and nothing else is drawn. The assertion
consumer service’s answers, and the form that sends a person to a SAML
partner, are unchanged. One path receives all five
protocols, so there is exactly one URL to configure at the partner.
This service as service provider
The five protocols, and where each differs:
- SAML 2.0 — an
<AuthnRequest>out on HTTP-Redirect (default) or HTTP-POST (fedBinding), a<Response>back. The request always asks for the response on HTTP-POST.fedSignRequestsigns the request with this service’s key; on the Redirect binding the request goes unsigned and the log says so, because that binding signs the query string, a construction this service does not build. - SAML 1.1 — there is no request message. The browser goes to the
partner’s inter-site transfer service with a
TARGET, and unsolicited responses are forced on for the relationship because there is nothing to beInResponseTo. - WS-Federation —
wa=wsignin1.0with this service’swtrealm; thewresultcarries a SAML 1.1 or SAML 2.0 assertion inside an RSTR. - OpenID Connect — the authorization code flow by default.
fedResponseType: id_tokenwithresponse_mode=form_postneeds no back channel at all, which is the way to federate with an OIDC partner from a deployment with no egress. The other response types are taken too — see OpenID Connect as the relying party. Thenonceis checked. Attributes come off the ID Token and, when configured, UserInfo. With the code flow, configurefedUserinfoUrl: a provider that follows OpenID Connect Core section 5.4 (this service among them, since #118) puts profile claims such aspreferred_usernameandemailin UserInfo, not in a code-flow ID Token. - OAuth 2.0 — the authorization code flow with no ID Token; attributes come off the access token when it is a JWT and otherwise from a configured userinfo-shaped endpoint. It is a distinct protocol rather than OIDC with a flag, and it warns on every sign-in, because an access token says a client was authorized, not that a person signed in.
PKCE is always sent in both OAuth-shaped protocols, whatever the partner advertises, and cannot be turned off.
What is checked on the way in, in every mode:
- the signature, against the certificate configured on the relationship
(
fedSigningCertificate) — never one the document carries in its own<ds:KeyInfo>— and over the element being trusted, not the first signature in the document; - an ID Token or JWT access token against the relationship’s keys
(
fedJwks, orfedJwksUri), withalg: nonerefused by name and the algorithm family taken from the key, so HS256 cannot be verified with a public key; - the issuer against
fedPeer, which is required — a relationship with no peer is missing a field and not usable, and a WS-Federation assertion carrying no issuer is refused; - the audience: every
AudienceRestrictionmust name this service (several audiences in one restriction are an OR, several restrictions an AND). A SAML 2.0 assertion with no restriction is refused, because the Web Browser SSO profile requires one. SAML 1.1 and WS-Federation, whose profiles make it optional, are accepted with a warning in development mode and refused in product mode (STS-FED-0241) unlessfederation.allowAssertionWithoutAudienceis on. An assertion a partner minted for any other of its relying parties verifies against the same key, names the same issuer and is inside its window, so this is what stops anybody holding one from signing in here; - the validity window, and that the response answers a request this service
sent (
InResponseTo, or the handle inRelayState/wctx/state), unlessfedAllowUnsolicitedis on; - that an OAuth 2.0 or OpenID Connect answer belongs to the partner the
sign-in was started for: its
statemust have been minted for the relationship whose endpoint received it, and anissparameter (RFC 9207), wherever the partner sends one, must be the partner’s issuer (STS-FED-0238); - that a SAML or WS-Federation assertion is used once. Its ID is claimed for as
long as it is valid, whether or not it answered a request, so a captured
assertion cannot be replayed (
STS-FED-0239); - how long ago the partner authenticated the person, when
federation.maxPartnerAuthAgeSis set (see When the partner authenticated the person); - the partner’s signing certificate for revocation, under
pki.revocationCheck.
When the partner authenticated the person
A federated session’s authentication time is the one the partner states: an ID
Token’s auth_time, or a SAML or WS-Federation assertion’s AuthnInstant. An
application’s max_age is judged on it, not on when the person arrived here.
A partner that states no time is taken to have authenticated the person when
its answer arrived, unless federation.maxPartnerAuthAgeS is set (below).
When an application’s max_age or prompt=login sends a federated person back
to sign in, the partner is asked for a fresh authentication: prompt=login to
an OpenID Connect or OAuth 2.0 partner, ForceAuthn="true" in a SAML 2.0
AuthnRequest, and wfresh=0 to a WS-Federation partner. A partner that ignores
the request and answers with an authentication from before it was asked is
refused (STS-FED-0242), so the person is not sent round in a loop.
federation.maxPartnerAuthAgeS sets an upper limit of its own on that age, for
every sign-in through a partner. It is 0, off, by default. While it is set, a
sign-in whose partner authenticated the person longer ago is refused
(STS-FED-0240), and so is one whose partner states no time at all.
OpenID Connect as the relying party
An inbound OpenID Connect relationship is checked against the OpenID Foundation’s relying-party certification plans (conformance). What it does, in every mode:
- The ID Token must carry
sub,iatandexp. Itsazp, when present, must be this service’s client id, and it must be present when there are several audiences. Thenoncethis service always sends must come back, from either endpoint (STS-FED-0195to0198,0039). A partner that leaves the nonce out of a code-flow ID Token is refused; until #930 that was accepted with a warning. - UserInfo must answer for the ID Token’s
sub, or the sign-in is refused (STS-FED-0202). A UserInfo endpoint that does not answer still only costs its attributes. - Every response type:
code,id_token,id_token token,code id_token,code tokenandcode id_token token. Whatever the authorization endpoint sends is checked first. Its ID Token needsc_hashnext to a code andat_hashnext to an access token, and the code is redeemed only after that. The token endpoint’s ID Token must name the sameissandsub(STS-FED-0199to0201). PKCE goes with every code. fedResponseMode: empty asks forform_postfor every type that carries an ID Token or an access token, and nothing (query) forcode.fragmentis the specification’s default for those types. The answer comes back after#, and a page with one script posts it to/federation/acs/{id}. This is a warning: the ID Token is in the browser’s history until the script replaces the entry. Use it only for a partner that cannot post.querycannot carry an ID Token and makes the relationship not ready.fedDiscoveryreadsfedSsoUrl,fedTokenUrl,fedUserinfoUrlandfedJwksUrifrom{fedPeer}/.well-known/openid-configurationat the start of every sign-in. The document’sissuermust befedPeerexactly (STS-FED-0203,0204). Off by default.fedEndSessionUrlis still written by hand.fedIdTokenSignedResponseAlgholds ID Tokens and Logout Tokens to the algorithm registered at the partner (STS-FED-0208). Check the partner on the relationship’s page (check-partneron/admin-api) fetches its discovery document and key set and reports them, writing nothing.-
fedInitiateLoginanswers/federation/initiate-login/{id}, theinitiate_login_urito register at the partner (STS-FED-0205,0206). Off by default, because any page could otherwise start a sign-in in a person’s browser. fedRefreshTokens(off by default) keeps the refresh token the partner issues at sign-in, sealed, for the session it started. EveryfedRefreshEverySeconds(empty: when the access token expires, or hourly) the scheduler jobfederation.partner-refreshrefreshes it. The new ID Token must name the sameissandsub, and UserInfo must still answer for thatsub. A refresh the partner refuses, or an answer that fails those checks, ends the session (STS-FED-0210,0211,0202). The token is dropped when the session ends. Off, the partner’s tokens are used once and discarded. Turning it on is a warning: this service then holds a long-lived credential at the partner. A partner that issues refresh tokens only foroffline_accessneeds that infedScope.- A signed or encrypted UserInfo answer is verified against the
partner’s keys (
fedUserinfoSignedResponseAlgpins its algorithm) before it is used. -
fedUserinfo(on by default) asks the partner’s UserInfo endpoint at sign-in and at each refresh. Set it toFALSEfor a partner whose UserInfo this relationship may not call: the person’s claims then come from the ID Token alone, whateverfedUserinfoUrlor the discovery document names. Some FAPI 1.0 Advanced authorization servers list a UserInfo address inmtls_endpoint_aliasesand do not answer it there. fedRegister(off by default, needsfedDiscovery) registers this service at the partner’sregistration_endpoint(RFC 7591) whenever the relationship holds no client registered with that issuer: at a sign-in, or with Register at the partner (register-partneron/admin-api). Theclient_idand secret are written to the relationship, the secret sealed. What is registered is the relationship’s own addresses, response type, client authentication and algorithms, and the one public key that signs its Request Objects.fedRequestObjectsends the authorization request as a Request Object (Core section 6, RFC 9101):requestby value, orrequest_uriby reference, served once at/federation/request/{id}/{handle}. Signed underfedRequestObjectSigningAlg(RS256by default,PS256,ES256) with the realm’s key.noneis a warning: an unsigned object, by reference over https only.fedWebFinger(off by default, needsfedDiscovery) answers/federation/webfinger/{id}, where a person types an address or URL and this service asks that host for their OpenID Provider (OpenID Connect Discovery section 2). This is a warning: it is the one federation request whose host a caller chooses. It goes through the outbound policy, and the issuer it finds must lie withinfedPeer: the same scheme, host and port, andfedPeer’s path or a path below it. Being a prefix of the text is not enough, sohttps://op.exampledoes not admithttps://op.example.evil.com. The person sees the issuer and continues only by following the link (STS-FED-0215to0217).
One thing the plans test is not done, by design:
- Session Management. This service does not poll the partner’s
check_session_iframe. Back-Channel Logout tells it the same thing.
FAPI client profiles
fedFapi holds an inbound OpenID Connect relationship to a FAPI profile the
partner enforces. The usual partner is a bank, or another financial OpenID
Provider, that refuses a code-flow client with a client secret. The person
still starts at this service. After the partner answers, this service’s own
applications see only this service.
Empty, the default, is the relying party above. The three values:
1-advanced(FAPI 1.0 Advanced).code id_token, PKCE S256, a PS256 request object by value, andprivate_key_jwt— ortls_client_authwherefedTokenAuthsays so. The endpoints may be written by hand. The access token is bound to the relationship’s TLS client certificate (RFC 8705), which this service presents at the partner’s token and UserInfo endpoints. No DPoP proof is sent.2-security(FAPI 2.0 Security Profile). NeedsfedDiscovery. The authorization request is pushed to the endpoint the discovery document names, and the browser is sent onlyclient_idandrequest_uri.code, PKCE S256,private_key_jwt, and a DPoP-bound access token. A relationship with discovery off, or a document that names no pushed-authorization endpoint, is refused at the sign-in (STS-FED-0243).2-message-signing. The same as2-security, plus a PS256 request object inside the push and a signed authorization response (JARM), checked before the code is redeemed (STS-FED-0246).
A profile also holds the partner’s answer to more than a plain relationship
does. 1-advanced requires s_hash over the state in the front-channel
ID Token (STS-FED-0248). A 2-security or 2-message-signing answer must
name its issuer, RFC 9207 (STS-FED-0249; with JARM, the iss inside the
signed response), and its token response must say token_type DPoP
(STS-FED-0251, at the sign-in and at every refresh). A JARM response must
carry exp (STS-FED-0250). A relationship with no profile is not asked
any of these.
A 2-security or 2-message-signing profile forces private_key_jwt
whatever fedTokenAuth says; 1-advanced takes tls_client_auth as well.
The DPoP
key for a 2-security or 2-message-signing sign-in is kept for that
sign-in, and sealed with the partner’s refresh token when
fedRefreshTokens is on.
The 1-advanced client certificate
A 1-advanced relationship holds a TLS client certificate issued by the
realm’s TLS Client Issuing CA (clientAuth, subject
CN=federation <id> client). It is issued when fedFapi is set to
1-advanced, and otherwise at the first sign-in that needs it. Register it
at the partner before the first sign-in: the relationship’s console page
(TLS client certificate) and GET /admin-api/federation?relationship=<id>
(clientCertificate) show the certificate and its chain, the subject DN a
partner registers as tls_client_auth_subject_dn, and the x5t#S256 a
bound access token carries. The private key is sealed and never shown.
The scheduler job federation.client-certificate-renew issues a new
certificate, with the same subject, federation.clientCertificateRenewDays
(30) days before the current one expires. A partner that registered the
subject DN needs nothing; one that pinned the certificate must be given the
new one. Where the partner’s discovery document names
mtls_endpoint_aliases, those token and UserInfo addresses are used. A
certificate that cannot be issued or opened refuses the sign-in
(STS-FED-0252) rather than calling the partner without it.
fedTokenAuth tls_client_auth authenticates with the certificate and
sends no assertion; a relationship naming it without 1-advanced is not
ready.
This service is not a CIBA client: nothing here asks a partner to
authenticate a person who is not in a browser at that partner.
POST /oauth2/bc-authorize is this service as the authorization server.
The OpenID Foundation’s FAPI client plans run in
sts_fapi_client_conformance.
The request context
The request context — the request id, nonce, PKCE verifier and where the
person was going — is kept on the server, per trust realm; the partner carries
only an opaque handle. A handle minted in one realm cannot be spent in another.
What this service is called to a partner is derived from the base URL a
browser reached it at (<base>/federation/acs/<id>, which
global.publicBaseUrl pins). fedLocalEntityId on the relationship sets it
outright: it is the Issuer of the AuthnRequest, the wtrealm, the SAML 1.1
providerId (sent when fedSsoUrl names none) and the audience an inbound
assertion must name. A partner configured with another name for this service
needs it set.
What a federated sign-in writes
A verified sign-in maps the partner’s attributes onto a directory entry under
ou=users and starts the same session every other protocol reads, so a
federated identity then satisfies an OAuth 2.0 authorization request, a
wsignin1.0, a SAML AuthnRequest or the console with none of those knowing
federation exists.
A verified assertion is trusted for one thing: that this partner’s subject authenticated there. What this service does with that is decided in this order. A rule in step 3 can still refuse the person step 1 or 2 named.
- The link, if one entry already carries
<relationship> <issuer> <subject>. That person is the candidate. The partner’s current name for them is not consulted, so a rename at the partner does not move the session onto somebody else. - Otherwise
fedSubjectPolicy, in Which people a partner may assert. The default confirms an existing local person under the confirm-lookup name, and creates<relationship>~<subject>when that name does not exist andfedAutocreateUsersallows it. The other three policies are in that table. - On top of either answer,
fedSubjectGroup,fedSubjectDomain,fedSubjectPattern, and the administrator refusal. A failure writes nothing: no attribute, no link, no counter. - A create, when the policy and
fedAutocreateUsersboth allow it.fedProvisionCapcan still refuse the newcomer.ldap.autocreateUsersdoes not decide this door. - After the session has started,
fedProvisionGroupsmay add memberships. It cannot grant a console role.
- Attributes are mapped in three layers: the relationship’s own
fedAttributeMap(<incoming name>=<LDAP attribute>), then a default table covering the ordinary OIDC claims, SAMLurn:oid:names and AD FS claim URIs, then nothing — an unrecognised name is listed as unmapped on the result page, on/admin/federationand in the log, not written under its own name. - A partner’s value overwrites an invented one and never the other way
round. In product nothing is invented, so an attribute the partner did not
send is absent. An attribute the partner stopped sending is left alone
— a partner that dropped
titlefrom its release policy has not said the person has no title.uidis never written from an assertion, because that is what the DN is built from.memberOfis never written from one either: memberships are onlyfedProvisionGroups, below, and a mapping that namesmemberOfis dropped. federationAttributeon the entry says which attributes came from the partner, besidefederationRelationship,federationIssuer,federationLinkandfederationLastSeen. In development this service invents a persona for everybody it has never met, so a federatedmailand an inventedmailwould otherwise be indistinguishable on the entry.- The session’s
amrstarts withfederated, followed by what the partner said; a SAML partner’s authentication context travels onacr— so a SAML assertion this service then issues states the partner’s class rather than calling every federated sign-in a password.
An entry link-at-first-sign-in or jit-namespaced creates looks like this.
The uid is the namespaced subject, not a prefixed local name.
any-existing is the one policy that creates under the confirm-lookup name
instead:
uid=partner-a~alice@partner.example,ou=users,dc=example,dc=com
cn: Alice Anderson <- from the partner
mail: alice@partner.example <- from the partner
federationRelationship: partner-a
federationIssuer: https://idp.partner.example/saml
federationLink: partner-a https://idp.partner.example/saml alice@partner.example
federationAttribute: cn | mail | givenName | sn
federationLastSeen: 20260824T235014Z
It works in every protocol without any of them being told. The federated
sign-in ends by calling the same session start the sign-in screen calls; there
is no federation session store, and no protocol module contains the word. That
is why /authn/login grows a button per usable partner: a person arriving at
that screen is in the middle of something — an authorization request, a
wsignin1.0, an AuthnRequest, the console — and the button hands that whole
request to the federated flow and brings them back to it. Only relationships
that would actually work are offered; a button leading to a refusal is worse
than no button, because the person has already left the screen by the time
they find out.
A partner’s photo is copied (profilePhoto.cacheFederated, on by default).
When the mapped attributes carry a pictureUrl, as the OpenID Connect picture
claim does, this service fetches the image after the sign-in has finished and
keeps it, and the person’s picture claim names that copy from then on. No
sign-in waits for it or fails because of it. The fetch follows
the outbound policy and follows no redirect, the image must
be a JPEG or PNG of at most profilePhoto.maxStoredBytes, and the same address
is not fetched again for a week. Where a copy cannot be made the claim keeps the
partner’s address (STS-FED-0219, STS-FED-0220, STS-FED-0221 in the log), and
the next sign-in tries again. In product mode a copy needs global.publicBaseUrl.
A photo the person set themselves is never replaced, and one they removed is not
copied again. With fedUpdateUserAttributes off, a returning person’s photo is
left as it is.
Which people a partner may assert
A partner signs in only the person its subject is linked to. The link is a
federationLink value on the person’s entry,
<relationship> <issuer> <subject>: the relationship, the partner’s issuer (its
fedPeer, which every response is already checked against) and the partner’s
stable identifier for the person — OpenID Connect’s sub, a SAML NameID. OpenID
Connect Core section 5.7 makes iss and sub together the only identifier a
relying party may rely on, and says email and preferred_username must not be
used as one; SAML 2.0 Core section 8.3.7 has a persistent NameID linked to a
local account rather than matched against one. So a name — however
fedUsernameSource maps it — never signs anybody in on its own, except under
any-existing, which product refuses. A transient NameID names nobody for
longer than one exchange and is refused (STS-FED-0096); configure the partner
to send a persistent (or other stable) NameID.
fedSubjectPolicy decides what happens to a subject nobody has linked yet:
fedSubjectPolicy |
An unlinked subject |
|---|---|
link-at-first-sign-in (default; empty means it) |
the confirm-lookup name already exists: that person is sent to this service’s own sign-in screen, the name fixed, and must sign in as themselves — their password, and a second factor wherever they hold one or one is required. Only then is the link recorded, the partner’s attributes written and the federated session started. Cancel links nothing (STS-FED-0099). That name does not exist: a new entry <relationship>~<subject>, linked at creation, when fedAutocreateUsers is on; otherwise refused 403 (STS-FED-0090) |
pre-linked |
refused 403 (STS-FED-0091). Nothing is created. Links are made on the console, through /admin-api or SCIM |
jit-namespaced |
always a new entry <relationship>~<subject>, linked at creation, when fedAutocreateUsers is on — never an existing person, whatever its confirm-lookup name. Off, the same 403 (STS-FED-0090) |
any-existing |
the confirm-lookup name is matched onto a local person, as this service did before #109. When that name does not exist and fedAutocreateUsers is on, the entry is created under that name, with no <relationship>~ in front. Development only: product refuses to set it (STS-FED-0095) and refuses a sign-in through a relationship that carries it (STS-FED-0094). Warning: it lets this partner sign in any local account it can name |
A linked subject signs in the person it is linked to under every policy — even where the partner’s name for them has changed.
On top of every policy, a link included:
fedSubjectGroup— the person must be in one of these groups (cn or DN); a person a sign-in would create is in none, so nobody is created.fedSubjectDomain— the address the partner sent (the mappedmail, or a username that is an address) must be in one of these domains, and so must the entry’s ownmailwhere it has one.fedSubjectPattern— a regular expression the entry’s DN must match whole (anchored for you); at most 256 characters, no backreference, no quantifier on a quantified group.- A console administrator — a member of the Admin Read or Admin Write
roster, or a holder of
REMOTE_PEPS— is refused (STS-FED-0093) unless the relationship setsfedMayAssertAdministrators. Warning: turning it on makes this partner’s signing key a key to the console for every administrator linked to it.
A refusal is the refusal page, 403, and an audit row naming the relationship,
the subject and the rule (STS-FED-0092 for the three rules). Nothing is
written onto the entry — no attribute, no link, no counter.
Linking and unlinking. On a person’s /admin/users page (Federation
links), through POST /admin-api/users/federation-link and
/federation-unlink (the person’s links are federationLinks on
GET /admin-api/users?user=, paged; a relationship’s are links on
GET /admin-api/federation?relationship=), and through SCIM’s
urn:ietf:params:scim:schemas:extension:iya-sts:2.0:User extension, whose
federationLinks is a list of { relationship, issuer, subject } (issuer
optional: the relationship’s fedPeer). A link names one person: one another
person carries is refused (STS-FED-0107). Removing a link ends every session
that partner signed the person in to, whichever door removed it — the
console, the API, SCIM or an ldapmodify — and their next sign-in through it
is treated as unlinked.
Provisioning: dynamic or pre-provisioned
On each service-provider-side relationship (an ssf relationship signs nobody
in, and these fields are not on it):
| Field | What it does |
|---|---|
fedAutocreateUsers |
the first sign-in creates the person’s entry. Written TRUE when the relationship is created in development, and FALSE in product. A relationship that stores neither reads the same way. A stored TRUE or FALSE always wins, including a TRUE that keeps creating in product. Off, the entry must already exist (SCIM, /admin/users/new, /admin-api); a sign-in for somebody with none is refused 403 has not been provisioned (STS-FED-0090). This switch is the only create switch on this door: on, a newcomer is created even when ldap.autocreateUsers is off; off, this relationship creates nobody even when that realm setting is on. Every other protocol still reads the realm setting |
fedUpdateUserAttributes |
on by default. A returning person’s attributes are overwritten from the latest assertion. Off, the partner’s values are written only when the sign-in creates the entry |
fedProvisionGroups |
off by default, and a missing value is off. On, each group name the assertion carries (groups, this realm’s groups.claimName, and the two WS-Federation group claim URIs; not the role claim) becomes a membership of the person, on every successful sign-in. A group created this way is marked with the relationship (federationRelationship). A name that already exists and is not that relationship’s is ignored, audited (STS-FED-0161, federation.group-ignored) and the sign-in continues. A group that grants something by being held is never created and never joined, whether or not it exists — the console’s admin-read and admin-write (or whatever admin.readGroup and admin.writeGroup name), the roles.remotePepGroup and roles.xacmlUserGroup groups, a group a role names as its member group, a group named as an owner, an application’s delegation subject group, another relationship’s fedSubjectGroup, and a group an XACML policy names (STS-FED-0164, the same audit action). It does not satisfy fedSubjectGroup: that rule runs before anybody is added. One value is one group name. A name that cannot be a directory name is ignored the same way |
fedProvisionCap |
how many people this relationship may create. 0 is unlimited. Empty is unlimited for an enterprise partner; a consumer or social provider’s relationship is created with federation.consumerProvisionCap (10000 by default) written here, and empty means that setting. At the cap a new subject is refused STS-FED-0090; a person already linked still signs in. ldap.maxEntries remains the realm ceiling. fedUsers counts a change of user, and is not this cap |
fedProvisionIdleMinutes |
disable a person whose only sign-in path is this relationship, once federationLastSeen is older than this many minutes. Empty or 0 is off. The scheduler job federation.provision-idle does it; the entry and the link are kept. A local userPassword, or a link through another relationship, is left alone. A passkey this sweep does not see is a local path it does not count. A partner’s account-disabled signal stays STS-FED-0156 and blocks only that partner’s sign-ins |
There are three strings, and they are not interchangeable.
| String | What it is |
|---|---|
The link, <relationship> <issuer> <subject> |
who signs in, once it exists. Found before any name |
The created name, <relationship>~<subject> |
the uid of an entry link-at-first-sign-in or jit-namespaced creates. <subject> is the partner’s stable identifier, kept whole. A urn:uuid: value is filed as sub-<uuid>, lower case. alice@a.example and alice@b.example are two entries (partner-a~alice@a.example and partner-a~alice@b.example). @, ~ and : are legal. fedUsernameSource does not choose this name, and federation.usernamePrefix is not applied to it |
| The confirm-lookup name | what link-at-first-sign-in looks up before it will create, and what any-existing matches and, when it creates, uses as the uid. fedUsernameSource names the incoming value, or the subject when that is empty. A urn:uuid: value becomes sub-<uuid> and is not resolved as a local subject. Every other value is reduced the way a username typed at the sign-in screen is: a urn:sts:user: prefix is removed, then the part before the last @ is kept, so alice@a.example and alice@b.example both look up alice. federation.usernamePrefix, empty by default, is then put in front. Empty means this lookup shares the local namespace, and a partner’s alice@partner.example confirms the local alice. Set the prefix when that confirm, or any-existing, must not meet a local person |
A name that cannot be a directory entry — empty, or carrying a character RFC
4514 reserves (, = + < > # ; " \) — is refused STS-FED-0090 rather than
written escaped. If <relationship>~<subject> already exists and does not
carry this subject’s link, the sign-in is refused STS-FED-0098: it does not
take that entry over.
fedProvisionGroups does not satisfy fedSubjectGroup, which runs before
anybody is added, so a person a sign-in would create is in no group and a
group rule refuses them. A token that names admin-read, admin-write, or
any other group this relationship did not create is ignored. The flag never
makes a newcomer a console administrator. fedMayAssertAdministrators is the
other question: a person who is already an administrator, and already
linked, may sign in through the partner. An operator, the console, SCIM or
an LDAP write may still put a federated person in a local group; that is
outside the flag. Nothing in the assertion assigns a role.
A pre-provisioned person is linked to the partner’s subject by an
administrator, the API or SCIM, or links themselves at their first federated
sign-in under link-at-first-sign-in.
Home realm discovery
appFederationRelationship on an application entry names the partners that
application’s people sign in through, and holds a list:
| What the entry names | What a person meets |
|---|---|
| nothing | the sign-in screen, with a button per usable partner under it (federation.loginButtons) |
| one usable relationship | nothing — the browser goes straight to that partner |
| several usable | /authn/select-idp: one button per partner, no password field |
several, appFederationAutoRedirect FALSE |
the sign-in screen, with those partners as its only buttons |
| only unusable values | the sign-in screen, with a banner naming what is wrong with each |
The values need not share a protocol — a SAML 2.0 partner and an OpenID
Connect one are the ordinary pair, and they arrive at the same
/federation/acs/{id}. Configuration decides the set; the person decides
within it. The generic buttons ask “which of the identity services this
service has heard of are you?”; this asks “which of your employer’s two”.
appFederationAutoRedirect means without the sign-in screen, never without a
page: with one partner that is a redirect, with several it is the chooser — no
boolean can say which identity provider somebody’s employer is.
A relationship that is disabled, half-configured, identity-provider-side or absent from this realm is printed, not dropped — a list of three with one disabled would otherwise look exactly like a correct list of two. The one case that shows nobody anything is one usable value with the auto-redirect on: it works and draws no page, so the other values’ problems go to the log at INFO.
The checks are made when the attribute is read, never when it is written:
it is a string on a directory entry that ldapmodify reaches, and the
relationship it names can be disabled by somebody who never looked at this
application. The chooser re-reads them when it is drawn, because the pending
record lives ten minutes.
This service as identity provider
Every protocol endpoint here already answers any partner, so an
identity-provider-side relationship changes nothing about whether a partner is
answered. It names the partner’s application entry (fedApplication — its
entityID, endpoints and certificate stay there) and adds two things:
- A release policy.
fedReleaselists the claims or attributes released to this partner. It can only remove, and only from what/admin/claims,/admin/userinfo-claims,/admin/saml-attributes, the groups claim and a client’s own OpenID Connect Core section 5.5 claims request would add — the last because the list is about what an audience may see, not which mechanism produced the value, so a partner releasedemailalone cannot ask forbirthdateand be given it. It can never removesub,iss,exp, a NameID or anything else a protocol puts in an artifact itself — those make the artifact verifiable, and a release list that could dropisswould produce tokens that fail to verify with nothing pointing back at the page. An empty list is no policy, not “release nothing”, so registering a partner never stops it receiving what it received the day before. - How this service authenticates for the partner (
fedAuthnMechanism):
| Value | What the person meets |
|---|---|
password |
the sign-in screen |
password-mfa |
the sign-in screen with the second factor required (amr ["pwd","hwk"], acr "mfa") |
webauthn |
a passkey alone, with no password — one factor |
spnego |
a Kerberos ticket the browser already holds, no screen (see Kerberos) |
wallet |
a credential this realm issued, presented from the person’s wallet (see OpenID4VP) |
federation |
on to another service-provider-side relationship in this realm, named by fedAuthnRelationship |
| (empty) | says nothing: falls through to the application entry and then the sign-in screen |
federation makes this realm an identity bridge: a SAML 2.0 partner can be
answered by consuming a WS-Federation token from somebody else, and nothing
bounds the depth. A request that demanded two factors (a
RequestedAuthnContext, a wauth) is never answered with a one-factor
mechanism because a relationship preferred one.
Outbound requests
Federation is where this service first made an outbound request, and it
dials only URLs an administrator wrote on a relationship: the partner’s token
endpoint (fedTokenUrl), UserInfo (fedUserinfoUrl) and JWKS (fedJwksUri),
and with fedDiscovery on, the discovery document at an address derived from
fedPeer.
The distinction is not “this feature needs it”, which is the argument every
server-side request forgery ever shipped was made with: a URL a caller
supplies (WS-Federation’s wreqptr) is refused, while these are supplied by an
administrator — a relationship is created through the gated console or
/admin-api, and anybody who can set fedTokenUrl can already do worse than
make this process issue a GET. The API keeps that honest rather than the
intention: the outbound client will not take a URL; it takes a
relationship and the name of the attribute holding one, and refuses any name
outside its list of three. The rules:
federation.outboundturns every one of them off;- https only, with the partner’s certificate verified. In development,
federation.outboundAllowHttpadmits plain http andfederation.outboundSkipTlsVerificationturns verification off, each logged on every request. In product mode neither is honoured (#171): plain http is refused (STS-FED-0112), a stored skip is ignored (STS-FED-0113) and cannot be set. A partner certified by a private CA is reached by naming that CA infederation.outboundCaFile; - no redirect is followed — a 302 from a token endpoint would hand the
client credential to whatever
Locationsaid; - the body is capped (
federation.maxResponseBytes) and the request timed out (federation.outboundTimeoutMs), because a browser is waiting; - nothing that comes back is trusted until it is verified.
SAML 2.0, SAML 1.1 and WS-Federation need no back channel at all, and an OIDC
partner can be used with no egress through fedResponseType: id_token and its
keys pasted into fedJwks.
A partner’s sign-out
The partner is the authority on the person’s sign-on. When it ends a session
— a sign-out there, an account disabled at the source — its sign-out message
is the only signal that reaches this service, so it ends the session here that
the partner started (#167). Only that session: the federated session
carrying the partner’s SAML NameID and SessionIndex, or its OpenID Connect
sid (or, with only a sub, that person’s sessions from that partner) —
never a local sign-in of the same person, and never a session another partner
started. Ending it is the protocol-independent sign-out’s own act, so this
service’s own relying parties are told as for any sign-out: Back-Channel
Logout Tokens, CAEP session-revoked, and — where the message came through a
browser — front-channel notifications drawn before the answer goes back.
| Protocol | What the partner sends | What is checked |
|---|---|---|
| SAML 2.0 | a <LogoutRequest> to /federation/slo/{id}, Redirect or POST binding |
signed (saml-profiles-2.0-os section 4.4.4.1) and verified against fedSigningCertificate and nothing else — the Redirect binding’s detached signature over the query string, or an enveloped one; issued by fedPeer; Destination this endpoint; IssueInstant within federation.requestTtlMin and NotOnOrAfter not passed; its ID accepted once ever. Answered with a signed <LogoutResponse> to fedSloUrl on fedSloBinding — Requester/UnknownPrincipal where no session matched |
| OpenID Connect | a Logout Token POSTed to /federation/backchannel-logout/{id} |
verified exactly as the partner’s ID Token is (its keys, the key’s algorithm family, aud = fedClientId, iss = fedPeer), then Back-Channel Logout 1.0 section 2.6: the events member, no nonce, sub or sid, a jti accepted once ever, iat within federation.requestTtlMin. In product mode it must be typed logout+jwt unless federation.allowUntypedLogoutToken is on. 200, or 400 invalid_request |
| OpenID Connect | /federation/frontchannel-logout/{id}?iss=…&sid=… in the partner’s iframe |
iss must be fedPeer and sid is required. Only the partner’s origin may frame the page (frame-ancestors narrowed, never dropped) and it runs no script. Best-effort by nature — the iframe is the partner’s page — so Back-Channel Logout is the reliable path |
| WS-Federation | wa=wsignoutcleanup1.0 or wsignout1.0 at /federation/slo/{id} |
unsigned by its specification, so it ends nothing by itself: it draws a page with a real button, and the session in that browser ends only when the button is pressed |
| SAML 1.1, OAuth 2.0 | — | neither defines a sign-out: SAML 1.1 has no logout protocol, and OAuth 2.0 authorizes a client rather than signing anybody in. A message for either is refused naming that |
The partner’s session bound. A SAML 2.0 AuthnStatement’s
SessionNotOnOrAfter — including a SAML 2.0 token inside WS-Federation — is
the session’s latest end here (with the oauth2.clockSkewS allowance an
assertion’s own window gets), and an assertion whose bound has already passed
starts no session. An ID Token’s exp is the token’s lifetime, not the
session’s, and bounds nothing.
A sign-out here tells the partner. /logout in the person’s own browser
offers, for each session a partner signed in, that partner’s sign-out: a signed
<LogoutRequest> naming the NameID and SessionIndex (to fedSloUrl, whose
<LogoutResponse> comes back to /federation/slo/{id} and is matched once by
InResponseTo and RelayState), RP-Initiated Logout to fedEndSessionUrl
with the partner’s ID Token as id_token_hint, client_id, this
relationship’s post_logout_redirect_uri and a state matched once on the way
back, or wa=wsignout1.0 to a WS-Federation partner. Each is a link or a form
with a real button, never an automatic redirect. /admin/logout and the
management API list the partner and say it is told only from the person’s own
sign-out, because it is their browser that goes there.
Not used as a relying party: OpenID Connect Session Management. Polling a
partner’s check_session_iframe needs a script running in this service’s page,
this service admits a script only where a page cannot work without one, and
Back-Channel Logout already tells it what that script would find out.
A partner’s encrypted assertion (#168)
Every SAML 2.0, WS-Federation and OpenID Connect relationship holds an
encryption key pair of its own, issued under the realm’s Intermediate when the
relationship is created and published where the partner reads it: the
metadata’s KeyDescriptor use="encryption" or /federation/jwks/{id}. The
relationship’s page shows the certificate, the JWKS URL and, for OpenID
Connect, the id_token_encrypted_response_alg and _enc to register.
What arrives encrypted is decrypted with that key, under exactly the algorithms the relationship publishes:
- a SAML
<EncryptedAssertion>— its own signature is checked on what was inside it, a Response’s on the ciphertext — and an<EncryptedID>or<EncryptedAttribute>inside the assertion, after that signature; - a WS-Federation token encrypted in the
RequestedSecurityToken; - an OpenID Connect ID Token or Logout Token as a JWE, which must hold a signed token (signed, then encrypted — OpenID Connect Core section 10.2);
- an
<EncryptedID>in a partner’s<LogoutRequest>.
The defaults are RSA 3072 with XML Encryption 1.1’s RSA-OAEP (SHA-256, MGF1
SHA-256) and AES-256-GCM for SAML 2.0 and WS-Federation, and P-256 with ECDH-ES
and A256GCM for OpenID Connect; EC key agreement for XML and RSA-OAEP-256 for
JOSE may be chosen instead. AES-CBC, rsa-1_5 and RSA1_5 are refused in
every mode. Every decryption failure is one code, STS-FED-0138, with one
sentence: which step failed is in the log, not on a page anybody can submit a
ciphertext to.
Rotate the encryption key on the relationship’s page or with POST
/admin-api/federation/rotate-key: the new key is published at once, and the
key it replaced still decrypts for federation.encryptionKeyGraceS and then
nothing — the scheduler job federation.encryption-key-retire removes it.
Post-quantum keys are offered for OpenID Connect only (#82):
fedEncryptionKeyType x-wing (key management HPKE-10-KE, the ML-KEM-768
and X25519 hybrid) or ml-kem-768 (ML-KEM-768). Both come from
Internet-Drafts few partners implement yet. Such a key has no X.509
certificate, so the partner reads it from /federation/jwks/{id}. XML
Encryption defines no post-quantum key transport, so a SAML 2.0 or
WS-Federation relationship is refused them.
Not implemented
- Re-checking a federated person with the partner while the session lasts —
beyond the partner’s own sign-out, its
SessionNotOnOrAfter, and an OpenID Connect relationship’sfedRefreshTokens(off by default), above. - Validating the partner’s certificate against a CA or its validity dates — it is a pinned key; only its revocation is checked.
A partner’s Shared Signals
A partner can send this service CAEP and RISC events (OpenID Shared Signals
Framework 1.0) about the people it signs in. They are configured on its
service-provider-side relationship, in the relationship page’s Shared
Signals from this partner section
(#373). By default, a verified
event from a partner people sign in through ends only the sessions that
relationship started for the person, and its account-disabled blocks
that partner’s sign-ins of the person until its account-enabled or an
administrator lifts it. The person’s local sign-in and every other partner
keep working. Its session-revoked, account-disabled, account-purged and
credential-compromise also revoke the person’s GNAP and OAuth grants and
tokens (#432) — for a
session-revoked, those issued on the sessions it started — unless
ssf.signalsRevokeGrants is off.
A partner that signs nobody in is an ssf relationship
(#374). It takes the Shared
Signals fields and nothing else, is offered on no sign-in screen, and names
its people through links an administrator writes on each person’s page. By
default its events are recorded and nothing more, except a device’s
compliance, which is set.
Shared Signals has the steps, the fields and the default reactions. Every arrival is on Monitoring → Signals from partners.
An identity-provider-side relationship shows, read only, the Shared Signals streams its application holds on this service’s own transmitter: what this service tells the partner.
Consumer and social providers
Google, Discord, GitHub and other consumer providers are relationships of
their own category, consumer rather than enterprise
(#565). Each one is an OpenID
Connect or OAuth 2.0 relationship that names its provider in fedProvider.
Everything above applies to them. They are off in a realm until
federation.consumerProviders is on. A newcomer gets an entry of their own,
and an email address is never used to match an existing person.
Consumer and social providers has the
steps, the catalogue and which of the requested platforms can be supported.
The federation map
/admin/federation/map, reached from a link on the relationship table, draws
the same register as a diagram generated on the server. It is three bands,
and the bands are a claim about direction: everything on the left arrives
wanting somebody signed in — an application registered here, or a foreign
service provider — the hexagon in the middle is the trust realm the picture is
of, and everything on the right is a party this service asks to do the signing
in. So an arrow is a request, not an assertion, which is the one thing
that looks backwards: an identity-provider-side relationship points inward
even though this service asserts outward, and that is what turns an identity
broker — one relationship authenticating through another — into a single
straight line through the middle. A hexagon is an identity service, a
rectangle a party that consumes what one issues, and a dashed outline
means foreign.
Lines are coloured by the relationship’s state, the list page’s own four: green is ready; grey is disabled, how every relationship starts; red is enabled and not configured, which will refuse the moment somebody uses it and looks finished from every other angle; amber is a broker whose onward partner is unusable — the only failure here that still produces a working sign-in, at the password screen.
The map adds three things a table of relationships has nowhere to put, each a
fact about two registers at once: how many applications are configured to use
each partner, how many people have signed in through each application and
relationship pair, and what the identity-provider side does about
authenticating somebody. One filter — role, protocol and free text — narrows
the picture and the tables under it. ?format=svg is the document alone and
?format=json the graph. With a language selected, that document is in that
language, the same drawing the page shows. It carries no script, so it does
not pan or zoom, and the page says so.
The per-application counts do not have to add up, and the page names the
difference. A relationship’s own total counts every credential that crossed
it; the rows count only the ones that named an application this service is
configured for. Three ordinary things make the gap: the partner buttons on the
sign-in screen belong to no application, /federation/login/{id} needs no
configuration to reach, and a sign-in naming an application that does not
point at that relationship is refused a row and logged. That last is a refusal
rather than a convenience: ?application= is a string anybody who can reach
the port chose, and the attribute it would grow is on the one entry whose
contents decide whether an assertion is verified.
Under paranoid PKI mode, on by default in product mode, a partner’s signing certificate is held to its validity, keyUsage and revocation at every use. An administrator registering it on the relationship names it, so it needs no chain. A partner key that carries an x5c is held to what its certificate says, and needs no chain either; a bare key is left alone. See the federation-partner row of the use cases.
Development and product mode
Under paranoid PKI mode, on by default in product mode, a back channel to a partner the certificate of whoever answers is checked before anything is sent: extendedKeyUsage serverAuth and revocation, stapled first, as the tls-server-outbound row of the use cases says. A CA in the realm’s signer truststore is trusted beside the setting that names a CA file.
The refusals above are the same in both modes, except that a SAML 1.1 or WS-Federation assertion with no audience is accepted with a warning in development — federation is not permissive in development. What the mode changes:
| Development | Product | |
|---|---|---|
| A person with no directory entry | under link-at-first-sign-in and jit-namespaced, created on first sign-in as <relationship>~<subject>, linked, unless fedAutocreateUsers is off. A new relationship is created with the switch on. any-existing creates under the confirm-lookup name instead |
created when fedAutocreateUsers is on, as <relationship>~<subject>, linked. A new relationship is created with the switch off, and a sign-in for somebody with no entry is then refused STS-FED-0090. A relationship that already stores TRUE keeps creating. any-existing cannot be set |
fedSubjectPolicy any-existing |
the name match of old | refused, when set and at the sign-in |
| The browser the answer arrives in | any | the browser that started the sign-in: a cookie set when the person is sent to the partner must come back with the answer, or it is refused (STS-FED-0237) |
| A SAML 1.1 or WS-Federation assertion with no audience restriction | accepted, with a warning | refused (STS-FED-0241) unless federation.allowAssertionWithoutAudience is on |
| An untyped Logout Token from an OpenID Connect partner | accepted when it is typed jwt or carries no type |
accepted only typed logout+jwt, unless federation.allowUntypedLogoutToken is on |
| The password at the linking sign-in | not checked (the reserved invalid is refused) |
verified, with the second factor |
Revocation of the partner’s signing certificate (pki.revocationCheck=auto) |
soft-fail: a status that cannot be fetched is accepted | hard-fail: a status that cannot be established is refused |
fedRequireSignedLogout off |
an unsigned SAML logout message from the partner is accepted — a warning: anybody who can name a partner session can then end it | refused on the relationship (STS-FED-0132), and an unsigned logout message is refused whatever it says |
A plaintext SAML 2.0 or WS-Federation assertion, or a signed-only id_token by form_post |
accepted | refused (STS-FED-0140) unless the relationship sets fedAllowUnencrypted — a warning: the person’s identifier and attributes then cross their browser in clear. An ID Token redeemed at the partner’s token endpoint crosses no browser and is not asked about |
A newcomer is asked for what the partner did not send, in product mode
(#396, #701): where fedAutocreateUsers lets a first sign-in create the
person, the entry must hold what the realm’s
attribute policy requires of every
person — by default a given name, a surname and an address. When the partner’s
mapped attributes leave one of them empty, the person is shown a short form
at /federation/profile/{handle} asking for exactly the missing values, and
the account is created from the partner’s values and theirs. This holds for
every relationship, enterprise partners as well as consumer providers. A value
the partner did send is never replaced by a typed one, and an address typed
there is recorded as unverified. The form is good for one sign-in, in the
browser it started in, and for five tries.
The sign-in is refused, STS-FED-0158 on the page and STS-AUTHN-0180 on the
session refusal, only when a required attribute is not one a person can be
given a value of, or the values given still leave the policy unmet. To spare
people the form, map the attributes on the relationship (fedAttributeMap,
for example given_name=givenName, family_name=sn, email=mail), or
provision the person first.
See What is not checked, Federation inverts all of this.
Configuration
| Setting | Environment variable | Default | Runtime? | What it does |
|---|---|---|---|---|
federation.enabled |
STS_FEDERATION_ENABLED |
true |
yes | Whether /federation answers at all; off, every route 404s and no partner button appears, with no relationship changed. |
federation.max |
STS_FEDERATION_MAX |
50 |
yes | How many relationships may exist under ou=federations; past it a new one is refused, never an old one evicted. |
federation.usernamePrefix |
STS_FEDERATION_USERNAME_PREFIX |
(empty) | yes | Put in front of the confirm-lookup name and the any-existing name, after that value is reduced to the part before the last @. Empty, the default, means alice@partner.example confirms the local alice. An entry created under link-at-first-sign-in or jit-namespaced is <relationship>~<subject> either way. |
federation.loginButtons |
STS_FEDERATION_LOGIN_BUTTONS |
true |
yes | Show a button per usable service-provider-side relationship on /authn/login. |
federation.consumerProviders |
STS_FEDERATION_CONSUMER_PROVIDERS |
false |
yes | Allow consumer and social providers in this realm. See Consumer and social providers. |
federation.connectRecentAuthMinutes |
STS_FEDERATION_CONNECT_RECENT_AUTH_MINUTES |
10 |
yes | How recently a person must have authenticated to connect a consumer or social provider on the portal’s Connected accounts page; older, and they sign in again first. |
federation.consumerProvisionCap |
STS_FEDERATION_CONSUMER_PROVISION_CAP |
10000 |
yes | How many people a consumer or social provider’s relationship may create. Written onto the relationship when it is created, and used where its fedProvisionCap is empty. An enterprise partner is not affected. |
federation.outbound |
STS_FEDERATION_OUTBOUND |
true |
yes | Whether this service may call a partner’s token, UserInfo or JWKS endpoint at all. |
federation.outboundTimeoutMs |
STS_FEDERATION_OUTBOUND_TIMEOUT_MS |
15000 |
yes | How long to wait for a partner before the sign-in fails with an error naming the timeout. |
federation.outboundAllowHttp |
STS_FEDERATION_OUTBOUND_ALLOW_HTTP |
false |
yes | Accept an http:// partner endpoint, logged on every request. Development only: product refuses plain http. |
federation.outboundSkipTlsVerification |
STS_FEDERATION_OUTBOUND_SKIP_TLS_VERIFICATION |
false |
yes | Development only — a warning. Accept a partner certificate nothing here trusts, logged on every request. Ignored in product, and refused on write there. |
federation.outboundCaFile |
STS_FEDERATION_OUTBOUND_CA_FILE |
(empty) | yes | A PEM file of CA certificates a partner may chain to, beside node’s own store. How product reaches a privately certified partner. |
federation.requestTtlMin |
STS_FEDERATION_REQUEST_TTL_MIN |
10 |
yes | How long an outbound sign-in’s context is remembered; a later response is refused as unsolicited. |
federation.allowUntypedLogoutToken |
STS_FEDERATION_ALLOW_UNTYPED_LOGOUT_TOKEN |
false |
yes | Product mode accepts a partner’s Logout Token only if it is typed logout+jwt. On, one typed jwt or carrying no type is accepted too, for a partner that does not send the type. |
federation.maxContexts |
STS_FEDERATION_MAX_CONTEXTS |
500 |
yes | How many in-flight sign-in contexts are held per trust realm; past it the oldest is dropped. |
federation.maxApplicationLength |
STS_FEDERATION_MAX_APPLICATION_LENGTH |
256 |
yes | The longest ?application= a federated login carries across the round trip. |
federation.maxApplicationUse |
STS_FEDERATION_MAX_APPLICATION_USE |
64 |
yes | How many per-application usage rows one relationship keeps; the busiest are kept. |
federation.releaseIndexTtlMs |
STS_FEDERATION_RELEASE_INDEX_TTL_MS |
5000 |
yes | How long the index of release lists is reused before it is rebuilt; 0 rebuilds it for every token. |
federation.maxResponseBytes |
STS_FEDERATION_MAX_RESPONSE_BYTES |
262144 |
yes | The cap on a partner’s token response, UserInfo document or JWKS. |
federation.jwtAlgorithms |
STS_FEDERATION_JWT_ALGORITHMS |
RS256,RS384,RS512,PS256,PS384,PS512,ES256,ES384,ES512 |
yes | The JWS algorithms a partner’s ID Token or JWT access token may use; it only narrows, never admitting none or an HMAC. |
federation.spNameIdFormat |
STS_FEDERATION_SP_NAMEID_FORMAT |
urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified |
yes | The <md:NameIDFormat> published in /federation/metadata/{id}. |
federation.encryptionKeyGraceS |
STS_FEDERATION_ENCRYPTION_KEY_GRACE_S |
86400 |
yes | How long a relationship’s encryption key still decrypts after a rotation replaced it; 0 ends it at the rotation (#168). |
federation.clientCertificateRenewDays |
STS_FEDERATION_CLIENT_CERTIFICATE_RENEW_DAYS |
30 |
yes | How many days before a 1-advanced relationship’s TLS client certificate expires a new one is issued, with the same subject (#931). |
federation.maxPartnerAuthAgeS |
STS_FEDERATION_MAX_PARTNER_AUTH_AGE_S |
0 |
yes | Refuses a federated sign-in whose partner says the person authenticated longer ago than this many seconds, by auth_time or AuthnInstant. While it is set, a partner that does not say when is refused. 0, the default, does not ask. |
federation.allowAssertionWithoutAudience |
STS_FEDERATION_ALLOW_ASSERTION_WITHOUT_AUDIENCE |
false |
yes | Product mode only. On, a partner’s SAML 1.1 or WS-Federation assertion with no audience restriction is accepted with a warning, for a partner that cannot send one; off, the default, it is refused. |
federation.allowUntypedLogoutToken |
STS_FEDERATION_ALLOW_UNTYPED_LOGOUT_TOKEN |
false |
yes | Product mode only. On, a partner’s Logout Token typed jwt or carrying no type is accepted as well as one typed logout+jwt. The OpenID specification only recommends the type. |
What this service calls itself to a partner is derived from the URL the browser
reached it at; global.publicBaseUrl pins it for everything, and
fedLocalEntityId on one relationship pins it for that partner.
This table is a copy of rows in common/config.js; the live source is
/admin/federation and GET /admin-api/config.
See Configuration for how a value is resolved and where it
is changed: on /admin/federation, through POST /admin-api/config/set, or in
an appconfig file.
The relationship’s own fields
These are attributes of the relationship entry, set on /admin/federation or
/admin-api/federation, not settings.
| Field | Side | What it holds |
|---|---|---|
fedName, fedEnabled |
both | a display name; whether the relationship does anything (created FALSE) |
fedPeer |
both | the partner’s own identifier — entityID, issuer or wtrealm; required and checked on the service-provider side |
fedLocalEntityId |
SP | what this service is called to this partner, when not the derived name |
fedSsoUrl |
SP | where the browser is sent |
fedTokenUrl, fedUserinfoUrl |
SP | the two URLs this service dials for an OAuth-shaped partner |
fedJwksUri, fedJwks |
SP | the partner’s keys, fetched or pasted (pasted is read first and never refreshed) |
fedSigningCertificate |
SP | the partner’s signing certificate, base64 DER — what every SAML and WS-Federation assertion is verified against |
fedClientId, fedClientSecret |
SP | this service’s client credentials at the partner |
fedScope, fedResponseType |
SP | the scope asked for (openid profile email by default for OIDC); code (default), id_token, id_token token, code id_token, code token or code id_token token |
fedResponseMode |
SP | empty, query, form_post or (OIDC) fragment — fragment is a warning: see OpenID Connect as the relying party |
fedRegister, fedRegisteredIssuer |
SP (OIDC) | register this service at the partner (FALSE by default); the issuer the client was registered with |
fedRequestObject, fedRequestObjectSigningAlg |
SP (OIDC) | request or request_uri; RS256, PS256, ES256 or none (a warning) |
fedWebFinger |
SP (OIDC) | find a person’s provider from an identifier they type (FALSE by default — a warning) |
fedRefreshTokens, fedRefreshEverySeconds |
SP (OIDC) | keep and use the partner’s refresh token for each session (FALSE by default — a warning when on); how often, in seconds |
fedUserinfoSignedResponseAlg |
SP (OIDC) | the algorithm a signed UserInfo answer must use |
fedUserinfo |
SP (OIDC) | ask the partner’s UserInfo endpoint (TRUE by default); FALSE takes the person’s claims from the ID Token alone |
fedIdTokenSignedResponseAlg |
SP (OIDC) | the one algorithm the partner signs ID Tokens and Logout Tokens with (what was registered as id_token_signed_response_alg); a token under another is refused even when a partner key verifies it. Empty is a warning: any algorithm of the key’s family is accepted |
fedDiscovery, fedInitiateLogin |
SP (OIDC) | read the endpoints from the partner’s discovery document; answer a sign-in the partner starts. Both FALSE by default |
fedFapi |
SP (OIDC) | empty (today’s relying party), 1-advanced, 2-security or 2-message-signing — see FAPI client profiles |
fedBinding, fedSignRequest |
SP | the outbound SAML binding; whether the AuthnRequest is signed |
fedSloUrl, fedSloBinding |
SP | the partner’s SAML SingleLogoutService, and the binding (HTTP-Redirect, the default, or HTTP-POST) this service’s LogoutRequest and LogoutResponse go on |
fedEndSessionUrl |
SP | the partner’s OpenID Connect end_session_endpoint; the ID Token is kept for id_token_hint only while this is set |
fedAcceptSignout |
SP | honour the partner’s sign-out; TRUE by default, and off every one is refused (STS-FED-0123) |
fedRequireSignedLogout |
SP | require a SAML logout message to be signed; TRUE by default and always in product — off is a warning: an unsigned sign-out is anybody signing anybody out |
fedUsernameSource, fedAttributeMap |
SP | which incoming value the confirm lookup and any-existing match; not the name a created entry gets. Extra attribute mappings |
fedAutocreateUsers, fedUpdateUserAttributes, fedAllowUnsolicited |
SP | whether a sign-in creates an entry (TRUE in development, FALSE in product, when the relationship is created); whether a returning person’s attributes are overwritten; accepting a response nobody asked for |
fedProvisionGroups, fedProvisionCap, fedProvisionIdleMinutes |
SP | group memberships from the partner’s token, off; how many people the relationship may create, empty for unlimited (for a consumer provider, federation.consumerProvisionCap); idle minutes before a person whose only path is this relationship is disabled, empty for off |
fedSubjectPolicy |
SP | what an unlinked subject may become: link-at-first-sign-in (default), pre-linked, jit-namespaced, any-existing (development only — see the warning above) |
fedSubjectGroup, fedSubjectDomain, fedSubjectPattern |
SP | the rules on top of the policy |
fedMayAssertAdministrators |
SP | let the partner sign in a console administrator; FALSE by default — see the warning above |
fedEncryptionKeyType, fedKeyManagementAlgorithm, fedContentEncryptionAlgorithm |
SP (SAML 2.0, WS-Federation, OIDC) | what a partner encrypts to: rsa-3072 or ec-p256, and for OIDC only the post-quantum x-wing and ml-kem-768; rsa-oaep/ecdh-es (XML) or RSA-OAEP-256, RSA-OAEP (a warning: SHA-1), ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A256KW, HPKE-10-KE, ML-KEM-768 (JOSE); aes256-gcm/aes128-gcm or A256GCM/A128GCM. A new key type issues a key of that type at once |
fedAllowUnencrypted |
SP (SAML 2.0, WS-Federation, OIDC) | accept a plaintext assertion in product; FALSE by default — a warning: the partner then sends the person’s identifier and attributes in clear through the browser |
fedEncryptionKey |
SP | the key table: never editable, never shown with its private key |
fedSignalsEnabled, fedSignalsIssuer, fedSignalsDelivery, fedSignalsEvents |
SP | receive the partner’s Shared Signals (on for an ssf relationship); its SSF issuer (empty is fedPeer); poll or push; the event types asked for (#373) |
fedSignalsTokenUrl, fedSignalsClientId, fedSignalsClientSecret, fedSignalsScope, fedSignalsBearer |
SP | how this realm authenticates to the partner’s stream management: client credentials (the first three fall back to fedTokenUrl, fedClientId, fedClientSecret) or a bearer token. The two secrets are sealed wherever keys persist |
fedSignalEmailMatch |
SP | let the partner’s events name a person by mail; FALSE by default |
fedApplication |
IdP | the partner’s entry under ou=applications |
fedAuthnMechanism, fedAuthnRelationship |
IdP | how this service authenticates for the partner |
fedRelease |
IdP | the attributes released to the partner |
What each protocol requires before a relationship is usable: for the five
sign-in protocols, fedSsoUrl and fedPeer always; fedSigningCertificate
for the three SAML-shaped protocols; fedClientId for OIDC, with
fedTokenUrl for a response type with a code and fedJwks / fedJwksUri for
one with an ID Token from the authorization endpoint (neither, nor fedSsoUrl,
with fedDiscovery); fedTokenUrl and fedClientId for OAuth 2.0,
with fedUserinfoUrl (or fedJwks / fedJwksUri, when the access token is a
JWT); for ssf, fedPeer and a way to reach the partner’s stream (a bearer,
or a token endpoint and client). An OIDC relationship with fedTrustAnchor
needs only fedPeer, and the code flow (OpenID Federation).
Where plaintext would be refused, the relationship also needs its encryption
key. An identity-provider-side relationship needs fedApplication, and
fedAuthnRelationship when fedAuthnMechanism is federation. A missing one
is named on the page and the relationship refuses until it is filled.
Design decisions
- A relationship must be configured, and what it configures is a key.
The other authenticated surfaces here — SCIM, the SPIRE Server API, the
console — are turnstiles: they refuse a caller so that a client can
exercise a refusal. This one is different.
/federation/acs/{id}receives an unauthenticated request claiming to be a person; the only thing between “alice signed in at the partner” and “somebody POSTed some XML” is the signature check, and the session it produces is the one/oauth2/authorize,/wsfed,/saml2/sso,/saml11/ssoand/adminall read. “Accept any SAML Response” would be an authentication bypass for the whole process, reachable withcurl, and the tokens minted afterwards would be indistinguishable from real ones — so there is no permissive version to offer. - Created disabled; enabled as a second act; half-configured refuses. A partner that half-worked would look finished from every angle except the one where it accepts something it should not.
- Verified against the relationship’s certificate, never the document’s. A signature carrying its own certificate proves only that somebody signed it; pinning the key is the difference between a check and a decoration.
- Issuer and audience are refusals, not warnings. An assertion a partner minted for another of its relying parties verifies against the same key, so accepting any audience would let anybody holding one sign in here.
- The gate is on the signer and on the subject. A verified assertion signs in only the person its subject is linked to, and a name never links anybody; until #109 any person the partner named was accepted and had the partner’s attributes written onto their entry before anything could refuse.
- The link is made by the person, or by an administrator — never by the
partner. Under
link-at-first-sign-inthe person proves here that they are the local account the partner named; a match by name alone is a way for any partner to sign inadmin. - One path receives all five protocols. A SAML ACS, a
wreplyand aredirect_uriare three names for “where the answer comes back”; five paths would be four more ways to configure the wrong one. - The return address is kept on the server.
RelayState,wctxandstatecarry only a handle, because a return URL in the parameter is an open redirect for anybody who can forge one. - A failure is shown, recorded and not redirected. The person already signed in at the partner; the page names the check this service disliked, and the relationship records it as its last error.
- Unmapped attributes are listed, not stored under their own names. The directory has no schema, so a wrongly named attribute would be accepted silently forever.
- An empty release list filters nothing. “No policy” and “release nothing” must be different states, or registering a partner would silently change what it receives.
- Only administrator-configured URLs are dialled. A partner’s token
endpoint was written down by somebody configuring the partnership; a
WS-Federation
wreqptrwas chosen by a caller and is never followed. - A happy path proves close to nothing here. This is the surface whose bugs
are security bugs rather than fidelity bugs, so what matters is the
negatives;
tests/protocol/sts_federation_realms.js,sts_federation_subject_policy.jsandsts_federation_signout.jsdrive most of them over HTTP, andfederation/CLAUDE.mdlists the ones still open. - The outbound HTTP-POST binding is a real form with a real button. A person leaving this service for a foreign identity provider is the moment a deliberate click is worth having, so that page has a button rather than a script that submits it.
- A created entry is namespaced to the relationship; a confirm lookup is not.
An entry
link-at-first-sign-inorjit-namespacedcreates is<relationship>~<subject>even whenfederation.usernamePrefixis empty. That prefix, empty by default, is applied only to the confirm-lookup name and toany-existing, after the part before the last@is taken, which is what lets those two meet a local person. Set it when they should not.any-existingis the one policy whose createduidis that lookup name.
In the running service
- Protocols → Federation (
/admin/federation): every relationship in both directions with its state and readiness, the URL to give each partner, the unmapped attributes a partner sent, create and edit forms, and thefederation.*settings. /admin/federation/map: the register drawn as a picture — see The federation map.GET /federation: the public description, with the URL to configure at each partner.- Management API:
GET /admin-api/federationandPOST /admin-api/federation/{action}(createand its siblings) — see/admin-api/openapi.json. - Every federation failure is recorded under an
STS-FED-NNNNcode on the audit row and in the log, never sent to the client — see Error codes.
Related
- Sessions — the session a federated sign-in starts
- Authentication — the sign-in screen, the partner buttons and the chooser
- SAML 2.0 Web Browser SSO, SAML 1.1, WS-Federation, OAuth 2.0 & OpenID Connect — the same protocols with this service as the identity provider
- Kerberos — the
spnegomechanism - SCIM — pre-provisioning people a relationship will not create
- Trust realms — the register is per realm
- PKI — revocation checking of a partner’s certificate
- What is not checked
- Configuration