Role Based Access Control Overview
Role-based Access Control (RBAC) is an API that creates, updates, or deletes permissions for users and groups. These users and groups are managed locally by the PCE or externally by a single sign-on (SSO) identity provider (IdP).
RBAC Concepts
Become familiar with these RBAC concepts before using this API.
User
A user is a PCE account that provides login or API access to the PCE. A user can be managed locally by the PCE or externally through an IdP.
Permission
A permission represents a combination of a user's account, an RBAC role, and an optional scope. You can grant multiple permissions to a user, depending on your requirements. A permission is a three tuple consisting of a role, a scope, and an authorization security principal:
Role: User personas associated with a set of allowed operations, such as creating new labels or provisioning policy changes. Roles can be one of two general types: unscoped and scoped.
Unscoped roles (or roles with “global scopes”) do not restrict the types of resources a user can operate. This means that the role is not affected by any label scopes.
Scoped roles use one or more unique application, environment, and location labels (each with a label HREF, key, and value) to restrict user or group permissions to only those objects that share the same labels. Specifically, scoped roles allow certain users to create and provision rules and rulesets.
Scope: A set of three labels (one of each type for Application, Environment, and Location) that restricts operations to those workloads sharing the same labels as the scope label set.
GET, POST, and PUT permissions methods for the Ruleset Manager (limited or full) or Ruleset Provisioner roles have a required scope parameter. When granting permissions, choose a scope restricting which resources these users can use in a ruleset or which resources they can provision.
A scope contains zero or more applications, environment, and location labels. Each label in the scope is identified by its HREF. A scope can also contain zero or more label groups.
If the scope is an empty array (
[]), it includes all applications, environments, and locations.If one of the label types is not specified, all instances of that type are permitted. For example, all applications are within the scope if application labels are omitted but environment and location labels are present.
Authorization Security Principal: The binding that connects a user account with its permissions (a role, and depending on the role, scopes).
Note
If you are using an external identity provider to manage user access to the PCE, make sure that your identity provider is configured and those external users have been added to the PCE before you use this API to assign user permissions.
Grant Permissions Workflow
Granting user permissions with the REST API follows this workflow:
Create a local user (optional)
This step creates a new local PCE user with no permissions and sends an e-mail invitation to the user's e-mail address. (If you use an external identity provider to manage user access to the PCE, skip this step.)
Create an authorization security principal.
An authorization security principal is binding between a user or group, an RBAC role, and optional scopes.
Grant permissions by assigning a role and scope to the authorization security principal
Once a user account has been associated with an authorization security principal, you can assign an RBAC role to the account and add custom scopes if the user role requires them.
List User Roles and Role Names
The APIs GET roles and GET role_name have been promoted from Internal to Public Experimental.
They allow users to list roles and role names.
Functionality | HTTP | URI |
|---|---|---|
Get the roles in the organization. |
|
|
Get information for this role name. |
|
|