This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.
Who holds a role, and what requires one. A role is a name a person, a GROUP or an APPLICATION can be mapped into, and holding one is what an ISSUANCE is decided on — which is the whole difference from Groups above, where a group grants nothing. The decision is made by the XACML PDP against a policy, never by an if in an issuance site, so a refusal is a document somebody can read. It is not Admin roles either: those are two directory groups that grant the /admin console and nothing else.
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/roles
getRoles
Who holds a role, and what requires one
The role register, both relations.
A role is a name somebody may hold, and holding one is what an ISSUANCE is decided on. Three kinds of thing can be mapped into one — a person, a GROUP (so every member of it holds the role, resolved at decision time) and an APPLICATION, which is what a client_credentials grant is decided on where there is no person at all.
roles is MEMBERSHIP and requiring is REQUIREMENT, and they are opposite. Membership is stored on the ROLE entry under ou=roles and is written through this resource. A requirement is appRequiredRole on an APPLICATION’s own entry and is written through POST /admin-api/applications/add — one store, one door that writes it. It is READ here because this is the only surface that can resolve it: requiring[].unknown names a role an application demands that NOTHING defines, which refuses everybody, silently and correctly, and looks exactly like the application being broken.
Only NARROWED applications are in requiring. An application that names no required role requires EVERYBODY, everybody holds EVERYBODY, and nothing is refused — which is how this service behaved before roles existed and is what makes the feature off by default without being absent.
The six builtIn roles are COMPUTED and in no container. They cannot be created, edited or deleted, they have no members, and every one of them is answered from the CONTEXT of the decision being made. They are never in the roles claim either: EVERYBODY and ALL_AUTHENTICATED_USERS are true of almost every token this service issues, so carrying them would tell a relying party nothing it did not know from holding the token.
gated: false means the XACML family is not loaded in this process, so common/issuance_gate.js has no decider and every issuance is allowed whatever this register says. enforced: false means roles.enforceIssuance is off, which is the same outcome by a different route and is the way back if a policy edit locks something out.
Mirrors GET /admin/roles on the admin console.
Scope: admin:read.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
q |
query | string | Narrows the configured roles to those whose name, description or a member contains this. | |
role |
query | string | One role’s name (#604): the answer also carries role — the role in full, its owners resolved, requiredBy (the applications whose requirement names it) and its directory entry — or role.found: false. |
|
rolesPage |
query | integer | Which page of the configured roles the search matched, answered by paging and shownRoles; twenty-five by default. |
|
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. | |
requiringPage |
query | integer | Which page of requiring to return, answered by requiringPaging. The applications that narrowed the roles they require (#313); requiringPaging says where the page is and counts.requiring counts them all. |
|
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 six built-in roles, every configured role with its three membership lists, every application that has been narrowed, and whether the decision is being asked for at all.
| Member | Type | Required | What it is |
|---|---|---|---|
actions |
list | ||
actions[] |
string | ||
applicationChoices |
list | ||
applicationChoices[].identifier |
string | ||
applicationChoices[].name |
string | ||
builtIn |
list | ||
builtIn[].builtIn |
boolean | ||
builtIn[].name |
string | ||
builtIn[].what |
string | ||
claim |
boolean | ||
claimName |
string | ||
container |
string, or null | ||
counts |
object | ||
counts.builtIn |
number | ||
counts.configured |
number | ||
counts.members |
number | ||
counts.requiring |
number | ||
counts.unsatisfiable |
number | ||
defaultRequired |
list, or string | ||
defaultRequired[] |
string | ||
enforced |
boolean | ||
gated |
boolean | ||
issuanceKinds |
list | ||
issuanceKinds[] |
string | ||
matched |
number | ||
memberKinds |
list | ||
memberKinds[].field |
string | ||
memberKinds[].kind |
string | ||
memberKinds[].label |
string | ||
memberKinds[].what |
string | ||
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 | ||
permissionIds |
list | ||
permissionIds[] |
string | ||
permissions |
list | ||
permissions[].application |
string | ||
permissions[].gated |
boolean | ||
permissions[].id |
string | ||
permissions[].name |
string | ||
policy |
object | ||
policy.builtIn |
boolean | ||
policy.effect |
string | ||
policy.enabled |
boolean, or null | ||
policy.entry |
boolean | ||
policy.name |
string | ||
policy.ok |
boolean | ||
policy.readsRisk |
boolean | ||
policy.setting |
string | ||
policy.template |
string | ||
policy.why |
string | ||
query |
object | ||
query.q |
string | ||
requiring |
list | ||
requiring[].application |
string | ||
requiring[].name |
string | ||
requiring[].required |
list | ||
requiring[].required[] |
string | ||
requiring[].unknown |
list | ||
requiring[].unknown[] |
string | ||
requiringPaging |
object | ||
requiringPaging.firstRow |
integer | ||
requiringPaging.lastRow |
integer | ||
requiringPaging.noun |
string | ||
requiringPaging.page |
integer | ||
requiringPaging.pages |
integer | ||
requiringPaging.param |
string | ||
requiringPaging.perPage |
integer | ||
requiringPaging.total |
integer | ||
role |
object | ||
role.application |
string | ||
role.applications |
list | ||
role.applications[] |
string | ||
role.builtIn |
boolean | ||
role.canWrite |
boolean | ||
role.conferredBy |
list | ||
role.conferredBy[] |
string | ||
role.console |
boolean | ||
role.description |
string | ||
role.displayName |
string | ||
role.dn |
string | ||
role.entry |
object | ||
role.entry.attributes |
map | ||
role.entry.attributes.{key} |
list, or string | ||
role.entry.attributes.{key}[] |
string | ||
role.entry.createdAt |
string, or number, or null | ||
role.entry.dn |
string | ||
role.entry.modifiedAt |
string, or number, or null | ||
role.entry.operational |
list | ||
role.entry.operational[] |
string | ||
role.entry.origin |
string | ||
role.found |
boolean | ||
role.groups |
list | ||
role.groups[] |
string | ||
role.holderCount |
number | ||
role.id |
string | ||
role.localName |
string | ||
role.maxOwners |
number | ||
role.memberTypes |
list | ||
role.memberTypes[] |
string | ||
role.name |
string | ||
role.native |
boolean | ||
role.ownerProtected |
boolean | ||
role.owners |
one of 2 shapes | ||
role.owners (shape 1) |
list | ||
role.owners (shape 1)[] |
string | ||
role.owners (shape 2) |
list | ||
role.owners (shape 2)[].dn |
string | ||
role.owners (shape 2)[].kind |
string | ||
role.owners (shape 2)[].name |
string | ||
role.owners (shape 2)[].present |
boolean | ||
role.ownership |
object | ||
role.ownership.kind |
string | ||
role.ownership.marked |
boolean | ||
role.ownership.name |
string | ||
role.ownership.protected |
boolean | ||
role.ownership.reasons |
list | ||
role.ownership.reasons[] |
string | ||
role.permissions |
list | ||
role.permissions[] |
string | ||
role.requiredBy |
list | ||
role.requiredBy[].application |
string | ||
role.requiredBy[].name |
string | ||
role.users |
list | ||
role.users[] |
string | ||
role.what |
string | ||
roles |
list | ||
roles[].application |
string | ||
roles[].applications |
list | ||
roles[].applications[] |
string | ||
roles[].builtIn |
boolean | ||
roles[].conferredBy |
list | ||
roles[].conferredBy[] |
string | ||
roles[].console |
boolean | ||
roles[].description |
string | ||
roles[].displayName |
string | ||
roles[].dn |
string | ||
roles[].groups |
list | ||
roles[].groups[] |
string | ||
roles[].id |
string | ||
roles[].localName |
string | ||
roles[].memberTypes |
list | ||
roles[].memberTypes[] |
string | ||
roles[].name |
string | ||
roles[].native |
boolean | ||
roles[].ownerProtected |
boolean | ||
roles[].owners |
list | ||
roles[].owners[] |
string | ||
roles[].permissions |
list | ||
roles[].permissions[] |
string | ||
roles[].users |
list | ||
roles[].users[] |
string | ||
settings |
object | ||
settings.context |
object | ||
settings.context.configFile |
string, or null | ||
settings.context.defaultsFile |
string, or null | ||
settings.context.inRealm |
boolean | ||
settings.context.persistenceMode |
string | ||
settings.context.persistsAppconfig |
boolean | ||
settings.context.persistsRealms |
boolean | ||
settings.context.realmId |
string | ||
settings.editableCount |
integer | ||
settings.groups |
list | ||
settings.groups[].group |
string | ||
settings.groups[].settings |
list | ||
settings.groups[].settings[].appconfigPath |
string | ||
settings.groups[].settings[].csvValueNotes |
map | ||
settings.groups[].settings[].csvValueNotes.{key} |
string | ||
settings.groups[].settings[].csvValues |
list | ||
settings.groups[].settings[].csvValues[] |
string, or number, or boolean, or null | ||
settings.groups[].settings[].default |
list, or string, or number, or boolean, or null | ||
settings.groups[].settings[].default[] |
string, or number, or boolean, or null | ||
settings.groups[].settings[].description |
string | ||
settings.groups[].settings[].editRefusal |
string | ||
settings.groups[].settings[].editable |
boolean | ||
settings.groups[].settings[].enumValues |
list | ||
settings.groups[].settings[].enumValues[] |
string, or number, or boolean, or null | ||
settings.groups[].settings[].env |
list, or string | ||
settings.groups[].settings[].env[] |
string | ||
settings.groups[].settings[].group |
string | ||
settings.groups[].settings[].key |
string | ||
settings.groups[].settings[].label |
string | ||
settings.groups[].settings[].legacyEnv |
list, or string | ||
settings.groups[].settings[].legacyEnv[] |
string | ||
settings.groups[].settings[].masked |
boolean | ||
settings.groups[].settings[].max |
number | ||
settings.groups[].settings[].min |
number | ||
settings.groups[].settings[].ordered |
boolean | ||
settings.groups[].settings[].overridden |
boolean | ||
settings.groups[].settings[].realmSettable |
boolean | ||
settings.groups[].settings[].restartReason |
string | ||
settings.groups[].settings[].selectAll |
object | ||
settings.groups[].settings[].selectAll.aloneWhileOn |
list | ||
settings.groups[].settings[].selectAll.aloneWhileOn[].canBeOn |
object | Nested deeper than this page draws. | |
settings.groups[].settings[].selectAll.aloneWhileOn[].on |
object | Nested deeper than this page draws. | |
settings.groups[].settings[].selectAll.aloneWhileOn[].setting |
object | Nested deeper than this page draws. | |
settings.groups[].settings[].selectAll.aloneWhileOn[].values |
object | Nested deeper than this page draws. | |
settings.groups[].settings[].selectAll.onlyWhileOn |
list | ||
settings.groups[].settings[].selectAll.onlyWhileOn[].canBeOn |
object | Nested deeper than this page draws. | |
settings.groups[].settings[].selectAll.onlyWhileOn[].on |
object | Nested deeper than this page draws. | |
settings.groups[].settings[].selectAll.onlyWhileOn[].setting |
object | Nested deeper than this page draws. | |
settings.groups[].settings[].selectAll.onlyWhileOn[].values |
object | Nested deeper than this page draws. | |
settings.groups[].settings[].source |
string | ||
settings.groups[].settings[].step |
number | ||
settings.groups[].settings[].text |
string, or null | ||
settings.groups[].settings[].type |
string | ||
settings.groups[].settings[].value |
list, or string, or number, or boolean, or null | ||
settings.groups[].settings[].value[] |
string, or number, or boolean, or null | ||
settings.overridden |
list | ||
settings.overridden[] |
string | ||
settings.page |
string | ||
settings.setWith |
string | ||
settings.settingCount |
integer | ||
settings.sharedWith |
map | ||
settings.sharedWith.{key} |
list | ||
settings.sharedWith.{key}[] |
object, or string | ||
settings.sharedWith.{key}[].label |
string | ||
settings.sharedWith.{key}[].path |
string | ||
shown |
number | ||
shownRoles |
list | ||
shownRoles[].application |
string | ||
shownRoles[].applications |
list | ||
shownRoles[].applications[] |
string | ||
shownRoles[].builtIn |
boolean | ||
shownRoles[].conferredBy |
list | ||
shownRoles[].conferredBy[] |
string | ||
shownRoles[].console |
boolean | ||
shownRoles[].description |
string | ||
shownRoles[].displayName |
string | ||
shownRoles[].dn |
string | ||
shownRoles[].groups |
list | ||
shownRoles[].groups[] |
string | ||
shownRoles[].id |
string | ||
shownRoles[].localName |
string | ||
shownRoles[].memberTypes |
list | ||
shownRoles[].memberTypes[] |
string | ||
shownRoles[].name |
string | ||
shownRoles[].native |
boolean | ||
shownRoles[].ownerProtected |
boolean | ||
shownRoles[].owners |
list | ||
shownRoles[].owners[] |
string | ||
shownRoles[].permissions |
list | ||
shownRoles[].permissions[] |
string | ||
shownRoles[].users |
list | ||
shownRoles[].users[] |
string | ||
storable |
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/roles/add-conferring-client
addRoleConferringClient
Let a client confer a role on everybody signing in through it
Adds one value to the role’s roleConferredBy (#454): every PERSON who signs in through that client holds the role on the access token the client is issued, beside the roles they hold themselves, and on no other token. It is how the console’s client, sts-admin-console, gives everybody who signs in to the console ADMIN_CONSOLE. The client must be registered in this realm. A role only applications may hold, and the two console roles, cannot be conferred.
Mirrors POST /admin/roles and POST /admin/roles/owners 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 |
|---|---|---|---|
client |
string | yes | The client_id of the application that confers it. |
role |
string | yes | The role. |
200: Which client now confers the role.
| Member | Type | Required | What it is |
|---|---|---|---|
client |
string | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
role |
string |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
client |
string | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
role |
string |
POST /admin-api/roles/add-member
addRoleMember
Give somebody a role
Adds one value to the role entry. Which of the three lists it goes in is kind, and the three are looked up in three different places, so naming the wrong one succeeds and writes something that will never match:
user— a username. The person need not exist: this service creates a directory entry for any name on first sight, so a role can be granted before its holder has ever signed in.group— a group inou=groups. Every member holds the role, resolved at DECISION TIME rather than expanded on write, so anldapmodifyadding somebody to the group changes the very next token.application— an application that holds the role AS ITSELF, which is what aclient_credentialsgrant is decided on.
It is NOT the same relation as appRequiredRole on an application entry, which is what that application DEMANDS of others. An application appears in both and means opposite things in each.
A BUILT-IN role is refused by name: those six are computed and have no membership to edit.
Mirrors POST /admin/roles and POST /admin/roles/owners 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 |
|---|---|---|---|
kind |
one of user, group, application |
yes | Which of the three lists the member goes in. |
member |
string | yes | The person, group or application. Named member rather than name on purpose: role is the role’s own name, and a body that confused the two would succeed and create something plausible. |
role |
string | yes | The role being given. |
200: Who now holds what.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
member |
string | ||
message |
string | ||
ok |
boolean | yes | |
role |
string |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
member |
string | ||
message |
string | ||
ok |
boolean | yes | |
role |
string |
POST /admin-api/roles/add-owner
addRoleOwner
Add one owner to a role
Adds a person or a group of this realm to the role’s owner values and writes at once, keeping the other owners and everything else on the role. owner is a username, a DN or a urn:uuid: subject for a person, a cn or DN for a group.
An owner must name somebody: one that names no person and no group here is refused. A role names at most 25 owners. An owner already listed is ok with changed: false.
AN OWNER GRANTS NOTHING: nothing in this service reads owner to decide anything; the user portal lists what a person owns.
Mirrors POST /admin/roles and POST /admin/roles/owners 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 |
|---|---|---|---|
owner |
string | yes | The person or group to add. |
role |
string | yes | The role. |
200: Whether anything changed, and the role’s owners as they now stand (owners).
| Member | Type | Required | What it is |
|---|---|---|---|
changed |
boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
owner |
string | ||
owners |
list | ||
owners[].dn |
string | ||
owners[].kind |
string | ||
owners[].name |
string | ||
owners[].present |
boolean | ||
role |
string |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
changed |
boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
owner |
string | ||
owners |
list | ||
owners[].dn |
string | ||
owners[].kind |
string | ||
owners[].name |
string | ||
owners[].present |
boolean | ||
role |
string |
POST /admin-api/roles/add-permission
addRolePermission
Let a role authorize a permission
Adds one value to the role’s rolePermission (#303). A scope is a request and a role is what authorizes it: a permission its resource application GATES (oauthRoleGatedPermission) is issued only to a subject — a person, or an application on client_credentials — holding a role that names it, and left off the token otherwise.
permission is the full identifier a client asks for: the resource’s oauthPermissionBaseUri followed by the name. It must be DEFINED by an application in this realm first. gated: false in the reply means the resource does not gate it yet, so the role changes nothing until it does.
The native permissions admin:read and admin:write are refused: they are authorized by the console roles ADMIN_READ and ADMIN_WRITE alone, whose permissions are fixed. Put an application in one of those with add-member.
Mirrors POST /admin/roles and POST /admin/roles/owners 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 |
|---|---|---|---|
permission |
string | yes | The permission identifier, base + name. |
role |
string | yes | The role. |
200: What the role now authorizes, and whether its resource gates it.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
gated |
boolean | ||
message |
string | ||
ok |
boolean | yes | |
permission |
string | ||
role |
string |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
gated |
boolean | ||
message |
string | ||
ok |
boolean | yes | |
permission |
string | ||
role |
string |
POST /admin-api/roles/create-role
createRole
Make a role
Writes one entry under ou=roles with no members. Adding members is add-member; the two are separate because a role is worth creating before anybody holds it — an application can be narrowed to it first, and the register will then say so.
The name becomes an LDAP RDN and a value in a token claim, so it is up to 64 characters of letters, digits, and . _ : @ - or a space. It may not be one of the six built-in roles: those are computed and answered first, so a stored role of the same name could never be reached.
Mirrors POST /admin/roles and POST /admin/roles/owners 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 |
|---|---|---|---|
application |
string | The ONE application this role belongs to (#310), by its identifier. The role is registered as <role>@<application> — two applications may each have a reader — and a token or assertion for that application carries it as <role>, no other application’s at all. Omit it for a realm-wide role, whose name may not contain @. |
|
description |
string | What it is for, for the next person. | |
displayName |
string | A name for people to read (#93). The role’s name is still what a token carries; this is its label. Optional. | |
memberTypes |
list | Who may hold it (#93): user (people, directly or through a group) and application (an application as itself). Empty is both. A member of an excluded kind is refused, already held or added later; the two console roles cannot be restricted. Omitted, both. |
|
memberTypes[] |
one of user, application |
||
role |
string | yes | The role’s name. |
200: The role that was made.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
name |
string | ||
ok |
boolean | yes |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
name |
string | ||
ok |
boolean | yes |
POST /admin-api/roles/delete-role
deleteRole
Remove a role
Deletes the entry. Applications that still REQUIRE it are named in the reply and the delete still happens, which is deliberate: refusing would mean a role could not be removed until every application naming it had been edited, and those entries are usually the thing somebody is in the middle of changing. Each of them now requires a role NOBODY holds and is therefore issued nothing at all — so the consequence is said at the moment it is created rather than discovered later as a service that stopped working.
Nothing already ISSUED is touched. A token minted while somebody held the role is still valid and still carries it in the roles claim.
Mirrors POST /admin/roles and POST /admin/roles/owners 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 |
|---|---|---|---|
role |
string | yes | The role to remove. |
200: What was removed, and which applications now require something nobody can hold.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
name |
string | ||
ok |
boolean | yes | |
stillRequired |
list | ||
stillRequired[] |
string |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
name |
string | ||
ok |
boolean | yes | |
stillRequired |
list | ||
stillRequired[] |
string |
POST /admin-api/roles/describe-role
describeRole
Change what a role says it is for, and who may hold it
Replaces the description — and, where given, the displayName and memberTypes (#93) — and leaves the membership exactly as it was. It is an action of its own rather than a field on create-role because creating an existing role is refused: roles are edited in place.
Mirrors POST /admin/roles and POST /admin/roles/owners 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 |
|---|---|---|---|
description |
string | The new description. An empty string clears it. | |
displayName |
string | A name for people to read (#93). The role’s name is still what a token carries; this is its label. Omitted, it is kept; an empty string clears it. | |
memberTypes |
list | Who may hold it (#93): user (people, directly or through a group) and application (an application as itself). Empty is both. A member of an excluded kind is refused, already held or added later; the two console roles cannot be restricted. Omitted, they are kept. |
|
memberTypes[] |
one of user, application |
||
role |
string | yes | The role. |
200: The role that was changed.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
name |
string | ||
ok |
boolean | yes |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
message |
string | ||
name |
string | ||
ok |
boolean | yes |
GET /admin-api/roles/preview
previewRoleIssuance
Would this be issued?
Asks the embedded PEP whether this service would issue something, without issuing it and without recording anything.
It is the SAME call the nine issuance sites make — common/issuance_gate.check(), through xacml/xacml_role_pep.ts, against the policy xacml.issuancePolicy names — so a preview that agreed with the enforcement only by coincidence is impossible. That is the only reason it is worth having.
It is not POST /xacml/pdp, which asks the same engine a different question: an arbitrary request against the repository ROOT, which is the policy about somebody else’s boundary. Two questions, two documents.
available: false means the XACML family is not loaded in this process: nothing is gated and every issuance is allowed.
application and subject are both needed and neither is declared required, because this is a READ and a read with no question in it has nothing to refuse — it answers 200 with answered: false and says what was missing, exactly as a GET of /admin/roles with no parameters draws the form and no answer. Read answered first. There is deliberately no decision member on that reply: the gate ALLOWS a call that names no application, so an operation that fell through to it would hand back a Permit meaning “you did not ask”.
Mirrors GET /admin/roles on the admin console.
Scope: admin:read.
Parameters
| Name | In | Type | Required | What it is |
|---|---|---|---|---|
username |
query | string | The older spelling of subject, read when subject is absent. |
|
application |
query | string | What something would be issued FOR — a client_id, a wtrealm, a SAML entityID, an SPN. An application no entry names requires EVERYBODY, because this service registers one on first sight and refusing the first request from a new client is precisely the permissiveness it is for. |
|
subject |
query | string | Who it would be issued to — a username, or a client_id where subjectKind is application. |
|
subjectKind |
query | one of user, application |
Whether the subject is a person or a client authenticating as itself. Defaults to user. |
|
kind |
query | one of start-session, issue-access-token, issue-id-token, issue-refresh-token, issue-authorization-code, issue-saml-assertion, issue-wsfed-token, issue-wstrust-token, issue-kerberos-ticket, issue-certificate, create-account |
Which issuance. It becomes the XACML action-id, so a policy may permit an access token and refuse a refresh token. GET /admin-api/roles lists the nine in issuanceKinds; the default is issue-access-token. |
|
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 decision, the sentence explaining it, the roles the subject holds and the roles the application requires.
| Member | Type | Required | What it is |
|---|---|---|---|
allowed |
boolean | ||
answered |
boolean | ||
asked |
object | ||
asked.application |
string | ||
asked.kind |
string | ||
asked.subject |
string | ||
asked.subjectKind |
string | ||
available |
boolean | ||
decision |
string | ||
deferred |
boolean | ||
device |
object | ||
device.refusal |
string | ||
exchange |
any JSON | An exchange or per-right verdict the role PEP passes through from the XACML obligations of the policy that decided it. An exchange or per-right verdict the role PEP passes through from the XACML obligations of the policy that decided it. | |
gnapRights |
list | ||
gnapRights[] |
any JSON | An exchange or per-right verdict the role PEP passes through from the XACML obligations of the policy that decided it. An exchange or per-right verdict the role PEP passes through from the XACML obligations of the policy that decided it. | |
mechanism |
object | ||
mechanism.allowed |
list | ||
mechanism.allowed[] |
string | ||
mechanism.satisfied |
list | ||
mechanism.satisfied[] |
string | ||
mechanism.secondFactor |
boolean | ||
passkey |
object | ||
passkey.decidedBy |
string | ||
passkey.reason |
string | ||
passkey.verdict |
string | ||
policy |
string | ||
protocolRefused |
object | ||
protocolRefused.declared |
list | ||
protocolRefused.declared[] |
string | ||
protocolRefused.families |
list | ||
protocolRefused.families[] |
string | ||
required |
list | ||
required[] |
string | ||
risk |
object | ||
risk.action |
string | ||
risk.factor |
string | ||
risk.observed |
boolean | ||
roles |
list | ||
roles[] |
string | ||
scopes |
list | ||
scopes[].allowed |
boolean | ||
scopes[].decision |
string | ||
scopes[].policy |
string | ||
scopes[].required |
list | ||
scopes[].required[] |
string | ||
scopes[].roles |
list | ||
scopes[].roles[] |
string | ||
scopes[].scope |
string | ||
scopes[].why |
string | ||
status |
any JSON | The XACML response’s Status element, which is the PDP’s to word and can carry a status detail of any shape. The XACML response’s Status element, which is the PDP’s to word and can carry a status detail of any shape. |
|
transfer |
object | ||
transfer.decidedBy |
string | ||
transfer.verdict |
string | ||
why |
string |
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/roles/remove-conferring-client
removeRoleConferringClient
Stop a client conferring a role
Removes one value from the role’s roleConferredBy (#454). The client’s tokens stop carrying the role at once at /admin-api, whose gate asks on every call, and at the next issuance everywhere else. Taking sts-admin-console off ADMIN_CONSOLE leaves the console unable to draw itself until it is put back.
Mirrors POST /admin/roles and POST /admin/roles/owners 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 |
|---|---|---|---|
client |
string | yes | The client_id to take off. |
role |
string | yes | The role. |
200: Which client no longer confers the role.
| Member | Type | Required | What it is |
|---|---|---|---|
client |
string | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
role |
string |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
client |
string | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
role |
string |
POST /admin-api/roles/remove-member
removeRoleMember
Take a role away
Removes one value from the role entry. Matched case-insensitively, for the reason the register gives: a username here arrives from a login form, a SAML subject, a Kerberos principal and a client_id, and this service has always treated those as one identity however they were typed.
Nothing already ISSUED is touched, exactly as revoking a delegated permission does not re-judge a grant already made. The next issuance is decided without the role; a token minted a minute ago still carries it.
Mirrors POST /admin/roles and POST /admin/roles/owners 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 |
|---|---|---|---|
kind |
one of user, group, application |
yes | Which list to remove it from. |
member |
string | yes | The person, group or application. |
role |
string | yes | The role being taken away. |
200: Who no longer holds what.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
member |
string | ||
message |
string | ||
ok |
boolean | yes | |
role |
string |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
kind |
string | ||
member |
string | ||
message |
string | ||
ok |
boolean | yes | |
role |
string |
POST /admin-api/roles/remove-owner
removeRoleOwner
Take one owner off a role
Takes one owner value off the role and writes at once (#604). owner is the DN the role lists; one it does not list is refused. The last owner may go: a role needs none.
Mirrors POST /admin/roles and POST /admin/roles/owners 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 |
|---|---|---|---|
owner |
string | yes | The owner’s DN. |
role |
string | yes | The role. |
200: The role’s owners as they now stand (owners).
| Member | Type | Required | What it is |
|---|---|---|---|
changed |
boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
owner |
string | ||
owners |
list | ||
owners[].dn |
string | ||
owners[].kind |
string | ||
owners[].name |
string | ||
owners[].present |
boolean | ||
role |
string |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
changed |
boolean | ||
errors |
list | ||
errors[] |
string | ||
message |
string | ||
ok |
boolean | yes | |
owner |
string | ||
owners |
list | ||
owners[].dn |
string | ||
owners[].kind |
string | ||
owners[].name |
string | ||
owners[].present |
boolean | ||
role |
string |
POST /admin-api/roles/remove-permission
removeRolePermission
Stop a role authorizing a permission
Removes one value from the role’s rolePermission (#303). The next issuance is decided without it; a token already issued keeps what it carries, except at /admin-api, whose gate asks the roles again on every call.
Mirrors POST /admin/roles and POST /admin/roles/owners 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 |
|---|---|---|---|
permission |
string | yes | The permission identifier. |
role |
string | yes | The role. |
200: What the role no longer authorizes.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
gated |
boolean | ||
message |
string | ||
ok |
boolean | yes | |
permission |
string | ||
role |
string |
400: The operation was refused; errors says why and nothing changed.
| Member | Type | Required | What it is |
|---|---|---|---|
errors |
list | ||
errors[] |
string | ||
gated |
boolean | ||
message |
string | ||
ok |
boolean | yes | |
permission |
string | ||
role |
string |