Managing users, roles, and permissions

The Apigee documentation site has extensive information on managing user roles and permissions. Users can be managed using both the Edge UI and the Management API; roles and permissions can be managed only with the Management API.

For information on users and creating users, see:

Many of the operations that you perform to manage users requires system administrator privileges. In a Cloud based installation of Edge, Apigee functions in the role of system administrator. In an Edge for the Private Cloud installation, your system administrator must perform these tasks as described below.

Adding a user

You can create a user either by using the Edge API, the Edge UI, or Edge commands. This section describes how to use Edge API and Edge commands. For information on creating users in the Edge UI, see Creating global users.

After you create the user in an organization, you must assign a role to the user. Roles determine the access rights of the user on Edge.

Use the following command to create a user with the Edge API:

curl -H "Content-Type:application/xml" \
  -u SYS_ADMIN_EMAIL:SYS_ADMIN_PASSWORD -X POST http://ms_IP:8080/v1/users \
  -d '<User> \
    <FirstName>New</FirstName> \
    <LastName>User</LastName> \
    <Password>NEW_USER_PASSWORD</Password> \
    <EmailId>foo@bar.com</EmailId> \
  </User>'

Or use the following Edge command to create a user:

/opt/apigee/apigee-service/bin/apigee-service apigee-provision create-user -f configFile

Where the configFile creates the user, as the following example shows:

APIGEE_ADMINPW=SYS_ADMIN_PASSWORD    # If omitted, you will be prompted.
USER_NAME=foo@bar.com
FIRST_NAME=New
LAST_NAME=User
USER_PWD="NEW_USER_PASSWORD"
ORG_NAME=myorg

You can then use this call to view information about the user:

curl -u SYS_ADMIN_EMAIL:SYS_ADMIN_PASSWORD http://ms_IP:8080/v1/users/foo@bar.com

Assigning the user to a role in an organization

Before a new user can do anything, they have to be assigned to a role in an organization. You can assign the user to different roles, including: orgadmin, businessuser, opsadmin, user, or to a custom role defined in the organization.

Assigning a user to a role in an organization automatically adds that user to the organization. Assign a user to multiple organizations by assigning them to a role in each organization.

Use the following command to assign the user to a role in an organization:

curl -X POST -H "Content-Type:application/x-www-form-urlencoded" \
  http://ms_IP:8080/v1/o/org_name/userroles/role/users?id=foo@bar.com \
  -u SYS_ADMIN_EMAIL:SYS_ADMIN_PASSWORD

This call displays all the roles assigned to the user. If you want to add the user, but display only the new role, use the following call:

curl -X POST -H "Content-Type: application/xml" \
  http://ms_IP:8080/v1/o/org_name/users/foo@bar.com/userroles \
  -d '<Roles><Role name="role"/><Roles>' \
  -u SYS_ADMIN_EMAIL:SYS_ADMIN_PASSWORD

You can view the user's roles by using the following command:

curl -u SYS_ADMIN_EMAIL:SYS_ADMIN_PASSWORD http://ms_IP:8080/v1/users/foo@bar.com/userroles

To remove a user from an organization, remove all roles in that organization from the user. Use the following command to remove a role from a user:

curl -X DELETE -u SYS_ADMIN_EMAIL:SYS_ADMIN_PASSWORD \
  http://ms_IP:8080/v1/o/org_name/userroles/role/users/foo@bar.com

Adding a system administrator

A system administrator can:

  • Create orgs
  • Add Routers, Message Processors, and other components to an Edge installation
  • Configure TLS/SSL
  • Create additional system administrators
  • Perform all Edge administrative tasks

While only a single user is the default user for administrative tasks, there can be more than one system administrator. Any user who is a member of the "sysadmin" role has full permissions to all resources.

You can create the user for the system administrator in either the Edge UI or API. However, you must use the Edge API to assign the user to the role of "sysadmin". Assigning a user to the "sysadmin" role cannot be done in the Edge UI.

To add a system administrator:

  1. Create a user in the Edge UI or API.
  2. Add user to the "sysadmin" role: 
    curl -u SYS_ADMIN_EMAIL:SYS_ADMIN_PASSWORD \
  -X POST http://ms_IP:8080/v1/userroles/sysadmin/users -d 'id=foo@bar.com'
  3. Ensure that the new user is in the "sysadmin" role: 
    curl -u SYS_ADMIN_EMAIL:SYS_ADMIN_PASSWORD http://ms_IP:8080/v1/userroles/sysadmin/users

    Returns the user's email address:

    [ " foo@bar.com " ]
  4. Check permissions of new user: 
    curl -u SYS_ADMIN_EMAIL:SYS_ADMIN_PASSWORD http://ms_IP:8080/v1/users/foo@bar.com/permissions

    Returns:

    {
  "resourcePermission" : [ {
  "path" : "/",
    "permissions" : [ "get", "put", "delete" ]
  } ]
}
  5. After you add the new system administrator, you can add the user to any orgs.
  6. If you later want to remove the user from the system administrator role, you can use the following API: 
    curl -X DELETE -u SYS_ADMIN_EMAIL:SYS_ADMIN_PASSWORD \
  http://ms_IP:8080/v1/userroles/sysadmin/users/foo@bar.com

    Note that this call only removes the user from the role, it does not delete the user.

Changing the default system administrator user

At the time you install Edge, you specify the email address of the system administrator. Edge creates a user with that email address, and sets that user to be the default system administrator. You can later add additional system administrators as described above.

This section describes how to change the default system administrator to be a different user, and how to change the email address of the user account for the current default system administrator.

To see the list of users currently configured as system administrators, use the following API call:

curl -u SYS_ADMIN_EMAIL:SYS_ADMIN_PASSWORD http://ms_IP:8080/v1/userroles/sysadmin/users

To determine the current default system administrator, view the /opt/apigee/customer/defaults.sh file. The file contains the following line showing the email address of the current default system administrator:

ADMIN_EMAIL=foo@bar.com

To change the default system administrator to be a different user:

  1. Create a new system administrator as described above, or ensure that the user account of the new system administrator is already configured as a system administrator.
  2. Edit /opt/apigee/customer/defaults.sh to set ADMIN_EMAIL to the email address of the new system administrator.
  3. Edit the silent config file that you used to install the Edge UI to set the following properties: 
    ADMIN_EMAIL=NEW_SYS_ADMIN_EMAIL
APIGEE_ADMINPW=NEW_SYS_ADMIN_PASSWORD
SMTPHOST=smtp.gmail.com
SMTPPORT=465
SMTPUSER=foo@gmail.com
SMTPPASSWORD=bar
SMTPSSL=y

    Note that you must include the SMTP properties because all properties on the UI are reset.

  4. Reconfigure the Edge UI: 
    /opt/apigee/apigee-service/bin/apigee-service edge-ui stop
/opt/apigee/apigee-service/bin/apigee-service edge-ui setup -f configFile
/opt/apigee/apigee-service/bin/apigee-service edge-ui start

If you just want to change the email address of the user account for the current default system administrator, you first update the user account to set the new email address, then change the default system administrator email address:

  1. Update the user account of the current default system administrator user with a new email address: 
    curl -H content-type:application/json -X PUT -u CURRENT_SYS_ADMIN_EMAIL:SYS_ADMIN_PASSWORD \
  http://ms_IP:8080/v1/users/CURRENT_SYS_ADMIN_EMAIL \
  -d '{"emailId": "NEW_SYS_ADMIN_EMAIL", "lastName": "admin", "firstName": "admin"}'
  2. Repeat steps 2, 3. and 4 from the previous procedure to update the /opt/apigee/customer/defaults.sh file and to update the Edge UI.

Specifying the email domain of a system administrator

As an extra level of security, you can specify the required email domain of an Edge system administrator. When adding a system administrator, if the user's email address is not in the specified domain, then adding the user to the "sysadmin" role fails.

By default, the required domain is empty, meaning you can add any email address to the "sysadmin" role.

To set the email domain:

  1. Open the management-server.properties file in an editor: 
    vi /opt/apigee/customer/application/management-server.properties

    If this file does not exist, create it.

  2. Set the conf_security_rbac.global.roles.allowed.domains property to the comma-separated list of allowed domains. For example: 
    conf_security_rbac.global.roles.allowed.domains=myCo.com,yourCo.com
  3. Save your changes.
  4. Restart the Edge Management Server: 
    /opt/apigee/apigee-service/bin/apigee-service edge-management-server restart

    If you now attempt to add a user to the "sysadmin" role, and the email address of the user is not in one of the specified domains, the add fails.

Deleting a user

You can create a user either by using the Edge API or the Edge UI. However, you can only delete a user by using the API.

To see the list of current users, including email address, use the following curl command:

curl -u SYS_ADMIN_EMAIL:SYS_ADMIN_PASSWORD http://ms-IP:8080/v1/users

Use the following curl command to delete a user:

curl -u SYS_ADMIN_EMAIL:SYS_ADMIN_PASSWORD -X DELETE http://ms_IP:8080/v1/users/USER_EMAIL