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/sessions
getSessions
Every session this service is holding right now, across the three protocols that have one
WHAT IS LIVE, as opposed to what has been ISSUED — which is GET /admin-api/tokens, and everything in that list outlives everything in this one.
A session is state THIS SERVICE holds that makes somebody currently authenticated. Three protocols here have one and the other seven do not:
- the browser sign-on session from
/authn/login, which OAuth 2.0 / OIDC, WS-Federation, SAML 2.0, SAML 1.1 and the admin console all share — so one row may be carrying relying parties, realms and service providers at once, andprotocolsays which protocol the sign-in came THROUGH whilecarriessays what is riding on it; - the Kerberos ticket-granting ticket, because a TGT is the Kerberos session and a service ticket is one use of it;
- the LDAP connection, because RFC 4511 section 4.2 makes a Bind the authorization state of a CONNECTION.
THE EXPIRY IS WORKED OUT DIFFERENTLY IN EACH AND expiryRule SAYS HOW. A browser session expires at an absolute instant fixed when it was created (authn.sessionLifetimeS) and is NOT extended by use; authn.sessionIdleTimeoutS, off by default, ends one earlier when it goes unused. A TGT expires at the endtime the KDC sealed into the ticket, which nothing can move. An LDAP connection has NO EXPIRY and answers expiresAt: 0, which is not an expiry of the epoch.
Every row carries the key and id that POST /admin-api/sessions/revoke takes, and — for a browser session — the sessionId that GET /admin-api/tokens?session= takes.
Mirrors GET /admin/sessions on the admin console.
Scope: admin:read.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
q |
query | string | Narrows to rows whose username, subject, handle, identity key, kind or protocol contains this. One box over all of them, because a reader arrives holding exactly one and does not know which. | |
protocol |
query | string | Only sessions started through this protocol. The protocol values in the reply are what there is to ask for; they are read off the live rows rather than written down, because a federated sign-in names the relationship it came through. |
|
anonymousPage |
query | integer | Which page of unauthenticatedSessions, the sessions that authenticated nobody. They are never filtered, and unauthenticatedHeld counts them all. It shares per with the live list. |
|
page |
query | integer | Which page of the match to return. CLAMPED rather than refused: a page past the end returns the last one, and the reply says which page it actually is. | |
per |
query | integer | Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own. | |
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 live sessions, filtered and paged.
| Member | Type | Required | What it is |
|---|---|---|---|
accountChoices |
object | ||
accountChoices.counts |
map | ||
accountChoices.counts.{key} |
number | ||
accountChoices.enabled |
boolean | ||
at |
number | ||
expiryRules |
map | ||
expiryRules.{key} |
string | ||
filter |
object | ||
filter.protocol |
string, or null | ||
filter.q |
string, or null | ||
firstRow |
integer | ||
held |
number | ||
heldByKind |
map | ||
heldByKind.{key} |
number | ||
installed |
boolean | ||
lastRow |
integer | ||
matched |
number | ||
note |
string | ||
page |
integer | ||
pages |
integer | ||
paging |
object | ||
paging.firstRow |
integer | ||
paging.lastRow |
integer | ||
paging.noun |
string | ||
paging.page |
integer | ||
paging.pages |
integer | ||
paging.param |
string | ||
paging.perPage |
integer | ||
paging.total |
integer | ||
perPage |
integer | ||
protocols |
list | ||
protocols[] |
string | ||
sessions |
list | ||
sessions[] |
object | One live session of any kind. | |
sessions[].accountSet |
string | ||
sessions[].acr |
string | ||
sessions[].amr |
list, or string | ||
sessions[].amr[] |
string | ||
sessions[].authenticated |
boolean | ||
sessions[].carries |
list | ||
sessions[].carries[] |
string | ||
sessions[].derivedFrom |
string | ||
sessions[].detail |
string | ||
sessions[].deviceBound |
object | ||
sessions[].deviceBound.alg |
string | ||
sessions[].deviceBound.bound |
boolean | ||
sessions[].deviceBound.boundAt |
number | ||
sessions[].deviceBound.fact |
string | ||
sessions[].deviceBound.reasons |
list | ||
sessions[].deviceBound.reasons[] |
string | ||
sessions[].deviceBound.refreshedAt |
number | ||
sessions[].deviceBound.refreshes |
number | ||
sessions[].expiresAt |
number | ||
sessions[].expiryRule |
string | ||
sessions[].family |
string | ||
sessions[].handle |
string | ||
sessions[].id |
string | ||
sessions[].key |
string | ||
sessions[].kind |
string | ||
sessions[].protocol |
string | ||
sessions[].rpClientId |
string | ||
sessions[].sessionId |
string | ||
sessions[].startedAt |
number | ||
sessions[].sub |
string | ||
sessions[].terminable |
boolean | ||
sessions[].username |
string | ||
sessions[].why |
string | ||
shown |
number | ||
unauthenticatedHeld |
number | ||
unauthenticatedKept |
boolean | ||
unauthenticatedPaging |
object | ||
unauthenticatedPaging.firstRow |
integer | ||
unauthenticatedPaging.lastRow |
integer | ||
unauthenticatedPaging.noun |
string | ||
unauthenticatedPaging.page |
integer | ||
unauthenticatedPaging.pages |
integer | ||
unauthenticatedPaging.param |
string | ||
unauthenticatedPaging.perPage |
integer | ||
unauthenticatedPaging.total |
integer | ||
unauthenticatedSessions |
list | ||
unauthenticatedSessions[] |
object | One live session of any kind. | |
unauthenticatedSessions[].accountSet |
string | ||
unauthenticatedSessions[].acr |
string | ||
unauthenticatedSessions[].amr |
list, or string | ||
unauthenticatedSessions[].amr[] |
string | ||
unauthenticatedSessions[].authenticated |
boolean | ||
unauthenticatedSessions[].carries |
list | ||
unauthenticatedSessions[].carries[] |
string | ||
unauthenticatedSessions[].derivedFrom |
string | ||
unauthenticatedSessions[].detail |
string | ||
unauthenticatedSessions[].deviceBound |
object | ||
unauthenticatedSessions[].deviceBound.alg |
string | ||
unauthenticatedSessions[].deviceBound.bound |
boolean | ||
unauthenticatedSessions[].deviceBound.boundAt |
number | ||
unauthenticatedSessions[].deviceBound.fact |
string | ||
unauthenticatedSessions[].deviceBound.reasons |
list | ||
unauthenticatedSessions[].deviceBound.reasons[] |
string | ||
unauthenticatedSessions[].deviceBound.refreshedAt |
number | ||
unauthenticatedSessions[].deviceBound.refreshes |
number | ||
unauthenticatedSessions[].expiresAt |
number | ||
unauthenticatedSessions[].expiryRule |
string | ||
unauthenticatedSessions[].family |
string | ||
unauthenticatedSessions[].handle |
string | ||
unauthenticatedSessions[].id |
string | ||
unauthenticatedSessions[].key |
string | ||
unauthenticatedSessions[].kind |
string | ||
unauthenticatedSessions[].protocol |
string | ||
unauthenticatedSessions[].rpClientId |
string | ||
unauthenticatedSessions[].sessionId |
string | ||
unauthenticatedSessions[].startedAt |
number | ||
unauthenticatedSessions[].sub |
string | ||
unauthenticatedSessions[].terminable |
boolean | ||
unauthenticatedSessions[].username |
string | ||
unauthenticatedSessions[].why |
string | ||
windowed |
boolean |
400: The answer.
| Member | Type | Required | What it is |
|---|---|---|---|
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes |
POST /admin-api/sessions/end-all
endAllSessions
End every sign-on session in this realm
Every session started before now ends the next time it is read. The cost does not grow with the number of sessions. Issued tokens are not revoked: use /admin-api/tokens/revoke-all as well.
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. |
200: Every session has ended.
| Member | Type | Required | What it is |
|---|---|---|---|
message |
string | yes | |
ok |
boolean | yes |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
accepted |
boolean | ||
error |
string | ||
error_description |
string | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
run |
string | The address to follow the run at. | |
runId |
string |
POST /admin-api/sessions/revoke
revokeSession
End one live session
The Revoke button on every row of /admin/sessions, driven without a browser. It is terminate() with a selection of one — the SAME function a global logout goes through — so it writes the same audit row, honours the same two settings and gives the same refusals.
IT IS NOT ONE ACT ACROSS THE THREE KINDS AND THE DIFFERENCE MATTERS. On a browser session it ends that session and everything hanging off it: the relying parties are notified, the refresh tokens issued on it are revoked. On an LDAP row it closes the socket, which the client sees as its connection dropping mid-conversation. On a Kerberos row it does MORE than the row it names — it stamps a sign-out instant on the PRINCIPAL, after which every ticket-granting ticket that principal authenticated before now is refused KDC_ERR_TGT_REVOKED (20), because Kerberos has no per-ticket revocation. It still reaches no service ticket already in a cache: accepting one never contacts this KDC. Every row’s why says which of the three it is before it is pressed.
A row that names nothing any more — it ended between the read and the write — answers 400 saying so rather than 200 having done nothing, and the whole terminate() result is in result.
Mirrors POST /admin/sessions 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 |
|---|---|---|---|
key |
string | yes | Whose session it is: the normalised identity key, which every row of GET /admin-api/sessions carries as key. The termination is keyed on an identity, which is why this is needed beside the id. |
select |
string | yes | Which session, in the form the list gives it as id: session:…, ldap:… or krb5:…@REALM. It is the identifier POST /admin-api/logout/selective takes too, because both go through one termination. |
200: What was ended, or why it could not be. The whole termination result is in result, including skipped and unknown.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
result |
object | ||
result.acrossCluster |
list | ||
result.acrossCluster[].at |
string, or number, or null | ||
result.acrossCluster[].family |
string | ||
result.acrossCluster[].message |
string | ||
result.backchannel |
list | ||
result.backchannel[].attempts |
number | ||
result.backchannel[].clientId |
string | ||
result.backchannel[].encrypted |
string | ||
result.backchannel[].finishedAt |
string | ||
result.backchannel[].generation |
number | ||
result.backchannel[].holder |
string | ||
result.backchannel[].id |
string | ||
result.backchannel[].inFlight |
boolean | ||
result.backchannel[].iss |
string | ||
result.backchannel[].lastAttemptAt |
string | ||
result.backchannel[].nextAttemptAt |
string | ||
result.backchannel[].queuedAt |
string | ||
result.backchannel[].realm |
string | ||
result.backchannel[].sessionId |
string | ||
result.backchannel[].sessionRequired |
boolean | ||
result.backchannel[].sid |
string | ||
result.backchannel[].state |
string | ||
result.backchannel[].status |
number, or null | ||
result.backchannel[].sub |
string | ||
result.backchannel[].trigger |
string | ||
result.backchannel[].uri |
string | ||
result.backchannel[].via |
string | ||
result.backchannel[].why |
string, or null | ||
result.cleanups |
list | ||
result.cleanups[].realm |
string | ||
result.cleanups[].url |
string | ||
result.cleanups[].why |
string | ||
result.cleanups[].wreply |
string | ||
result.key |
string | ||
result.logoutRequests |
list | ||
result.logoutRequests[].destination |
string | ||
result.logoutRequests[].entityId |
string | ||
result.logoutRequests[].from |
string | ||
result.logoutRequests[].url |
string | ||
result.logoutRequests[].why |
string | ||
result.message |
string | ||
result.notifications |
list | ||
result.notifications[].clientId |
string | ||
result.notifications[].sessionRequired |
boolean | ||
result.notifications[].uri |
string | ||
result.notifications[].url |
string | ||
result.notifications[].why |
string | ||
result.ok |
boolean | ||
result.partnerLogouts |
list | ||
result.partnerLogouts[].action |
string | ||
result.partnerLogouts[].fields |
map | ||
result.partnerLogouts[].fields.{key} |
string | ||
result.partnerLogouts[].kind |
string | ||
result.partnerLogouts[].label |
string | ||
result.partnerLogouts[].protocol |
string | ||
result.partnerLogouts[].relationship |
string | ||
result.partnerLogouts[].url |
string | ||
result.partnerLogouts[].what |
string | ||
result.scope |
string | ||
result.skipped |
list | ||
result.skipped[].family |
string | ||
result.skipped[].id |
string | ||
result.skipped[].kind |
string | ||
result.skipped[].label |
string | ||
result.skipped[].message |
string | ||
result.skipped[].pending |
boolean | ||
result.terminated |
list | ||
result.terminated[].family |
string | ||
result.terminated[].id |
string | ||
result.terminated[].kind |
string | ||
result.terminated[].label |
string | ||
result.terminated[].message |
string | ||
result.terminated[].pending |
boolean | ||
result.unknown |
list | ||
result.unknown[] |
string |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
result |
object | ||
result.acrossCluster |
list | ||
result.acrossCluster[].at |
string, or number, or null | ||
result.acrossCluster[].family |
string | ||
result.acrossCluster[].message |
string | ||
result.backchannel |
list | ||
result.backchannel[].attempts |
number | ||
result.backchannel[].clientId |
string | ||
result.backchannel[].encrypted |
string | ||
result.backchannel[].finishedAt |
string | ||
result.backchannel[].generation |
number | ||
result.backchannel[].holder |
string | ||
result.backchannel[].id |
string | ||
result.backchannel[].inFlight |
boolean | ||
result.backchannel[].iss |
string | ||
result.backchannel[].lastAttemptAt |
string | ||
result.backchannel[].nextAttemptAt |
string | ||
result.backchannel[].queuedAt |
string | ||
result.backchannel[].realm |
string | ||
result.backchannel[].sessionId |
string | ||
result.backchannel[].sessionRequired |
boolean | ||
result.backchannel[].sid |
string | ||
result.backchannel[].state |
string | ||
result.backchannel[].status |
number, or null | ||
result.backchannel[].sub |
string | ||
result.backchannel[].trigger |
string | ||
result.backchannel[].uri |
string | ||
result.backchannel[].via |
string | ||
result.backchannel[].why |
string, or null | ||
result.cleanups |
list | ||
result.cleanups[].realm |
string | ||
result.cleanups[].url |
string | ||
result.cleanups[].why |
string | ||
result.cleanups[].wreply |
string | ||
result.key |
string | ||
result.logoutRequests |
list | ||
result.logoutRequests[].destination |
string | ||
result.logoutRequests[].entityId |
string | ||
result.logoutRequests[].from |
string | ||
result.logoutRequests[].url |
string | ||
result.logoutRequests[].why |
string | ||
result.message |
string | ||
result.notifications |
list | ||
result.notifications[].clientId |
string | ||
result.notifications[].sessionRequired |
boolean | ||
result.notifications[].uri |
string | ||
result.notifications[].url |
string | ||
result.notifications[].why |
string | ||
result.ok |
boolean | ||
result.partnerLogouts |
list | ||
result.partnerLogouts[].action |
string | ||
result.partnerLogouts[].fields |
map | ||
result.partnerLogouts[].fields.{key} |
string | ||
result.partnerLogouts[].kind |
string | ||
result.partnerLogouts[].label |
string | ||
result.partnerLogouts[].protocol |
string | ||
result.partnerLogouts[].relationship |
string | ||
result.partnerLogouts[].url |
string | ||
result.partnerLogouts[].what |
string | ||
result.scope |
string | ||
result.skipped |
list | ||
result.skipped[].family |
string | ||
result.skipped[].id |
string | ||
result.skipped[].kind |
string | ||
result.skipped[].label |
string | ||
result.skipped[].message |
string | ||
result.skipped[].pending |
boolean | ||
result.terminated |
list | ||
result.terminated[].family |
string | ||
result.terminated[].id |
string | ||
result.terminated[].kind |
string | ||
result.terminated[].label |
string | ||
result.terminated[].message |
string | ||
result.terminated[].pending |
boolean | ||
result.unknown |
list | ||
result.unknown[] |
string |