This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.

Management API

Every answer is checked against the model shown here before it is sent, and no answer carries a member its model does not list. A member shown as any JSON is one whose shape belongs to somebody else, and says whose. .{key} is a key that is data, and [] an element of a list.

A refusal

Unless an operation below says otherwise, any status it does not list answers this:

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean    
status integer    
why string    

GET /admin-api/saml-assertions

getSamlAssertions

How long an issued assertion is valid, and the clock skew written into it

The two assertion lifetimes — SAML 2.0 and SAML 1.1 — and the clock skew added to BOTH ENDS of each, which is what this service writes into Conditions/NotBefore and NotOnOrAfter, beside the signing, NameID, artifact and SAML 2.0 encryption choices and the WS-Federation assertion lifetime — sixteen settings in all.

All of them are ordinary configuration settings and appear in GET /config too; settings here is the same row shape, carrying each one’s bounds, its source and its default. assertions beside it is the numbers, and includes saml2WindowS and saml11WindowS — the WHOLE width of the stated window, which is the lifetime plus TWICE the skew and is the figure a caller actually has to reason about. No single setting states it.

THE LIFETIMES ARE PER PROFILE AND THE SKEW IS NOT. SAML 2.0 and SAML 1.1 are separate implementations here, consumed differently, so each has its own lifetime; the skew is a fact about the clocks in the estate this service issues into, which a deployment decides once. The settings reach WS-Trust and WS-Federation as well — their assertions come out of the same two builders — but a WS-Federation sign-in, which carries a SAML 1.1 assertion, has a lifetime of its own, wsfed.assertionLifetimeMin.

saml.clockSkewS IS NOT oauth2.clockSkewS. This one is written INTO a document this service issues. That one is the tolerance applied wherever this service READS one back, including an inbound federation partner’s assertion, and it is on GET /token-lifetimes.

It also reports what has already been issued, per profile, counted against this service’s own clock with no allowance applied.

A WINDOW IS STAMPED INTO AN ASSERTION WHEN IT IS SIGNED, so changing one reaches the next assertion and nothing already issued.

Mirrors GET /admin/saml2 on the admin console.

The reply also carries protocolEndpoints: every endpoint of this family in the realm the call arrived in, as { name, methods, url } (plus route for an HTTP endpoint, transport for a socket, and registered: false for a route the router no longer has).

Scope: admin:read.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The settings, and what has been issued under them.

Member Type Required What it is
assertions object    
assertions.clockSkewS number    
assertions.saml11LifetimeMin number    
assertions.saml11WindowS number    
assertions.saml2LifetimeMin number    
assertions.saml2WindowS number    
assertionsIssued object    
assertionsIssued.byKind list    
assertionsIssued.byKind[].expired number    
assertionsIssued.byKind[].issued number    
assertionsIssued.byKind[].kind string    
assertionsIssued.byKind[].noExpiry number    
assertionsIssued.byKind[].valid number    
assertionsIssued.cap number    
assertionsIssued.forgotten number    
assertionsIssued.held number    
context object    
context.configFile string, or null    
context.defaultsFile string, or null    
context.inRealm boolean    
context.persistenceMode string    
context.persistsAppconfig boolean    
context.persistsRealms boolean    
context.realmId string, or null    
now number    
perApplication list    
perApplication[].attribute string    
perApplication[].profile string    
perApplication[].setting string    
protocolEndpoints list    
protocolEndpoints[].listening boolean    
protocolEndpoints[].methods list, or string    
protocolEndpoints[].methods[] string    
protocolEndpoints[].name string    
protocolEndpoints[].registered boolean    
protocolEndpoints[].route string    
protocolEndpoints[].transport string    
protocolEndpoints[].url string    
rows list    
rows[].field string    
rows[].key string    
rows[].kind string, or null    
rows[].profile string    
rows[].unit string    
seconds map   Each setting in seconds, by key.
seconds.{key} number, or null    
settings list    
settings[].appconfigPath string    
settings[].csvValueNotes map   The sentence beside each value.
settings[].csvValueNotes.{key} string    
settings[].csvValues list    
settings[].csvValues[] string    
settings[].default list, or boolean, or number, or string, or null    
settings[].default[] string    
settings[].description string    
settings[].editRefusal string    
settings[].editable boolean    
settings[].enumValues list    
settings[].enumValues[] string    
settings[].env string, or null    
settings[].group string    
settings[].key string    
settings[].label string    
settings[].legacyEnv string, or null    
settings[].masked boolean    
settings[].max number    
settings[].min number    
settings[].ordered boolean    
settings[].overridden boolean    
settings[].realmSettable boolean    
settings[].restartReason string    
settings[].selectAll map   The rules by kind: onlyWhileOn and aloneWhileOn.
settings[].selectAll.{key} list    
settings[].selectAll.{key}[].canBeOn boolean    
settings[].selectAll.{key}[].on boolean    
settings[].selectAll.{key}[].setting string    
settings[].selectAll.{key}[].values list    
settings[].selectAll.{key}[].values[] string    
settings[].source string    
settings[].step number    
settings[].text string, or null    
settings[].type string    
settings[].value list, or boolean, or number, or string, or null    
settings[].value[] string    

POST /admin-api/saml-assertions/defaults

resetSamlAssertions

Put the SAML assertion settings back

Clears the runtime override on THESE SIXTEEN ONLY, so each falls back to its environment variable, the appconfig file, or env/defaults.js — for the lifetimes sixty minutes each, and no skew at all.

It is deliberately not POST /config/reset-all, which would also drop an override somebody set on an unrelated page.

A setting that was not overridden is skipped rather than refused, because this means “put these back” rather than “undo this one change” — the per-key refusal is on POST /config/reset.

Mirrors POST /admin/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body (optional)

An empty object.

200: The keys that had an override cleared, in cleared.

Member Type Required What it is
applied list    
applied[] string    
changed list    
changed[] string    
cleared list    
cleared[] string    
errors list    
errors[] string    
message string    
ok boolean yes  
settings list    
settings[].appconfigPath string    
settings[].csvValueNotes map   The sentence beside each value.
settings[].csvValueNotes.{key} string    
settings[].csvValues list    
settings[].csvValues[] string    
settings[].default list, or boolean, or number, or string, or null    
settings[].default[] string    
settings[].description string    
settings[].editRefusal string    
settings[].editable boolean    
settings[].enumValues list    
settings[].enumValues[] string    
settings[].env string, or null    
settings[].group string    
settings[].key string    
settings[].label string    
settings[].legacyEnv string, or null    
settings[].masked boolean    
settings[].max number    
settings[].min number    
settings[].ordered boolean    
settings[].overridden boolean    
settings[].realmSettable boolean    
settings[].restartReason string    
settings[].selectAll map   The rules by kind: onlyWhileOn and aloneWhileOn.
settings[].selectAll.{key} list    
settings[].selectAll.{key}[].canBeOn boolean    
settings[].selectAll.{key}[].on boolean    
settings[].selectAll.{key}[].setting string    
settings[].selectAll.{key}[].values list    
settings[].selectAll.{key}[].values[] string    
settings[].source string    
settings[].step number    
settings[].text string, or null    
settings[].type string    
settings[].value list, or boolean, or number, or string, or null    
settings[].value[] string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
applied list    
applied[] string    
changed list    
changed[] string    
cleared list    
cleared[] string    
errors list    
errors[] string    
message string    
ok boolean yes  
settings list    
settings[].appconfigPath string    
settings[].csvValueNotes map   The sentence beside each value.
settings[].csvValueNotes.{key} string    
settings[].csvValues list    
settings[].csvValues[] string    
settings[].default list, or boolean, or number, or string, or null    
settings[].default[] string    
settings[].description string    
settings[].editRefusal string    
settings[].editable boolean    
settings[].enumValues list    
settings[].enumValues[] string    
settings[].env string, or null    
settings[].group string    
settings[].key string    
settings[].label string    
settings[].legacyEnv string, or null    
settings[].masked boolean    
settings[].max number    
settings[].min number    
settings[].ordered boolean    
settings[].overridden boolean    
settings[].realmSettable boolean    
settings[].restartReason string    
settings[].selectAll map   The rules by kind: onlyWhileOn and aloneWhileOn.
settings[].selectAll.{key} list    
settings[].selectAll.{key}[].canBeOn boolean    
settings[].selectAll.{key}[].on boolean    
settings[].selectAll.{key}[].setting string    
settings[].selectAll.{key}[].values list    
settings[].selectAll.{key}[].values[] string    
settings[].source string    
settings[].step number    
settings[].text string, or null    
settings[].type string    
settings[].value list, or boolean, or number, or string, or null    
settings[].value[] string    

POST /admin-api/saml-assertions/set

setSamlAssertions

Set one or more of the SAML assertion settings

A RUNTIME OVERRIDE, like every other change made through this API: written down and re-applied at the next start when persistence.appconfig has a store under it (persistence.realms for a write made inside a realm), and gone on restart only with persistence.mode=memory; the reply’s message says which. Nothing writes to the appconfig file in either case.

Name any of them; the console forms post several at once and a caller may post one. ALL-OR-NOTHING: every value is checked before any is written, so a body with one bad field changes nothing and names it.

UNLIKE POST /config/set-many, a property that is not one of the sixteen is REFUSED rather than ignored, for the reason POST /token-lifetimes/set gives.

THE TWO LIFETIMES ARE MINUTES AND THE SKEW IS SECONDS (the artifact lifetimes are seconds too). That is not a formatting accident: a lifetime is set to a number of minutes to watch an assertion go stale, and a skew is a handful of seconds covering the difference between two machines. The skew is 0 to 300 — five minutes is what Kerberos allows here (krb5.clockSkew), and wider than that the window has stopped being a tolerance. The bounds are on each setting’s row in the GET, so a client can render them rather than repeat them.

The change applies to the NEXT assertion signed. Nothing already issued is affected: a validity window is two attributes inside a signed document.

Mirrors POST /admin/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
saml.clockSkewS integer   Assertion clock skew (s)
saml11.artifactTtlS integer   Artifact lifetime (seconds)
saml11.assertionLifetimeMin integer   Assertion lifetime (minutes)
saml11.nameIdFormat string   Default NameIdentifier format
saml11.signAssertion boolean   Sign the assertion
saml11.signResponse boolean   Sign the response
saml2.artifactTtlS integer   Artifact lifetime (seconds)
saml2.assertionLifetimeMin integer   Assertion lifetime (minutes)
saml2.encryptAssertion boolean   Encrypt the assertion
saml2.encryptLogoutNameId boolean   Encrypt the NameID in a LogoutRequest
saml2.encryptionAlgorithm one of aes256-gcm, aes128-gcm, aes256-cbc, aes128-cbc   Encryption algorithm
saml2.keyTransportAlgorithm one of rsa-oaep-mgf1p, rsa-oaep, rsa-1_5   Key transport algorithm
saml2.nameIdFormat string   Default NameID format
saml2.signAssertion boolean   Sign the assertion
saml2.signResponse boolean   Sign the response
wsfed.assertionLifetimeMin integer   Assertion lifetime (minutes)

200: What was applied, in applied, and what actually changed, in changed.

Member Type Required What it is
applied list    
applied[] string    
changed list    
changed[] string    
cleared list    
cleared[] string    
errors list    
errors[] string    
message string    
ok boolean yes  
settings list    
settings[].appconfigPath string    
settings[].csvValueNotes map   The sentence beside each value.
settings[].csvValueNotes.{key} string    
settings[].csvValues list    
settings[].csvValues[] string    
settings[].default list, or boolean, or number, or string, or null    
settings[].default[] string    
settings[].description string    
settings[].editRefusal string    
settings[].editable boolean    
settings[].enumValues list    
settings[].enumValues[] string    
settings[].env string, or null    
settings[].group string    
settings[].key string    
settings[].label string    
settings[].legacyEnv string, or null    
settings[].masked boolean    
settings[].max number    
settings[].min number    
settings[].ordered boolean    
settings[].overridden boolean    
settings[].realmSettable boolean    
settings[].restartReason string    
settings[].selectAll map   The rules by kind: onlyWhileOn and aloneWhileOn.
settings[].selectAll.{key} list    
settings[].selectAll.{key}[].canBeOn boolean    
settings[].selectAll.{key}[].on boolean    
settings[].selectAll.{key}[].setting string    
settings[].selectAll.{key}[].values list    
settings[].selectAll.{key}[].values[] string    
settings[].source string    
settings[].step number    
settings[].text string, or null    
settings[].type string    
settings[].value list, or boolean, or number, or string, or null    
settings[].value[] string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
applied list    
applied[] string    
changed list    
changed[] string    
cleared list    
cleared[] string    
errors list    
errors[] string    
message string    
ok boolean yes  
settings list    
settings[].appconfigPath string    
settings[].csvValueNotes map   The sentence beside each value.
settings[].csvValueNotes.{key} string    
settings[].csvValues list    
settings[].csvValues[] string    
settings[].default list, or boolean, or number, or string, or null    
settings[].default[] string    
settings[].description string    
settings[].editRefusal string    
settings[].editable boolean    
settings[].enumValues list    
settings[].enumValues[] string    
settings[].env string, or null    
settings[].group string    
settings[].key string    
settings[].label string    
settings[].legacyEnv string, or null    
settings[].masked boolean    
settings[].max number    
settings[].min number    
settings[].ordered boolean    
settings[].overridden boolean    
settings[].realmSettable boolean    
settings[].restartReason string    
settings[].selectAll map   The rules by kind: onlyWhileOn and aloneWhileOn.
settings[].selectAll.{key} list    
settings[].selectAll.{key}[].canBeOn boolean    
settings[].selectAll.{key}[].on boolean    
settings[].selectAll.{key}[].setting string    
settings[].selectAll.{key}[].values list    
settings[].selectAll.{key}[].values[] string    
settings[].source string    
settings[].step number    
settings[].text string, or null    
settings[].type string    
settings[].value list, or boolean, or number, or string, or null    
settings[].value[] string