User roles endpoints

User roles contain sets of permissions. When you assign a user (or a user group) to a role, you can assign the entire set of permissions at once. This is more organized and easier to manage than assigning individual permissions to individual users. Use the roles endpoints to manage roles.

You can:

GET /roles: Get a list of roles.
GET /roles/<rid>: Get information about a specific role.
POST /roles: Create a role.
PUT /roles/<rid>: Edit a role.
DELETE /roles/<rid>: Delete a role.
POST /command/roles/add-users: Assign a role to users.
POST /command/roles/remove-users: Remove a role from users.
POST /command/roles/add-user-groups: Assign a role to user groups.
POST /command/roles/remove-groups: Remove a role from user groups.
POST /command/roles/add-permissions: Add permissions to a role.
POST /command/roles/remove-permissions: Remove permissions from a role.

Tip: You'll want to be familiar with the User roles endpoints keys that appear in these endpoints' requests and responses.

Some command endpoints are similar to other endpoints, such as the POST /command/users/add-roles endpoint. However, in this case, the role is the focus. For example, whereas the POST /command/users/add-roles endpoint assigns multiple roles to one user, the POST /command/roles/add-users endpoint assigns one role to multiple users.

User roles endpoints keys

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


Key	Definition	Example
`id`	An integer identifying the role.	`18`
`display_name`	The role's name as a string.	`"Viewers"`
`description`	A string describing the role's function.	`"View-only permissions"`
`permissions`	An array containing permission objects that indicate what permissions a role grants. An empty array is valid. See Permissions endpoints keys for possible content.	`[]`
`user_ids` `group_ids`	An array of UUIDs indicating which users and groups are directly assigned to the role. An empty array is valid. Users belonging to specified groups receive the role through the group, but those users aren't listed individually.	`["fc115750-555a-11e4-916c-0800200c9a66"]`

GET /roles

Fetches information about all user roles. 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/roles' -H "X-Authentication:$(puppet-access show)"

Response format

The response is a JSON object that lists metadata for roles, including permissions objects, and lists of users and groups assigned to the role. For example:

[{"id": 123,
  "permissions": [{"object_type":"node_groups",
                   "action":"edit_rules",
                   "instance":"*"}, ...],
  "user_ids": ["1cadd0e0-5887-11e4-8ed6-0800200c9a66","5c1ab4b0-588b-11e4-8ed6-0800200c9a66"],
  "group_ids": ["2ca57e30-5887-11e4-8ed6-0800200c9a66"],
  "display_name": "A role",
  "description": "Edit node group rules"},
...]

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

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

GET /roles/<rid>

Fetches information about a single role indentified by its role ID (rid). Authentication is required.

Request format

When Forming RBAC API requests to this endpoint, provide authentication and specify a role ID, such as:

curl 'https://$(puppet config print server):4433/rbac-api/v1/roles/1234' -H "X-Authentication:$(puppet-access show)"

Response format

Returns a 200 OK response with a JSON object containing information about the requested role. For example:

{"id": 123,
 "permissions": [{"object_type":"node_groups",
                  "action":"edit_rules",
                  "instance":"*"}, ...],
 "user_ids": ["1cadd0e0-5887-11e4-8ed6-0800200c9a66","5c1ab4b0-588b-11e4-8ed6-0800200c9a66"],
 "group_ids": ["2ca57e30-5887-11e4-8ed6-0800200c9a66"],
 "display_name": "A role",
 "description": "Edit node group rules"}

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

For error responses, refer to RBAC service errors.

POST /roles

Create a role. 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:

permissions: An array of permission objects (consisting of sets of object_type, action, and instance) defining the permissions associated with this role. Required, but can be empty. An empty array means no permissions are associated with the role.
group_ids: An array of group IDs defining the user groups you want to assign this role to. All users in the groups (or added to the groups in the future) receive this role through their group membership. Required, but can be empty. An empty array means the role is not assigned to any groups.
user_ids: An array of user IDs defining the individual users that you want to assign this role to. You do not need to repeat any users who are part of a group mentioned in group_ids. Required, but can be empty. An empty array means the role is not assigned to any individual users.
display_name: A string naming the role.
description: A string describing the role's purpose. Can be null.

For example:

curl -X POST 'https://$(puppet config print server):4433/rbac-api/v1/roles' \
-H "X-Authentication:$(puppet-access show)" \
-H "Content-type: application/json" \
-d '{"permissions": [{"object_type":"node_groups", "action":"edit_rules", "instance":"*"}],
     "user_ids": ["1cadd0e0-5887-11e4-8ed6-0800200c9a66", "5c1ab4b0-588b-11e4-8ed6-0800200c9a66"],
     "group_ids": ["2ca57e30-5887-11e4-8ed6-0800200c9a66"],
     "display_name": "A role",
     "description": "Edit node group rules"}'

For more information about these keys, refer to User roles endpoints keys.

Tip:

If you're writing a role for a task-target, you must include unique action and instance key values to specify permissions:


Key	Value	Explanation
`action`	`run_with_constraints`	Specifies that the user has permission to run a task on certain nodes within the confines of a given task-target.
`instance`	`<task-target_ID>`	Specifies the ID of the task-target the user has permission to run.

For the complete task-target workflow, refer to the Puppet Enterprise RBAC API, or how to manage access to tasks blog post.

Response format

If the role was successfully created, the endpoint returns a 201 Created response with a location header pointing to the new resource.

Tip: If your request included any empty arrays, you can use these endpoints to add permissions, groups, and users to your role:

Error responses

Returns a 409 Conflict response if the role has a name that collides with an existing role.

For other errors, refer to RBAC service errors.

PUT /roles/<rid>

Replaces the content of the specified role object. For example, you can update the role's permissions or user 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 /roles/<rid> endpoint response. You must supply all keys; however, you can't update the id key. Any values supplied in editable keys replace the role's current values. If you want to values, you need to supply all of the role's current values plus the new values. If you supply an empty array (or a null description), the current content is removed. For example, supplying an empty user_ids array removes any individual users that were assigned to the role.

For example:

curl -X PUT 'https://$(puppet config print server):4433/rbac-api/v1/<rid> \
-H "X-Authentication: $(puppet-access show)"  \
-H "Content-type: application/json" \
-d '{
     "permissions": [{"object_type":"node_groups", "action":"edit_rules", "instance":"*"}],
     "user_ids": ["1cadd0e0-5887-11e4-8ed6-0800200c9a66", "5c1ab4b0-588b-11e4-8ed6-0800200c9a66"],
     "group_ids": ["2ca57e30-5887-11e4-8ed6-0800200c9a66"],
     "display_name": "A role",
     "description": "Edit node group rules"}'

Response format

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

Error responses

For errors, refer to RBAC service errors.

DELETE /roles/<rid>

Deletes the role with the specified role ID. Users who had this role (either directly or through a user group) immediately lose the role and all permissions granted by it, but their session is otherwise unaffected. The next action the user takes in PE is determined by their permissions without the deleted role.

Request format

When Forming RBAC API requests to this endpoint, the URI path must include the ID of the role you want to delete. For example:

curl -X DELETE 'https://$(puppet config print server):4433/rbac-api/v1/roles/1234' \
-H "X-Authentication:$(puppet-access show)"

Response format

Returns a 200 OK response if the role was deleted.

Error responses

Returns a 404 Not Found response if no role exists for the specified role ID.

Returns a 403 Forbidden response if the requesting user lacks permission to delete the role identified by role ID.

For other errors, refer to RBAC service errors.

POST /command/roles/add-users

Assign a role to one or more users.

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:

role_id: The ID of the role you want to assign users to.
user_ids: An array of user IDs defining the users that you want to assign to the role.

Example payload:

{ "role_id": <role_id>, "user_ids": [<user_id1>, <user_id2>, <user_id3>, ...]}

Example curl request:

curl -X POST 'https://$(puppet config print server):4433/rbac-api/v1/command/roles/add-users' \
-H "X-Authentication:$(puppet-access show)"  \
-H "Content-type: application/json" \
-d '{"role_id": 1, "user_ids": ["5c1ab4b0-588b-11e4-8ed6-0800200c9a66"]}'

Tip: To assign multiple roles to a single user at once, use the POST /command/users/add-roles endpoint.

Response format

Returns 204 No Content if the users are successfully assigned the role.

Returns 404 Not Found if any of the users don't exist.

For other errors, refer to RBAC service errors.

POST /command/roles/remove-users

Remove a role from one or more users.

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:

role_id: The ID of the role you want to remove users from.
user_ids: An array of user IDs defining the users that you want to remove from the role.

Example payload:

{ "role_id": <role_id>, "user_ids": [<user_id1>, <user_id2>, <user_id3>, ...]}

Example curl request:

curl -X POST 'https://$(puppet config print server):4433/rbac-api/v1/command/roles/remove-users' \
-H "X-Authentication:$(puppet-access show)"  \
-H "Content-type: application/json" \
-d '{"role_id": 1, "user_ids": ["5c1ab4b0-588b-11e4-8ed6-0800200c9a66"]}'

Response format

Returns 204 No Content if the users are removed from the role.

Note: A request with an invalid role_id still returns 204 No Content even though no users were removed from the nonexistent role.

Returns 400 Bad request if a user doesn't exist.

For other errors, refer to RBAC service errors.

POST /command/roles/add-user-groups

Add a role to one or more user groups.

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:

role_id: The ID of the role you want to assign to groups.
group_ids: An array of user group IDs defining the groups that you want to assign the role to.

Example payload:

{ "role_id": <role-id>, "group_ids":[<id>,<id>,<id>] }

Example curl request:

curl -X POST 'https://$(puppet config print server):4433/rbac-api/v1/command/roles/add-user-groups' \
-H "X-Authentication:$(puppet-access show)"  \
-H "Content-type: application/json" \
-d '{"role_id": 1, "group_ids": ["2ca57e30-5887-11e4-8ed6-0800200c9a66"]}'

Response format

Returns 204 No Content if the user groups are successfully added to the role.

For errors, refer to RBAC service errors.

POST /command/roles/remove-groups

Remove a role from one or more user groups.

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:

role_id: The ID of the role you want to remove groups from.
group_ids: An array of user group IDs defining the groups that you want to remove the role from.

Example payload:

{ "role_id": <role-id>, "group_ids":[1,2,3] }

Example curl request:

curl -X POST 'https://$(puppet config print server):4433/rbac-api/v1/command/roles/remove-groups' \
-H "X-Authentication:$(puppet-access show)"  \
-H "Content-type: application/json" \
-d '{"role_id": 1, "group_ids": ["a2450020-4217-439d-9bc4-258f6d2d7e76"]}'

Response format

Returns 204 No Content if the user groups are successfully removed from the role.

For errors, refer to RBAC service errors.

POST /command/roles/add-permissions

Add permissions to a role.

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:

role_id: The ID of the role you want to add permissions to.
permissions: An array of permissions objects describing the permissions to add to the role. Permissions objects consist of sets of object_type, action, and instance.

Example payload:

{
 "role_id": <role-id>,
 "permissions:[
    {"object_type": <TYPE>, 
     "action": <ACTION>, 
     "instance": <INSTANCE>}, 
...]

Example curl request:

curl -X POST 'https://$(puppet config print server):4433/rbac-api/v1/command/roles/add-permissions' \
-H "X-Authentication:$(puppet-access show)"  \
-H "Content-type: application/json" \
-d '{"role_id": 1, 
     "permissions": [
          {"object_type":"node_groups", 
           "action":"edit_rules", 
           "instance":"*"}
      ]
    }'

Response format

Returns 204 No Content if the permissions are successfully added to the role.

For errors, refer to RBAC service errors.

POST /command/roles/remove-permissions

Remove permissions from a role.

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:

role_id: The ID of the role you want to remove permissions from.
permissions: An array of permissions objects describing the permissions to remove from the role. Permissions objects consist of sets of object_type, action, and instance.

Example payload:

{
 "role_id": <role-id>,
 "permissions:[
    {"object_type": <TYPE>, 
     "action": <ACTION>, 
     "instance": <INSTANCE>}, 
...]

Example curl request:

curl -X POST 'https://$(puppet config print server):4433/rbac-api/v1/command/roles/remove-permissions' \
-H "X-Authentication:$(puppet-access show)" \
-H "Content-type: application/json" \
-d '{"role_id": 1, 
     "permissions": [
          {"object_type":"node_groups", 
           "action":"edit_rules", 
           "instance":"*"}
      ]
    }'

Response format

Returns 204 No Content when the permissions are successfully removed from the role.

An error in the standard format is returned for all other responses.

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.