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
Label groups have been added to the response and parameters in addition to labels 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 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.
Managing 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
Label groups have been added to the response and parameters in addition to labels because they are now supported in user scopes.
Get RBAC Permissions
These methods get an individual user permission or a collection of permissions in the organization. By default, the maximum number of permissions returned on a GET collection is 500.
URI to get all permissions in your organization:
GET [api_version][org_href]/permissions
URI to get an individual permission:
GET [api_version][permissions_href]
Grant RBAC Permissions
When RBAC permission is granted to a user in the PCE, the user account (identified by its authorization security principal) is associated with a role. Depending on the role, scopes that restrict the permission to operate on specified labeled resources can be applied.
URI to Create a New Permission:
POST [api_version][org_href]/permissions
Update an RBAC Permission
This method updates permissions, such as changing the permission role, authorization security principal, user, or group.
URI to update permission:
PUT [api_version][permissions_href]
Delete an RBAC Permission
Curl Command to Delete a Permission:
curl -i -X DELETE https://pce.mycompany.com:8443/api/v2/orgs/7/.permissions/xxxxxxxx-354b-45de-9bf5-d1b613ac3719 -H "Accept: application/json-u $KEY:$TOKEN
User Permissions
Organization-wide Default User Permissions
This Public Experimental API supplies an organization-wide default user permission and allows users to log into the PCE and view resources. These resources must not be explicitly assigned to any RBAC roles or scopes.
About Default User Permissions
If you use an external identity source for user management, you might want to block some of those users from the PCE without removing them from your identity source. Deleting the organization-wide read-only permission allows you to achieve this.
When the read-only user permission is disabled for your organization, users not explicitly assigned this permission cannot log into the PCE and access Illumio resources. If users, without permission, attempt to log into the PCE, their external identity source authenticates them, but the PCE immediately logs them out.
To disable organization-wide read-only permissions:
Get a collection of all authorization security principals in your organization, and search the response for the one named
null. Once you find this authorization security principal, note its full HREF.Get the HREF of the permissions object associated with the
nullauthorization security principal. Keep a record of the JSON object for this permission if you want to re-enable it later.Delete the permission associated with the
nullauthorization security principal.
Get a Collection of Authorization Security Principals
The first step in disabling organization-wide read-only permission is to collect all authorization security principals in your organization.
Get Permission for Null Auth Security Principal
To get the permission object associated with the null authorization security principal, call the GET Permissions API with the query parameter value set to the HREF for the null authorization security principal, similar to the curl command:
curl -i -X GET -H "Accept: application/json" -u $KEY:$TOKEN https://pce.mycompany.com:8443/api/v2/orgs/7/permissions?auth_security_principal=/orgs/7/auth_security_principals/a23ea011-4191-49e6-a22a-d3dba4fb8058
Response
The response returns the HREF of the permission associated with the organization-wide read-only permission.
{
"href": "/orgs/7/permissions/14c92849-e88e-4930-8804-3245565619e5",
"role": {
"href": "/orgs/7/roles/read_only"
},
"scope": [],
"auth_security_principal": {
"href": "/orgs/7/auth_security_principals/a23ea011-4191-49e6-a22a-d3dba4fb8058"
}Delete Null Authorization Security Principal Permission
Keep a record of the permission object returned in case you want to re-enable the permission in the future.
Delete the read-only permission HREF to disable it.
Curl Command to Delete Null Authorization Security Principal Permission
curl -i -X DELETE -H "Accept: application/json" -u $KEY:$TOKEN https://pce.mycompany.com:8443/api/v2/orgs/7/permissions?auth_security_principal=/orgs/7/auth_security_principals//orgs/7/permissions/14c92849-e88e-4930-8804-3245565619e5
Response
An HTTP 200 response is returned on successfully deleting the organization-wide read-only permission.
Re-Enable Organization Read-Only Permission
If the organization-wide read-only permission was disabled, you can re-enable it by recreating the permission object. This object must be constructed exactly as the object returned to you when you got the permission. The request body below illustrates the JSON structure of this permission object.
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. Individual permissions do not need to be obtained or deleted. 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"}
}