Documentation

EPM-UL role-based policies

Suggest Edits

ℹ️

Note

Role-based policy management is disabled on hosts configured to use script-based policy.

An Endpoint Privilege Management for Unix and Linux (EPM-UL) role-based policy defines which users can use commands and when they can perform these actions on hosts. These role entities are then associated to a role. A User, Host, Command, and Schedule entity can be used in multiple roles, allowing the user to create a single definition and share it. The role-based policy editor is divided into sections allowing for the management of roles and each of the role entities.

Choose the EPM-UL role-based policy option and an appropriate policy server from the selection lists to load the Role Based Policy menu.

ℹ️

Note

Fields may be disabled during policy configuration when the options are not available for the installed version of EPM-UL.

Entitlement reporting

EPM-UL hosts running 10.1 and later in Role Based Policy Mode can take advantage of Entitlement reporting to discover who is able to do what, where, and when.

Entitlement reporting can be enabled per policy or to all role-based policies.

A default value for reporting can be configured in Settings; if enabled, all new role-based policies defaults to entitlement reporting enabled, or vice versa if set to false. Additionally, this setting can be locked so the default value is both set and unchangeable per policy. This is for new policies only; disabling entitlement reporting does not change the values for existing policies.

Role-based policy roles

A list of available roles shows the existing entities. This list is searchable and can be filtered by Enabled, Disabled, or all options. Selecting the Add Role option creates a role.

  • To edit an existing role, select an entry from the Roles list and click Edit.
  • To delete an existing role, select an entry from the Roles list and click Delete.

Role ordering

The order in which role-based policies are applied can be set by ordering the roles in the list of available roles. Click and drag a role entry up or down in the Roles list to establish the priority order. Changes to role order is saved automatically.

General details

The following options are available:

  • Role name: This should be unique on the policy server.
  • Tag: Add a tag to the role. Once added, tags function as a filter and can be used to sort through policy roles.
  • Description: A brief description to identify the role.
  • Comment: The admin can add a comment here. These are only visible to the admin.
  • Role Risk Level: The perceived risk level of the policy.
  • Request Type: Allows the administrator to specify which request types this policy will apply to. For example, a policy might apply to commands issued only by pbrun invocations. Use the dropdown to select the appropriate request type, or select Any. The default value is to allow any request type.
  • Policy Enabled: Whether or not the role is active (default Enabled).
  • Action: Whether this should trigger an accept or reject action (default Accept).
  • Entitlement Reporting: Whether or not Entitlement Reporting is enabled (default Disabled).

ℹ️

Note

If Change Management is enabled, an additional Change requested by [loggedInUserName] field is visible and requires you to enter a reason for the change.

Click Save.

Assignments

Assign allowed users, hosts, commands, and schedule to a role. Each role can have zero to many relationships with each entity type. This is managed using the lists matching the appropriate entity. The following configuration sections are available:

  • Who: Defines which users the policy applies to. This item is divided into two user types:

    • Submit Users
    • Run Users

    These lists contain the user entities.

    Select Use Default Group and Working Directory to automatically populate the run users in a script block on the Script Policy page. Changing the block properties is not recommended.

  • What: Defines which commands the policy applies to. This list contains the command entities.

  • Where: Defines which hosts the policy applies to. This item is divided into two host types:

    • Submit Hosts
    • Run Hosts

    These lists contain the host entities.

  • When: Defines which schedule the policy applies to. This list contains the schedule entities.

ℹ️

Note

If Change Management is enabled, an additional Change requested by [loggedInUserName] field is visible and requires you to enter a reason for the change.

Click Save.

Reauthentication

If configured, this feature requires users to reauthenticate themselves when this policy is invoked. Only one reauthentication method can be configured per policy. Most reauthentication options allow for customization of messages and prompts to be displayed to the user as well as logs. Reauthentication can be enabled in a number of configurations:

  • None: Reauthentication is not required.
  • Shared Secret: Create a shared secret value. The user must provide it to reauthenticate.
  • Privilege Access Management (PAM): A number of PAM modules can be selected, or a custom one can be provided. Additionally, most options allow the user to configure where the authentication will occur.

To configure the Shared Secret option:

  1. From the Type dropdown, select Shared Secret.
  2. Enter the Shared Secret and confirm it.
  3. Enter a Reauthentication Prompt message, or use the default.
  4. Enter the Number of attempts (retries) before reauthentication locks up.
  5. Enter the Failure Message the user sees if reauthentication fails, or use the default.
  6. Enter the Log Message that is recorded in the log when reauthentication fails, or use the default.

ℹ️

Note

If Change Management is enabled, an additional Change requested by [loggedInUserName] field is visible and requires you to enter a reason for the change.

  1. Click Save.

To configure the PAM option:

  1. rom the Type dropdown, select PAM.
  2. Select the PAM Service to use for authentication.
  3. Select the Location to use, where the authentication happens. If you select the Run Host option, you only need to complete steps 4 and 5, and then click Save.
  4. Select the User Type, whether you are providing authentication for the user requesting the elevation, the user running the command, or some other user. If you select Custom, enter a custom user name.
  5. Enter a Reauthentication Prompt message, or use the default.
  6. Enter the Number of attempts (retries) before reauthentication locks up. That depends entirely on the policies imposed by the authentication services that EPM-UL accesses through PAM.
  7. Enter the Valid time length, in seconds, or use the default. This is how long the reauthentication is cached for, before a login is required again.
  8. Enter the Failure Message the user sees if reauthentication fails, or use the default.
  9. Enter the Log Message that is recorded in the log when reauthentication fails, or use the default.
  10. In the Change requested by [loggedInUserName] field, enter a reason for the assignment or change.

ℹ️

Note

If Change Management is enabled, an additional Change requested by [loggedInUserName] field is visible and requires you to enter a reason for the change.

  1. Click Save.

Messages

Enables the administrator to output a message to the user when this policy is processed. This field can interpolate variables to provide a custom, context specific message using the EPM-UL template syntax of %%. A few options are available using buttons to quickly insert the most popular options. Values can also be entered freely.

Click Save.

Session replay

Generate a file location for session replay logs and configure Path Options.The Session Replay Location field allows for the use of variables in the file name. BIUL provides a template builder to assist with creating the path; select the build option, provide a path to save the file, and select the desired variable options. Values can also be entered freely.

ℹ️

Note

If Change Management is enabled, an additional Change requested by [loggedInUserName] field is visible and requires you to enter a reason for the change.

Click Save.

Script policy

A configuration area to include a custom script. Script policy can be entered into the code editor to set the script content.

ℹ️

Note

If Change Management is enabled, an additional Change requested by [loggedInUserName] field is visible and requires you to enter a reason for the change.

Click Save.

Users and user groups

Users and user groups determine who the role will be applied to.

ℹ️

Note

Role-based policy management is disabled on hosts configured to use script-based policy.

User and user group types

There are three types of users and user groups:

  • Secure: A user or group not associated with any system. The name and credential are added to the policy.
  • System: The users and groups are retrieved from the selected host. System roles are only available with Endpoint Privilege Management for Unix and Linux versions 9.4.4 or later.
  • Directory Service: The users and groups are retrieved from Directory Service. Create a connection to Directory Service on the Settings > Integration page.

ℹ️

Note

If a wildcard character (*) is in the username, the user is treated as a group.

Add a secure user

  1. Go to the Policy Management page.
  2. In the Hostname list, select a server entry, and then at the far right, click the ellipsis menu icon and select Server Details.
  3. Click Policy.
  4. Click Who.
  5. Click Add User / Group and select Secure User.
  6. Enter Username, Description, and choose to enable or disable the entry.
  7. Click Save Changes.

Add a secure group

  1. Go to the Policy Management page.
  2. In the Hostname list, select a server entry, and then at the far right, click the ellipsis menu icon and select Server Details.
  3. Click Policy.
  4. Click Who.
  5. Click Add User / Group and select Secure Group.
  6. Enter Group name, Description, and choose to make the group active or inactive.
  7. In the Group members section, enter existing secure users in the Username field to add them to the group.
  8. Click Save Changes.

Delete a secure user or group

  1. Go to the Policy Management page.
  2. In the Hostname list, select a server entry, and then at the far right, click the ellipsis menu icon and select Server Details.
  3. Click Policy.
  4. Click Who.
  5. Select a secure user or group entry from the Users list.
  6. On the Users and Groups pane, click Delete User or Delete Group to delete the entry.

Add a system user or group

  1. Go to the Policy Management page.
  2. In the Hostname list, select a server entry, and then at the far right, click the ellipsis menu icon and select Server Details.
  3. Click Policy.
  4. Click Who.
  5. Click Add User / Group and select System User or System Group. A list of available entries is displayed on the Users and Groups pane.
  6. On the Users and Groups pane, check the box to import users or user groups. The imported users or user groups are displayed in the Users list.

Remove a system user or group

  1. Go to the Policy Management page.
  2. In the Hostname list, select a server entry, and then at the far right, click the ellipsis menu icon and select Server Details.
  3. Click Policy.
  4. Click Who.
  5. Select a system user or group entry from the Users list.
  6. On the Users and Groups pane, click Remove User or Remove User Group to remove the entry.

Add a directory service user or group

  1. Go to the Policy Management page.
  2. In the Hostname list, select a server entry, and then at the far right, click the ellipsis menu icon and select Server Details.
  3. Click Policy.
  4. Click Who.
  5. Click Add User / Group and select Directory Service Users and Groups.
  6. On the Users and Groups pane, select the Search Type to Find Users or Find Groups.
  7. Enter the Forest and Domain.
  8. Click Browse to filter by organizational unit (OU) and enter criteria in the Search for field.
  9. Click Search Directory Service.
  10. Check the box to import Directory Service users or user groups. The imported users or user groups are displayed in the Users list.

Remove a directory service user or group

  1. Go to the Policy Management page.
  2. In the Hostname list, select a server entry, and then at the far right, click the ellipsis menu icon and select Server Details.
  3. Click Policy.
  4. Click Who.
  5. Select a Directory Service user or group entry from the Users list.
  6. On the Users and Groups pane, click Remove User or Remove Group to remove the entry.

Command groups

Command Groups determine which commands will be allowed or rejected.

ℹ️

Note

Role-based policy management is disabled on hosts configured to use script-based policy.

Add a command group

  1. Go to the Policy Management page.
  2. In the Hostname list, select a server entry, and then at the far right, click the ellipsis menu icon and select Server Details.
  3. Click Policy.
  4. Click What.
  5. Click Add Command Group.
  6. Enter Command Group Name, Command Group Description, and choose whether the Command Group is enabled or disabled.
  7. Enter Commands. When adding a command to the list, you must enter Command, which is the command an Endpoint Privilege Management for Unix and Linux user types. Optionally, you can enter Executed, which is executed in place of the Command.
  8. Click Save.

Delete a command group

  1. Go to the Policy Management page.
  2. In the Hostname list, select a server entry, and then at the far right, click the ellipsis menu icon and select Server Details.
  3. Click Policy.
  4. Click What.
  5. Select an existing entry from the Command Groups list.
  6. Click Delete.

Host groups

Host Groups determine where the roles are applied.

ℹ️

Note

Role-based policy management is disabled on hosts configured to use script-based policy.

Add a host group

  1. Go to the Policy Management page.
  2. In the Hostname list, select a server entry, and then at the far right, click the ellipsis menu icon and select Server Details.
  3. Click Policy.
  4. Click Where.
  5. Click Add Host Group.
  6. Enter Host Group Name, Host Group Description, and choose whether the Host Group is enabled or disabled.
  7. Enter Matching Hosts.
  8. Click Save.

Delete a host group

  1. Go to the Policy Management page.
  2. In the Hostname list, select a server entry, and then at the far right, click the ellipsis menu icon and select Server Details.
  3. Click Policy.
  4. Click Where.
  5. Select an existing entry from the Host Groups list.
  6. Click Delete.

Schedule groups

Schedule Groups determine when roles are applied. When adding a schedule, there are two types of dates you can create in your schedule:

  • Fixed Schedule: Choose a specific date range. If the end date is not specified, the range defaults to continuous. If the start date is not specified, the default starts immediately.
  • Recurring Schedule: Choose active blocks of time per day. Choose a range of 15 minute blocks per each day for a full calendar week.

Add a schedule group

  1. Go to the Policy Management page.
  2. In the Hostname list, select a server entry, and then at the far right, click the ellipsis menu icon and select Server Details.
  3. Click Policy.
  4. Click When.
  5. Click Add Schedule Group.
  6. Enter Schedule Group Name, Schedule Group Description, and choose whether the Schedule Group is enabled or disabled.
  7. Configure schedules using Recurring Schedule and Fixed Schedule options.
  8. Click Save.

Delete a schedule group

  1. Go to the Policy Management page.
  2. In the Hostname list, select a server entry, and then at the far right, click the ellipsis menu icon and select Server Details.
  3. Click Policy.
  4. Click When.
  5. Select an existing entry from the Schedule Groups list.
  6. Click Delete.

Backup and restore

Role-based policy data can be managed in this section.

  • Backup Role Based Policy: Download a copy of the policy database on the selected policy server.
  • Restore Role Based Policy: Upload and set the current policy to the provided backup.
  • Version Control: Restore the database to a particular version by selecting a version from the Version list and clicking Restore Version.

Updated 5 days ago

©2003-2025 BeyondTrust Corporation. All Rights Reserved. Other trademarks identified on this page are owned by their respective owners. BeyondTrust is not a chartered bank or trust company, or depository institution. It is not authorized to accept deposits or trust accounts and is not licensed or regulated by any state or federal banking authority.