Management API

What to add to every SAML 2.0 and SAML 1.1 assertion issued from now on — WS-Trust’s and WS-Federation’s alike. The same store the custom claims are in, and the same two halves: a typed attribute and a directory one.

Every answer is checked against the model shown here before it is sent, and no answer carries a member its model does not list. A member shown as any JSON is one whose shape belongs to somebody else, and says whose. .{key} is a key that is data, and [] an element of a list.

A refusal

Unless an operation below says otherwise, any status it does not list answers this:

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean    
status integer    
why string    

GET /admin-api/saml-attributes

getSamlAttributes

The custom attributes every new SAML assertion will carry

The two SAML sets — SAML 2.0 Attribute and SAML 1.1 Attribute (WS-Federation) — with the rules that govern them. The 2.0 set reaches every assertion WS-Trust issues with a 2.0 token type; the 1.1 set reaches the 1.1 ones, which is what WS-Federation’s passive requestor profile carries, so the 1.1 half is the one a browser sign-in exercises.

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 assertion, and an LDAP client and a SAML relying party pointed at this service are shown the same person.

THERE IS NO reservedJwtClaims HERE and the absence is the answer rather than an omission: that list is enforced for a JWT set only, because an assertion attribute called exp collides with nothing. defaultSaml11Namespace is the rule that IS this family’s — the namespace a 1.1 attribute gets when the call does not name one.

The two JWT sets are at GET /admin-api/claims. One store behind both, and one audit row per change whichever door made it.

Mirrors GET /admin/saml2 on the admin console.

The reply also carries protocolEndpoints: every endpoint of this family in the realm the call arrived in, as { name, methods, url } (plus route for an HTTP endpoint, transport for a socket, and registered: false for a route the router no longer has).

Scope: admin:read.

Parameters

Name In Type Required What it is
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. It is the same parameter, the same cap and the same default GET /admin-api/claims takes, deliberately: the two replies preview one person unless asked otherwise.
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 two SAML 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    
defaultSaml11Namespace 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    
protocolEndpoints list    
protocolEndpoints[].listening boolean    
protocolEndpoints[].methods list, or string    
protocolEndpoints[].methods[] string    
protocolEndpoints[].name string    
protocolEndpoints[].registered boolean    
protocolEndpoints[].route string    
protocolEndpoints[].transport string    
protocolEndpoints[].url string    
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/saml-attributes/add

addSamlAttribute

Add one attribute to one set

Every assertion 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. There is NO reserved list here: those names are load-bearing in a JWT, and an assertion attribute called exp collides with nothing. An entry with no name, and two entries of one name, are still refused.

Mirrors POST /admin/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
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 saml2, saml11 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/saml-attributes/add-attribute-claim

addSamlDirectoryAttributeClaim

Add one attribute carrying a directory attribute

The attribute’s value is attribute on the entry of the person the assertion 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 attribute, 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/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
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 saml2, saml11 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/saml-attributes/attributes

setSamlDirectoryAttributes

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 attribute; 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 attribute 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/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
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 saml2, saml11 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/saml-attributes/attributes-all

selectAllSamlDirectoryAttributes

Put every catalogued attribute in one set

Every attribute type in the catalogue, which is a legitimate thing to test and makes a large assertion. 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/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
set one of saml2, saml11 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/saml-attributes/attributes-clear

clearSamlDirectoryAttributes

Take every directory attribute out of one set

The TYPED attributes 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/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
set one of saml2, saml11 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/saml-attributes/clear

clearSamlAttributes

Empty one set

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

Mirrors POST /admin/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
set one of saml2, saml11 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/saml-attributes/remove

removeSamlAttribute

Remove one attribute 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/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
name string yes  
set one of saml2, saml11 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/saml-attributes/replace

replaceSamlAttributes

Set a whole attribute 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/saml2 on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
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 saml2, saml11 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