Permissions endpoints

You add permissions to roles to control what users can access and do in PE. Use the permissions endpoints to get information about objects you can create permissions for, what types of permissions you can create, and whether specific users can perform certain actions.

Tip: Before using these endpoints, you'll want to be familiar with User permissions and user roles, particularly Best practices for assigning permissions.
A permission consists of three components:
  • Type (object_type)
  • Permission (action)
  • Object (instance, not to be confused with a JSON object)
These three components are described in Structure of user permissions, as well as the crucial All object ("*").

RBAC API requests and responses use the system names (not the display names) described in Reference: User permissions and names. This reference also provides helpful information about some permissions, such as some permissions that require the All ("*") object.

Permissions endpoints keys

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

Key Definition Example
object_type A string identifying what PE object type the permission applies to, such as node groups, users, roles, and so on. "node_groups"
action A string indicating the permitted action, such as viewing, editing, or creating. "modify_children"
actions An array representing multiple actions, formatted as JSON objects. Each JSON object contains:
  • name: The action's system name.
  • display_name: The action's name as it appears in the PE console.
  • description:
  • has_instances: Boolean indicating whether you can apply instance specification to this action. If false, you must supply "*" for the instance when including the action in a permission JSON object. Refer to instance for more information.
instance A string describing the scope of the permission.

To apply the permission to all instances of the specified object_type, use "*" to indicate all instances.

To limit the permission to specific instances of the specified object_type, supply the appropriate UUID, such as a specific node group ID or user ID.

For any object_type that doesn't allow instance specification, you must supply "*".
  • To permit all instances (or if the object_type doesn't support instance specification): "*"
  • To define a specific instance, supply a UUID as a string, such as: "cec7e830-555b-11e4-916c-0800200c9a66"
display_name A string containing the object_type name as it appears in the PE console. "Node Groups"
description A string describing an object_type. "Groups that nodes can be assigned to."
token In the POST /permitted endpoint, this is a string representing the UUID of a user or user group. "cec7e830-555b-11e4-916c-0800200c9a66"
Tip: You'll use object_type, action, and instance to build permissions. Use the GET /types endpoint to get values you can use for these keys when writing permissions. For object_type and action, you must use system names, not display names.

GET /types

Lists each object_type that you can regulate with RBAC permissions, the available actions for each type, and whether each action allows instance specification. 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/types" -H "X-Authentication:$(puppet-access show)"

Response format

The response is 200 OK and an array of object_type objects and actions for each type. For example:
[{ "object_type": "node_groups",
   "display_name": "Node Groups",
   "description": "Groups that nodes can be assigned to."
   "actions": [{ "name": "view",
                 "display_name": "View",
                 "description": "View the node groups",
                 "has_instances": true
                },{
                 "name":"modify",
                 "display_name": "Configure",
                 "description": "Modify description, variables and classes",
                 "has_instances": true
                }, ...]
 },...]

For information about response keys and instance specification, refer to Permissions endpoints keys.

Error responses

Returns a 401 Unauthorized response if authentication is invalid.

Returns a 403 Forbidden response if the requesting user lacks permission to view types.

For other errors, refer to RBAC service errors.

POST /permitted

Query whether a user or user group can perform specified actions. Use this to check if a user or group already has a certain permission. 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 specifying a user or user group and one or more specific permissions. You must use these keys:
  • token: The UUID of a user or user group.
  • permissions: An array of JSON objects representing permissions. Each permissions object includes the object_type, action, and instance keys. For more information about these keys and how to populate them, refer to Permissions endpoints keys.
    Tip: For any object_type that doesn't support instance specification, you must supply "instance": "*".
For example, the following body queries a user or group with the UUID 456. It checks if this user or group can edit rules for a specific node group, and if the user or group can disable all ("*") user accounts. The response returns an array of Boolean values representing each JSON object in the permissions array. A true response indicates that the user or group can perform the specified action, whereas false indicates the user or group can't perform that action.
{"token": "456",
 "permissions": [{"object_type": "node_groups",
                  "action": "edit_rules",
                  "instance": "<NODE_GROUP_UUID"},
                 {"object_type": "users",
                  "action": "disable",
                  "instance": "*"}]
}
Here is an example of a complete curl request to the permitted endpoint:
curl -X POST "https://$(puppet config print server):4433/rbac-api/v1/permitted" \
-H "X-Authentication: 0RrYy80wuJZLNDcOwxnl19DJAe7LAkpPZtCbx8Jh3NxQ"  \
-H "Content-type:   application/json" \
-d '{"token": "42bf351c-f9ec-40af-84ad-e976fec7f4bd",
     "permissions": [{"object_type": "node_groups",
                      "action": "edit_rules",
                      "instance": "4"}]}'

Response format

If the request is well-formed and valid, the endpoint returns a 200 OK response with an array of Boolean values representing each JSON object in the permissions array in the request body.

The response array has the same length as the request's permissions array. Each returned Boolean value corresponds to the submitted permission query at the same index. For example, if you query two permissions, the response array contains two values, such as:
[true, false]

A true response indicates that the user or group can perform the specified action (described at the corresponding index position in the request), whereas false indicates the user or group can't perform that action.

The response is based on a full evaluation of permissions, including inherited roles and matching general permissions to more specific queries. For example, a query for users:edit:1 returns true if the token subject has either permission to edit that specific user (users:edit:1) or permission to edit all users (users:edit:*).

For error responses, refer to RBAC service errors.

GET /permitted/<object-type>/<action>

For a specific object_type and action, get a list of instance IDs that the current authenticated user is permitted to take the specified action on. Authentication is required.

Request format

When Forming RBAC API requests to this endpoint, the URI path must include the name of an object_type and applicable action for that object type. For example, this request refers to the node_groups type and the view action:
curl "https://$(puppet config print server):4433/rbac-api/v1/permitted/node_groups/view" \
-H "X-Authentication:$(puppet-access show)"
Tip: This endpoint checks permissions for the current authenticated user. If you want to check permissions for another user, use the GET /permitted/<object-type>/<action>/<uuid> endpoint.

Response format

A valid request returns 200 OK and an array of instance IDs that the authenticated user is permitted to perform the supplied action on. For example, this response has one instance:
["00000000-0000-4000-8000-000000000000"]

If the user does not have permission to act on any instance, an empty array is returned.

Error responses

Returns 404 Not Found if:
  • The supplied object_type does not map to a known object_type. Make sure your request used the type's system name, not the display name. System names are listed in Reference: User permissions and names.
  • The supplied action does not exist for the given object_type. You can use the GET /types endpoint to get a list of actions for each object_type.

For other errors, refer to RBAC service errors.

GET /permitted/<object-type>/<action>/<uuid>

For a specific object_type and action, get a list of instance IDs that the specific user (identified by UUID) is permitted to take the specified action on. Authentication is required.

Request format

When Forming RBAC API requests to this endpoint, the URI path must include the name of an object_type, an applicable action for that object type, and a user's UUID. For example, this request checks if a specific user can take the view action on node groups:
curl "https://$(puppet config print server):4433/rbac-api/v1/permitted/node_groups/view/42bf351c-e976fec7f4bd" \
-H "X-Authentication:$(puppet-access show)"

Response format

A valid request returns 200 OK and an array of instance IDs that the specified user is permitted to perform the supplied action on. For example, this response has one instance:
["00000000-0000-4000-8000-000000000000"]

If the user does not have permission to act on any instance, an empty array is returned.

Error responses

Returns 404 Not Found if:
  • The supplied object_type does not map to a known object_type. Make sure your request used the type's system name, not the display name. System names are listed in Reference: User permissions and names.
  • The supplied action does not exist for the given object_type. You can use the GET /types endpoint to get a list of actions for each object_type.
  • The uuid does not map to a known user.

For other errors, refer to RBAC service errors.