Configuring Role-Based Access Control

Contents

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

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

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

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:

  1. Log in to the server as a user with the Administrators role (the current system Administrator Role).
  2. Click the Users button in the Policy Studio toolbar to open the User List dialog.
  3. Click Edit Roles.
  4. Add a new role (for example, MyAdministrators), and click OK.
  5. Select the user that you are logged in as, and click Edit User Roles.
  6. 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.
  7. Edit the server configuration in the Policy Studio.
  8. Right-click the server process, and select Settings -> Default Settings (or Custom Settings if used).
  9. 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.
  10. Deploy the configuration.
  11. Add the following to the acl.policy file: 

    grant principal com.vordel.circuit.rbac.VordelPrincipal "MyAdministrators" {
  permission com.vordel.circuit.rbac.MgmtServicePermission "/*";
};

  12. Reboot the server.
  13. Restart the Policy Studio, and open the User List dialog.
  14. 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.
  15. 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:

  1. Log in to the server as a user with the Administrators role.
  2. Click the Users button in the Policy Studio toolbar to open the User List dialog.
  3. Click Edit Roles.
  4. Add a new role (for example, PDAdministrators), and click OK.
  5. Select the user you are logged in as, and click Edit User Roles.
  6. Add the PDAdministrators role to your list of roles, and keep the Administrators role.
  7. Edit the server configuration in the Policy Studio.
  8. Right-click the server process, and select Settings -> Default Settings (or Custom Settings if used).
  9. 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.
  10. 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.