Skip to main content

REST APIs for 24.2.20 and 24.2.10

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

[api_version]orgs/{org_id}/permissions

Get an individual permission (schema change)

GET

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

Grant 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"}}]
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 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.

Manage 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.

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
RBAC Permissions Reference

This topic covers parameters, properties, and examples for RBAC permissions.

Parameters
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, 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 Source matches a specified scope.

The rule Destination 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 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 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.

scope

The org_scope.schema.json is now used instead of labels_summary.schema.json and labels.schema.json.

Parameters for RBAC Permissions

Parameter

Description

Type

Required

org_id

Organization

Integer

Yes

auth_security_ principal

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

(auth_security_principal) associated with the user or group being granted the 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 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 [org_href]. For example:

[org_href]/roles/[role_name]

For example, to grant a user permission with the Global ObjectProvisioner 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 PCE Administration Guide, Role-Based Access for Application Owners.

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

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 is associated with the permission. It is not needed to get individual permission or to delete a permission.

Reference to auth_security_principal_uri. schema.json

role

The RBAC role is 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

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"}
}
See also: