This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.

Management API

The embedded LDAP directory’s groups. A group here GRANTS NOTHING: no token, assertion, ticket or PAC carries one and no endpoint reads 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/groups

getGroups

Every group in the embedded LDAP directory, or one in full

Without group it is the list. With it, one group: every attribute it holds, operational ones included, and every member resolved.

Two answers are easy to mistake for failures and are neither. A process with no directory loaded answers 200 with directory: false. A group that is not there answers 200 with found: false, because a client can delete or rename one through the protocol between one call and the next, and that is the interesting case rather than a routing problem.

A GROUP HERE GRANTS NOTHING, with two exceptions: no endpoint in this service decides anything on a group, and the only two that do are admin.readGroup and admin.writeGroup, which say who may use the console. A token CAN carry one — groups.claim is on by default and puts the subject’s groups in every access token, ID Token and SAML assertion — and carrying a fact is not acting on one.

Mirrors GET /admin/groups on the admin console.

Scope: admin:read.

Parameters

Name In Type Required What it is
group query string   One group’s DN. Returns the drill-down.
q query string   Substring of the DN or the name, case-insensitive.
exclude query array   A group DN to leave out of the match, compared as LDAP compares a DN (case and the spaces after a comma do not matter); repeat it for several. Applied before the paging, so a page still holds per rows. Ignored when group is given.
page query integer   Which page of the match to return. CLAMPED rather than refused: a page past the end returns the last one, and the reply says which page it actually is.
per query integer   Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own.
membersPage query integer   Which page of members to return, answered by membersPaging. The membership values of the group named by group, resolved. group.memberCount, presentCount and danglingCount beside them are counts of the WHOLE list and not of the page — a group whose seven members resolve to five is the fact this resource exists to report, and a per-page count would not be an answer to it.
claimedPage query integer   Which page of claimed to return, answered by claimedPaging. Entries whose own memberOf names this group while it does not list them back.
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 list, or one group.

Member Type Required What it is
(the answer) one of 5 shapes    
(shape 1) object   Every group the embedded directory holds.
(shape 1).adminGroups object    
(shape 1).adminGroups.read string, or null    
(shape 1).adminGroups.write string, or null    
(shape 1).baseDn string    
(shape 1).canWrite boolean    
(shape 1).dangling number    
(shape 1).entryCount number    
(shape 1).filter object    
(shape 1).filter.exclude list    
(shape 1).filter.exclude[] string    
(shape 1).filter.q string, or null    
(shape 1).firstRow integer    
(shape 1).groupCount number    
(shape 1).groups list    
(shape 1).groups[].attributeCount number    
(shape 1).groups[].claimedCount number    
(shape 1).groups[].cn string    
(shape 1).groups[].createdAt string, or number, or null    
(shape 1).groups[].danglingCount number    
(shape 1).groups[].description string    
(shape 1).groups[].dn string    
(shape 1).groups[].memberCount number    
(shape 1).groups[].modifiedAt string, or number, or null    
(shape 1).groups[].objectClass list    
(shape 1).groups[].objectClass[] string    
(shape 1).groups[].origin string    
(shape 1).groups[].ownerCount number    
(shape 1).groups[].presentCount number    
(shape 1).groups[].rule string    
(shape 1).groupsDn string    
(shape 1).lastRow integer    
(shape 1).ldapsListening boolean    
(shape 1).ldapsPort number, or null    
(shape 1).listenError string, or null    
(shape 1).listening boolean    
(shape 1).matched number    
(shape 1).membershipValues number    
(shape 1).page integer    
(shape 1).pages integer    
(shape 1).paging object    
(shape 1).paging.firstRow integer    
(shape 1).paging.lastRow integer    
(shape 1).paging.noun string    
(shape 1).paging.page integer    
(shape 1).paging.pages integer    
(shape 1).paging.param string    
(shape 1).paging.perPage integer    
(shape 1).paging.total integer    
(shape 1).perPage integer    
(shape 1).port number, or null    
(shape 1).settings object    
(shape 1).settings.context object    
(shape 1).settings.context.configFile string, or null    
(shape 1).settings.context.defaultsFile string, or null    
(shape 1).settings.context.inRealm boolean    
(shape 1).settings.context.persistenceMode string    
(shape 1).settings.context.persistsAppconfig boolean    
(shape 1).settings.context.persistsRealms boolean    
(shape 1).settings.context.realmId string    
(shape 1).settings.editableCount integer    
(shape 1).settings.groups list    
(shape 1).settings.groups[].group string    
(shape 1).settings.groups[].settings list    
(shape 1).settings.groups[].settings[].appconfigPath string    
(shape 1).settings.groups[].settings[].csvValueNotes map    
(shape 1).settings.groups[].settings[].csvValueNotes.{key} string    
(shape 1).settings.groups[].settings[].csvValues list    
(shape 1).settings.groups[].settings[].csvValues[] string, or number, or boolean, or null    
(shape 1).settings.groups[].settings[].default list, or string, or number, or boolean, or null    
(shape 1).settings.groups[].settings[].default[] object   Nested deeper than this page draws.
(shape 1).settings.groups[].settings[].description string    
(shape 1).settings.groups[].settings[].editRefusal string    
(shape 1).settings.groups[].settings[].editable boolean    
(shape 1).settings.groups[].settings[].enumValues list    
(shape 1).settings.groups[].settings[].enumValues[] string, or number, or boolean, or null    
(shape 1).settings.groups[].settings[].env list, or string    
(shape 1).settings.groups[].settings[].env[] object   Nested deeper than this page draws.
(shape 1).settings.groups[].settings[].group string    
(shape 1).settings.groups[].settings[].key string    
(shape 1).settings.groups[].settings[].label string    
(shape 1).settings.groups[].settings[].legacyEnv list, or string    
(shape 1).settings.groups[].settings[].legacyEnv[] object   Nested deeper than this page draws.
(shape 1).settings.groups[].settings[].masked boolean    
(shape 1).settings.groups[].settings[].max number    
(shape 1).settings.groups[].settings[].min number    
(shape 1).settings.groups[].settings[].ordered boolean    
(shape 1).settings.groups[].settings[].overridden boolean    
(shape 1).settings.groups[].settings[].realmSettable boolean    
(shape 1).settings.groups[].settings[].restartReason string    
(shape 1).settings.groups[].settings[].selectAll object    
(shape 1).settings.groups[].settings[].selectAll.aloneWhileOn list    
(shape 1).settings.groups[].settings[].selectAll.aloneWhileOn[] object   Nested deeper than this page draws.
(shape 1).settings.groups[].settings[].selectAll.onlyWhileOn list    
(shape 1).settings.groups[].settings[].selectAll.onlyWhileOn[] object   Nested deeper than this page draws.
(shape 1).settings.groups[].settings[].source string    
(shape 1).settings.groups[].settings[].step number    
(shape 1).settings.groups[].settings[].text string, or null    
(shape 1).settings.groups[].settings[].type string    
(shape 1).settings.groups[].settings[].value list, or string, or number, or boolean, or null    
(shape 1).settings.groups[].settings[].value[] object   Nested deeper than this page draws.
(shape 1).settings.overridden list    
(shape 1).settings.overridden[] string    
(shape 1).settings.page string    
(shape 1).settings.setWith string    
(shape 1).settings.settingCount integer    
(shape 1).settings.sharedWith map    
(shape 1).settings.sharedWith.{key} list    
(shape 1).settings.sharedWith.{key}[] object, or string    
(shape 1).settings.sharedWith.{key}[].label string    
(shape 1).settings.sharedWith.{key}[].path string    
(shape 1).shown number    
(shape 1).usersDn string    
(shape 2) object   One group, with the same directory facts the list carries around it.
(shape 2).adminGroups object    
(shape 2).adminGroups.read string, or null    
(shape 2).adminGroups.write string, or null    
(shape 2).baseDn string    
(shape 2).canWrite boolean    
(shape 2).claimedPaging object    
(shape 2).claimedPaging.firstRow integer    
(shape 2).claimedPaging.lastRow integer    
(shape 2).claimedPaging.noun string    
(shape 2).claimedPaging.page integer    
(shape 2).claimedPaging.pages integer    
(shape 2).claimedPaging.param string    
(shape 2).claimedPaging.perPage integer    
(shape 2).claimedPaging.total integer    
(shape 2).entryCount number    
(shape 2).found boolean    
(shape 2).group object    
(shape 2).group.attributes map    
(shape 2).group.attributes.{key} list, or string    
(shape 2).group.attributes.{key}[] string    
(shape 2).group.claimed list    
(shape 2).group.claimed[].attribute string    
(shape 2).group.claimed[].cn string    
(shape 2).group.claimed[].displayName string    
(shape 2).group.claimed[].dn string    
(shape 2).group.claimed[].holds string    
(shape 2).group.claimed[].kind string    
(shape 2).group.claimed[].mail string    
(shape 2).group.claimed[].present boolean    
(shape 2).group.claimed[].userKey string    
(shape 2).group.claimed[].value string    
(shape 2).group.cn string    
(shape 2).group.createdAt string, or number, or null    
(shape 2).group.danglingCount number    
(shape 2).group.dn string    
(shape 2).group.maxOwners number    
(shape 2).group.memberAttributes list    
(shape 2).group.memberAttributes[] string    
(shape 2).group.memberCount number    
(shape 2).group.members list    
(shape 2).group.members[].attribute string    
(shape 2).group.members[].cn string    
(shape 2).group.members[].displayName string    
(shape 2).group.members[].dn string    
(shape 2).group.members[].holds string    
(shape 2).group.members[].kind string    
(shape 2).group.members[].mail string    
(shape 2).group.members[].present boolean    
(shape 2).group.members[].userKey string    
(shape 2).group.members[].value string    
(shape 2).group.modifiedAt string, or number, or null    
(shape 2).group.operational list    
(shape 2).group.operational[] string    
(shape 2).group.origin string    
(shape 2).group.owners list    
(shape 2).group.owners[].dn string    
(shape 2).group.owners[].kind string    
(shape 2).group.owners[].name string    
(shape 2).group.owners[].present boolean    
(shape 2).group.presentCount number    
(shape 2).group.rule string    
(shape 2).groupCount number    
(shape 2).groups list    
(shape 2).groups[].attributeCount number    
(shape 2).groups[].claimedCount number    
(shape 2).groups[].cn string    
(shape 2).groups[].createdAt string, or number, or null    
(shape 2).groups[].danglingCount number    
(shape 2).groups[].description string    
(shape 2).groups[].dn string    
(shape 2).groups[].memberCount number    
(shape 2).groups[].modifiedAt string, or number, or null    
(shape 2).groups[].objectClass list    
(shape 2).groups[].objectClass[] string    
(shape 2).groups[].origin string    
(shape 2).groups[].ownerCount number    
(shape 2).groups[].presentCount number    
(shape 2).groups[].rule string    
(shape 2).groupsDn string    
(shape 2).known map    
(shape 2).known.{key} boolean    
(shape 2).ldapsListening boolean    
(shape 2).ldapsPort number, or null    
(shape 2).listenError string, or null    
(shape 2).listening boolean    
(shape 2).maxEntries number    
(shape 2).membersPaging object    
(shape 2).membersPaging.firstRow integer    
(shape 2).membersPaging.lastRow integer    
(shape 2).membersPaging.noun string    
(shape 2).membersPaging.page integer    
(shape 2).membersPaging.pages integer    
(shape 2).membersPaging.param string    
(shape 2).membersPaging.perPage integer    
(shape 2).membersPaging.total integer    
(shape 2).notAGroup boolean    
(shape 2).ownership object    
(shape 2).ownership.kind string    
(shape 2).ownership.marked boolean    
(shape 2).ownership.name string    
(shape 2).ownership.protected boolean    
(shape 2).ownership.reasons list    
(shape 2).ownership.reasons[] string    
(shape 2).policyReferences list    
(shape 2).policyReferences[].attribute string    
(shape 2).policyReferences[].choices list    
(shape 2).policyReferences[].choices[] string    
(shape 2).policyReferences[].noun string    
(shape 2).policyReferences[].value string    
(shape 2).port number, or null    
(shape 2).requested string    
(shape 2).usersDn string    
(shape 3) object    
(shape 3).directory boolean    
(shape 3).groups list    
(shape 3).groups[] string    
(shape 4) object    
(shape 4).adminGroups object    
(shape 4).adminGroups.read string, or null    
(shape 4).adminGroups.write string, or null    
(shape 4).baseDn string    
(shape 4).entryCount number    
(shape 4).entryDn string    
(shape 4).found boolean    
(shape 4).group null    
(shape 4).groupCount number    
(shape 4).groups list    
(shape 4).groups[].attributeCount number    
(shape 4).groups[].claimedCount number    
(shape 4).groups[].cn string    
(shape 4).groups[].createdAt string, or number, or null    
(shape 4).groups[].danglingCount number    
(shape 4).groups[].description string    
(shape 4).groups[].dn string    
(shape 4).groups[].memberCount number    
(shape 4).groups[].modifiedAt string, or number, or null    
(shape 4).groups[].objectClass list    
(shape 4).groups[].objectClass[] string    
(shape 4).groups[].origin string    
(shape 4).groups[].ownerCount number    
(shape 4).groups[].presentCount number    
(shape 4).groups[].rule string    
(shape 4).groupsDn string    
(shape 4).ldapsListening boolean    
(shape 4).ldapsPort number, or null    
(shape 4).listenError string, or null    
(shape 4).listening boolean    
(shape 4).maxEntries number    
(shape 4).notAGroup boolean    
(shape 4).port number, or null    
(shape 4).requested string    
(shape 4).usersDn string    
(shape 4).wanted string    
(shape 5) object    
(shape 5).found boolean    
(shape 5).group object    
(shape 5).group.cn string    
(shape 5).group.description string    
(shape 5).group.dn string    
(shape 5).group.maxOwners number    
(shape 5).group.memberCount number    
(shape 5).group.members list    
(shape 5).group.members[].attribute string    
(shape 5).group.members[].cn string    
(shape 5).group.members[].displayName string    
(shape 5).group.members[].dn string    
(shape 5).group.members[].holds string    
(shape 5).group.members[].kind string    
(shape 5).group.members[].mail string    
(shape 5).group.members[].present boolean    
(shape 5).group.members[].userKey string    
(shape 5).group.members[].value string    
(shape 5).group.owners list    
(shape 5).group.owners[].dn string    
(shape 5).group.owners[].kind string    
(shape 5).group.owners[].name string    
(shape 5).group.owners[].present boolean    
(shape 5).membersPaging object    
(shape 5).membersPaging.firstRow integer    
(shape 5).membersPaging.lastRow integer    
(shape 5).membersPaging.noun string    
(shape 5).membersPaging.page integer    
(shape 5).membersPaging.pages integer    
(shape 5).membersPaging.param string    
(shape 5).membersPaging.perPage integer    
(shape 5).membersPaging.total integer    

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/groups/add-member

addGroupMember

Put somebody in a group that already exists

One membership value onto one group. group is its cn or its whole DN; member is a user name or any DN.

IT IS IDEMPOTENT. Adding somebody already listed answers ok: true with changed: false rather than an error, so a script that adds on every run does not fail on its second one. Membership is asked across member, uniqueMember and memberUid together, which is how /admin/groups and the groups claim ask it — an add that could not see a memberUid would write a second value for one membership.

It writes onto member whatever else the entry carries, rather than extending whichever convention the group already uses: this service’s groups claim, the console and RFC 4519 all read member first, and guessing which of three attributes was meant would be this operation deciding something the caller did not say.

It does not create the group as a side effect. A typo in the name would then be a new group rather than an error. And it writes nothing onto the PERSON: memberOf is maintained by nothing here — it is not even a standard attribute — and a value written there is one no other door in this service can take away.

Removing one is not here. It is an ldapmodify or a SCIM PATCH, and POST /admin-api/rbac for the two groups that grant the console.

Mirrors POST /admin/groups and POST /admin/groups/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
group string yes The group’s cn or its whole DN.
member string yes A user name, or the DN of any entry.
user string   Accepted for member.
username string   Accepted for member.

200: Whether anything changed, the value written, and whether it resolves to an entry this directory holds.

Member Type Required What it is
attribute string    
changed boolean    
dn string    
entry object    
entry.attributes map    
entry.attributes.{key} list, or string    
entry.attributes.{key}[] string    
entry.createdAt string, or number, or null    
entry.dn string    
entry.members list    
entry.members[].attribute string    
entry.members[].cn string    
entry.members[].displayName string    
entry.members[].dn string    
entry.members[].holds string    
entry.members[].kind string    
entry.members[].mail string    
entry.members[].present boolean    
entry.members[].userKey string    
entry.members[].value string    
entry.modifiedAt string, or number, or null    
entry.operational list    
entry.operational[] string    
entry.origin string    
entry.rule string    
errors list    
errors[] string    
member string    
memberCount number    
message string    
ok boolean yes  
present boolean    
reason string    

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

Member Type Required What it is
attribute string    
changed boolean    
dn string    
entry object    
entry.attributes map    
entry.attributes.{key} list, or string    
entry.attributes.{key}[] string    
entry.createdAt string, or number, or null    
entry.dn string    
entry.members list    
entry.members[].attribute string    
entry.members[].cn string    
entry.members[].displayName string    
entry.members[].dn string    
entry.members[].holds string    
entry.members[].kind string    
entry.members[].mail string    
entry.members[].present boolean    
entry.members[].userKey string    
entry.members[].value string    
entry.modifiedAt string, or number, or null    
entry.operational list    
entry.operational[] string    
entry.origin string    
entry.rule string    
errors list    
errors[] string    
member string    
memberCount number    
message string    
ok boolean yes  
present boolean    
reason string    

POST /admin-api/groups/add-owner

addGroupOwner

Add one owner to a group

Adds a person or a group of this realm to the group’s owner values (RFC 4519 section 2.23) and writes at once, keeping the other owners. owner is a username, a DN or a urn:uuid: subject for a person, a cn or DN for a group.

Unlike a member, an owner must name somebody: one that names no person and no group here is refused. A group may not own itself, and 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.

Mirrors POST /admin/groups and POST /admin/groups/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
group string yes The group’s cn, DN or SCIM id.
owner string yes The person or group to add.

200: Whether anything changed, and the group’s owners as they now stand (owners).

Member Type Required What it is
changed boolean    
dn string    
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    

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

Member Type Required What it is
changed boolean    
dn string    
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    

POST /admin-api/groups/create

createGroup

Put a group in the directory

An entry under ou=groups, as a groupOfNames — so it is counted as a group by BOTH of the rules /admin/groups applies, its placement and its object class, and stays one if a client moves it.

The name becomes the cn AND the RDN, so it is refused if it carries a character RFC 4514 section 2.4 reserves in a DN (one of , = + < > # ; " \) — the same rule a username is refused by, and refused rather than escaped for the same reason: an ldapadd can still create such an entry with the escaping written out. A DN sent here is refused too, because what it would create is a group whose name is another group’s DN.

A member that names nothing is WRITTEN, not refused. This directory does no referential integrity in either direction — deleting a person leaves their DN in every group that listed them — so a create that refused a dangling member would make the state /admin/groups exists to report impossible to produce from this door. They come back in dangling.

An empty group is allowed and RFC 4519 says it should not be (member is MUST on groupOfNames). SCIM already creates one; a management API stricter than SCIM about the same store would be two doors disagreeing about what this directory holds.

IT GRANTS NOTHING. No endpoint here decides anything on a group. The two that do are admin.readGroup and admin.writeGroup, and they are granted at POST /admin-api/rbac rather than by creating a group with the right name — though creating one with the right name and adding somebody to it does the same thing, because those two ARE ordinary groups in this directory.

Mirrors POST /admin/groups and POST /admin/groups/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
displayName string   Accepted for group, spelt the way SCIM spells it.
group string yes The cn. Not a DN — this puts it under ou=groups in the realm the call is made in.
mail string   The group’s own email address, its mail attribute (#989): where a report definition shared with the group sends its result notices. One address, or omitted.
members list, or string    
members[] string    
note string   What the entry’s description says about why it exists. Defaults to a sentence saying it was created by hand rather than by a directory client.

200: The DN it was created at, the membership values written, and which of them name nothing.

Member Type Required What it is
dangling list    
dangling[] string    
dn string    
entry object    
entry.attributes map    
entry.attributes.{key} list, or string    
entry.attributes.{key}[] string    
entry.createdAt string, or number, or null    
entry.dn string    
entry.members list    
entry.members[].attribute string    
entry.members[].cn string    
entry.members[].displayName string    
entry.members[].dn string    
entry.members[].holds string    
entry.members[].kind string    
entry.members[].mail string    
entry.members[].present boolean    
entry.members[].userKey string    
entry.members[].value string    
entry.modifiedAt string, or number, or null    
entry.operational list    
entry.operational[] string    
entry.origin string    
entry.rule string    
errors list    
errors[] string    
existing object    
existing.dn string    
existing.origin string    
group string    
members list    
members[] string    
message string    
ok boolean yes  
reason string    

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

Member Type Required What it is
dangling list    
dangling[] string    
dn string    
entry object    
entry.attributes map    
entry.attributes.{key} list, or string    
entry.attributes.{key}[] string    
entry.createdAt string, or number, or null    
entry.dn string    
entry.members list    
entry.members[].attribute string    
entry.members[].cn string    
entry.members[].displayName string    
entry.members[].dn string    
entry.members[].holds string    
entry.members[].kind string    
entry.members[].mail string    
entry.members[].present boolean    
entry.members[].userKey string    
entry.members[].value string    
entry.modifiedAt string, or number, or null    
entry.operational list    
entry.operational[] string    
entry.origin string    
entry.rule string    
errors list    
errors[] string    
existing object    
existing.dn string    
existing.origin string    
group string    
members list    
members[] string    
message string    
ok boolean yes  
reason string    

POST /admin-api/groups/remove-owner

removeGroupOwner

Take one owner off a group

Takes one owner value off the group and writes at once (#603). owner is the DN the group lists; one it does not list is refused. The last owner may go: a group needs none.

Mirrors POST /admin/groups and POST /admin/groups/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
group string yes The group’s cn, DN or SCIM id.
owner string yes The owner’s DN.

200: The group’s owners as they now stand (owners).

Member Type Required What it is
changed boolean    
dn string    
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    

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

Member Type Required What it is
changed boolean    
dn string    
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    

POST /admin-api/groups/set-mail

setGroupMail

Set or clear a group’s email address

Writes one mail value onto the group’s own entry, or removes it when mail is empty. It is where a report definition shared with the group sends its result notices (the reports application, #989); a shared group with no address is written up as STS-REPORT-0037 when a notice is due. group is its cn or its whole DN. Idempotent: the same address again, or clearing one that is already absent, answers ok: true with changed: false. A value that is not an address (one local part, one @, a domain with a dot, no whitespace) is refused.

Mirrors POST /admin/groups and POST /admin/groups/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
group string yes The group’s cn or its whole DN.
mail string   The address, or empty to remove it.

200: Whether anything changed, and the address now on the entry.

Member Type Required What it is
changed boolean    
dn string    
entry object    
entry.attributes map    
entry.attributes.{key} list, or string    
entry.attributes.{key}[] string    
entry.createdAt string, or number, or null    
entry.dn string    
entry.members list    
entry.members[].attribute string    
entry.members[].cn string    
entry.members[].displayName string    
entry.members[].dn string    
entry.members[].holds string    
entry.members[].kind string    
entry.members[].mail string    
entry.members[].present boolean    
entry.members[].userKey string    
entry.members[].value string    
entry.modifiedAt string, or number, or null    
entry.operational list    
entry.operational[] string    
entry.origin string    
entry.rule string    
errors list    
errors[] string    
mail string    
message string    
ok boolean yes  
reason string    

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

Member Type Required What it is
changed boolean    
dn string    
entry object    
entry.attributes map    
entry.attributes.{key} list, or string    
entry.attributes.{key}[] string    
entry.createdAt string, or number, or null    
entry.dn string    
entry.members list    
entry.members[].attribute string    
entry.members[].cn string    
entry.members[].displayName string    
entry.members[].dn string    
entry.members[].holds string    
entry.members[].kind string    
entry.members[].mail string    
entry.members[].present boolean    
entry.members[].userKey string    
entry.members[].value string    
entry.modifiedAt string, or number, or null    
entry.operational list    
entry.operational[] string    
entry.origin string    
entry.rule string    
errors list    
errors[] string    
mail string    
message string    
ok boolean yes  
reason string    

POST /admin-api/groups/set-policy

setGroupPolicy

Set or clear the named policy a group names of one kind

Writes one value of attribute — the attribute by which a group names its policy of a kind, stsPasskeyPolicy for the passkey policy — onto the group’s own entry, or removes it when policy is empty. policy is default or a named policy of that kind this realm holds (STS-LDAP-0195 otherwise); an attribute no kind declares is refused (STS-LDAP-0194). The policy a group names competes for each of its members on precedence with the policy the application names, the policy the person names and the policies their other groups name: the lowest applies, ties by name, else default. A named policy a group still names cannot be deleted. GET /admin-api/groups?group= lists the attributes and their choices as policyReferences. Idempotent: the value the group already names answers changed: false.

Mirrors POST /admin/groups and POST /admin/groups/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
attribute string yes The reference attribute, as policyReferences lists it.
group string yes The group’s cn or its whole DN.
policy string   default, a named policy of the kind, or empty to remove it.

200: Whether anything changed, and the policy the group now names.

Member Type Required What it is
attribute string    
changed boolean    
dn string    
errors list    
errors[] string    
message string    
ok boolean yes  
reason string    
value string    

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

Member Type Required What it is
attribute string    
changed boolean    
dn string    
errors list    
errors[] string    
message string    
ok boolean yes  
reason string    
value string