Appendix: Require a Ticket ID Workflow for Jump Item Access

If your service requests use ticket IDs as part of the change management workflow, connect your ticket IDs to endpoint access in BeyondTrust. By leveraging BeyondTrust Jump Technology with your existing ticket ID process, your change management workflow integration lets you restrict a BeyondTrust access request by requiring a Ticket ID to be entered as part of the access request process before an access session begins.

What Users See

When users of the BeyondTrust representative console attempt to access a Jump Item that uses a Jump Policy configured to require a ticket ID, a dialog opens. In the administrator-configured dialog, users enter the ticket ID needed, authorizing access this Jump Item.

To set up the connection to your existing ITSM or ticket ID system, create a Jump Policy you can apply to those Jump Items you want to only be used if a ticket ID from your external system is entered.

How It Works

After the user enters the required ID and clicks OK, the B Series Appliance posts an HTTP outbound request to the ticket system URL configured in Jump Policies. The request contains information about both the ticket ID and the Jump Item, as well as user information. Your external system then replies asynchronously to either allow or deny access.

If the request is allowed, the external ticket ID system assigns the allowed session. Optionally, your external ITSM or ticket ID system may send a list of custom session attributes in its response to assign to the allowed session.

Follow the steps below to set up a ticket ID requirement for access.

For more information on using the BeyondTrust API see the Remote Support API Programmer's Guide.

Create a Jump Policy Requiring Ticket ID Approval

First, create a Jump Policy with the requirement of ticket ID approval enabled.

  1. From your BeyondTrust /login administrative interface, go to Jump > Jump Policies.

Jump Policies

  1. In the Jump Policies section, click the Add button.


A Jump Policy does not take effect until you have applied it to at least one Jump Client item.

Add a New Jump Policy

  1. Enter a Display Name, Code Name, and Description in the corresponding locations to enable you to effectively apply this Jump Policy appropriate to your purposes after its creation.
  2. Optionally, complete the configuration for Jump Schedule and Jump Notification, if appropriate for the access control desired on this Jump Policy.
  3. In the Jump Approval section, check Require a ticket ID before a session starts. To instantly disable ticket ID approval on this policy, simply uncheck this box. If ticket ID approval is enabled on a policy that does not have a ticket system URL configured, users attempting to access a Jump Item to which the policy is applied receive a message to contact the administrator.
  4. Optionally, complete any additional approval configuration you wish this Jump Policy to enforce.
  5. Click Save.


Connect External Ticket ID System to Jump Policies

Next, connect your existing ITSM or ticket ID system to the BeyondTrust Appliance B Series.

  1. Remain in your BeyondTrust /login administrative interface on the Jump > Jump Policies page.

The /login section Ticket System where you can configure ticket IDs for Jump Items and Sessions.

  1. At the bottom of the Jump Policies page, locate the Ticket System section.
  2. In Ticket System URL, enter the URL for your external ticket system. The BeyondTrust Appliance B Series sends an outbound request to your external ticketing system. The URL must be formatted for either HTTP or HTTPS. If an HTTPS URL is entered, the site certificate must be verified for a valid connection. If a Jump Policy requiring a ticket ID exists, a ticket system URL must be entered or you will receive a warning message.

  3. The Current Status field is shown only when a valid status value exists to report the connection to the ticket system configured in Ticket System URL. Any ticket system configuration change resets the value.

  4. Click Choose a certificate to upload the certificate for the HTTPS ticket system connection to the B Series Appliance. If your certificate is uploaded, the B Series Appliance uses it when it contacts the external system. If you do not upload a certificate and the Ignore SSL certificate errors box below this setting is checked, the B Series Appliance optionally falls back to use the built-in certificate store when sending the request.


When the Ignore SSL certificate errors box is checked, the B Series Appliance will not include the certificate validation information when it contacts your external ticket system.

  1. In the User Prompt field, enter the dialog text you want representative console users to see when they are requested to enter the ticket ID required for access.

  2. In the User Prompt field, enter the dialog text you want representative console users to see when they are requested to enter the ticket ID required for access.

  3. If your company's security policies consider ticket ID information as sensitive material, check the Treat the Ticket ID as sensitive information box.
  4. Click Save.

API Approval Request

BeyondTrustRS sends an HTTP Post request to the ticketing system URL. The POST request contains the following key-value pairs:


Unique ID that identifies the approval request.

The request ID must be sent from the external ticketing system to BeyondTrust RS in the response. The maximum length is 255 characters, and the ticketing system must treat the request ID as an opaque value.

ticket_id ticket ID entered by the user.
response_url URL to which the integration should POST its response.
jump_item.computer_name Hostname or IP address of the endpoint the user is requesting access for.

Type of Jump Item being accessed:

  • client (for Jump Clients)
  • shell (for Shell Jump Shortcuts)
  • RDP
  • VNC
  • push_and_start (for Remote Jump and Local Jump)
  • vPro
jump_item.comments Comments noted about the Jump Item. Group associated with the Jump Item.
jump_item.tag Tags associated with the Jump Item.
jump_item.jumpoint_name Name of the Jumpoint.

Public IP address of the Jump Item.

This is not provided for Jumpoints.


Private IP address of the Jump Item.

This is not provided for Jumpoints.


Key-value pair designated for the Jump Item custom field.

Only one key-value pair is permitted for each Jump Item custom field. The requesting user's unique ID.
user.username Username used by the requesting user for authentication.
user.public_display_name The requesting user's public display name.
user.private_display_name The requesting user's private display name.
user.email_address Email address listed for the requesting user.

API Approval Response

The external ticketing system sends an HTTP POST request to the B Series Appliance URL at

The API must be accessed over HTTPS.

The POST request can contain the following key-value pairs in the POST body:

response_id Request ID sent in the approval request (required).
response Response to the request; either allow or deny (required).

Message displayed to the requesting user if the request is denied (optional).

The maximum length set for the message is 255 characters.

session.custom.<code name> One or more custom session attributes set for the access session (optional).

Error Messages

In certain circumstances, an error message displays in the Ticket System section:

  • Ticket System URL is required because one or more Jump Policies still require a ticket ID: A Jump Policy exists requiring the entry of a ticket ID for access.
  • Invalid ticket ID: The external ticket system explicitly denied the request. If the external ticket system sends the error message, that message is shown.
  • The Ticket System URL must start with "https://" when the Ticket ID is sensitive: You must enter an HTTPS URL when the Treat the Ticket ID as sensitive information option is checked.
  • Cannot ignore SSL errors when the Ticket ID is sensitive: When this option is checked, you cannot ignore SSL errors and must provide a valid SSL certificate.
  • The given host was not resolved: An invalid ticket system URL was attempted.
  • The ticket system failed to respond in time: The external ticket system failed to respond in a timely manner.

Users who are unable to connect due to misconfiguration or user error will see explanatory pop-up messages in the representative console for the error state of the configuration.

  • No ticket system URL is configured. Please contact your administrator: A ticket ID system URL is not configured in the /login administrative interface.
  • User Prompt Not Configured: The User Prompt is not configured in the /login administrative interface.
  • The ticket system returned an invalid response: An invalid ticket ID was entered.

The following errors can be returned by the BeyondTrust Appliance B Series:

404 Returned when no ticketing system URL is configured in /login.

Returned when the request_id is not valid.

This error message is received when the request has timed out.