Send Docs Feedback

Role-based access control

Overview

Role-based access control (RBAC) governs the actions that Edge users can perform upon entities in an Apigee Edge organization. Entities include APIs, API products, apps, developers, environments, and reports. 

This topic is mainly concerned with custom roles that an organization adminstrator creates. If you're interested in learning about the predefined roles Apigee Edge provides out-of-the-box, see Manage users and roles.

Before you begin

Before working with roles, be sure to note the following:

  • The role-based access control covered here protects artifacts that are used by Apigee Edge API Services, like API proxies, developers, apps, products, and custom reports. They do not provide runtime role-based access to the APIs that you expose via API proxies. To configure security for your APIs, please refer to the collection of Security topics, like Secure APIs with API keys.
  • Resources protected by RBAC in Apigee Edge are distinct from 'API resources'. Therefore, we refer to these protected resources as RBAC Resources.

What are the predefined user roles?

A person with an account in an Apigee Edge organization can be assigned one of the following predefined roles:

  • Organization Administrator
  • Operations Administrator
  • Business User
  • User

Organization administrators assign roles to individual users. Each role has a set of clearly defined permissions. For example, the user role can create, update, and delete API proxies, but an operations administrator cannot. On the other hand, an operations admin can deploy a project to the production environment, while the user role does not convey that permission. 

For a complete listing the permissions granted to each user role, see Manage users and roles.

Understanding role permissions

A role permission states what actions a role permits. They are basic CRUD operations: 

  • GET: Enables a user to view a list of RBAC resources or to view a singleton RBAC resource
  • POST: Enables a user to create or update an RBAC resource (encompassing both PUT and POST HTTP methods)
  • DELETE: Only supported on singletons, enables a user to delete an RBAC resource. Users cannot delete collections of RBAC resources

Note that in the UI, the permissions are called "operations": View, Edit, Delete. They correspond GET, POST/PUT, and DELETE

What are custom roles?

You can create custom roles for applying access control to these Apigee Edge entities:

  • APIs
  • API Products
  • Apps
  • Developers
  • Reports

You can achieve even more granularity by applying role based access to specific instances of an entity. For example, you can apply role-based access to all API products or to specific ones. 

Precedence: More granular permissions take precedence over less granular ones. For example, permissions applied to a specific developer app take precedence over a less-granular permission applied to all developer apps.

Creating users

An org admin creates users in an organization through the Edge management UI. When logged in as an organization administrator, go to Admin > Organization Users. During the creation process, the admin can assign pre-defined or custom roles (if they exist) to the new user. 

Note: If the org admin decides to remove a user from the organization, that user's account is not deleted from the Apigee Edge system. To delete a user from the system, contact Apigee Customer Support. 

For more details, see Manage users and roles.

Using the management UI to create custom roles

An org administrator can create custom roles through the management UI.

  1. Go to Admin > Organization Roles
  2. Click + Custom Role
  3. Use the New Custom Role dialog to create the custom role. 

The dialog lets you apply fine-grained, custom permissions to:

  • API Proxies
  • Environments
  • Products
  • Developers and Apps
  • Reports

You can apply CRUD permissions either to all instances of an entity (all API Proxies) or to specific instances, for example, only to the /weatherapi proxy. You can also apply "environment operations" to some resources. These operations include specifying whether the role permits viewing trace results and/or permission to deploy to a specific environment (e.g., test and/or prod). 

The following screen shot shows part of the New Custom Role dialog. For example, this role is called WeatherApiRole, and it allows a user to view, edit, and delete an API proxy with the path /weatherapi. In addition, this user can view trace sessions in both prod and test environements, but can only deploy to the test environment. 

Using the API to create custom roles

This section discusses how to create and edit custom roles through the management API.

Create a role: development

Create a 'development' role to enable developers to view, create, and update API proxies.

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/userroles -H "Content-type:application/json" -X POST -d'{ "role" : [ { "name" : "development" } ] }'

Add permissions to development role

The permissions that can be set on collections are GET and PUT. The permissions that can be set on individual members of a collection are GET, PUT, and DELETE. For the 'development' role, we add GET and PUT permissions on APIs. GET enables users to view any APIs, including API proxy configuration files, associated policies, Javascript, XSLT files, and so on. The PUT permission on APIs enables developers to create, modify, import, export, deploy and undeploy API proxies.

The path attribute specifies the resource on which you set the permissions. For example,  /applications, /apps, /apiproducts, /developers, or /reports.

curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/userroles/development/permissions -H "Content-type:application/json" -X POST -d'{"path" : "/applications","permissions" : [ "post", "get" ]}'

Create a role: testing

Create a 'testing' role to enable quality engineers to view API proxies and their contents (including, for example, policies).

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/userroles -H "Content-type:application/json" -X POST -d'{ "role" : [ { "name" : "testing" } ] }'

Add permissions to testing role

GET enables users to view any APIs, including their configuration files, as well as any associated policies, JavaScript, XSLT files, and so on. By adding this permission to the 'testing' role, we enable quality engineers to view the contents of the APIs that they are testing. Users in this role will not, however, be able to create, modify, import, export, deploy and undeploy API proxies.

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/userroles/testing/permissions -H "Content-type:application/json" -X POST -d'{"path" : "/applications","permissions" : [ "get" ]}'

Add user to testing role

To provision a user with a user role:

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/users/justauser@apigee.com/userroles -H "Content-type:application/json" -X POST -d'{"role" : [ {"name" : "testing"} ] }'

View APIs as user

Impersonate the user and make a request to API Services to view API proxies. The user should be able to view APIs, along with their contents.
$ curl -u justauser@apigee.com:secret https://api.enterprise.apigee.com/v1/o/{org_name}/apis
$ curl -u justauser@apigee.com:secret https://api.enterprise.apigee.com/v1/o/{org_name}/apis/{api_name}/policies

Create API as user in testing role

Impersonate the user and make a request to API Services to create an API proxy. The request will be rejected by API Services, as the role 'testing' does not permit the user to create APIs.

$ curl -u justauser@apigee.com:secret -H "Content-Type: application/json" https://api.enterprise.apigee.com/v1/o/{org_name}/apis -X POST -d'{"name" : "rbacTestApi"}'

Add user to development role

Now provision the user with the 'development' role.

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/users/justauser@apigee.com/userroles -H "Content-type:application/json" -X POST -d'{"role" : [ {"name" : "development"} ] }'

Create API as user in development role

Impersonate the user and repeat the request to the API Platform to create an API proxy. The request will be successful, as the role 'development' does permit the user to create APIs.

$ curl -u justauser@apigee.com:secret -H "Content-Type: application/json" https://api.enterprise.apigee.com/v1/o/{org_name}/apis -X POST -d'{"name" : "rbacTestApi"}'

Get user roles for a user

As an organization administrator, you can check the list of user roles for a user at any time:

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/users/justauser@apigee.com/userroles

 

Help or comments?

  • If something's not working: Ask the Apigee Community or see Apigee Support.
  • If something's wrong with the docs: Click Send Docs Feedback on this page.
    (Incorrect? Unclear? Broken link? Typo?)