Skip to main content

REST APIs for 23.5

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

[api_version]orgs/{org_id}/permissions

Get an individual permission (schema change)

GET

[api_version]{org_id}/permissions/{permission_id}

Grant a permission (schema change)

POST

[api_version]orgs/{org_id}/permissions

Update a permission (schema change)

PUT

[api_version]orgs/{org_id}/permissions/{permission_id}

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"}}]
Parameters for Roles
Unscoped Roles

API Role Name

UI Role Name

Granted Access

owner

Global Organization Owner

Perform all actions: Add, edit, or delete any resource, security settings, or user accounts.

admin

Global Administrator

Perform all actions except cannot change security settings and cannot perform user management tasks.

read_only

Global read-only

View any resource or security settings. Cannot perform any operations.

global_object_provisioner

Global Policy Object Provisioner

Provision rules containing IP lists, services, and 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

ruleset_manager

Full Ruleset Manager

Add, edit, and delete all rulesets within a specified scope.

Add, edit, and delete rules when the provider matches a specified scope.

The rule consumer can match any scope.

limited_ruleset_manager

Limited Ruleset Manager

Add, edit, and delete all rulesets within a specified scope.

Add, edit, and delete rules when the provider and consumer match the specified scope. Ruleset managers with limited privileges cannot manage rules that use IP lists, user groups, label groups, iptables rules as consumers, or rules that allow internet connectivity.

ruleset_provisioner

Ruleset Provisioner

Provision rulesets within a specified scope.

Cannot provision virtual servers, virtual services, SecureConnect gateways, security settings, IP lists, services, or label groups.

Ruleset Manager and Ruleset Provisioner

Suppose you are granting 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.

There is a default read-only user permission that is organization-wide and inherited by all users in the organization. This global permission allows users with no permissions explicitly granted to them to access the PCE.

Note

For 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
Parameters for RBAC Permissions

Parameter

Description

Type

Required

org_id

Organization

Integer

Yes

auth_security_principal

The authorization security principal associated with the permission. It is not needed to get an individual permission or to delete a permission.

The HREF of the authorization security principal

(auth_security_principal) associated with the user or group being granted a permission.

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

role

The RBAC role 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 [org_href]. For example:

[org_href]/roles/[role_name]

For example, to grant a user permission with the Global Object Provisioner role, with a PCE organization HREF of /org/6, the role HREF would be: /orgs/6/roles/global_object_provisioner

(For additional information about these roles and their associated capabilities, see the PCE Administration Guide.)

Unscoped roles:

  • owner

  • admin

  • read_only

  • global_object_provisioner

Scoped roles:

  • ruleset_manager

  • limited_ruleset_manager

  • ruleset_provisioner

String

Yes

scope

Scope to filter on, where the scope is in the format defined in org_scope.schema.json

String

No

permission_id

UUID of the permission

String

Yes

RBAC Properties

Parameter

Description

Type

Required

org_id

Organization

Integer

Yes

permission_id

UUID of the permission. Used to get, update, and delete an individual permission

String

Yes

auth_security_principal

The authorization security principal associated with the permission. It is not needed to get an individual permission or to delete a permission.

Reference to auth_security_principal_uri.schema.json

role

The RBAC role associated with the permissions.

Reference to common/orgs_roles.schema.json

Yes

scope

Scope to filter on, where the scope is in the format defined in org_scope.schema.json

Yes

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. If you want to get more than 500, use an Asynchronous GET Collection.

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]

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
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 can be applied that restrict the permission to operating on specified labeled resources.

URI to Create a New Permission

POST [api_version][org_href]/permissions
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.

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 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"
                      }
	},
		........
}
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.

{
  "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"}
}
Update an RBAC Permission

This method updates permission, for example, changing the permission role, authorization security principal, user, or group.

URI to Update a Permission

PUT [api_version][permissions_href]

Curl Command to Update the Role Permission

curl -i -X PUT https://pce.mycompany.com:8443/api/v2/orgs/7/permissions/xxxxxxxx-354b-45de-9bf5-d1b613ac3719 -H "Content-Type: application/json" -u $KEY:$TOKEN -d '{"scope": [{"href": "/orgs/7/labels/91", "key": "app", "value": "db"},{"href": "/orgs/7/labels/92", "key": "loc", "value": "nyc"},{"href": "/orgs/7/labels/100", "key": "env", "value": "prod"}],"role": {"href": "/orgs/7/roles/global_object_provisioner"}, "auth_security_principal":{"href":"/orgs/7/auth_security_principals/xxxxxxxx-e4bf-4ba5-bd77-ccfc3a8ad999"}}'
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
See also: