User groups endpoints

User groups allow you to quickly assign one or more roles to a set of users by placing all relevant users in the group. This is more efficient than assigning roles to each user individually. Use the groups endpoints to get lists of groups and add, delete, and change groups.

Remember: Group membership is determined by your directory service hierarchy. Therefore, local users (that exist only in the PE console) can't be in directory groups. You'll need to use the Users endpoints to manage these users' roles.

User groups endpoints keys

These keys are used with the RBAC API v1 groups endpoints.

Key Definition Example
id A UUID string identifying the group. "c099d420-5557-11e4-916c-0800200c9a66"
login The identifier for the user group on the directory server. "admins"
display_name The group's name as a string. "Admins"
role_ids An array of role IDs indicating roles to assign to the group's members. An empty array is valid.
Tip: This is the only field that can be updated via RBAC; the rest are immutable or synced from the directory service.
 [3 6 5]

is_group

is_remote

is_superuser

 These flags indicate that the group is a group, derived from the directory service, and not a super user (inherently, a group can't be a user). These are set to true, true, and false, respectively
is_revoked No effect. Because groups are not user objects, setting this flag to true does nothing. true orfalse
user_ids An array of UUIDs indicating which users belong to the group. ["3a96d280-54c9-11e4-916c-0800200c9a66"]

GET /groups

Fetch information about all user groups. Authentication is required.

Request format

When Forming RBAC API requests to this endpoint, the request is a basic call with authentication, such as:
curl "https://$(puppet config print server):4433/rbac-api/v1/groups" \
-H "X-Authentication:$(puppet-access show)"
To query specific groups, append a comma-separated list of group IDs:
curl "https://$(puppet config print server):4433/rbac-api/v1/groups?id=<SID>,<SID>" \
-H "X-Authentication:$(puppet-access show)"

Response format

The response is a JSON object that lists the metadata for all requested groups. For example:
[{
  "id": "65a068a0-588a-11e4-8ed6-0800200c9a66",
  "login": "admins",
  "display_name": "Admins",
  "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": "owners",
  "display_name": "Owners",
  "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": "viewers",
  "display_name": "Viewers",
  "role_ids": [2, 3],
  "is_group" : true,
  "is_remote" : true,
  "is_superuser" : false,
  "user_ids": []
}]

For information about keys in the response, refer to User groups endpoints keys.

For information about error responses, refer to RBAC service errors.

GET /groups/<sid>

Fetches information about a single user group identified by ID. Authentication is required.

Request format

When Forming RBAC API requests to this endpoint, provide authentication and specify a group ID, such as:
curl "https://$(puppet config print server):4433/rbac-api/v1/groups/<SID>" \
-H "X-Authentication:$(puppet-access show)"

To request information for multiple specific groups, use the GET /groups endpoint with the id parameter.

Response format

The response is a JSON object containing information about the requested group. For example:
{"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"]}

For information about keys in the response, refer to User groups endpoints keys.

Error responses

If the user who submits the GET request has not successfully authenticated, the endpoint returns a 401 Unauthorized response.

If the requesting user does not have the appropriate user permissions to request the group data, the endpoint returns a 403 Forbidden response.

For other error responses, refer to RBAC service errors.

POST /groups

Creates a new remote directory user group. Authentication is required.

Tip: The v2 POST /groups endpoint supports more options for creating groups, including assigning a display name and the option to validate if the group exists on the LDAP server before creating it.

Request format

When Forming RBAC API requests to this endpoint, the content type is application/json. The body must be a JSON object using the following keys:
  • login: Defines the group for an external IdP. This could be an LDAP login or a SAML identifier for the group.
  • role_ids: An array of role IDs defining the roles that you want to assign to users in this group. An empty array might be valid, but users can't do anything in PE if they are not assigned to any roles.
For example:
curl -X 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]}'

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 a 409 Conflict response.

For other errors, refer to RBAC service errors.

PUT /groups/<sid>

Replaces the content of the specified user group object. For example, you can update the group's roles or membership. Authentication is required.

Request format

When Forming RBAC API requests to this endpoint, the content type is application/json. The body must be a JSON object using all keys supplied in the GET /groups/<sid> endpoint response. You must supply all keys; however, the only key you can update is role_ids. Any values supplied in role_ids replace the group's current role values. If you want to add roles, you need to supply all of the group's current role IDs plus the new role IDs. If role_ids is empty, all roles are removed from the group (and, by extension, the roles are removed from users who belong to this group). Changes to keys other than role_ids are ignored.

Example curl request:
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":"admins",
     "display_name":"Admins",
     "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"]}'

Response format

If the operation is successful, the endpoint returns a 200 OK response and a group object with updated roles.

For errors, refer to RBAC service errors.

DELETE /groups/<sid>

Deletes the user group with the specified ID from PE RBAC. This endpoint does not change the directory service. Authentication is required.

Request format

When Forming RBAC API requests to this endpoint, the URI path must include the ID of the group you want to delete from the PE console. For example:
curl -X DELETE "https://$(puppet config print server):4433/rbac-api/v1/groups/75370a30-588a-11e4-8ed6-0800200c9a66" \
-H "X-Authentication:$(puppet-access show)"

Response format

If the user group is successfully deleted, the endpoint returns a 204 No Content response.

Error responses

If the requesting user does not have the user_groups:delete permission for this user group, the endpoint returns a 403 Forbidden response.

If there is no user group with the specified ID, the endpoint returns a 404 Not Found response.

For other errors, refer to RBAC service errors.