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 |