Appendix: Require a Ticket ID for Access to Jump Items

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 access 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. For more information on using the BeyondTrust API see the Privileged Remote Access API Programmer's Guide .

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

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 B Series Appliance.

  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 B Series Appliance 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 User Prompt, enter the dialog text you want access console users to see when they are requested to enter the ticket ID required for access.

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

    If this box is checked, the ticket ID is considered sensitive information and asterisks are shown instead of text. You must use an HTTPS Ticket System URL. If an address with HTTP is entered, an error message appears to remind you HTTPS is required.

    When this feature is enabled you cannot bypass issues with SSL certificates by checking the Ignore SSL certificate errors box. This means you must have a valid SSL certificate in place. If you try to check the Ignore SSL certificate errors box, a message appears stating that you cannot ignore SSL certificate errors.

    When the Ticket ID is sensitive, the following rules apply:

    • Both the desktop and the web access consoles show asterisks instead of text.
    • The ticket is not logged anywhere by the access console or on the B Series Appliance.
  3. Click Save.

API Approval Request

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

request_id

Unique ID that identifies the approval request.

The request ID must be sent from the external ticketing system to BeyondTrust PRA 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 reponse.
jump_item.computer_name Hostname or IP address of the endpoint the user is requesting access for.
jump_item.type

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.
jump_item.group Group associated of the Jump Item.
jump_item.tag Tags associated with the Jump Item.
jump_item.jumpoint_name Name of the Jumpoint.
jump_item.public_ip

Public IP address of the Jump Item.

This is not provided for Jumpoints.
jump_item.private_ip

Private IP address of the Jump Item.

This is not provided for Jumpoints.
jump_item.custom.<code>

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

Only one key-value pair is permitted for each Jump Item custom field.
user.id 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 https://example.beyondtrust.com/api/endpoint_approval.

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

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 Treat the Ticket ID as sensitive information 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 access 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 B Series Appliance:

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

Returned when the request_id is not valid

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