DocumentationAPI ReferenceRelease Notes
Log In
Documentation

What are messages in EPM for Windows and Mac?

Messages are alerts to the user before an action is performed (for example, before elevating an application or allowing content to be modified, or advising that an application launch or content modification is blocked). You can also use messages to request information from the user.

How are messages useful?

Messages (and notifications) display when a user’s action triggers a rule (application, on-demand, or content rule). Rules are triggered by an application launch or block, or when content is modified.

You can define two types of end user messages:

  • Messages: Messages take focus when they are displayed to the user.
  • Notifications: (Windows only) Message notifications appear on the user's task bar. A notification is displayed as a toast notification.

Important information about messages

  • Messages are assigned to Application Rules. A message displays different properties, depending on the targets it is assigned to.
  • There are attributes of a message that you can choose to use when configuring messaging:
    • General message features such as Header and Body options.
    • User Reason settings when you want your end users to provide a reason before proceeding.
    • User Authorization where a user must provide password, smart card, or both types of authentication information.
    • Multifactor Authentication where an Identity Provider is configured.
    • Challenge/Response Authorization where a user must enter a response code before proceeding.

Create a new message

  1. From the left menu, click .
    The Policies page displays.
  1. Create a new policy.
  2. Alternatively, locate an unlocked policy you want to edit from the list and click > Edit & Lock Policy.
    The Policy Editor opens, and the Workstyles page displays by default.
  3. In the left panel, click Messages.
    The Messages page displays.
  4. Click Create New Message.
    The Create New Message panel displays.
  5. If you are working in a Windows policy, select a message type.
  6. Select a message template.
  7. Enter the details as required by the template selected.
  8. Create the message header and body.
  9. Click Create New Message.
    The message is created and added to the Messages list.

Create an ActiveX message type

When you are elevating the installation of an ActiveX control in an application group, a built-in progress dialog box displays during the installation. You can customize the messaging on the installation progress dialog box.

ActiveX messages can be displayed in multiple languages. In EPM, the regional language of the end user can be detected, and if ActiveX strings in that language are configured, the correct translation is displayed.

ℹ️

Note

If language settings for the region of the end user are not configured, then the default language text is displayed. To change the default language, select a language and click Set Default.

  1. From the left menu, click .
    The Policies page displays.
  1. Create a new policy.
  2. Alternatively, locate an unlocked policy you want to edit from the list and click > Edit & Lock Policy.
    The Policy Editor opens, and the Workstyles page displays by default.
  3. In the left panel, click Messages.
    The Messages page displays.
  4. Click Create New Message.
    The Create New Message panel displays.
  5. Select Use ActiveX Control from the Message Type list.
  6. Fill in the text fields that will display on the dialog box.
  7. Click Create New Message.
  8. If you want to select a language other than English, click the newly created message in the navigation panel, and then click Manage Languages.
  9. Select and save the language.

Preview a message

📘

Note

Message preview is available for messages on Mac or Windows templates.

  1. From the left menu, click .
    The Policies page displays.
  1. Create a new policy.
  2. Alternatively, locate an unlocked policy you want to edit from the list and click > Edit & Lock Policy.
    The Policy Editor opens, and the Workstyles page displays by default.
  3. In the left panel, click Messages.
    The Messages page displays.
  4. Locate an existing message you want to preview.
  5. Click > Edit.
    The Message Editor displays.
  6. Click Preview.
    A preview of the end user view displays.

Add a reason prompt

📘

Note

Use a a reason prompt to ask the user about the reason for the request.

  1. Under section 3 on the left, check the Provide a Reason box.
  2. Select the User Reason Type, a textbox or a dropdown.
  3. (Optional). Select if you want to Remember the User Reason (per application).
  4. (Optional). You can change the default Reason Text and Reason Error Message Text.
  5. (Optional). If you select the drop-down type, you can change the default Drop-down List Prompt Text.
  6. (Optional). With the drop-down option, you can use the default User Reason List to be displayed for the user to choose from. You can also:
    • Change the text of the default list options.
    • Delete one or more of the default options.
    • Click the Add User Reason option to add your own user reason to the list.
  7. Click Save Changes.

Add a Challenge/Response authorization

⚠️

Important information

There are two parts to setting up challenge/response authorization:

  • Set a shared key: The Challenge/Response Key must be set to use Challenge/Response authorization in your messages. The key is encrypted. The key is required by the Challenge/Response generator to generate response codes. The only way to change the shared key is by setting a new one.
  • Add the authorization type to a message: When configuring your message, configure the Challenge/Response settings.

The Challenge/Response feature is a global setting and can be configured for Windows and macOS messages. Challenge/Response authorization only applies to Allow message types.

  1. Add a shared key:
    1. In the Policy Editor, click Messages.
    2. Click Challenge/Response Keys.
    3. Enter a key value and enter again to confirm.
    4. Click Set Key.
  2. Configure the Challenge/Response Authorization:
  3. In the Policy Editor, click Messages.
  4. Create a message following the steps provided earlier. If this is an existing message, select Edit from the menu.
  5. Under section 3 on the left, check the Request Access via Challenge/Response box.
  6. Open the Challenge / Response Authorization dropdown, and set the following:
    • Header text: The text that introduces the challenge/response authorization.
    • Hint text: The text that is in the response code field for challenge/response messages.
    • Authorization Period (per application): Set this option to determine the length of time a successfully returned challenge code is active for.
      • One Use Only: A new challenge code is presented to the user on every attempt to run the application.
      • Entire Session (Windows only): A new challenge code is presented to the user on the first attempt to run the application. After a valid response code is entered, the user is not presented with a new challenge code for subsequent uses of that application until they next log on.
      • As defined by helpdesk (Windows only): A new challenge code is presented to the user on the first attempt to run the application. If this option is selected, the responsibility of selecting the authorization period is delegated to the helpdesk user at the time of generating the response code. The helpdesk user can select one of the three above authorization periods. After a valid response code is entered, the user does not receive a new challenge code for the duration of time specified by the helpdesks.
    • Suppress messages once authorized (Windows only): Select to suppress messages. This setting is not shown when set to One Use Only.
    • Show Information Tip (Windows only): Select to add helpful information for the end user.
    • Information Tip Text: Add text that appears above the challenge and response code fields. In Windows, this only appears if the Show Information Tip option above is selected.
    • Error Message Text: Add text to display to the end user if they enter an incorrect response code.
    • Maximum Attempts: Select from Unlimited and Three Attempts.
    • Maximum Attempts Exceeded Message Text: The message is only displayed when Three Attempts is selected. Add text to display to the end user if they exceed the allowed number of challenge/response attempts.

Add a message header and body content

📘

Note

You can configure specific header options.
  • Show Message On Secure Desktop: (Windows only). Select to show the message on the secure desktop. We recommend this if the message is being used to confirm the elevation of a process, for enhanced security.
  • Title Text: (Windows only). Add text that appears in the title bar of the dialog box.
  • Header Type: Select the type of header: Default, Error, None, Question, Warning.
  • Header Background Type: Select Solid or Custom Image.
  • If you select Solid, use the color picker to select a header background color.
  • If you select Custom Image, you must select an image from the Select Image dropdown list.
  • Show Header Text: Select if you want to display header text.
  • Header Text: Add text that displays next to the header type icon.
  • Header Text Color: Select the color for the header text.
  • For Windows only: For a Notification message type, you can only configure the Title Text.

Additional header message design properties are available when using the User Request Message template. You can customize the text for the interactive prompts displayed during the request workflow, such as request text, pending text, and approval text.

You can configure specific body options.

You can configure the following message body options:

For Windows only: For Notification message types, you can only configure Body Text.

  • Body Text: Add additional information for the end user.
  • Message Mode: (Windows only). From the list, select Automatic or Custom. You can decide what information you want to display on the message. By default, all rows are on and will be displayed as part of the message. The Automatic default values are:
    • Show Line One: The Program Name or the Content Name.
    • Show Line Two: The Program Publisher or the Content Owner.
    • Show Line Three: The Program Path or the Content Program.
    • Show Reference Hyperlink: Turn the option on (it is off by default). Update text for existing link on the message. In some cases, you might want to provide a website with more information for your end users. The URL appears below the body text.
  • Publisher: Enter a publisher name and information to display if the verification for the publisher fails.
  • Buttons: Customize the labels for the OK and Cancel buttons (Mac sample message shown in image at right).

Additional body message design properties are available when using the User Request Message template. You can customize the text for the interactive prompts displayed during the request workflow, such as request text, pending text, approval text, denial text, and referral text.

Add an image to your message header

To use different images in the header than the default BeyondTrust ones (such as your own company's logo, for branding purposes), you can import images into the Manage Images list.

Image requirements

  • File type must be .png
  • Maximum file size is 240KB
  • Recommended size is 450x50 pixels
  • Images smaller than 450x50 pixels and greater than 600x100 pixels will be rejected.
  1. To the right of the Select Image field, click Manage Images.
  2. Click Import Image.
  3. On the Upload Image panel, drag or click to select an image to upload.
  4. Enter the image name and a description.
  5. Click Upload Image. The image is added to the list and is available for selection as a custom image.

You can delete images you imported. You cannot delete the BeyondTrust images.

Change the name/description of an uploaded message header image

  1. To the right of the Select Image field, click Manage Images.
  2. Select the image, and then select Edit from the menu.
  3. Update the name and/or description for the image, and then click Save Changes.

Delete an image from your message header

❗️

WARNING

Deleting an image is an unrecoverable operation.

  1. To the right of the Select Image field, click Manage Images.
  2. Select an image. You cannot delete an image already in use. Select another image to use before proceeding.
  3. Click Delete.

Edit an image

To edit an image that you uploaded:

  1. To the right of the Select Image field, click Manage Images.
  2. Select the image, and then select Edit from the menu.
  3. Update the name and/or description for the image, and then click Save Changes.

Configure message email settings (Windows only)

Email settings can be configured when using the Block and Request message templates.

To access email settings, you must first create the message, then configure these message properties:

  • Mail To: Email address to send the request to (separate multiple email addresses with semicolons).
  • Subject: Subject line for the email request.

Add user authorization

When using a message to allow access to an application, you can enforce strict access to network resources using the authorization settings. When configured, users are required to enter credentials to proceed. The credential can be a password, smart card, or both.

User authorization settings can be configured on both Windows and macOS messages.

  1. Select the message where you want to add user authorization as part of the access workflow.
  2. Under section 3 on the left, check the Verify the requestor's identity, on behalf of: box.
  3. Choose either The User or Designated User.
  4. Select the authorization method: .Password or Smartcard, Password only, or Smartcard only.
  5. Click User Authorization to expand and customize labels and descriptions. The available fields will change depending on which method of authorization is selected, as noted here:
    • The User: When selected, enter the password. Optionally, customize the message that displays to users when the credentials are not approved.
    • Designated User: When selected, click the Edit Designated Users/Groups button to add the authorized users/groups. A designated user can be selected from a local account, Active Directory domain, or Microsoft Entra ID. Only Microsoft Entra ID groups are supported. See Edit a designated user for more information.
      • After the groups are added, enter the user name, password, and domain.
      • (Optional). Select Run application as Authorizing User. When selected, the application runs in the context of the authenticating user. When not selected, the application runs in the context of the logged on user.
      • (Optional). Customize the message that displays to users when the credentials are not approved.
      • (Optional). Customize the default messaging that displays when the Entra ID login session expires.
    • Windows Hello: Select to use the Windows Hello service to authenticate the user. Windows Hello must be installed on the endpoint for this to work with EPM.
      • Windows Hello is not supported with the Designated User option.
      • Set Authentication to the Password or Smartcard or the Password only option.
      • Windows Hello is unavailable when using Secure Desktop.
    • TouchID: Select to use TouchID to authenticate the user. TouchID must be configured on the endpoint to work with the policy editor messages.
      • TouchID is not supported with the Designated User option.
      • Set Authentication to the Password or Smartcard or the Password only option.
    • Smart Card: When smart card authorization is included, you can:
      • (Optional). Customize the Smart Card Authentication Labels that display to the user. The hint field is only displayed if your smart card authentication environment is configured to use them.
      • (Mac only). Select the Sudo User Authorization option.

ℹ️

Note

You must complete all the fields in the User Authorization section to confirm your changes.

Edit a designated user

You can add, edit, and remove users and groups from the Designated Users/Groups List list in the message configuration. You can manage multiple accounts at once from the Designated Users/Groups List page.

You can add groups via your local Active Directory domain groups and users, or by setting up a connector that populates group information from your local Active Directory domains or your Microsoft Entra ID instance.

ℹ️

Note

For the Edit Designated Users/Groups button to display on the User Authorization page, you must select and configure Verify the requestor's identity, on behalf of when adding user authorization.

  1. Expand User Authorization.

  2. Click Edit Designated User/Groups.

  3. Select one of the following:

    • Add Account: Add an account name and SID details. Click Add Account.
    • Add Account from Search: Select a connector on the Add From AD Connectors page. The default connector is Built-In. Enter search criteria in the Account Name box to find a specific account. Select the account name, and then select Add.

    If searching Microsoft Entra ID, a minimum of two characters is required to initiate the search. Use the search options, Contains or Starts with to narrow the scope of the search results.

  4. Click Save Changes.

Configure multi-factor authentication

Multi-factor authentication (MFA) using an identity provider can be configured for messages in Endpoint Privilege Management. Identity providers supported by Endpoint Privilege Management include those using OpenID Connect (OIDC) and RADIUS protocols, and BeyondTrust should be setup as a Native or Desktop app within your Identity Provider configuration.

The RADIUS protocol is supported on Windows OS only.

Add an identity provider
  1. In the Policy Creator, click Messages.
  2. Click Identity Provider Settings.
  3. On the Identity Provider Settings panel, select an identity provider from the list: OIDC or RADIUS.
  4. Enter the following details for the identity provider:
    • OIDC Settings
      • Authority URI: The address of your identity provider.
      • Client ID: Must match the same value configured for your identity provider's BeyondTrust application.
      • Redirect URI: Must match the same value configured for your identity provider's BeyondTrust application. The format is http://127.0.0.1:**_port\_number, where _port_number is an open port on your network. The port_number is only needed if required by your identity provider.
      • Proxy URI: (Windows only) Add a proxy server if you route your OIDC authentication through a proxy server.
    • RADIUS Settings
      • Authentication Mechanism: The authentication type that is required by your RADIUS server. Supported authentication mechanisms are MS-CHAPV2 or PAP.
      • Host: The hostname of your RADIUS server.
      • Port: The port number for connecting to your RADIUS server.
      • Shared Secret: The secret key required by your RADIUS server.
  5. Click Save RADIUS Settings or Save OIDC Settings depending on the type you selected.

After an identity provider is added you can configure any allow message type to use multifactor authentication.

ℹ️

For more information about adding identity providers, Authentication provider settings.

Set up a multifactor authentication message
  1. In the Policy Creator, click Messages.
  2. Click Create New Message.
  3. Select the template Allow Message (with Authentication), and then click Create New Message.
  4. Select the message in the Messages navigation pane.
  5. Under section 3 on the left, check the Verify their Identity through an Identity Provider box.
  6. Expand Multifactor Authentication.
  7. Select Idp - OIDC or Idp - RADIUS.
  8. ln the Suppress Message when Authenticated for (Mins) box, enter a value (maximum 720) to set the number of minutes that the authentication message is suppressed. The message will not be shown again for the given number of minutes after a successful authentication.
  9. Enter information that displays on the message dialog box such as authentication failure text and authentication success text. Optionally, you can use the default text provided.
  10. Enter the ACR value. The value is optional and required only if your identity provider uses it.
  11. The following fields are specific to configuring Microsoft Entra ID conditional policies. If you are using conditional policies, contact BeyondTrust Technical Support for configuration details.
*   **Additional Scopes (optional)**: Some IdPs can trigger additional authentication policies server-side based on the scopes requested. This field can be used to provide that context to the IdP.
*   **Max age (seconds) (optional)**: The lifetime of the authorization request. The authorization runs out when the maximum age is reached.
  1. Click Save Changes.
  2. In the Policy Creator, click Messages.
  3. Click Create New Message.
  4. Select the template Allow Message (with Authentication), and then click Create New Message.
  5. Select the message in the Messages navigation pane.
  6. Under section 3 on the left, check the Verify their Identity through an Identity Provider box.
  7. Expand Multifactor Authentication.
  8. Select Idp - OIDC or Idp - RADIUS.
  9. ln the Suppress Message when Authenticated for (Mins) box, enter a value (maximum 720) to set the number of minutes that the authentication message is suppressed. The message will not be shown again for the given number of minutes after a successful authentication.
  10. Enter information that displays on the message dialog box such as authentication failure text and authentication success text. Optionally, you can use the default text provided.
  11. Enter the ACR value. The value is optional and required only if your identity provider uses it.
  12. The following fields are specific to configuring Microsoft Entra ID conditional policies. If you are using conditional policies, contact BeyondTrust Technical Support for configuration details.
*   **Additional Scopes (optional)**: Some IdPs can trigger additional authentication policies server-side based on the scopes requested. This field can be used to provide that context to the IdP.
*   **Max age (seconds) (optional)**: The lifetime of the authorization request. The authorization runs out when the maximum age is reached.
  1. Click Save Changes.

Select your message language

⚠️

Important information

  • You can configure message text to display a language of your choice.
  • If you are using more than one language, select a language and click Set As Default. The default language is English.
  • If you delete the default language, then the language at the top of the list is set to the default. You must always have at least one language selected.
  • EPM for Windows and Mac does not localize the text in the language you select. You must edit the message text in your chosen language.
  • If you import a policy with messages in a supported language, then the strings display in that language.
  • EPM for Windows and Mac checks the locale of the user's language and tries to match it to a supported language.
    • If there is a match, the strings for that language are displayed for the message text.
    • If there isn't a match, the language assigned as the default language is used.
  1. Click Add Languages and select the language from the dropdown list.

©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.