User roles endpoints
Sections
By assigning roles to users, you can manage them in sets
that are granted access permissions to various PE objects. This makes tracking user access
more organized and easier to manage. The roles
endpoints enable you to get lists of roles and create new
roles.
User role keys
The following keys are used with the RBAC v1 API’s roles endpoints.
Key | Explanation | 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 Permission keys for more information. |
[]
|
|
An array of UUIDs indicating which users and groups are directly assigned to the role. An empty array is valid. |
["fc115750-555a-11e4-916c-0800200c9a66"]
|
GET /roles
Fetches all roles with user and group ID lists and permission lists. Authentication is required.
Response format
Returns a JSON object containing all roles with user and group ID lists and permission lists.
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"},
...]
Copied!
GET /roles/<rid>
Fetches a single role by its ID (rid). Authentication is required.
Response format
Returns a 200 OK response with the role object with a full list of permissions and user and group IDs.
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"}
Copied!
POST /roles
Creates a role, and attaches to it the specified permissions and the specified users and groups. Authentication is required.
Permissions keys for task-targets
action
and instance
key values to specify
permissions. For the complete task-target
workflow, see the blog post Puppet Enterprise
RBAC API, or how to manage access to tasks.
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. |
Request format
Accepts a new role object. Any of the arrays can be empty and "description" can be null.
For example:
{"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"}
Copied!
Response format
Returns a 201 Created response with a location header pointing to the new resource.
Error responses
Returns a 409 Conflict response if the role has a name that collides with an existing role.
PUT /roles/<rid>
Replaces a role at the specified ID (rid) with a new role object. Authentication is required.
Request format
Accepts the modified role object.
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"}
Copied!
Response format
Returns a 200 OK response with the modified role object.
Error responses
Returns a 409 Conflict response if the new role has a name that collides with an existing role.
DELETE /roles/<rid>
Deletes the role identified by the role ID (rid). Users with this role immediately lose the role and all permissions granted by it, but their session is otherwise unaffected. Access to the next request that the user makes is determined by the new set of permissions the user has without this role.
Response format
Returns a 200 OK response if the role
identified by <rid>
has been
deleted.
Error responses
Returns a 404 Not Found response if no role
exists for <rid>
.
Returns a 403 Forbidden response if the current user lacks
permission to delete the role identified by <rid>
.
POST /command/roles/add-users
Add users to a role.
Request format
Key | Definition |
---|---|
role_id |
The ID of the role you want to add users to. |
user_ids |
A list of user IDs you want to add to the role. |
{ "role_id": <role_id>, "user_ids": [<user_id1>, <user_id2>, <user_id3>, ...]}
Copied!
Response format
A 204 response with no content is returned when the users are successfully added to the role.
A 404 not found response is returned if any of the users don't exist.
An error in the standard format is returned for all other responses.
POST /command/roles/remove-users
Remove users from a role.
Request format
The request accepts the following keys:
Key | Definition |
---|---|
role_id |
The ID of the role. |
user_ids |
A list of user IDs you want to remove from the role. |
{ "role_id": <role_id>, "user_ids": [<user_id1>, <user_id2>, <user_id3>, ...]}
Copied!
Response format
role_id
, the response is still a 204 even if the users aren’t
removed.A 400 response is returned if a user doesn't exist.
An error in the standard format is returned for all other responses.
POST /command/roles/add-user-groups
Add user groups to a role.
Request format
Key | Definition |
---|---|
role_id |
The ID of the role you want to add user groups to. |
group_ids |
A list of group IDs you want to add to the role. |
{ "role_id": <role-id>, "group_ids":[<id>,<id>,<id>] }
Copied!
Response format
A 204 response with no content is returned when the user groups are successfully added to the role.
An error in the standard format is returned for all other responses.
POST /command/roles/remove-groups
Remove user groups from a role.
Request format
Key | Definition |
---|---|
role_id |
The ID of the role you want to remove users from. |
group_ids |
A list of group IDs you want to remove from the role. |
{ "role_id": <role-id>, "group_ids":[1,2,3] }
Copied!
Response format
A 204 response with no content is returned when the user groups are successfully removed from the role.
An error in the standard format is returned for all other responses.
POST /command/roles/add-permissions
Add permissions to a role.
Request format
Key | Definition |
---|---|
role_id |
The ID of the role you want to add permissions to. |
permissions |
A list of permissions you want to add to the role. |
{ "role_id": <role-id>, "permissions:[{"object_type": <ot>, "action": <action>, "instance": <instance>},...]
Copied!
Response format
A 204 response with no content is returned when the permissions are successfully added to the role.
An error in the standard format is returned for all other responses.
POST /command/roles/remove-permissions
Remove permissions from a role.
Request format
Key | Definition |
---|---|
role_id |
The ID of the role you want to remove permissions from. |
permissions |
A list of permissions you want to remove from the role. |
{ "role_id": <role-id>, "permissions:[{"object_type": <ot>, "action": <action>, "instance": <instance>},...]
Copied!
Response format
A 204 response with no content is returned when the permissions are successfully removed from the role.
An error in the standard format is returned for all other responses.