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.

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 ** button, for example **Save SAML 2.0**. The **SAML assertions** tab has one **Save assertion settings** button. The API equivalents are `POST /admin-api/config/set`, `/config/set-many` and `/config/reset`.

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.requireSignedAuthnRequests is auto, which means on in product mode).
  • Assertions are always signed.
  • rsa-1_5 and SHA-1 are refused.

SAML 2.0

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:

  1. 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.
  2. 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.
  3. 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:

  1. On Applications → New application ›, under What it is called, enter the Identifier.
  2. Under Protocol families it is declared for, tick SAML 2.0.
  3. Under Its fields, on the SAML 2.0 and SAML 1.1 tab, fill in samlEntityId, samlAssertionConsumerService (the ACS), samlSingleLogoutService (the SLO address) and samlSigningCertificate.
  4. 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:

  • Destination must be the endpoint the request arrived at. A signed request must carry one: a signed request with no Destination is 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 as STS-SAML-0085. If your SP signs its requests, make sure it sets Destination.
  • IssueInstant may be at most one minute in the future and no older than saml2.requestTtlMin (10 minutes) plus a minute (STS-SAML-0086).
  • Version must be 2.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 ArtifactResolve with a key whose certificate is registered in samlSigningCertificate; 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 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:

  1. samlEncryptionCertificate
  2. a registered samlSigningCertificate
  3. 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:

  1. the SLO endpoint in the SP’s consumed metadata
  2. samlSingleLogoutService
  3. saml2.defaultSingleLogoutService
  4. 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. A transient NameID 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 answered NoPassive, 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:

  1. On Applications → New application ›, under What it is called, enter the Identifier.
  2. Under Protocol families it is declared for, tick SAML 1.1.
  3. Under Its fields, on the SAML 2.0 and SAML 1.1 tab, fill in samlEntityId, samlAssertionConsumerService (the relying party’s shire) and samlSigningCertificate (base64 DER).
  4. 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 Resource or 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.