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 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 BeyondTrust 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.
- From your BeyondTrust /login administrative interface, go to Jump > Jump Policies.
- In the Jump Policies section, click the Add New Jump Policy button.
A Jump Policy does not take effect until you have applied it to at least one Jump Client item.
- 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.
- Optionally, complete the configuration for Jump Schedule and Jump Notification if appropriate for the access control desired on this Jump Policy.
- 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.
- Optionally, complete any additional approval configuration you wish this Jump Policy to enforce.
- Click Save Jump Policy.
Connect External Ticket ID System to Jump Policies
Next, connect your existing ITSM or ticket ID system to the BeyondTrust Appliance.
- Remain in your BeyondTrust /login administrative interface on the Jump > Jump Policies page.
- At the bottom of the Jump Policies page, locate the Jump Policies :: Ticket System section.
In Ticket System URL, enter the URL for your external ticket system. The BeyondTrust 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.
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.
Click Choose File to upload the certificate for the HTTPS ticket system connection to the appliance. If your certificate is uploaded, the 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 BeyondTrust Appliance optionally falls back to use the built-in certificate store when sending the request.
When the Ignore SSL certificate errors checkbox is checked, the BeyondTrust Appliance will not include the certificate validation information when it contacts your external ticket system.
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.
- 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 appliance.
- 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:
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 aas 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.|
Type of Jump Item being accessed:
|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.|
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.
|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 Reponse
The external ticketing system sends an HTTP POST request to the BeyondTrust 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 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|
In certain circumstances, an error message displays in the Jump Policies :: 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 BeyondTrust Appliance:
|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.