Permissions endpoints
Sections
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
curl GET 'https://$(puppet config print server):4433/rbac-api/v1/types' \
-H "X-Authentication: 0RrYy80wuJZLNDcOwxnl19DJAe7LAkpPZtCbx8Jh3NxQ"
Copied!
Response format
[{ "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
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.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
[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
node_groups
object type and
the view
action:GET /permitted/node_groups/view
Copied!
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
["00000000-0000-4000-8000-000000000000"]
Copied!
If the user does not have permissions for any instance, an empty array is returned.
Error responses
- The
object-type
does not map to a knownobject-type
. - The
action
does not exist for the givenobject-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
node_groups
object type and
the view
action:GET /permitted/node_groups/view/fe62d770-5886-11e4-8ed6-0800200c9a66
Copied!
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
["00000000-0000-4000-8000-000000000000"]
Copied!
If the user does not have permissions for any instances, an empty array is returned.
Error responses
- The
object-type
does not map to a knownobject-type
. - The
action
does not exist for the givenobject-type
. - The
uuid
does not map to a knownuser
.