Management API

What to add to every access token and ID Token issued from now on. The assertions are next door, under Custom SAML attributes.

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/claims

getClaims

The custom claims every new token and assertion will carry

The four sets — OAuth 2.0 access token, OIDC ID Token, SAML 2.0 Attribute, SAML 1.1 Attribute — with the rules that govern them: the claim names this service sets itself and will not let you override, and the placeholders a value may use.

Each set has TWO HALVES and they are configured by different operations. claims are TYPED: a name and a value somebody wrote, the same for everybody except where a ${placeholder} carries the sign-in. attributes are LDAP ATTRIBUTE TYPES chosen from attributeCatalogue, whose value is read off that person’s entry under ou=users — so an ldapmodify changes the next token, and an LDAP client and an OIDC client pointed at this service are shown the same person.

attributeClaims is what the current selection would actually put in each set for the previewed person, built by the same function the issuance path calls. A caller with no browser has no other way to ask “what would this issue”.

Mirrors GET /admin/claims on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
user query string   Whose attribute values to preview. Defaults to a person the directory holds from startup, so the preview shows real values on a fresh process. Somebody with no entry gets generated values — the same invented person every time, seeded from the name — and preview.entryFound says which of the two happened.
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 four sets, the attribute catalogue and the preview.

Member Type Required What it is
attributeCatalogue list    
attributeCatalogue[].claim string    
attributeCatalogue[].custom boolean    
attributeCatalogue[].generated boolean    
attributeCatalogue[].label string, or null    
attributeCatalogue[].ldap string    
attributeCatalogue[].pacClaimId string    
attributeCatalogue[].schema string, or null    
attributeCatalogue[].sets map   Whether it is ticked, by claim set.
attributeCatalogue[].sets.{key} boolean    
attributeCatalogue[].syntax string, or null    
attributeChoices list    
attributeChoices[].attribute string    
attributeChoices[].from list    
attributeChoices[].from[] string    
groups object    
groups.claim string, or null    
groups.enabled boolean    
groups.grants string    
groups.loaded boolean    
groups.memberOfCounts boolean    
groups.precedence string    
groups.preview object    
groups.preview.application string    
groups.preview.claim string, or null    
groups.preview.dn string, or null    
groups.preview.enabled boolean    
groups.preview.entryFound boolean    
groups.preview.groups list    
groups.preview.groups[].cn string, or null    
groups.preview.groups[].dn string    
groups.preview.groups[].rule string, or null    
groups.preview.groups[].via list    
groups.preview.groups[].via[] string    
groups.preview.groups[].viaMemberOf boolean    
groups.preview.key string, or null    
groups.preview.loaded boolean    
groups.preview.memberOfCounts boolean    
groups.preview.reason string    
groups.preview.user string    
groups.preview.valueForm string, or null    
groups.preview.values list    
groups.preview.values[] string    
groups.problem string    
groups.sets list    
groups.sets[] string    
groups.settings list    
groups.settings[] string    
groups.valueForm string, or null    
placeholders list    
placeholders[] string    
precedence string    
preview object    
preview.byLdap map   By directory attribute.
preview.byLdap.{key}.claim string    
preview.byLdap.{key}.claimId string    
preview.byLdap.{key}.ldap string    
preview.byLdap.{key}.ldpTerm string, or null    
preview.byLdap.{key}.source string    
preview.byLdap.{key}.value any JSON   A claim value as it would be issued. Its JSON type is the catalogue row’s and the person’s own data, and a row may nest under a dotted path. A claim value as it would be issued. Its JSON type is the catalogue row’s and the person’s own data, and a row may nest under a dotted path.
preview.byLdap.{key}.values list    
preview.byLdap.{key}.values[] any JSON   A claim value as it would be issued. Its JSON type is the catalogue row’s and the person’s own data, and a row may nest under a dotted path. A claim value as it would be issued. Its JSON type is the catalogue row’s and the person’s own data, and a row may nest under a dotted path.
preview.entryFound boolean    
preview.user string    
reservedJwtClaims list    
reservedJwtClaims[] string    
sets list    
sets[].attributeClaimPreview list    
sets[].attributeClaimPreview[].attribute string    
sets[].attributeClaimPreview[].carried boolean    
sets[].attributeClaimPreview[].name string    
sets[].attributeClaimPreview[].value any JSON   A claim value as it would be issued. Its JSON type is the catalogue row’s and the person’s own data, and a row may nest under a dotted path. A claim value as it would be issued. Its JSON type is the catalogue row’s and the person’s own data, and a row may nest under a dotted path.
sets[].attributeClaims any JSON   The claims one person would be issued, keyed and nested by the claim names the catalogue and an administrator chose. The claims one person would be issued, keyed and nested by the claim names the catalogue and an administrator chose.
sets[].attributeReport list    
sets[].attributeReport[].claim string    
sets[].attributeReport[].claimId string    
sets[].attributeReport[].ldap string    
sets[].attributeReport[].ldpTerm string, or null    
sets[].attributeReport[].source string    
sets[].attributeReport[].value any JSON   A claim value as it would be issued. Its JSON type is the catalogue row’s and the person’s own data, and a row may nest under a dotted path. A claim value as it would be issued. Its JSON type is the catalogue row’s and the person’s own data, and a row may nest under a dotted path.
sets[].attributeReport[].values list    
sets[].attributeReport[].values[] any JSON   A claim value as it would be issued. Its JSON type is the catalogue row’s and the person’s own data, and a row may nest under a dotted path. A claim value as it would be issued. Its JSON type is the catalogue row’s and the person’s own data, and a row may nest under a dotted path.
sets[].attributes list    
sets[].attributes[] string    
sets[].claims list    
sets[].claims[].attribute string    
sets[].claims[].claimId string    
sets[].claims[].multi boolean    
sets[].claims[].name string    
sets[].claims[].nameFormat string    
sets[].claims[].namespace string    
sets[].claims[].type string    
sets[].claims[].value string    
sets[].id string    
sets[].label string    
sets[].withheldFrom map   Partners withholding it, by claim.
sets[].withheldFrom.{key} list    
sets[].withheldFrom.{key}[] string    
withholding list    
withholding[].id string    
withholding[].names list    
withholding[].names[] string    

POST /admin-api/claims/add

addClaim

Add one claim to one set

Every token of that kind issued from now on carries it; nothing already issued changes.

ADDITIVE ONLY. What the protocol puts in is never displaced — an ID Token’s sub, a SAML 2.0 assertion’s name, a WS-Federation assertion’s whole identity claim list. A name this service sets itself is REFUSED rather than allowed to win, because every one of those is load-bearing — a settable exp would produce tokens that fail to verify with nothing pointing back at the call that caused it. GET /admin-api/claims lists the refused names.

Mirrors POST /admin/claims 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
name string yes  
nameFormat string   The SAML 2.0 set only.
namespace string   The SAML 1.1 set only. Defaults to the WS-Federation claim namespace, which is what every relying party already reads.
set one of access_token, id_token yes  
type one of string, int64, uint64, boolean   The Kerberos PAC set only (#493): the PAC claim type. Defaults to string; ignored by the other sets.
value string   May carry a ${…} placeholder.

200: The set as it now stands, in claims.

Member Type Required What it is
added list    
added[] string    
attributes list    
attributes[] string    
claims list    
claims[].attribute string    
claims[].claimId string    
claims[].multi boolean    
claims[].name string    
claims[].nameFormat string    
claims[].namespace string    
claims[].type string    
claims[].value string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
set string    

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

Member Type Required What it is
added list    
added[] string    
attributes list    
attributes[] string    
claims list    
claims[].attribute string    
claims[].claimId string    
claims[].multi boolean    
claims[].name string    
claims[].nameFormat string    
claims[].namespace string    
claims[].type string    
claims[].value string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
set string    

POST /admin-api/claims/add-attribute-claim

addAttributeClaim

Add one claim carrying a directory attribute

The claim’s value is attribute on the entry of the person the token is about (#94) — any attribute, where the directory-attribute half of a set offers only the fixed catalogue, under the name given here. Only the directory, never an invented value: a person whose entry lacks it gets no such claim, and a lower layer of the same name still answers. multi carries every value. A secret, a binary value or an attribute this service keeps (sts, hoba, app, pwd) is refused. Removed by remove, by name. The same reserved names are refused as for add, and a directory write that moves the attribute sends CAEP token-claims-change to holders of live tokens.

Mirrors POST /admin/claims 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
attribute string yes The directory attribute.
multi boolean   Every value rather than the first.
name string yes  
nameFormat string   The SAML 2.0 set only.
namespace string   The SAML 1.1 set only.
set one of access_token, id_token yes  
type one of string, number, boolean, json   The JSON type of each value, in a JWT or UserInfo set. Ignored by the SAML sets.

200: The set as it now stands, in claims.

Member Type Required What it is
added list    
added[] string    
attributes list    
attributes[] string    
claims list    
claims[].attribute string    
claims[].claimId string    
claims[].multi boolean    
claims[].name string    
claims[].nameFormat string    
claims[].namespace string    
claims[].type string    
claims[].value string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
set string    

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

Member Type Required What it is
added list    
added[] string    
attributes list    
attributes[] string    
claims list    
claims[].attribute string    
claims[].claimId string    
claims[].multi boolean    
claims[].name string    
claims[].nameFormat string    
claims[].namespace string    
claims[].type string    
claims[].value string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
set string    

POST /admin-api/claims/attributes

setClaimAttributes

Set which LDAP attributes one set carries

The array REPLACES the selection for that set. An attribute not in the array is removed, which is how removal is expressed — there is no per-attribute remove, because the console’s control is a table of checkboxes and an API that removed differently would be a second model of the same state.

The value a selected attribute carries is the one on that person’s entry under ou=users, or — where the entry has nothing — invented from their username, deterministically, so one username is one invented person across restarts. Unlike POST /admin-api/credential-claims/select this does NOT sweep the directory: the credential page writes the attributes it needs onto every entry, and doing it from here as well would mean two pages racing to populate one directory. Selecting an attribute nobody has an entry value for still produces a claim; it is generated, and attributeReport says so per claim.

An unknown attribute name refuses the WHOLE call rather than being skipped: the catalogue is fixed, so an unknown name is either a hand-written request that deserves an answer or a rename that left a caller behind. attributeCatalogue in the GET beside this is the list — and it is ONE catalogue for all four sets, so either GET answers it in full.

A TYPED claim of the same name WINS over one of these, and THE PROTOCOL’S OWN beats both — which is worth knowing before it is discovered on the wire. An ID Token always carries name, given_name, family_name, preferred_username and email built from the sign-in, so selecting cn, givenName, sn, uid or mail ON THAT SET changes nothing the client sees; the same five reach an access token from the directory, because the protocol sets none of them there. A SAML 2.0 assertion sets name the same way and a WS-Federation one sets the whole identity claim list. Both halves are reported by that same GET.

Mirrors POST /admin/claims 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
attributes list yes LDAP attribute type names, from attributeCatalogue. An EMPTY array clears the selection — and so does an ABSENT one, so a misspelt field name empties the set rather than being refused. The reply names everything it removed and the audit log keeps a row saying the same, and attributes-clear is how a caller that means it says so.
attributes[] string    
set one of access_token, id_token yes  

200: What the set carries now, in attributes, with added and removed.

Member Type Required What it is
added list    
added[] string    
attributes list    
attributes[] string    
claims list    
claims[].attribute string    
claims[].claimId string    
claims[].multi boolean    
claims[].name string    
claims[].nameFormat string    
claims[].namespace string    
claims[].type string    
claims[].value string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
set string    

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

Member Type Required What it is
added list    
added[] string    
attributes list    
attributes[] string    
claims list    
claims[].attribute string    
claims[].claimId string    
claims[].multi boolean    
claims[].name string    
claims[].nameFormat string    
claims[].namespace string    
claims[].type string    
claims[].value string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
set string    

POST /admin-api/claims/attributes-all

selectAllClaimAttributes

Put every catalogued attribute in one set

Every attribute type in the catalogue, which is a legitimate thing to test and makes a large token. It exists as its own operation so that “all of them” does not mean a caller constructing the whole list of names that has to be updated whenever the catalogue is.

Mirrors POST /admin/claims 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
set one of access_token, id_token yes  

200: The whole catalogue, in attributes.

Member Type Required What it is
added list    
added[] string    
attributes list    
attributes[] string    
claims list    
claims[].attribute string    
claims[].claimId string    
claims[].multi boolean    
claims[].name string    
claims[].nameFormat string    
claims[].namespace string    
claims[].type string    
claims[].value string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
set string    

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

Member Type Required What it is
added list    
added[] string    
attributes list    
attributes[] string    
claims list    
claims[].attribute string    
claims[].claimId string    
claims[].multi boolean    
claims[].name string    
claims[].nameFormat string    
claims[].namespace string    
claims[].type string    
claims[].value string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
set string    

POST /admin-api/claims/attributes-clear

clearClaimAttributes

Take every directory attribute out of one set

The TYPED claims on that set are untouched — this is the other half. Clearing both takes this and clear.

Nothing is deleted from the directory: what was written onto an entry stays there, because an operator may have set it and nothing here has the standing to remove it.

Mirrors POST /admin/claims 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
set one of access_token, id_token yes  

200: An empty attributes, and what was removed.

Member Type Required What it is
added list    
added[] string    
attributes list    
attributes[] string    
claims list    
claims[].attribute string    
claims[].claimId string    
claims[].multi boolean    
claims[].name string    
claims[].nameFormat string    
claims[].namespace string    
claims[].type string    
claims[].value string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
set string    

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

Member Type Required What it is
added list    
added[] string    
attributes list    
attributes[] string    
claims list    
claims[].attribute string    
claims[].claimId string    
claims[].multi boolean    
claims[].name string    
claims[].nameFormat string    
claims[].namespace string    
claims[].type string    
claims[].value string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
set string    

POST /admin-api/claims/clear

clearClaims

Empty one set

Those tokens then carry only what the protocol puts in them.

Mirrors POST /admin/claims 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
set one of access_token, id_token yes  

200: An empty claims.

Member Type Required What it is
added list    
added[] string    
attributes list    
attributes[] string    
claims list    
claims[].attribute string    
claims[].claimId string    
claims[].multi boolean    
claims[].name string    
claims[].nameFormat string    
claims[].namespace string    
claims[].type string    
claims[].value string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
set string    

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

Member Type Required What it is
added list    
added[] string    
attributes list    
attributes[] string    
claims list    
claims[].attribute string    
claims[].claimId string    
claims[].multi boolean    
claims[].name string    
claims[].nameFormat string    
claims[].namespace string    
claims[].type string    
claims[].value string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
set string    

POST /admin-api/claims/remove

removeClaim

Remove one claim from one set

By name. A name the set does not carry is refused rather than treated as already done, because the two are different facts and a caller that misspelt a name would otherwise be told it succeeded.

Mirrors POST /admin/claims 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
name string yes  
set one of access_token, id_token yes  

200: The set as it now stands, in claims.

Member Type Required What it is
added list    
added[] string    
attributes list    
attributes[] string    
claims list    
claims[].attribute string    
claims[].claimId string    
claims[].multi boolean    
claims[].name string    
claims[].nameFormat string    
claims[].namespace string    
claims[].type string    
claims[].value string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
set string    

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

Member Type Required What it is
added list    
added[] string    
attributes list    
attributes[] string    
claims list    
claims[].attribute string    
claims[].claimId string    
claims[].multi boolean    
claims[].name string    
claims[].nameFormat string    
claims[].namespace string    
claims[].type string    
claims[].value string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
set string    

POST /admin-api/claims/replace

replaceClaims

Set a whole claim set at once

The array replaces whatever the set held. An EMPTY array is a legitimate call and clears it. Every entry is checked by the same rules add applies, and a single bad entry refuses the whole call — a partial replace would leave the set in a state nobody asked for.

Mirrors POST /admin/claims 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
claims list yes  
claims[] object   One custom claim. nameFormat applies to the SAML 2.0 set and namespace to the SAML 1.1 set; both are ignored by the two JWT sets.
claims[].attribute string   AN ATTRIBUTE CLAIM (#94), in place of value: the directory attribute of the person the artifact is about that the claim carries. Only the directory, never an invented value; absent on the entry, the claim is absent. A secret, a binary value or an attribute this service keeps (sts, hoba, app, pwd) is refused.
claims[].multi boolean   An attribute claim: every value (a JSON array; several AttributeValues) rather than the first.
claims[].name string yes  
claims[].nameFormat string    
claims[].namespace string    
claims[].type one of string, number, boolean, json, int64, uint64   An attribute claim in a JWT or UserInfo set: the JSON type each value becomes (string, number, boolean, json). A value that is not one is left out. Ignored by the SAML sets. In the Kerberos PAC set (#493) EVERY row has one, of string, int64, uint64 and boolean — the PAC claim type.
claims[].value string   May carry a placeholder such as ${username}; GET /admin-api/claims lists the ones this service expands.
set one of access_token, id_token yes  

200: The set as it now stands, in claims.

Member Type Required What it is
added list    
added[] string    
attributes list    
attributes[] string    
claims list    
claims[].attribute string    
claims[].claimId string    
claims[].multi boolean    
claims[].name string    
claims[].nameFormat string    
claims[].namespace string    
claims[].type string    
claims[].value string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
set string    

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

Member Type Required What it is
added list    
added[] string    
attributes list    
attributes[] string    
claims list    
claims[].attribute string    
claims[].claimId string    
claims[].multi boolean    
claims[].name string    
claims[].nameFormat string    
claims[].namespace string    
claims[].type string    
claims[].value string    
errors list    
errors[] string    
message string    
ok boolean yes  
removed list    
removed[] string    
set string