Using the SAML workflow
Copied from the id-proto-debugger release 0.9.3 user guide, which is the debugger this service embeds. Its addresses are the embedded ones: the debugger is
https://localhost:8444/and its apihttps://localhost:8444/api. Accessing the debugger says how to reach, enable and disable it.
The SAML workflow is the SAML Protocol card on the landing page. It is
two pages. saml_request.html builds the request and sends it to an identity
provider. saml_response.html shows the response that came back to the
assertion consumer service.
Protocol Version defaults to SAML 2.0. SAML 1.1 is a different exchange and has its own page. SAML 1.0 (reference only) fills the form and does not complete a sign-in.
These pages have no screenshots. The pictures in the OAuth2 / OIDC guide come from the Selenium jobs, and those jobs were not re-run for this pass.
Before you start
Open https://localhost:8444/ and sign in as a console administrator
(Accessing the debugger), then pick SAML Protocol.
The assertion consumer and the single logout endpoint are on the API service
(https://localhost:8444/api). A deployed static site has no API, so Call
IdP has nowhere to land the response.
Point it at iya-sts
On a fresh browser the form is filled with Keycloak-shaped placeholders,
all http://localhost:8080/samlp/.... If Metadata Document URL is
empty, the page writes the local default, which is also Keycloak:
http://localhost:8080/realms/debugger-testing/protocol/saml/descriptor
SP entityID and ACS URL are filled the same way when they are empty:
| Field | Filled with |
|---|---|
| SP entityID | https://localhost:8444/saml/sp |
| ACS URL | https://localhost:8444/api/samlacs |
iya-sts answers SAML 2.0 at
https://localhost:8081. Put one of these in Metadata Document URL and
click Load Metadata:
https://localhost:8081/saml2/metadata— one document for any service provider.https://localhost:8081/saml2/metadata/app-<12 hex>— the document for one service provider. The twelve hex characters are the start of the SHA-256 of the SP entityID. The test launchers use this form. iya-sts mints the document when you ask for it.
SAML 1.1 metadata is the same slug under
https://localhost:8081/saml11/metadata/.
iya-sts signs a person in with any username. The literal password
invalid is refused, so a failed sign-in stays reachable. Any other
password is accepted.
Load Metadata replaces the placeholder entityID, the SSO and SLO URLs, the artifact resolution service, the NameID formats, and the signer certificate with what that document says. Upload Metadata does the same from a file, with no fetch.
IdP Metadata
| Field or button | Default | What it does |
|---|---|---|
| Metadata Document URL | the Keycloak URL above, once the page has run | Where Load Metadata fetches the descriptor. |
| Load Metadata | Fetches that URL and fills Configuration Parameters. | |
| Upload Metadata | Opens a file picker (.xml) and parses the file. |
|
| Metadata Document | empty | The raw XML, read-only, with Copy. |
Configuration Parameters
These values are what a fresh page shows before you load metadata. After Load Metadata they are the identity provider’s.
| Field | Placeholder on a fresh page |
|---|---|
| IdP entityID | http://localhost:8080/samlp/metadata |
| HTTP-POST binding URL | http://localhost:8080/samlp/sso/post |
| HTTP-Redirect (GET) binding URL | http://localhost:8080/samlp/sso/redirect |
| HTTP-Artifact binding URL | http://localhost:8080/samlp/sso/artifact. The label says this URL is not needed for an artifact response. |
| Artifact Resolution Service (SOAP) | http://localhost:8080/samlp/ars |
| HTTP-POST logout URL | http://localhost:8080/samlp/slo/post |
| HTTP-Redirect (GET) logout URL | http://localhost:8080/samlp/slo/redirect |
| HTTP-Artifact logout URL | http://localhost:8080/samlp/slo/artifact |
| Supported NameIDFormat | filled from metadata. Empty until a document is loaded. |
| Signer Certificate | a sample certificate, subject saml-debugger-sp-test. Load Metadata replaces it with the IdP signing certificate. View signer certificate details opens Certificate Details. |
Single logout fields are hidden when the protocol version has no logout. See SAML 1.1.
SP / Request Settings
| Field | Default | What it does |
|---|---|---|
| Protocol Version | SAML 2.0 | Also SAML 1.1 and SAML 1.0 (reference only). Changing it greys out the settings that version does not have. |
| Request binding | HTTP-Redirect (GET) | Or HTTP-POST. There is no artifact option for the request. |
| Response binding (ProtocolBinding) | HTTP-POST | Or HTTP-Artifact. This is how the response comes back, which is separate from how the request goes out. |
| Username hint | empty | Optional. The selected NameID format constrains what you may type. |
| SP entityID | https://localhost:8444/saml/sp |
The Issuer of the AuthnRequest, when the field was empty. |
| ACS URL | https://localhost:8444/api/samlacs |
Where the IdP posts the response, when the field was empty. |
| Digitally sign the AuthnRequest | on | Hides the key-pair fields when you clear it. |
| Signature Algorithm | RSA-SHA256 | Also RSA-SHA1, RSA-SHA384, RSA-SHA512. After the page loads, a further group is added: Post-quantum — draft-eastlake-rfc9231bis-xmlsec-uris. Those sixteen methods are described in Post-quantum XML Signature. |
| Key Size | 2048 | Also 3072 and 4096, for a generated RSA pair. |
| Generate Keys | A fresh RSA pair and a self-signed SP certificate. | |
| Download | The pair as PEM. | |
| Private Signer Key / Public Signer Certificate | empty | PKCS#8 PEM and the certificate. Register the certificate at the IdP if it checks the request signature. |
| Save this key pair in browser localStorage | on | Clearing it removes the pair already stored. The response page needs the private key to decrypt an encrypted assertion. With saving off, use Download and paste the key into Decryption Key on the response page. |
| Encrypt the AuthnRequest | off | The note on the form says Keycloak and most IdPs do not accept an encrypted AuthnRequest. Encryption runs in the browser, after the signature. |
| Encryption Certificate | empty until metadata is loaded | The IdP certificate that wraps the session key. |
| Encrypted Type | Element (whole AuthnRequest) | Or Content (children only). |
| Canonicalization | None (serialize as-is) | Or exclusive or inclusive C14N 1.0. |
| Data Encryption Algorithm | AES-256-GCM | Also AES-192-GCM, AES-128-GCM, AES-256/192/128-CBC, Triple DES CBC. |
| Key Transport Algorithm | RSA-OAEP (xmlenc11) | Also RSA-OAEP-MGF1P and RSA-1_5. |
| Key Transport Digest (OAEP) | SHA-256 | Also SHA-1, SHA-384, SHA-512. |
| MGF (RSA-OAEP xmlenc11) | MGF1 with SHA-256 | Also SHA-1, SHA-384, SHA-512. |
| Add WS-Addressing headers | off | SOAP headers on the artifact-resolution call only. They do not change a redirect or POST AuthnRequest. |
| wsa:To | the artifact resolution URL, if blank | |
| wsa:Action | empty | |
| wsa:ReplyTo | placeholder http://www.w3.org/2005/08/addressing/anonymous |
|
| wsa:From | empty | |
| wsa:MessageID | a urn:uuid: value if blank |
|
| Generated AuthnRequest | rebuilt as you edit | Read-only. Copy is on the label. For the redirect binding this is the signed request URL. |
Call IdP signs the request (when signing is on) and sends it to the SSO URL for the request binding you chose.
Logout builds a signed LogoutRequest for the last session. It is unavailable for SAML 1.1.
Download SP Metadata saves this service provider’s EntityDescriptor, to register at the identity provider.
The response page
saml_response.html opens when the API has caught the response.
| Pane | What you do there |
|---|---|
| SAMLResponse | XML is the full response. Details is the parsed status and the bindings. |
| Assertion (extracted) | XML and Attributes. Validate Signature checks the enveloped signature with the certificate in KeyInfo. Decrypt uses Decryption Key, prefilled from the SP private key when that key was saved. |
| Tools | Request decoder, response decoder, assertion tool, certificate details, and the PKI page. See SAML decoders and SAML Assertion Tool. |
| Operations History | The same log as the request page. Clear History drops it. A response turns the matching Sent row into Success or Failure from the status code. |
What the browser keeps
Endpoints, the entityIDs, the bindings, and the certificates are stored in
localStorage. The SP private key is stored only while Save this key pair
in browser localStorage is checked. There is no password field on this
workflow.