About RBAC Permissions
This Public Experimental API grants permissions to PCE users and groups. It also returns a collection of permissions in the organization, gets individual user permissions, and updates and deletes permissions.
Note
In addition to labels, label groups have been added as part of the response and parameters because they are now supported in user scopes.
API Methods
Functionality | HTTP | URI |
|---|---|---|
Get a list of all RBAC permissions for the organization (schema and query parameter format change) |
|
|
Get an individual permission (schema change) |
|
|
Grant permission (schema change) |
|
|
Update a permission (schema change) |
|
|
New Schema and Query Parameter
For the above endpoints, the org_scope.schema.json is now used instead of labels_summary.schema.json and labels.schema.json.
For the endpoint GET /api/v2/orgs/1/permissions, the query parameter is changed from
scope: ["/orgs/1/labels/5", "/orgs/1/labels/3"]
to
scope: [{"label":{"href":"/orgs/1/labels/5"}},{"label":{"href":"/orgs/1/labels/3"}}]Ruleset Manager and Ruleset Provisioner
Suppose you grant a user or group the Ruleset Manager or the Ruleset Provisioner role. In that case, you can also associate a scope to the role so you can control which rulesets they can add and provision.
A default read-only user permission is organization-wide and inherited by all users. This global permission allows users with no permissions explicitly granted to access the PCE.
Note
For more information, see Organization-Wide Default User Permission.
Role HREF Syntax
An RBAC role is identified in the REST API by its HREF, the exact syntax of which is based on the PCE organization HREF [org_href].
[org_href]/roles/[role_name]
For example, if you wanted to grant a user permission with the Global Object Provisioner role, and your PCE organization HREF is /org/6, the role HREF would look like:
/orgs/6/roles/global_object_provisioner
Scoped Permissions
The permission for this scoped role consists of the following elements:
A scope for the role (application, environment, and location labels)
The role
An authorization security principal associated with a user account
Note
See the scope parameter change explained in Use the New Schema and Query Parameter.
Unscoped Permissions
Request - Unscoped Permission
In this request for unscoped permission, the required scope property is defined as an empty JSON array ( [ ]).
Note
When the scope parameter is empty, the change explained in Use the New Schema and Query Parameter does not apply.
RBAC Permissions Reference
This topic covers parameters, properties, and examples for RBAC permissions.
Parameters
Unscoped Roles
API Role Name | UI Role Name | Granted Access |
|---|---|---|
| Global Organization Owner | Perform all actions: Add, edit, or delete any resource, security settings, or user accounts. |
| Global Administrator | Perform all actions except cannot change security settings and cannot perform user management tasks. |
| Global read-only | View any resource or security settings. Cannot perform any operations. |
| Global Policy Object Provisioner | Provision rules containing IP lists, services, label groups, and manage security settings. Cannot provision rulesets, virtual services, or virtual servers or add, modify, or delete policy items. |
Scoped Roles
API Role Name | UI Role Name | Granted Access |
|---|---|---|
| Full Ruleset Manager | Add, edit, and delete all rulesets within a specified scope. Add, edit, and delete rules when the Source matches a specified scope. The rule Destination can match any scope. |
| Limited Ruleset Manager | Add, edit, and delete all rulesets within a specified scope. Add, edit, and delete rules when the Source and Destination match the specified scope. Ruleset managers with limited privileges cannot manage rules that use IP lists, user groups, label groups, iptables rules as destinations, or rules that allow internet connectivity. |
| Ruleset Provisioner | Provision rulesets within a specified scope. Cannot provision virtual servers, virtual services, SecureConnect gateways, security settings, IP lists, services, or label groups. |
| The |
Parameters for RBAC Permissions
Parameter | Description | Type | Required |
|---|---|---|---|
| Organization | Integer | Yes |
| The authorization security principal is associated with the permission. It is not needed to get individual permission or to delete a permission. The HREF of the authorization security principal ( The HREF of an authorization security principal is returned when you create a new one, or you can GET a collection of authorization security principals in your PCE. | String | POST:Yes PUT:No |
| The RBAC role is associated with the permissions. An RBAC role is identified in the REST API by its HREF, the exact syntax of which is different for every user and is based on the PCE organization. HREF
For example, to grant a user permission with the Global ObjectProvisioner role with a PCE organization HREF of
(For additional information about these roles and their associated capabilities, see PCE Administration Guide, Role-Based Access for Application Owners. Unscoped roles:
Scoped roles:
| String | Yes |
| Scope to filter on, where the scope is in the format defined in | String | No |
| UUID of the permission | String | Yes |
Properties
Parameter | Description | Type | Required |
|---|---|---|---|
| Organization | Integer | Yes |
| UUID of the permission. Used to get, update, and delete an individual permission | String | Yes |
| The authorization security principal is associated with the permission. It is not needed to get individual permission or to delete a permission. Reference to | ||
| The RBAC role is associated with the permissions. Reference to | Yes | |
| Scope to filter on, where the scope is in the format defined in | Yes |
Examples
Curl Command Get Permissions with a Specific Role
curl -i -X GET https://pce.my-company.com:8443/api/v2/orgs/7/permissions?role=ruleset_provisioner -H "Accept: application/json" -u $KEY:$TOKEN
Example Request Body with orgs_permission.schema.json
{
"scope": [
{
"label_group": {
"href": "/orgs/1/sec_policy/active/label_groups/7d480df0-f5e1-4d1e-b088-d8105150a883"
}
},
{
"label": {
"href": "/orgs/1/labels/12"
}
}
],
"role": {
"href": "/orgs/1/roles/limited_ruleset_manager"
},
"auth_security_principal": {
"href": "/orgs/1/auth_security_principals/177027ca-c3fe-4610-ac14-fe5cba173af5"
}
}Example Response for a Scoped Permission
The response shows the new permission (at the top) that has been created and identified by its HREF:
{
"href": "/orgs/2",
"display_name": "Luke",
"permissions": [
{
"href": "/orgs/2/permissions/23dde367-41ea-4752-bfe5-16c173aad1a5",
"role": {
"href": "/orgs/2/roles/limited_ruleset_manager"
},
"scope": [
{
"label": {
"href": "/orgs/2/labels/452",
"key": "app",
"value": "App1"
}
}
{
label: {
"href": "/orgs/2/labels/454",
"key": "loc",
"value": "Loc1"
}
}
],
"auth_security_principal": {
"href": "/orgs/2/auth_security_principals/04b63b79-9883-4e84-acc5-f727f1c67fa1"
}
},
........
}{
"scope": [],
"role": { "href": "/orgs/7/roles/owner" },
"auth_security_principal":{"href":"/orgs/7/auth_security_principals/xxxxxxxx-e4bf-4ba5-bd77-ccfc3a8ad999"}
}Response - Unscoped Permission
{
"href": "/orgs/7/permissions/51d9207c-354b-45de-9bf5-d1b613ac3719",
"role": { "href": "/orgs/7/roles/owner" },
"scope": [],
"auth_security_principal":{"href":"/orgs/7/auth_security_principals/xxxxxxxx-e4bf-4ba5-bd77-ccfc3a8ad999"}
}