# Configuring Role-Based Access Control

## Contents
Overview Server acl.policy File Enterprise Gateway Welcome Page Protect Management and Policy Director Interfaces Policy Policy Center User Store System Administrators Role PD Superuser Privilege Management Service Roles and URIs

## Overview
Role-Based Access Control (RBAC) enables you to restrict system access to authorized users based on their assigned roles. Using the RBAC model, permissions to perform specific system operations are assigned to specific roles. This means that system users are granted permission to perform specific system operations only through their assigned roles. This simplifies system administration because users do not need to be assigned permissions directly, but instead acquire them through their assigned roles. RBAC is supported by the Enterprise Gateway, Policy Center, and Service Monitor servers to protect access to the management services provided by each server. Management services are invoked when a user performs the following tasks: Accesses the server using the Policy Studio Accesses the server using the Service Manager Requests the Enterprise Gateway Welcome page (`http://localhost:8090/`) in a web browser Requests trace, logs, or diagnostics in a web browser Uses the Traffic Monitor tool Uses the Real-time Monitoring tools User access to management services is determined by their role or roles. Each role has a defined set of management services that it can access. A management service is defined by the URI used to access it, and in some cases, the SOAP operation and namespace. For more information, see Management Service Roles and URIs. By default, a local Policy Center user store available in the Policy Studio is used to authenticate and perform RBAC on all access to the management services. This stores the user’s credentials so that their passwords can be verified, and also stores their roles. You can also use an LDAP repository for authentication and RBAC. For details on setting up an LDAP repository, see the Authentication Repository topic.
## Server acl.policy File
The `acl.policy` file is found in the `conf` directory of your server installation. This file lists each role and the management services that each role may access. By default, this file defines the following roles: Administrators Operators Auditors Deployers The default `admin` user has the `Administrators` role, which allows access to everything. For full details on the management services that each role has access to, and the URIs that must be listed in the `acl.policy` file to have access to them, see the table in Management Service Roles and URIs. The roles defined in the `acl.policy` file should exist in the user store used to authenticate the users and load their roles and groups. The default roles are defined in the local Policy Center (PD) user store, which is used to control access to the management services using the Protect Management and Policy Director Interfaces policy. If a different user store is used (for example, an LDAP repository), the LDAP groups should be listed in the `acl.policy` file. acl.policy File Format Each entry in the `acl.policy` file has the following format:
    grant principal com.vordel.circuit.rbac.VordelPrincipal "role-name" {
    permission com.vordel.circuit.rbac.MgmtServicePermission "URI [SOAP-operation-name]
     [SOAP-operation-namespace]";
    };
This entry format is explained as follows: The `permission` line is repeated for each URI that the role can access. To determine which URIs should be listed for each management service, see the table in Management Service Roles and URIs. The SOAP operation name and namespace are optional. They apply only to the SOAP-based management services. If they are omitted for a SOAP-based management service, the role has access to all operations on that interface. If a subset of operations is listed, the user may only invoke those operations that are listed. A separate `permission` line is required for each operation if the user only has access to a subset of operations. You can place a wildcard (`*`) at the end of the `URI` field. For example, see the permission for the default `Administrators` role in the `acl.policy` file. This means that the role has access to all URIs that start with the URI content that precedes the `*`. In some cases, you must protect a management service by specifying a query string after the URI. Exact matches only are supported for query strings.
## Enterprise Gateway Welcome Page
The Enterprise Gateway Welcome page (`http://localhost:8090`) is an index page to the management services for the Enterprise Gateway, and is controlled by RBAC. Connecting to this URL as users with different roles results in different options being displayed. Users with the `Administrators` role can access all available tools, such as Service Manager and Real-time Monitoring, while users in other roles can access a subset of available tools. For example, users with the `Operators`, `Deployers`, or `Auditors` role cannot access Service Manager.
## Protect Management and Policy Director Interfaces Policy
By default, the Protect Management and Policy Director Interfaces policy controls access to the management services (except the Service Manager login page). This policy includes the following filters:
Protect Management and Policy Director Interfaces Policy
HTTP Basic Filter This filter performs the following tasks: Verifies the user name and password against the local PD user store. If no credentials are specified or, they are invalid, this always throws an HTTP 401. This allows a retry for browser users. Assuming authentication has passed, the user roles are loaded from the user store. (Currently this automatic load of roles is only supported by the local PD user store, which means no additional filters are required to load the roles). The username is in the `authentication.subject.id` message attribute, and the user roles are in `authentication.subject.role`. For more details, see the HTTP Basic topic. RBAC Filter This filter performs the following tasks: Reads the roles from the `authentication.subject.role` message attribute. Determines what management service is currently being invoked (which URI, and which SOAP operation and namespace where applicable). The RBAC filter returns true if one of the roles has access to the management service currently being invoked, as defined in the `acl.policy` file. Otherwise, it returns false and the Return HTTP Error 403: Access Denied (Forbidden) policy is called. For example, this occurs if a new user is created and they have not yet been assigned any roles. For more details, see the RBAC Filter topic. Call Internal Service Filter This filter performs the following tasks: Assuming the RBAC filter passed, the management service is called. The `authentication.subject.id` and `authentication.subject.role` message attributes are passed to the service as HTTP headers. Some of the management services perform further access control checks on the user and their roles at a more in-depth level than URI and SOAP operation (for example, a check based on the parameters contained in the SOAP message). For more details, see the Call Internal Service topic.
## Policy Center User Store
The local Policy Center user store in the Policy Studio supports user roles. The User List screen in the Policy Studio enables the user to view and modify user roles (assuming they have a role that allows this). This screen is displayed as follows:
User List Screen
Managing User Roles You can select a User in the list to enable the Edit User Roles button, and click this button to enable roles for the selected user. You can also click the Edit Roles button to add or delete a role from the list of available roles. Adding a New User Role When you add a new role to the Policy Center user store, you must modify the `acl.policy` file if RBAC is to be performed on the basis of whether the user has this new role. You must add a new `grant` section to the `acl.policy` file, which lists all the URIs that the new role may access. You must then reboot the server to reload the `acl.policy` file. You do not need to reboot or refresh the server if a user’s roles change.
## System Administrators Role
11. By default, the `Administrators` role allows access to all management services. This access is defined in the `acl.policy` file using the `/*` URI. The default `admin` user is assigned to this role. To ensure that users with this role do not lock themselves out of the system, they are not allowed to remove themselves from this role. However, other users that are allowed to change a user’s roles are allowed to remove the user from the `Administrators` role. This special system administrator role is defined in the Default Settings as the Administrator Role. This setting is only used to provide special protection for the role (a user with this role cannot remove themselves from this role). This ensures that there is always at least one user in the system with this role. Configuring the Administrator Role If you wish configure a different role as the system Administrator Role, perform the following steps: Log in to the server as a user with the `Administrators` role (the current system Administrator Role). Click the Users button in the Policy Studio toolbar to open the User List dialog. Click Edit Roles. Add a new role (for example, `MyAdministrators`), and click OK. Select the user that you are logged in as, and click Edit User Roles. Add the `MyAdministrators` role to your list of roles, and keep the `Administrators` role. You are not allowed to remove it yet because it is still the system Administrator Role. Edit the server configuration in the Policy Studio. Right-click the server process, and select Settings -> Default Settings (or Custom Settings if used). Set the value of the Administrator Role and Policy Director Super User Role to `MyAdministrators`. For details on the Policy Director Super User Role, see the next section. Deploy the configuration. Add the following to the `acl.policy` file:
        grant principal com.vordel.circuit.rbac.VordelPrincipal "MyAdministrators" {
          permission com.vordel.circuit.rbac.MgmtServicePermission "/*";
        };
Reboot the server. Restart the Policy Studio, and open the User List dialog. Remove all users from the `Administrators` role by clicking Edit User Roles on each user with that role, assuming this role is no longer required. You can now remove the `Administrators` role by clicking Edit Roles.
## PD Superuser Privilege
PD Superuser privilege gives a specified role special system administrator rights in the system, for example: Add, delete, and update other users. Reset user passwords. Add another superuser. Perform actions only allowed by a Configuration Profile owner (for example, transfer ownership to another user). Perform actions only allowed by a Process owner (for example, deploy a new Configuration Profile to a Process owned by another user). The PD superuser privilege is checked in the Policy Center API. RBAC checks are also performed in the RBAC filter before getting to the Policy Center API. The superuser checks performed on the user in this API are as follows: Ensure is superuser to create or delete a role or user. Ensure is superuser/or logged in user to reset the password. Ensure is superuser to modify a user (change its roles). Users cannot remove their own PD superuser role, or system admin role. Ensure is superuser or configuration/process owner to reassign configurations or processes. Ensure is superuser/configuration group owner to update a configuration. Ensure is superuser/process group owner to create a process, get connection credentials, or modify a process. Ensure is superuser/process group and configuration group owner to deploy a configuration to a process. Configuring the PD Superuser Role By default, a user has the PD superuser privilege if they have the default `Administrators` role. This means that the default `admin` user has the PD superuser privilege. The role used to determine whether a user has the PD superuser is defined in the System Settings as Policy Director Super User Role. If you wish to separate the PD superuser privilege out of the `Administrators` role, perform the following steps: Log in to the server as a user with the `Administrators` role. Click the Users button in the Policy Studio toolbar to open the User List dialog. Click Edit Roles. Add a new role (for example, `PDAdministrators`), and click OK. Select the user you are logged in as, and click Edit User Roles. Add the `PDAdministrators` role to your list of roles, and keep the `Administrators` role. Edit the server configuration in the Policy Studio. Right-click the server process, and select Settings -> Default Settings (or Custom Settings if used). Set the value of the Administrator Role and Policy Director Super User Role to be the name of the role that determines if the user has the PD superuser privilege. Deploy the configuration. Only users with the `PDAdministrors` role are now able to perform PD superuser actions. Important Note: Having the `PDAdministrators` role does not ensure access to the management services. If required, add this access to the role by editing the `acl.policy` file, and reboot the server when the changes are made. To give the `PDAdministrators` role access to all management services, add the following entry to the `acl.policy` file:
    grant principal com.vordel.circuit.rbac.VordelPrincipal "PDAdministrators" {
      permission com.vordel.circuit.rbac.MgmtServicePermission "/*";
    };
## Management Service Roles and URIs
You can use the following table for reference purposes when making changes to the `acl.policy` file. It defines each management service, and the default roles that have access to them. It also lists the URIs that must be listed in the `acl.policy` to have access to the management service. Where applicable, the SOAP operation names of the management service are also listed.
Management Service | Default Roles | URI
Welcome page on http://localhost:8090/ | Administrators Operators Deployers Auditors | `/` `/index.html` `/images/*` `/css/*` `/favicon.ico`
Service Manager | Administrators | `/manager/*` `/VAADIN/*`
Real-time Monitoring | Administrators Operators | `/monitoring/*` `/metrics`
Traffic Monitor | Administrators Operators | `/trafficmonitor/*` `/ops/*`
Trace Files | Administrators Operators | `/file/view?type=trace&format=html` `/file/view*?type=trace`
Audit (Log) Files | Administrators Deployers Auditors | `/file/view?type=audit&format=html` `/file/view*?type=audit`
Diagnostics | Administrators Operators | `/file/view/diagnostics`
Documentation | Administrators Operators Deployers Auditors | `/docs/*`
Management API | Administrators Deployers (read-only and deploy operations) Auditors (read-only operations) | URI: `/runtime/management/ManagementAgent` Namespace: `http://www.vordel.com/2006/07/22/pd/ManagementAgent` Operations: `reloadConfiguration` `getHostName` `getProductKey` `getProductName` `getProductVersion` `deploy` `getActiveDeploymentInfo` `getStoreContents` `createNewStore` `createDuplicateStore` `deleteStore`
Policy Center API | Administrators Deployers (read-only and deploy operations) Auditors (read-only operations and change own password) | URI: `/configuration/deployments/DeploymentService` Operations: `login` `logout` `listConfigurationFlavors` `getConfiguration` `commit` `deploy` `setActiveConfiguration` `getActiveConfiguration` `getActiveConfigurationFingerprint` `listUsers` `getUserDetails` `getUserRoles` `createUser` `modifyUser` `modifyUserRoles` `setUserPassword` `removeUser` `listProcessGroups` `getProcessDetails` `getProcessDetailsForID` `listProcesses` `createProcess` `modifyProcess` `removeProcess` `reassignProcesses` `getConnectionCredentials` `listConfigurationGroups` `getConfigurationDetails` `getConfigurationDetailsForID` `listConfigurations` `createConfiguration` `spawnConfiguration` `importConfiguration` `importConfigurationFromProcess` `modifyConfiguration` `archiveConfiguration` `reassignConfigurations` `listVersions` `getVersionDetails` `getLatestVersion` `createProcessGroup` `modifyProcessGroup` `removeProcessGroup` `reassignProcessGroup` `createConfigurationGroup` `modifyConfigurationGroup` `removeConfigurationGroup` `reassignConfigurationGroup` `getRoleDetails` `listRoles` `createRole` `removeRole` `hasAccess` `hasAdminRole`
Management Agent API Operations The Management Agent API operations are described as follows:
Operation | Description
`createNewStore` | When the Policy Studio is connected to Policy Center, a Deployment Wizard is available. When a user deploys using the wizard, the Policy Center API `deploy` method is invoked. This in turn calls `createNewStore` on the management agent API of the Enterprise Gateway when the store needs to be created, followed by `deploy` on the management API of the Enterprise Gateway.
`deploy` | Invoked by the Policy Center `setActiveConfiguration` method which is called when a user clicks deploy when editing the active configuration.
`getActiveDeploymentInfo` | Called when a user edits the active configuration of a process.
`getHostName` | Called by Policy Center on managed processes (Enterprise Gateway also calls on itself).
`getProductKey` | Called by Policy Center on managed processes (Enterprise Gateway also calls on itself).
`getProductName` | Called by Policy Center on managed processes (Enterprise Gateway also calls on itself).
`getProductVersion` | Called by Policy Center on managed processes (Enterprise Gateway also calls on itself).
`getStoreContents` | Called when a user edits the active configuration of a process.
Policy Center API Operations The Policy Center API operations are described as follows:
Operation | Description
`archiveConfiguration` | Called when a user selects to archive a configuration on the Profile Repository view.
`createConfiguration` | Called when a user selects to Create a baseline Configuration, or Create New Configuration on their Profile Repository view.
`createProcess` | Called when a user adds a process to their process list.
`createUser` | Create a new user.
`create*` | Create users, roles, and so on.
`commit` | Called when a user commits a new version of a configuration. This can be done in the Profile Repository view, or while editing an active configuration.
`deploy` | When the Policy Studio is connected to Policy Center, a Deployment Wizard is available. When a user deploys using the wizard, this method is invoked. This in turn calls `createNewStore` on the management agent API of the Enterprise Gateway when the store needs to be created, followed by `deploy` on the management API of the Enterprise Gateway.
`getActiveConfiguration` | Called when a user edits the active configuration of a process. The management API methods `getActiveDeploymentInfo` and `getStoreContents` are also called. Note that when you connect to the Enterprise Gateway using the Policy Center server, `getActiveConfiguration` is called on Policy Center and `getActiveDeploymentInfo` and `getStoreContents` are called on the Enterprise Gateway by Policy Center.
`getActiveConfigurationFingerprint` | Determines the status of deployment for a process (has it changed since last known deployment).
`getConfiguration, getConfigurationDetailsForID` | Called when a user edits a configuration in the Profile Repository. Also called when a user exports a configuration.
`get*` | Read-only operations to retrieve details of users, roles, configurations, process and so on, which are stored in `pdEntities.xml`.
`hasAccess` | Called by the Policy Studio when connected to the Enterprise Gateway to determine if the user has access to a particular SOAP API method according to RBAC.
`hasAdminRole` | Called to determine if the user has the Policy Center Super User Role.
`importConfiguration` | Called when a user selects Create Configuration via Import in the Profile Repository view.
`importConfigurationFromProcess` | Called when a user selects Download the Active Configuration for a process.
`login` | User logs into the server using the Policy Studio.
`logout` | User logs out of the server using the Policy Studio.
`list*` | Read-only operations to retrieve users, roles, configurations, processes, and so on, which are stored in `pdEntities.xml`.
`modifyConfiguration` | Rename a configuration in the Profile Repository view.
`modifyProcess` | Modify the connection credentials for a process in the Connection Details tab.
`modify*` | Modify user roles, and so on.
`remove*` | Delete users, processes, and roles.
`reassign*` | Called when a user changes ownership of a process or configuration.
`setActiveConfiguration` | Called when a user clicks the Deploy button when they are editing an active configuration. This invokes the deploy method on the management agent. When the Policy Studio user is connected to a Enterprise Gateway using Policy Center, `setActiveConfiguration` is called on Policy Center and the `deploy` is called on the Enterprise Gateway.
`setUserPassword` | Reset the user password.
`spawnConfiguration` | Called when a user select to Create via Copy a configuration in the Profile Repository view.