Docs Grey arrow pointing right Puppet Enterprise Grey arrow pointing right Managing access Grey arrow pointing right RBAC API Grey arrow pointing right RBAC API v1 Grey arrow pointing right Permissions endpoints Grey arrow pointing right

Permissions endpoints

Sections

ExpandCollapse

You assign permissions to user roles to manage user access to objects. The permissions endpoints enable you to get information about available objects and the permissions that can be constructed for those objects.

Permissions keys

These keys are used with the RBAC v1 API’s permissions endpoints. The available values for these keys are available from the types endpoint.

Key Explanation Example
object_type A string identifying the type of object this permission applies to. "node_groups"
action A string indicating the type of action this permission permits. "modify_children"
instance A string containing the primary ID of the object instance this permission applies to, or "*" indicating that it applies to all instances. If the given action does not allow instance specification, use "*". "cec7e830-555b-11e4-916c-0800200c9a66" or "*"

GET /types

Lists the objects that integrate with RBAC and demonstrates the permissions that can be constructed by picking the appropriate object_type, action, and instance triplet. Authentication is required.

Request format

Example curl request:
curl GET 'https://$(puppet config print server):4433/rbac-api/v1/types' \
-H "X-Authentication: 0RrYy80wuJZLNDcOwxnl19DJAe7LAkpPZtCbx8Jh3NxQ"Copied!

Response format

Returns 200 OK with a listing of types 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
                }, ...]
 },...]Copied!

If has_instances is true, the action permission is instance-specific. If false, the action permission does not require instance specification.

Error responses

Returns 401 Unauthorized if no user is logged in.

Returns 403 Forbidden if the current user lacks permissions to view the types.

POST /permitted

This endpoint takes a token, in the form of a user or a user group's UUID, and a list of permissions. The endpoint returns true or false for each permission queried, representing whether the indicated user or user group is permitted to take the specified action. Authentication is required.

Request format

In the following example, the first permission queries whether the subject specified by the token is permitted to perform the edit_rules action on the instance of node_groups identified by the given UUID.
{"token": "<subject uuid>",
 "permissions": [{"object_type": "node_groups",
                  "action": "edit_rules",
                  "instance": "<node group UUID"},
                 {"object_type": "users",
                  "action": "disable",
                  "instance": "<UUID or *>"}]
}Copied!
Not all permissions require instance specification. Use * to indicate all instances or provide a UUID to identify a specific instance.
Example curl request:
curl 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"}]}'Copied!

Response format

Returns 200 OK with an array of Boolean values representing whether each submitted action on a specific object type and instance is permitted for the subject. The array always has the same length as the submitted array, and each returned Boolean value corresponds to the submitted permission query at the same index. For example, if you query two permissions, the array contains two values:
[true, false]Copied!

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

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

Returns an array of permitted instances for the given object-type/action pair based on the current authenticated user. Authentication is required.

Request format

Example request using the node_groups object type and the view action:
GET /permitted/node_groups/viewCopied!
Example curl request using the node_groups object type and the edit_child_rules action:
curl GET 'https://$(puppet config print server):4433/rbac-api/v1/permitted/node_groups/edit_child_rules' \
-H "X-Authentication: 0RrYy80wuJZLNDcOwxnl19DJAe7LAkpPZtCbx8Jh3NxQ"Copied!

Response format

Returns 200 OK with a list of instances that the current user is permitted to use with the specified action. For example, this response has one instance:
["00000000-0000-4000-8000-000000000000"]Copied!

If the user does not have permissions for any instance, an empty array is returned.

Error responses

Returns 404 Not Found if:
  • The object-type does not map to a known object-type.
  • The action does not exist for the given object-type.

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

Return an array of permitted instances for the given object-type/action pair based on the user matching the supplied uuid. Authentication is required.

Request format

Example request using the node_groups object type and the view action:
GET /permitted/node_groups/view/fe62d770-5886-11e4-8ed6-0800200c9a66Copied!
Example curl request using the node_groups object type and the edit_child_rules action:
curl GET 'https://$(puppet config print server):4433/rbac-api/v1/permitted/node_groups/edit_child_rules/42bf351c-f9ec-40af-84ad-e976fec7f4bd' \
-H "X-Authentication: 0RrYy80wuJZLNDcOwxnl19DJAe7LAkpPZtCbx8Jh3NxQ"Copied!

Response format

Returns 200 OK with a list of instances that the specified user is permitted to use with the specified action. For example, this response has one instance:
["00000000-0000-4000-8000-000000000000"]Copied!

If the user does not have permissions for any instances, an empty array is returned.

Error responses

The endpoint returns 404 Not Found if:
  • The object-type does not map to a known object-type.
  • The action does not exist for the given object-type.
  • The uuid does not map to a known user.