This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.
Configuring SAML 2.0 and SAML 1.1 profiles
This page shows how to set up iya-sts, as a SAML identity provider, for each SAML 2.0 binding and profile and each SAML 1.1 profile it supports. Each recipe covers the service provider (SP) to register, the settings to change, and what the SP sends. It is given twice: once as steps in the admin console and once as Management API calls.
The values come from this repository’s test jobs, and each recipe names the
job it is taken from. For SAML 2.0 these include the four interoperability
jobs, which run real Shibboleth, pysaml2, SimpleSAMLphp and Keycloak service
providers. How each profile behaves is covered on
SAML 2.0 Web Browser SSO and SAML 1.1, along
with every setting and its default. This page covers only what to fill in.
Configuring OAuth 2.0 grants → Before you start
explains the shared mechanics: the API token, the api shell helper used
below, and the application page’s forms.
- Configuring SAML 2.0 and SAML 1.1 profiles
- SAML 2.0
- Register the SP from its metadata (recommended)
- Register the SP by hand
- Web Browser SSO: request bindings
- Web Browser SSO: response bindings
- HTTP-Artifact and artifact resolution
- Who may start a sign-in
- Signed AuthnRequests
- Encrypted assertions
- NameID formats
- Attributes
- Single Logout
- Several accounts in one browser
- Metadata Query (MDQ)
- SAML 1.1
Where things are
| Page | Console menu | What you do there |
|---|---|---|
/admin/saml2 |
Protocols → SAML | One page with seven tabs: Metadata, Global settings (the SAML 2.0 and SAML 1.1 groups), Shared profile settings (the SAML group), SAML 2.0 IdP (register and list service providers, MDQ), SAML 1.1 IdP (register and list relying parties), SAML assertions and Custom SAML attributes. |
/admin/saml2?sp=<entityID> |
click a service provider’s row on SAML 2.0 IdP | Upload its metadata, set its certificates and logout address, and find the IdP metadata URL to give it. |
/admin/saml2?rp=<identifier> |
click a relying party’s row on SAML 1.1 IdP | See its endpoints and what has been recorded about it. |
/admin/applications?application=<id> |
Directory → Applications | Per-SP overrides on the Configuration tab, sub-tab SAML 2.0 and SAML 1.1, which has a SAML 2.0 and a SAML 1.1 tab for each family the application is declared for. Each has its own Save SAML 2.0 / Save SAML 1.1 button. The Directory entry tab’s Change one attribute by name form (Set / Add to / Remove from) reaches any attribute by name. |
Each settings group is saved with its own **Save
POST /admin-api/applications/set writes a single-valued attribute only. A
list attribute (samlEntityId, samlAssertionConsumerService,
samlSingleLogoutService, samlSigningCertificate) is refused there
(STS-REG-0008): use applications/add and applications/remove, or the
SAML actions below.
What development and product mode change. Development mode answers any
SP, registers it the first time it appears (saml2.autocreateApplications
and saml11.autocreateApplications, both on by default), and sends a response
to whatever consumer address the request names. Product mode does none of
this:
- An SP must be registered. Its per-SP endpoints answer 404 otherwise.
- The consumer address must be one that is registered, matching exactly.
- Requests must be signed (
saml2.requireSignedAuthnRequestsisauto, which means on in product mode). - Assertions are always signed.
rsa-1_5and SHA-1 are refused.
SAML 2.0
Register the SP from its metadata (recommended)
When the SP’s metadata is consumed, one save registers its assertion consumer
services (ACS) and their bindings, its logout endpoints, its signing and
encryption certificates, its NameID formats, and its AuthnRequestsSigned /
WantAssertionsSigned flags. All four interoperability jobs do this, through
saml_peer_kit.js.
Console:
- On Protocols → SAML, tab SAML 2.0 IdP, in Register a service provider, enter the SP’s entityID (for example
https://sp.example.com/saml) and click Register. - Click the new row. Under Its metadata, paste the SP’s metadata into Upload a document (or pick it under or a file), and click Consume it.
- In The endpoints it is configured from, copy the Metadata URL. That is the IdP metadata to load into the SP.
The application’s page has the same form: Configuration → SAML 2.0 and
SAML 1.1 → SAML 2.0 → Its metadata → Consume it. A metadata document typed
into samlSpMetadata on Applications → New application › is consumed
when you click Create the application. If it is refused, the application
is still created and the answer says why.
API:
api applications/create '{"identifier":"https://sp.example.com/saml","name":"Example SP",
"protocols":["saml2"],"fields":{}}'
jq -n --arg d "$(cat sp-metadata.xml)" '{sp:"https://sp.example.com/saml",document:$d}' |
curl -sk -X POST "$BASE/admin-api/saml2/upload-metadata" \
-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' --data-binary @-
# the IdP metadata to give the SP
curl -sk "$BASE/saml2/metadata/$(jq -rn --arg s https://sp.example.com/saml '$s|@uri')"
If you declare saml2 with no samlEntityId, the identifier is used as the
entityID, which is why "fields": {} is enough. A samlSpMetadata document
given in fields on the create is consumed too. Setting it later with
applications/set only stores it; use upload-metadata to consume one.
The interoperability jobs
first create a realm for the SP; the IdP’s entityID there is that realm’s
OAuth 2.0 issuer, which is not a setting (#523):
api realms/create '{"id":"sp1","domain":"sp1.example.net","name":"sp1"}'
To have the metadata fetched from a URL instead of uploaded: set
samlSpMetadataUrl on the application, then click Refresh the metadata
on its SP metadata tab (or Refresh it now on the SP’s page under
SAML 2.0 IdP). Through the API:
api applications/set '{"application":"https://sp.example.com/saml",
"attribute":"samlSpMetadataUrl","value":"https://sp.example.com/saml/metadata"}'
api applications/refresh-metadata '{"application":"https://sp.example.com/saml"}'
The fetch goes through the federation outbound policy: https only, with the
certificate verified in product mode.
Stale metadata is refreshed in the background while
saml2.spMetadataRefresh is on (the default). Metadata that has expired
refuses every request from that SP. To require the metadata itself to be
signed, set a trust anchor. saml2.metadataTrustAnchors does it for every
SP. For one SP, use Metadata signing certificate → Set on the SP’s page
under SAML 2.0 IdP, or the API:
api saml2/set-metadata-signing-certificate '{"sp":"https://sp.example.com/saml","value":"MIIC…"}'
Register the SP by hand
Without metadata, register the addresses and certificates yourself. The
values here are from sts_xml_schema_validation.js, which names its service
providers https://sp-<tag>-<stamp>.example.com/saml; sp-d stands in for
that below.
Console:
- On Applications → New application ›, under What it is called, enter the Identifier.
- Under Protocol families it is declared for, tick SAML 2.0.
- Under Its fields, on the SAML 2.0 and SAML 1.1 tab, fill in
samlEntityId,samlAssertionConsumerService(the ACS),samlSingleLogoutService(the SLO address) andsamlSigningCertificate. - Click Create the application.
To change the certificates later, open the SP’s page under SAML 2.0 IdP: under Its signing certificates, paste the certificate into Replace them with and click Set.
API:
api applications/create '{"identifier":"https://sp-d.example.com/saml","name":"sp-d",
"protocols":["saml2"],
"fields":{"samlEntityId":["https://sp-d.example.com/saml"],
"samlAssertionConsumerService":["https://sp-d.example.com/acs"],
"samlSingleLogoutService":["https://sp-d.example.com/slo"],
"samlSigningCertificate":["<PEM or base64 DER>"]}}'
Setting samlSpMetadata with applications/set only stores the document;
nothing in it is used. To register from metadata, use Consume it,
upload-metadata, or give the document on the create. Once metadata has been
consumed, the ACS must be one of its endpoints, in every mode.
In development mode, a certificate that a signed request carries is recorded
as observed. It is trusted only once you click Confirm — trust it or
call saml2/confirm-signing-certificate {"sp":…}. Clicking Discard or
calling …/discard-signing-certificate drops it.
Web Browser SSO: request bindings
The SP sends its AuthnRequest to /saml2/sso (or the per-SP
/saml2/sso/<entityID or slug>):
| Binding | How it is sent |
|---|---|
| HTTP-Redirect | GET, with SAMLRequest, and SigAlg / Signature in the query when signed |
| HTTP-POST | POST, with an enveloped signature |
| HTTP-POST-SimpleSign | POST, with SigAlg / Signature form fields |
The IdP metadata publishes all three as SingleSignOnService. HTTP-Artifact
is not supported for the request. No setting is needed.
Every request, in every mode, is checked as follows:
Destinationmust be the endpoint the request arrived at. A signed request must carry one: a signed request with noDestinationis refused, because what it was signed for cannot be told (SAML bindings sections 3.4.5.2 and 3.5.5.2). The refusal is a page, recorded asSTS-SAML-0085. If your SP signs its requests, make sure it setsDestination.IssueInstantmay be at most one minute in the future and no older thansaml2.requestTtlMin(10 minutes) plus a minute (STS-SAML-0086).Versionmust be2.0(STS-SAML-0087).- Each request ID is answered once (
STS-SAML-0088). - The SP may start a sign-in at all:
saml2.spInitiatedSso(see Who may start a sign-in).
The request the schema job builds (it signs it, so Destination is there) is:
<samlp:AuthnRequest ID="_…" Version="2.0" IssueInstant="…"
Destination="https://idp.example.com/saml2/sso"
AssertionConsumerServiceURL="https://sp-d.example.com/acs"
ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST">
<saml:Issuer>https://sp-d.example.com/saml</saml:Issuer>
</samlp:AuthnRequest>
ForceAuthn, IsPassive, RequestedAuthnContext and NameIDPolicy are
honoured; SAML 2.0 Web Browser SSO describes each one.
Web Browser SSO: response bindings
The response is sent on the binding the request’s ProtocolBinding names.
If the request instead gives an AssertionConsumerServiceIndex, the binding
of that consumed ACS endpoint is used. HTTP-POST is the default. The
Shibboleth job uses its indexes 1 (POST), 2 (SimpleSign) and 3
(Artifact).
| Binding | What the SP receives |
|---|---|
| HTTP-POST | A self-submitting form with a signed Response. The assertion is signed too. |
| HTTP-Redirect | The Response in the query, signed with a query-string signature. A Response longer than saml2.redirectWarnLength (8000) is still sent, with a warning in the log. |
| HTTP-POST-SimpleSign | The Response with SigAlg / Signature form fields. |
| HTTP-Artifact | See below. |
Signing is set by saml2.signResponse and saml2.signAssertion (both
true), on SAML assertions. Turning off assertion signing is refused in
product mode. The per-SP overrides are saml2SignResponse and
saml2SignAssertion (TRUE/FALSE):
api applications/set '{"application":"https://sp.example.com/saml",
"attribute":"saml2SignResponse","value":"FALSE"}'
HTTP-Artifact and artifact resolution
The SP receives a SAMLart and resolves it over SOAP at /saml2/ars (or
/saml2/ars/<sp>). The per-SP IdP metadata publishes that endpoint as
ArtifactResolutionService. Each artifact can be resolved once, across the
whole cluster. It expires after saml2.artifactTtlS (300 s); the per-SP
override is saml2ArtifactTtlS. At most saml2.maxArtifacts (10000)
unresolved artifacts are kept per realm. When the store is full of live ones,
the next sign-in on this binding is refused with a 503 page
(STS-SAML-0110) rather than forget an artifact.
The resolver must authenticate. It must be the SP the artifact was minted
for, and the artifact’s SourceID must be this realm’s. An artifact that
does not resolve, for whatever reason, gets the empty Success response. Where
signed requests are required (in product mode by default), the resolver must
also do one of these:
- sign the
ArtifactResolvewith a key whose certificate is registered insamlSigningCertificate; or - present one of those certificates as its TLS client certificate.
The schema job signs the request like this:
POST /saml2/ars/<sp entityID, percent-encoded>
Content-Type: text/xml; charset=utf-8
SOAPAction: ""
<soap:Envelope><soap:Body>
<samlp:ArtifactResolve ID="_…" Version="2.0" IssueInstant="…"
Destination="https://idp.example.com/saml2/ars/<sp>">
<saml:Issuer>https://sp-d.example.com/saml</saml:Issuer>
<samlp:Artifact>…</samlp:Artifact>
</samlp:ArtifactResolve> <!-- enveloped signature with the SP's key -->
</soap:Body></soap:Envelope>
The SP asks for this binding with
ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Artifact".
Who may start a sign-in
Each SAML profile has two switches. One says whether this identity provider may start a sign-in for an SP (IdP-initiated). The other says whether the SP may start one with its own request (SP-initiated). Each is a realm setting, and an attribute on the application’s entry overrides it for that SP.
| IdP-initiated (default off) | SP-initiated (default on) | |
|---|---|---|
| SAML 2.0 | saml2.idpInitiatedSso / saml2IdpInitiatedSso |
saml2.spInitiatedSso / saml2SpInitiatedSso |
| SAML 1.1 | saml11.idpInitiatedSso / saml11IdpInitiatedSso |
saml11.spInitiatedSso / saml11SpInitiatedSso |
In the console the realm settings are on Protocols → SAML → Global settings (Identity-provider-initiated sign-in and Service-provider-initiated sign-in, in the SAML 2.0 and SAML 1.1 groups). The per-SP attributes are on the application’s Configuration → SAML 2.0 and SAML 1.1 tab, under Who may start a sign-in.
The values below are from sts_idp_initiated_saml.js, which runs in
development and product mode. It creates each SP with the switch already in
fields:
api applications/create '{"identifier":"https://sp-idp-on.idp-initiated.test/sp",
"name":"sp-idp-on","protocols":["saml2"],
"fields":{"samlEntityId":["https://sp-idp-on.idp-initiated.test/sp"],
"samlAssertionConsumerService":["https://sp-idp-on.idp-initiated.test/acs"],
"samlSigningCertificate":["<PEM>"],
"saml2IdpInitiatedSso":"TRUE"}}'
(The job adds a run stamp to each host name.) To turn it on for an SP that already exists, or for every SP in the realm (an entry’s own value still wins):
api applications/set '{"application":"https://sp.example.com/shibboleth",
"attribute":"saml2IdpInitiatedSso","value":"TRUE"}'
api config/set '{"key":"saml2.idpInitiatedSso","value":true}'
An unsolicited Response carries no InResponseTo, so the SP cannot tell it
from one an attacker pushed into a browser. Turn it on only for SPs that
expect it.
The link. Every application has one IdP-initiated link,
/launch/{application}, with ?protocol=saml2 or ?protocol=saml11 when it
uses more than one protocol, and target for where to land. It is shown at
the top of the application’s SAML tab, and on the user portal’s
Sign in link. For SAML 2.0 it goes to /saml2/unsolicited/{sp} with
target as the RelayState; for SAML 1.1 to /saml11/sso/{rp} with
providerId and TARGET. Identity-provider-initiated sign-in
describes the link in full. sts_idp_initiated_launch.js is the job for it.
Which SPs it is on for. Protocols → SAML → IdP-Initiated SSO lists
every SAML 2.0 SP and SAML 1.1 relying party in the realm whose switch is on,
by the realm setting or its own attribute, with its link (opens in a new tab,
with a copy button) and the protocol’s own endpoint. The identifier links to
the application’s page. A row that has no registered assertion consumer
service says so: its link answers STS-LAUNCH-0006 until one is added. With
both realm settings off and no SP turning it on for itself, the tab says so
and how to turn it on. The same list is GET /admin-api/saml-idp-initiated,
paged with idpInitiatedPage and per:
curl -sk "$BASE/admin-api/saml-idp-initiated?idpInitiatedPage=2&per=25" \
-H "Authorization: Bearer $TOKEN"
SAML 2.0: the unsolicited Response
The protocol’s own endpoint is:
GET /saml2/unsolicited/<sp entityID or slug>?target=<RelayState>[&shire=<ACS URL>][&binding=post|simplesign|artifact]
GET /saml2/unsolicited?providerId=<sp>&target=<RelayState>[&shire=<ACS URL>]
shire picks one of the SP’s registered ACS endpoints; without it the
default one is used. The Shibboleth job uses
shire=https://sp.example.com/Shibboleth.sso/SAML2/POST&target=https://sp.example.com/peer/env.
The Redirect binding is refused here (STS-SAML-0093). In product mode, the
SP and the ACS must both be registered.
While the switch is off for the SP, the link answers a 403 page
(STS-SAML-0091), with no sign-in screen first. A sign-in started here is
held to the issuance policy like any other. A step-up on risk, or a sign-in
mechanism the SP does not allow (the named authentication policy it names
in appAuthnPolicy), sends the person to
sign in again once and back to the link. If it is still refused after that
trip, the SP gets a RequestDenied Response.
With saml2SpInitiatedSso set to FALSE, the SP’s own AuthnRequest is
answered with a RequestDenied Response and no sign-in screen
(STS-SAML-0111), and the SP can be signed in to only from the link.
SAML 1.1: a link with no shire
SAML 1.1 has no request message, so the shire parameter tells the two
apart. A /saml11/sso request that carries a shire is the relying party’s
own start (the Shibboleth 1.3 AuthnRequest profile) and answers to
saml11.spInitiatedSso. A request with only a TARGET (and providerId or
the path segment) is a sign-in started here, and answers to
saml11.idpInitiatedSso:
GET /saml11/sso/<rp>?TARGET=https://app.example.com/landing
That link is refused with a 403 page by default (STS-SAML-0113), and
answered once saml11IdpInitiatedSso is TRUE on the relying party. With
saml11SpInitiatedSso set to FALSE, a request carrying shire is refused
(STS-SAML-0114). Because the request is an unsigned URL, that switch closes
a door; it does not prove who opened it.
Signed AuthnRequests
saml2.requireSignedAuthnRequests (Require signed requests from service
providers) takes one of these values:
auto(the default): required in product mode, not in development.on: required in every mode.off: not required.
An SP whose metadata says AuthnRequestsSigned="true" must sign whatever the
setting says. A signature that is present is always verified, and only
against samlSigningCertificate, never against the KeyInfo in the
message. The same rules apply to the logout messages and to the
ArtifactResolve caller.
api config/set '{"key":"saml2.requireSignedAuthnRequests","value":"on"}'
api saml2/set-signing-certificate '{"sp":"https://sp.example.com/saml","value":"MIIC…"}'
The pysaml2 job cycles the setting through off, on and auto, sending an
unsigned request each time. The request is accepted with off and refused
with on. With auto it is refused in product mode and accepted in
development.
Encrypted assertions
To encrypt, set saml2.encryptAssertion (Encrypt the assertion) for every
SP, or saml2EncryptAssertion for one. An SP whose consumed metadata
publishes a use="encryption" key is encrypted to in every mode without
either setting.
Taken from sts_saml_encryption.js:
api applications/create '{"identifier":"https://enc-gcm.example.com","name":"enc-gcm",
"protocols":["saml2"],
"fields":{"samlAssertionConsumerService":["https://enc-gcm.example.com/acs"],
"samlSigningCertificate":["<base64 DER>"],
"samlEncryptionCertificate":"<base64 DER>",
"saml2EncryptAssertion":"TRUE"}}'
api applications/set '{"application":"https://enc-gcm.example.com",
"attribute":"saml2EncryptionAlgorithm","value":"aes128-gcm"}'
| Setting (and per-SP attribute) | Values |
|---|---|
saml2.encryptionAlgorithm (saml2EncryptionAlgorithm) |
aes256-gcm (the default), aes128-gcm, aes256-cbc and aes128-cbc (development only) |
saml2.keyTransportAlgorithm (saml2KeyTransportAlgorithm) |
rsa-oaep-mgf1p (the default; product uses rsa-oaep unless crypto.allowLegacyHashes is on), rsa-oaep, rsa-1_5 (development only) |
saml2.encryptLogoutNameId (saml2EncryptLogoutNameId) |
encrypts the NameID in a LogoutRequest |
The key to encrypt to is looked for in this order:
samlEncryptionCertificate- a registered
samlSigningCertificate - in development only, an observed certificate
If none is found, development mode sends the assertion unencrypted and logs a warning, and product mode refuses the request.
NameID formats
The IdP offers these formats: unspecified, emailAddress, persistent,
transient, X509SubjectName and entity. The default format is set by
saml2.nameIdFormat (Default NameID format); the per-SP override is
saml2NameIdFormat:
api applications/set '{"application":"https://sp.example.com/saml","attribute":"saml2NameIdFormat",
"value":"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"}'
An SP asks for a format with NameIDPolicy. If its consumed metadata lists
NameIDFormats, a request for any other format is answered with
InvalidNameIDPolicy. After changing the format on the SP, upload its
metadata again. The Keycloak job does this.
Attributes
Every assertion carries uid, mail, givenName, sn and displayName,
both under those names and under their urn:oid: names. For example, mail is
urn:oid:0.9.2342.19200300.100.1.3. Product mode reads the values from the
person’s directory entry, so create people with their attributes filled in:
api users/create '{"username":"alice","invent":false,"credential":"password","password":"<password>",
"attributes":{"cn":"Alice Example","givenName":"Alice","sn":"Example",
"displayName":"Alice Example","mail":"alice@example.com"}}'
To add an attribute to every assertion, use Protocols → SAML → Custom
SAML attributes → Add, or the API. Values may use ${subject} and
${audience}:
api saml-attributes/add '{"set":"saml2","name":"department","value":"engineering"}'
An application can carry attributes of its own as well: the Custom SAML
attributes section of its Configuration → SAML 2.0 and SAML 1.1 tab.
saml2ClaimsCombine (and saml11ClaimsCombine) says how its rows and the
realm’s are combined: application, union, intersection or realm.
Unset, its rows are added to the realm’s and win by name.
Attribute query. POST /saml2/aa takes a signed samlp:AttributeQuery
in a SOAP envelope. It answers only for a subject that has a live session
with the asking SP.
Single Logout
/saml2/slo (or /saml2/slo/<sp>) accepts a LogoutRequest or a
LogoutResponse on Redirect, POST or SimpleSign. The service looks for the
address to send its LogoutResponse to in this order:
- the SLO endpoint in the SP’s consumed metadata
samlSingleLogoutServicesaml2.defaultSingleLogoutService- the last ACS used (a guess, which is logged)
Console: on the SP’s page under SAML 2.0 IdP (/admin/saml2?sp=…),
under Where its LogoutResponse goes, enter the address in Add one and
click Add.
API:
api saml2/set-logout-service '{"sp":"https://sp.example.com/saml","value":"https://sp.example.com/saml/slo"}'
GET /saml2/slo with no message shows an IdP-initiated sign-out page with a
link for each SP. A back-channel (SOAP) LogoutRequest ends the session named
by its SessionIndex; the Keycloak job sends one.
Several accounts in one browser
With authn.multipleAccounts on (the default), one browser may be signed
in as several people at once. Several accounts in one browser
describes the setting. For SAML 2.0 it changes three things:
- The AuthnRequest’s
<saml:Subject>NameID chooses the account, if it names a username or e-mail address that is signed in. A NameID naming nobody signed in goes to the sign-in screen with it filled in, never to another account. AtransientNameID names nobody. - A request that names nobody, while more than one account is signed in,
goes to the account picker, and the account chosen there is the
assertion’s subject.
ForceAuthn="true"is a fresh sign-in, never the picker. IsPassive="true"with a choice to make is answeredNoPassive, with a generic status message that says nothing about the browser’s accounts.
sts_multi_account.js turns the setting on in a realm of its own and sends
signed requests:
api realms/create '{"id":"ma1","domain":"ma1.example.net","name":"ma1"}'
curl -sk -X POST "$BASE/realm/ma1/admin-api/config/set" \
-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d '{"key":"authn.multipleAccounts","value":true}'
SAML 1.1 can name nobody, so a browser with several accounts always reaches the picker there.
Metadata Query (MDQ)
Point the realm at an MDQ responder, and an SP can be looked up by entityID.
The lookup URL is <base>/entities/<percent-encoded entityID>.
api config/set-many '{"saml2.mdqBaseUrl":"https://mdq.example.org/","federation.outbound":true}'
api saml2/mdq-import '{"sp":"https://sp.example.com/saml"}'
The console equivalent is Protocols → SAML → SAML 2.0 IdP → Import one
from the Metadata Query responder → entityID → Import. In development mode, a request from an unknown SP
triggers a lookup. In product mode a lookup is never triggered by a request,
and refusals are listed in the Metadata Query lookups refused table. An
operator’s import is refused unless saml2.metadataTrustAnchors is set, or
saml2.mdqImportWithoutAnchors is true. sts_saml_unregistered.js is the
job that covers this.
SAML 1.1
The SAML 1.1 identity provider serves the Browser/POST and Browser/Artifact
profiles, Shibboleth 1.x’s AuthnRequest, and a SOAP responder that also acts
as an attribute authority. Its endpoints are /saml11/sso,
/saml11/responder and /saml11/metadata, each with an optional
/<relying party> path segment.
Register the relying party
Taken from sts_saml11.js.
Console:
- On Applications → New application ›, under What it is called, enter the Identifier.
- Under Protocol families it is declared for, tick SAML 1.1.
- Under Its fields, on the SAML 2.0 and SAML 1.1 tab, fill in
samlEntityId,samlAssertionConsumerService(the relying party’sshire) andsamlSigningCertificate(base64 DER). - Click Create the application.
A shorter way is Protocols → SAML → SAML 1.1 IdP → Register a relying
party: fill in Identifier and Assertion consumer (shire), then click
Register. Both are required. It registers no certificate, so add
samlSigningCertificate afterwards on the application’s page. The API
equivalent is:
api saml11/register '{"rp":"urn:test:saml11:rp1","shire":"https://rp.example.com/saml11/acs"}'
API (sts_saml11.js names its relying party urn:test:saml11:<stamp>):
api applications/create '{"identifier":"urn:test:saml11:rp1","name":"SAML 1.1 relying party",
"protocols":["saml11"],
"fields":{"samlEntityId":["urn:test:saml11:rp1"],
"samlAssertionConsumerService":["https://rp.example.com/saml11/acs"],
"samlSigningCertificate":["<base64 DER>"]}}'
Per-relying-party overrides. Use the application’s Configuration → SAML
2.0 and SAML 1.1 → SAML 1.1 tab and Save SAML 1.1, or set them in the
new-application form’s advanced view (Show every field (advanced view)).
The attributes are saml11AssertionLifetimeMin, saml11SignAssertion,
saml11SignResponse, saml11NameIdFormat and saml11ArtifactTtlS.
Settings (on Protocols → SAML, tabs Global settings and SAML assertions):
| Setting | Default | What it does |
|---|---|---|
saml11.defaultProfile |
post |
The profile used when the request names none: post or artifact. |
saml11.signAssertion / saml11.signResponse |
true |
Signs the assertion / the Response. Turning either off is refused in product mode. |
saml11.nameIdFormat |
…:1.1:nameid-format:unspecified |
The NameIdentifier format. |
saml11.artifactTtlS |
300 |
How long an artifact stays valid. |
saml11.maxArtifacts |
10000 |
Unresolved artifacts kept per realm; a full store refuses the next Browser/Artifact sign-in with a 503 page (STS-SAML-0110). |
saml11.idpInitiatedSso / saml11.spInitiatedSso |
false / true |
Who may start a sign-in; see above. |
sts_saml11.js flips each of these through config/set-many and restores
them with config/reset. For example:
api config/set-many '{"saml11.defaultProfile":"artifact"}'
api config/reset '{"key":"saml11.defaultProfile"}'
Browser/POST
GET /saml11/sso?providerId=urn:test:saml11:rp1&shire=https://rp.example.com/saml11/acs
&TARGET=https://rp.example.com/done?x=1[&profile=post]
This request carries a shire, so it is the relying party’s own start and
needs no switch turned on. After signing in, the person’s browser posts a
signed samlp:Response to the shire. The Response has Recipient set to the shire and uses the
cm:bearer confirmation. TARGET is returned unchanged.
The profile is chosen by the profile parameter first. If there is none, the
binding of the registered shire decides. Failing both,
saml11.defaultProfile applies.
The Shibboleth SP 1.3 form is accepted as it is sent: providerId, shire,
a lower-case target (returned as TARGET) and time, which is accepted
and ignored, so a stale value does not refuse the request. The job
sts_saml11.js sends that form with no profile to a relying party whose
metadata names a browser-post endpoint, and to one whose metadata names an
artifact-01 endpoint, and checks that each binding selects its profile.
In product mode, the shire must exactly match a registered
samlAssertionConsumerService, and a request that names no registered
relying party is refused.
Browser/Artifact and the SOAP responder
With profile=artifact, or a shire registered on the artifact binding, or
saml11.defaultProfile set to artifact, the relying party receives
<shire>?SAMLart=…&TARGET=…. It resolves that at /saml11/responder with a
signed request:
<!-- POST /saml11/responder, Content-Type: text/xml, inside a SOAP envelope -->
<samlp:Request xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"
RequestID="_req…" MajorVersion="1" MinorVersion="1" IssueInstant="…">
<ds:Signature>…</ds:Signature> <!-- RSA-SHA256, exc-c14n, over RequestID -->
<samlp:AssertionArtifact>…</samlp:AssertionArtifact>
</samlp:Request>
The request is signed with the key of the relying party’s registered
samlSigningCertificate. Presenting that certificate as the TLS client
certificate works too. A signature is required wherever
saml2.requireSignedAuthnRequests requires one, which in product mode is
always, because that setting also governs SAML 1.1 callers. An artifact can
be resolved once.
Attribute authority
The same responder answers samlp:AttributeQuery and
samlp:AuthenticationQuery:
<samlp:AttributeQuery Resource="urn:test:saml11:rp1">
<saml:Subject><saml:NameIdentifier>alice</saml:NameIdentifier></saml:Subject>
</samlp:AttributeQuery>
Development mode answers anybody. Product mode answers only when all three of these hold:
- the query names a registered relying party, through
Resourceor the path; - the caller authenticates as that relying party, by signing or with its TLS certificate;
- the subject has a live session that gave that relying party this NameIdentifier.
Shibboleth 1.3 AuthnRequest
GET /saml11/sso?providerId=<SP entityID>&shire=<ACS>&target=<relay>&time=<epoch seconds>
The IdP metadata advertises this profile. Register the SP with its
samlEntityId and samlAssertionConsumerService, or upload its metadata as
in SAML 2.0.
SAML 1.1-only metadata is consumed too. An SPSSODescriptor whose
protocolSupportEnumeration names only
urn:oasis:names:tc:SAML:1.1:protocol is read for an application declared
for saml11 and not saml2. Its ACS endpoints keep their bindings
(browser-post, artifact-01), so the shire chooses the profile. For an
application declared for both, upload from the application’s SAML 1.1
tab (Configuration → SAML 2.0 and SAML 1.1 → SAML 1.1 → Its metadata), or
pass "family":"saml11"; without it a dual-protocol application reads the
SAML 2.0 descriptor. sts_saml11.js does this:
api applications/create '{"identifier":"urn:test:saml11:rp1:metadata","name":"SAML 1.1 metadata-only relying party",
"protocols":["saml11"],"fields":{"samlEntityId":["urn:test:saml11:rp1:metadata"]}}'
jq -n --arg d "$(cat rp-metadata.xml)" \
'{sp:"urn:test:saml11:rp1:metadata",family:"saml11",document:$d}' |
curl -sk -X POST "$BASE/admin-api/saml2/upload-metadata" \
-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' --data-binary @-
The job sends no family, since its relying party is declared for SAML 1.1
alone. It then signs in with no profile and checks that the
artifact-01 endpoint selects Browser/Artifact.
NameIdentifier formats and attributes
SAML 1.1 has no NameIDPolicy. The format comes from saml11.nameIdFormat or
the per-relying-party saml11NameIdFormat:
| Format | NameIdentifier value |
|---|---|
emailAddress |
the person’s mail |
X509SubjectName |
CN=<username> |
WindowsDomainQualifiedName |
IYASTS\<username> |
unspecified |
the username |
Custom attributes use the saml11 set:
api saml-attributes/add '{"set":"saml11","name":"dept","value":"engineering"}'
SAML 1.1 tokens are also issued by WS-Federation’s wsignin1.0; see
WS-Federation.
Related
- SAML 2.0 Web Browser SSO and SAML 1.1: the behaviour and every setting.
- Identity-provider-initiated sign-in: the
/launch/{app}link. - Several accounts in one browser.
- SAML assertions (RFC 7522): a SAML assertion exchanged at the OAuth token endpoint.
- Configuring OAuth 2.0 grants and Configuring OpenID Connect flows.