—Rate this article—
 

Role-based access control

Overview

Role-based access control governs the actions that may be taken by Apigee Edge users upon entities (APIs, API products, apps, developers, and reports) in an Apigee Edge organization.

Two important clarifications before you begin:

  • The role-based access control covered here protects artifacts that are created by API Services. They do not provide runtime role-based access to the APIs that you expose via API proxies. To configure authorization for your APIs, please refer to 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

Users and User Roles

A person with an account in an Apigee Edge organization may be of one of the following predefined roles: 'Organization Administrator',  'Operations Administrator', 'Business User', or 'User'. Organization Administrators create and manage user roles, which define permissions on entities within an Apigee Edge organization.

For a full view of the access rights for each predefined role, see Manage users and roles.

Users

Users are provisioned with user roles by organization administrators.

User roles, in turn, provide users with permissions (GET, POST, DELETE) on RBAC resources. Note that POST covers both PUT and POST verbs.

RBAC Resources

RBAC resources are of two types: collections and members of a collection.

Collections: A set of RBAC resources:

  • APIs
  • API Products
  • Apps
  • Developers
  • Reports

Members of a collection: A named instance within a collection, for example, an API called 'weatherapi', an API product called 'premium_product', or an app called 'weatherapp'.

User Roles

A user role is defined by a set of permissions on an RBAC resource. Organization administrators are free to name user roles. For example, an organization administrator can create user roles called 'development', 'testing, 'release', 'operations', and so on. 

Permissions

A permission is a capability on an RBAC resource. The functional distinction among user roles depends upon which group is permitted to create, read, or update an RBAC resource collection, or to create, read, update and delete an RBAC resource singleton. (RBAC collections cannot be deleted en masse, regardless of user role.)

API Services defines three permissions:

  • 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 modify 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

RBAC permissions can be scoped to RBAC resource collections or individual members of a resource collection. For example, permissions for a role can set on all API products, or they can be set on an individual API product. Any permission for a role is inherited by all members of that collection, unless that permission has been explicitly overridden for any member of the resource collection.

For example, if the organization administrator configures the GET permission for the 'testing' role on an individual API product, then the new permission overrides any inherited GET/POST permission for the 'testing' role that may exist for the API product resource collection.

Provision Users and Roles

Create a user in your Apigee Edge organization

Create users in your organization in the Edge management UI. When logged in as an organization administrator, go to Admin > Organization Users.

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?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)