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.

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

In a trust realm every path is under /realm/{id}. 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. fedSignRequest signs 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 be InResponseTo.
• WS-Federation — wa=wsignin1.0 with this service’s wtrealm; the wresult carries a SAML 1.1 or SAML 2.0 assertion inside an RSTR.
• OpenID Connect — the authorization code flow by default. fedResponseType: id_token with response_mode=form_post needs no back channel at all, which is the way to federate with an OIDC partner from a deployment with no egress. The nonce is checked. Attributes come off the ID Token and, when configured, UserInfo. With the code flow, configure fedUserinfoUrl: a provider that follows OpenID Connect Core section 5.4 (this service among them, since #118) puts profile claims such as preferred_username and email in 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, or fedJwksUri), with alg: none refused 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 AudienceRestriction must 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. 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 in RelayState / wctx / state), unless fedAllowUnsolicited is on;
• the partner’s signing certificate for revocation, under pki.revocationCheck.

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.

• The username is the value fedUsernameSource names, or the subject (the NameID or sub). A partner’s urn:uuid: subject becomes sub-<uuid> and is never looked up locally. federation.usernamePrefix is put in front of it.
• Attributes are mapped in three layers: the relationship’s own fedAttributeMap (<incoming name>=<LDAP attribute>), then a default table covering the ordinary OIDC claims, SAML urn:oid: names and AD FS claim URIs, then nothing — an unrecognised name is listed as unmapped on the result page, on /admin/federation and in the log, not written under its own name.
• A partner’s value overwrites an invented one and never the other way round; an attribute the partner stopped sending is left alone — a partner that dropped title from its release policy has not said the person has no title; uid is never written from an assertion, because that is what the DN is built from.
• federationAttribute on the entry says which attributes came from the partner, beside federationRelationship, federationIssuer, federationLink and federationLastSeen. It exists because this service invents a persona for everybody it has never met, so a federated mail and an invented mail are otherwise indistinguishable on the entry.
• Nothing is written onto an entry until the subject has been admitted — see Which people a partner may assert below.
• The session’s amr starts with federated, followed by what the partner said; a SAML partner’s authentication context travels on acr — so a SAML assertion this service then issues states the partner’s class rather than calling every federated sign-in a password.

A federated sign-in leaves an entry like this:

uid=fedalice,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.

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, `