This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.
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 |