RBAC Overview
The Role-based Access Control (RBAC) is an API that gets, 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).
Before you begin using the RBAC feature with the REST API, learn about the Illumio Core permissions model and its terms and concepts.
RBAC Terms and Concepts
You should be familiar with the following RBAC terms 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 that are 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 have restrictions on the types of resources on which 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 rules and rulesets and provision them.
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 that restricts 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, if application labels are omitted but environment and location labels are present, all applications are within the scope.
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 general 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 serves as the binding between a user or a group and an RBAC role and optional scopes.
Grant permissions by assigning a role and scopes 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 the users to list user roles and role names.
Functionality | HTTP | URI |
|---|---|---|
Get the roles in the organization |
|
|
Get information for this role name |
|
|