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/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, and protocol says which protocol the sign-in came THROUGH while carries says 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