Setting up role-based access control in an organization

Overview

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

Two important clarifications before you begin:

• The role-based access control covered here protects artifacts that are created by the Apigee API Platform. They do not provide runtime role-based access to the APIs that you expose via API facades. To configure authorization for your APIs, please refer to Secure APIs with API keys
• Resources protected by RBAC in Apigee 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 organization may be of one of two types: 'organization administrator' or 'user'. Organization administrators create and manage user roles, which define permissions on entities within an Apigee organization.

Organization Administrators

Administrators have capabilities that cover users, user roles, and RBAC-protected resources.

Organization administrators can:

• Create, edit, and delete users
• Create, edit, and delete user roles
• Create, edit, and delete RBAC resources
• Define permissions (GET, PUT, DELETE) on RBAC resources
• Provision users with user roles
• Revoke user roles

Users

Users are provisioned with user roles by organization administrators.

User roles in turn provide users with permissions (GET, PUT/POST, DELETE) on RBAC resources.

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

Apigee defines three permissions:

• GET: Enables a user to view a list of RBAC resources or to view a singleton RBAC resource
• PUT: 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/PUT permission for the 'testing' role that may exist for the API product resource collection.

Define RBAC Resources

Each collection must be registered as a 'resource' under the URI /resources.

To view collections protected by RBAC:

List RBAC Resources

curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/resources

Define API proxy RBAC resource

curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/resources -H "Content-type:application/json" -X POST -d'{"displayName" : "API", "path" : "/applications"}'

Define API product RBAC resource

curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/resources -H "Content-type:application/json" -X POST -d'{"displayName" : "API Products","path" : "/apiproducts"}' 

Define app RBAC resource

curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/resources -H "Content-type:application/json" -X POST -d'{"displayName" : "Apps","path" : "/apps"}'

Define developer RBAC resource

curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/resources -H "Content-type:application/json" -X POST -d'{"displayName" : "Developers","path" : "/developers"}'

Define reports RBAC resource

curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/resources -H "Content-type:application/json" -X POST -d'{"displayName" : "Reports","path" : "/reports"}'

Provision Users and Roles

Create a user in your Apigee organization

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/users -H "Content-type:application/json" -X POST -d'{"emailId" : "justauser@apigee.com","firstName" : "Justa","lastName" : "User", "password" : "secret" }'

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.

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" : [ "put", "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'{"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 thispermission 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

$ 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"} ] }'

$ 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/{someAPI}/policies

$ 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"}'

$ 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"} ] }'

$ 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"}'

$ curl -u myname:mypass https://api.enterprise.apigee.com/v1/o/{org_name}/resources -H "Content-type:application/json" -X POST -d'{"displayName" : "rbacTestApi", "path" : "/applications/rbacTestApi"}'

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

Post questions to the Apigee Developer Forum.

Back to API Platform Developer Guide.