Creating roles with the API

You're viewing Apigee Edge documentation.
Go to the Apigee X documentation. info

This topic discusses how to create custom roles and assign roles to users through the management API. We also show how to test role assignments through the API. (For an overview of custom roles, see Creating custom roles in the UI.)

About permission setting

Role permissions are set on management API URIs (not management UI URIs). For example, if you want to set PUT, GET, and/or DELETE permissions on the app developer entities in your Edge organization, you'd set permissions on the /developers resource, because the management API path for developers is https://api.enterprise.apigee.com/v1/organizations/{org_name}/developers. (You don't need to include the organization part of the path when defining permissions, because permissions are scoped to a specific organization, as the management API calls in this topic illustrate.)

You can also set permissions on specific entities. For example:

If you wanted to set permissions on a single developer, set them on /developers/steve@example.com
For a specific API product, such as free-api-product, set them on /apiproducts/free-api-product
For a key value map in a specific environment, you'd set permission on something like /environments/test/keyvaluemaps/fooMap, or /environments/test/keyvaluemaps/* for all key value maps in the test environment.

The permissions you set using the API:

Allow users in a custom role to make management API calls according to their permissions. For example, if a role allows read-only access to all API proxies, a user in that role could use the List API Proxies API but not the Create an API Proxy API.
Determine what users in a custom role can see and do in the management UI. For example, read-only access to API proxies disables access to the +API Proxy and Delete buttons on the API Proxies page.

To see the resources and paths that you can set permissions on, look through the management API reference at the different resource URLs.

See the User roles API for complete reference information on role management.

Syntax and precedence

You can use the asterisk wild card (*) to indicate "everything after" in a permission setting. However, if you set permissions only on a parent resource (such as on /developers) without setting any more specific permissions (such as /developers/*), the permission applies to everything from /developers and after.

PUT also serves as POST in permissions.

You can mix general with more granular permissions on resources. The more granular settings take precedence where there is a permissions overlap. For example, assume the following permissions are set on a "developeradmin" role:

PUT on /developers
GET on /developers/*

This means the developeradmin can:

Create a developer, but not update any specific developers or any sub-entities (because of the more specific GET permission on that path).
Get any developer or sub-entity, but not get a list of all developers.

See Permissions reference for a complete list of permissions that you can set with the API.

Create a new custom role called "development"

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

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

Add permissions to the development role

The permissions that can be set on an entire group of Edge artifacts (such as all /apps, /apis, /apiproducts, and so on) as well as on individual artifacts (such as a specific app, API proxy, or API product) are GET, PUT, and DELETE.

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 artifact on which you set the permissions. For example, /applications, /apps, /apiproducts, /developers, or /reports.

curl -u email:password 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" ]}'

Note: The role resource path for all proxies is /applications and for a specific API proxy it is /applications/<proxy_name>.

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 email:password 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 email:password https://api.enterprise.apigee.com/v1/o/{org_name}/userroles/testing/permissions -H "Content-type:application/json" -X POST -d'{"path" : "/applications","permissions" : [ "get" ]}'

For an on-premises installation of Edge, the minimum set of permissions that have to be set to allow the user to log in to the Edge UI are:

{"path" : "/","permissions" : [ "get" ]}
{"path" : "/*","permissions" : [ ]}
{"path" : "/environments","permissions" : [ "get" ]}
{"path" : "/userroles","permissions" : [ "get" ]}

Use the following cURL command to set these permissions:

curl -H "Content-Type:application/json" -u email:password \
-X POST \
http://<ms-IP>:8080/v1/organizations/{org_name}/userroles/testing/resourcepermissions  \
-d '{
 "resourcePermission" : [ 
   {
    "path" : "/",
    "permissions" : [ "get" ]
   }, 
{
    "path" : "/*",
    "permissions" : []
   },
{
    "path" : "/environments",
    "permissions" : [ "get" ]
   },
   {
    "path" : "/userroles",
    "permissions" : [ "get"]
   }
  ]
}'

where <ms-IP> is the IP address or DNS name of the Edge Management Server.

Add user to testing role

To provision a user with a user role:

$ curl -u email:password 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 email:password 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 (across all organizations) at any time:

$ curl -u email:password -X GET https://api.enterprise.apigee.com/v1/users/justauser@apigee.com/userroles