User group endpoints
Sections
Groups are used to assign roles to a group of users, which is vastly more efficient
than managing roles for each user individually. The groups
endpoints enable
you to get lists of groups and to add a new directory group.
User group keys
These keys are used with the RBAC v1 API's groups
endpoints.
Key | Explanation | Example |
---|---|---|
id |
A UUID string identifying the group. | "c099d420-5557-11e4-916c-0800200c9a66" |
login |
The identifier for the user group on the directory server. | "poets" |
display_name |
The group's name as a string. | "Poets" |
role_ids |
An array of role IDs indicating roles to be inherited by the group's members. An empty array is valid. This is the only field that can be updated via RBAC; the rest are immutable or synced from the directory service. | [3 6 5] |
|
These flags indicate that the group is a group. |
true , true , false , respectively |
is_revoked |
Setting this flag to true currently
does nothing for a group. |
true /false
|
user_ids |
An array of UUIDs indicating which users inherit roles from this group. | ["3a96d280-54c9-11e4-916c-0800200c9a66"] |
GET /groups
Fetches all groups. Supports filtering by ID through query parameters. Authentication is required.
Request format
GET /groups
Copied!
GET /groups?id=65a068a0-588a-11e4-8ed6-0800200c9a66,75370a30-588a-11e4-8ed6-0800200c9a66
Copied!
curl 'https://$(puppet config print server):4433/rbac-api/v1/groups' \
-H "X-Authentication:$(puppet-access show)"
Copied!
Response format
[{
"id": "65a068a0-588a-11e4-8ed6-0800200c9a66",
"login": "hamsters",
"display_name": "Hamster club",
"role_ids": [2, 3],
"is_group" : true,
"is_remote" : true,
"is_superuser" : false,
"user_ids": ["07d9c8e0-5887-11e4-8ed6-0800200c9a66"]}
},{
"id": "75370a30-588a-11e4-8ed6-0800200c9a66",
"login": "chinchilla",
"display_name": "Chinchilla club",
"role_ids": [2, 1],
"is_group" : true,
"is_remote" : true,
"is_superuser" : false,
"user_ids": ["1cadd0e0-5887-11e4-8ed6-0800200c9a66","5c1ab4b0-588b-11e4-8ed6-0800200c9a66"]
},{
"id": "ccdbde50-588a-11e4-8ed6-0800200c9a66",
"login": "wombats",
"display_name": "Wombat club",
"role_ids": [2, 3],
"is_group" : true,
"is_remote" : true,
"is_superuser" : false,
"user_ids": []
}]
Copied!
GET /groups/<sid>
Fetches a single group by its subject ID (<sid>
).
Authentication is required.
Request format
curl 'https://$(puppet config print server):4433/rbac-api/v1/groups/65a068a0-588a-11e4-8ed6-0800200c9a66' \
-H "X-Authentication:$(puppet-access show)"
Copied!
Response format
The response contains an ID for the
group and a list of role_ids
the
group is directly assigned to.
For directory groups, the response contains the display name, the login field, a list of
role_ids
directly assigned to the group, and
user_ids
containing IDs of the remote users that belong to that
group.
{"id": "65a068a0-588a-11e4-8ed6-0800200c9a66",
"login": "hamsters",
"display_name": "Hamster club",
"role_ids": [2, 3],
"is_group" : true,
"is_remote" : true,
"is_superuser" : false,
"user_ids": ["07d9c8e0-5887-11e4-8ed6-0800200c9a66"]}
Copied!
Error responses
If the user who submits the GET
request has not successfully
authenticated, the endpoint returns 401 Unauthorized.
If the current user does not have the appropriate user permissions to request the group data, the endpoint returns 403 Forbidden.
POST /groups
Creates a new remote group and attaches to the new group any roles specified in its roles list. Authentication is required.
Request format
login
and an array of
role_ids
to assign to the group initially. For
example:{"login":"Augmentators",
"role_ids": [1,2,3]}
Copied!
curl POST 'https://$(puppet config print server):4433/rbac-api/v1/groups' \
-H "X-Authentication:$(puppet-access show)" \
-H "Content-type: application/json" \
-d '{"login":"Augmentators",
"role_ids": [1,2,3]}
Copied!
Response format
If the create operation is successful, the endpoint returns 201 Created with a location header that points to the new resource.
Error responses
If the login for the group conflicts with an existing group login, the endpoint returns 409 Conflict.
PUT /groups/<sid>
Replaces the group with the specified ID (<sid>
)
with a new group object. Authentication is required.
Request format
Accepts an updated group object containing all the keys that were received from the API
initially. The only field you can update is role_ids
. An empty
role_ids
array indicates a desire to remove the
group from all the roles it was directly assigned to. Any other changed values are
ignored.
{"id": "75370a30-588a-11e4-8ed6-0800200c9a66",
"login": "chinchilla",
"display_name": "Chinchillas",
**"role_ids": [2, 1],**
"is_group" : true,
"is_remote" : true,
"is_superuser" : false,
"user_ids": ["1cadd0e0-5887-11e4-8ed6-0800200c9a66","5c1ab4b0-588b-11e4-8ed6-0800200c9a66"]}
Copied!
curl -X PUT 'https://$(puppet config print server):4433/rbac-api/v1/groups/75370a30-588a-11e4-8ed6-0800200c9a66' \
-H "X-Authentication:$(puppet-access show)" \
-H "Content-type: application/json" \
-d '{"id":"75370a30-588a-11e4-8ed6-0800200c9a66",
"login":"chinchilla",
"display_name":"Chinchillas",
"role_ids":[2,1],
"is_group":true,
"is_remote":true,
"is_superuser":false,
"user_ids":["1cadd0e0-5887-11e4-8ed6-0800200c9a66","5c1ab4b0-588b-11e4-8ed6-0800200c9a66"]}'
Copied!
Response format
If the operation is successful, the endpoint returns 200 OK and a group object with updated roles.
DELETE /groups/<sid>
Deletes the user group with the specified ID (<sid>
) from RBAC without making any changes to the directory service.
Authentication required.
Request format
curl -X DELETE 'https://$(puppet config print server):4433/rbac-api/v1/groups/75370a30-588a-11e4-8ed6-0800200c9a66' \
-H "X-Authentication:$(puppet-access show)"
Copied!
Response format
If the user group is successfully deleted, the endpoint returns 204 No Content.
Error responses
If the current user does not have the user_groups:delete
permission for this
user group, the endpoint returns 403 Forbidden.
If a group with the provided identifier does not exist, the endpoint returns 404 Not Found.