Skip to content

SAML Broker

Broker authentication to an external SAML 2.0 identity provider, with HelixIAM acting as the service provider and owning the resulting user.

What it is

When you broker to a SAML 2.0 IdP, HelixIAM acts as the service provider (SP). Helix issues the authentication request, consumes the upstream assertion, and maps the asserted identity into the realm. This is the path for federating with enterprise IdPs, government identity hubs, and partner organisations that speak SAML.

  • Metadata-driven trust — import the upstream IdP's metadata to configure endpoints and signing certificates in one step.
  • Signing & encryption — authentication requests are signed with the realm's SAML signing key, assertions are verified against the IdP's signing certificates, and you can require encrypted assertions.
  • Attribute mappers — map SAML assertion attributes (by Name or FriendlyName, multi-valued) to Helix user attributes and roles; see Mappers.
  • JIT provision + link — new users are created on first login; returning users sign in to the account linked to their IdP identity (see Identity providers).

A SAML broker is an identity provider with protocol: "saml". Its config names the IdP's SSO endpoint and entity id, Helix's own SP entity id and ACS URL, and the IdP signing certificate used to verify assertions.

Watch: broker sign-in to a SAML 2.0 identity provider

61 seconds, no sound. Import IdP metadata to fill the connection, choose request signing, binding and encrypted assertions, then copy the service provider metadata. Fictitious example values only. Recorded on the current release.

In the console

  1. Open Identity providers (under Federation & eIDs) and click Add identity provider.
  2. Choose SAML 2.0. Under Identity provider metadata, upload the IdP's metadata XML, or enter its Metadata URL and click Fetch. This fills in IdP entity ID, IdP sign-in URL (HTTP-Redirect), IdP sign-in URL (HTTP-POST), IdP logout URL (HTTP-Redirect) and IdP signing certificates (PEM). Check the values; you can also enter them by hand. SP entity ID can stay empty: it then defaults to the connection's SP metadata URL.
  3. Under Requests and assertions, set Sign authentication requests (on by default; turned on automatically when the IdP's metadata asks for signed requests), Request binding (HTTP-Redirect or HTTP-POST, which needs the HTTP-POST sign-in URL) and Require encrypted assertions.
  4. Continue to Mappers to map assertion attributes to user attributes and roles (see Mappers), then Review and create the connection.
  5. Open the connection. On its Connection tab, the Service provider metadata section shows the SP metadata URL, SP entity ID and Assertion Consumer Service (HTTP-POST) URL, with Download SP metadata. Give this to the IdP's administrator. The metadata is also published at /realms/{realm}/broker/{alias}/saml/metadata, and lists the realm's signing certificate (and encryption certificate when assertions must be encrypted).
  6. The Signing tab holds the IdP signing certificates and the Attributes tab the assertion attribute names. On the Settings tab, Trust verified e-mail addresses from this provider decides whether the IdP's e-mail address counts as verified.

There are no separate switches for account linking, JIT provisioning or federated logout: users are created at their first sign-in, and signing out of HelixIAM also ends the IdP session when IdP Single Logout (SLO) URL is set.

Keep certificates current

When the IdP rotates its signing certificate or changes its endpoints, import its metadata again under Identity provider metadata on the Connection tab and save. Several certificates, one after another, cover a key rollover. Register the SP metadata with the IdP again after the realm's keys rotate.

Over the API

A SAML broker is created like any identity provider, with protocol: "saml". The examples below assume you have set $HELIX_URL / $REALM and logged in — see Authenticating to the API.

List SAML brokers

curl -s -b cookies.txt "$HELIX_URL/admin/realms/$REALM/identity-providers"
[
  { "realmId": "acme", "alias": "partner-saml", "protocol": "saml", "displayName": "Partner Corp", "enabled": true }
]

Create a SAML broker

The config map carries the SAML trust and endpoints. The server does not read metadata on create: to fill them from metadata, first call the preview endpoint (nothing is stored), then send its values in config.

curl -s -b cookies.txt -X POST \
  -H "Content-Type: application/json" -H "X-XSRF-TOKEN: $CSRF" \
  -d '{"metadataUrl":"https://idp.partner.example/metadata"}' \
  "$HELIX_URL/admin/realms/$REALM/identity-providers/saml/metadata/preview"
{
  "entityId": "https://idp.partner.example/",
  "ssoUrl": "https://idp.partner.example/sso",
  "ssoPostUrl": "https://idp.partner.example/sso/post",
  "singleLogoutServiceUrl": "https://idp.partner.example/slo",
  "signingCertificates": ["-----BEGIN CERTIFICATE-----\n…\n-----END CERTIFICATE-----\n"],
  "idpSigningCertificate": "-----BEGIN CERTIFICATE-----\n…\n-----END CERTIFICATE-----\n",
  "wantAuthnRequestsSigned": true,
  "warnings": ["samlMetadataWantsSignedRequests"]
}

The body takes metadataXml (the document) or metadataUrl (https, public hosts only); at most 1 MB, DTDs refused. GET /identity-providers/saml/sp-defaults?alias=partner-saml returns the default entityId and assertionConsumerServiceUrl for a new connection.

# Refresh CSRF after any GET, then POST (see the auth guide for the helper)
curl -s -b cookies.txt -c cookies.txt "$HELIX_URL/admin/realms/$REALM/identity-providers" >/dev/null
CSRF=$(awk '($6=="__Host-XSRF-TOKEN"||$6=="XSRF-TOKEN")&&$7~/^r1\./{t=$7} END{print t}' cookies.txt)

curl -s -b cookies.txt \
  -H "Content-Type: application/json" \
  -H "X-XSRF-TOKEN: $CSRF" \
  -d '{
        "alias": "partner-saml",
        "protocol": "saml",
        "displayName": "Partner Corp",
        "enabled": true,
        "config": {
          "ssoUrl": "https://idp.partner.example/sso",
          "idpEntityId": "https://idp.partner.example/",
          "spEntityId": "https://auth.example.com/realms/acme/broker/partner-saml/saml/metadata",
          "assertionConsumerServiceUrl": "https://auth.example.com/realms/acme/broker/partner-saml/callback",
          "idpSigningCertificate": "-----BEGIN CERTIFICATE-----\n…\n-----END CERTIFICATE-----",
          "signAuthnRequests": "true",
          "authnRequestBinding": "REDIRECT",
          "requireEncryptedAssertions": "false",
          "emailAttribute": "email",
          "firstNameAttribute": "givenName",
          "lastNameAttribute": "surname"
        }
      }' \
  "$HELIX_URL/admin/realms/$REALM/identity-providers"
{
  "realmId": "acme",
  "alias": "partner-saml",
  "protocol": "saml",
  "displayName": "Partner Corp",
  "enabled": true,
  "config": {
    "ssoUrl": "https://idp.partner.example/sso",
    "idpEntityId": "https://idp.partner.example/",
    "spEntityId": "https://auth.example.com/realms/acme/broker/partner-saml/saml/metadata",
    "assertionConsumerServiceUrl": "https://auth.example.com/realms/acme/broker/partner-saml/callback",
    "idpSigningCertificate": "-----BEGIN CERTIFICATE-----\n…\n-----END CERTIFICATE-----",
    "signAuthnRequests": "true",
    "authnRequestBinding": "REDIRECT",
    "requireEncryptedAssertions": "false",
    "emailAttribute": "email",
    "firstNameAttribute": "givenName",
    "lastNameAttribute": "surname"
  }
}

Config keys

ssoUrl, idpEntityId, spEntityId, assertionConsumerServiceUrl, idpSigningCertificate (one or more PEM certificates, one after another), the assertion-attribute names emailAttribute (defaults to email) / firstNameAttribute / lastNameAttribute, and an optional singleLogoutServiceUrl for federated SLO. Request options: signAuthnRequests (on unless "false"), authnRequestBinding (REDIRECT or POST; POST needs ssoPostUrl) and requireEncryptedAssertions ("true" accepts only encrypted assertions). An option that is not true or false is refused (samlOptionNotBoolean), as is an unknown binding (samlBindingUnknown) or the POST binding without ssoPostUrl (samlPostUrlRequired).

Full endpoint set

Method & path (under /admin/realms/{realm}) Purpose
GET /identity-providers · POST /identity-providers List / create providers
GET · PUT · DELETE /identity-providers/{alias} Read / update / delete a provider
POST /identity-providers/saml/metadata/preview Read an IdP's metadata (metadataXml or metadataUrl) into config values; nothing is stored
GET /identity-providers/saml/sp-defaults?alias= Default SP entity ID and ACS URL for a new connection
GET /identity-providers/{alias}/saml/sp-metadata Download the connection's SP metadata
GET /realms/{realm}/broker/{alias}/saml/metadata (protocol endpoint, public) The same SP metadata, published for the IdP's operator

See Identity providers for the shared flow, and the API reference for every field.

See also