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` or`false`
`user_ids`	An array of UUIDs indicating which users belong to the group.	`["3a96d280-54c9-11e4-916c-0800200c9a66"]`
`identity_provider_id`	The UUID of the LDAP identity provider associated with the group.	`"4522ca7e-5623-11ed-bdc3-0242ac120002"`

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 /command/groups/create

Create a remote directory user group. 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 the following keys:

login: Defines the group for an external IdP, such as an LDAP login or a SAML identifier for the group.
role_ids: An array of IDs defining the roles that you want to assign to users in this group. Roles grant permissions to group members.
identity_provider_id: Specify the UUID of an identity provider to bind to the group.
display_name: Optional. Specify a name for the group that is visible in the PE console. If this group originates from an LDAP group, this value is determined by the group's Display name setting in LDAP.

Request example:

curl -X POST "https://$(puppet config print server):4433/rbac-api/v1/command/groups/create" \
-H "X-Authentication:$(puppet-access show)" \
-H "Content-type: application/json" \
-d '{
     "login": "augmentators",
     "role_ids": [1,2,3],
     "display_name": "The Augmentators"
     "identity_provider_id": "0e1a11bd-658f...-732887"
    }'

Response format

If the group is created successfully, the endpoint returns 200 OK.

If you don't have permission to create groups, the response is 403 Not Permitted

Malformed requests return 400 Bad Request.

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.

POST /groups (deprecated)

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

Important: This endpoint is deprecated. Instead, use POST /command/groups/create.

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.

Was this page helpful?

We’re sorry to hear that!
Please tell us why so we can help. Enter your feedback and email. This form is sent to the Puppet docs team. We ask for your email as we might contact you regarding your feedback. If you need help with the product itself, visit Puppet Support or ask in Puppet Community on Slack. Feedback:

Email Address:

To learn about how Puppet uses your personal information, visit our privacy policy.

If you leave us your email, we may contact you regarding your feedback. For more information on how Puppet uses your personal information, see our privacy policy.

See an issue? Please file a JIRA ticket in our [DOCUMENTATION] project.