If your organization requires representatives to provide a reason before accessing an endpoint, use the justification feature in BeyondTrust. By configuring an Asset Policy to require a user justification, you can ensure that any representative attempting to start a session on an Asset must enter a written reason before the session begins. The justification is logged for auditing and appears in both session and access reports.
What users see
When users attempt to access an Asset that uses an Asset Policy configured to require a justification, a dialog displays. Users enter their reason for accessing the Asset in the text field provided. The session proceeds only after the user submits a valid justification.
To set up the justification requirement, create an Asset Policy that you can apply to the Assets you want to restrict until a written justification is entered.
How it works
After the user enters the required justification and clicks OK, the B Series Appliance validates the text (between 1 and 256 characters) and logs it in plain text to the session record. The session then proceeds normally.
If the user clicks Cancel or closes the dialog without submitting a justification, the session does not start and the user receives an explanatory message.
The justification text is attached to the session record and is visible in the session report details view for audit and compliance purposes.
Create an Asset Policy requiring justification
First, create an Asset Policy with the justification requirement enabled.
- From your BeyondTrust /login administrative interface, go to Asset Management > Asset Policies.
- In the Asset Policies section, click the Add button.
An Asset Policy does not take effect until you have applied it to at least one Asset.
- Enter a Display Name, Code Name, and Description in the corresponding locations to enable you to effectively apply this Asset Policy appropriate to your purposes after its creation.
- Optionally, complete the configuration for Schedule and Notification if appropriate for the access control desired on this Asset Policy.
- In the Context Requirement section, select Require a user justification before a session starts. To instantly disable the justification requirement on this policy, select No context required.
- Optionally, complete any additional approval configuration you wish this Asset Policy to enforce.
- Click Save.
What representatives enter
When a representative starts a session on an Asset linked to a policy that requires justification, a dialog appears in the access console.
| Aspect | Detail |
|---|---|
| Input type | Multi-line text area |
| Minimum length | 1 character |
| Maximum length | 256 characters |
| Character set | Any UTF-8 text, including Unicode and special characters |
| Sensitivity | Always plain text, never masked |
| OK button | Enabled only when the input is between 1 and 256 characters |
| Cancel button | Cancels the session start; the session does not proceed |
Justification in reports
The justification text entered by the representative appears in the session details properties table in the Session and Access Reportss.
| Property | Value |
|---|---|
| Justification | Text entered by the representative at session start |
The Justification field is populated only when the Asset Policy's Context Requirement is set to Require a user justification before a session starts. If the policy uses No context required or Require a ticket ID before a session starts, the Justification field is empty and not displayed.
The justification text is logged in plain text and is never obfuscated.
Asset Policy API
Endpoint: GET/POST/PATCH /api/v1/config/jump-policy[/:id]
Use the context_requirement field to configure the justification requirement on an Asset Policy via the API.
| Field | Type | Default | Description |
|---|---|---|---|
| context_requirement | enum (none | ticket_id | justification) | none | Pre-session context requirement for sessions on Assets linked to this policy. |
| ticket_system_user_prompt | string | "" | Prompt text shown with the ticket ID dialog. Only applicable when context_requirement is ticket_id. |
Example PATCH request:
{
"context_requirement": "justification"
}Deprecated fields
The following fields are deprecated and replaced by context_requirement:
| Deprecated field | Replacement | Migration |
|---|---|---|
| ticket_system (boolean) | context_requirement | true → ticket_id, false → none on upgrade |
The ticket_system field is accepted on ingress for one release (mapped to the new enum) and omitted from read responses.
Session Report API
The session report API returns a justification field on session records.
| Field | Type | Description |
|---|---|---|
| justification | string | null | Justification text entered by the representative, or null if context_requirement was not justification. |
Error messages
The following messages may appear when a representative attempts to start a session on an Asset that requires justification:
- A justification is required to start this session.: The representative clicked Cancel or closed the dialog without submitting a justification.
- This field must contain at least 1 character.: The representative submitted an empty justification field.
- This field may not exceed 256 characters.: The justification text entered exceeds the 256-character limit.
