EPM - ServiceNow integration | EPM-WM

🚧

Important information

You must purchase this integration separately for both your EPM-WM software and your ServiceNow solution. For more information, contact BeyondTrust's Sales team.

The BeyondTrust Endpoint Privilege Management for Cloud (EPM) - ServiceNow integration allows organizations to streamline their Just-In-Time (JIT) access approval workflow. This integration automatically creates ServiceNow tickets when EPM JIT access requests are submitted and enables approvers to make decisions directly from within ServiceNow.

ℹ️

This new version of EPM - ServiceNow integration supports Admin Access requests and introduces a redesigned ServiceNow app architecture that makes it easier for you to customize the experience to fit your workflows.

You can continue using the existing integration but we do provide migration steps in this topic.

Key features

• Automated ticket creation: Automatically creates ServiceNow tickets when JIT Application Access or Admin Access requests are submitted in EPM

• Dual request type support: Manages both Application Access requests and Admin Access (privilege elevation) requests

• Flexible ticket type support: Works out of the box with Incident, Change Request, Service Catalog Task, and Service Catalog Requested Item ticket types. Can be customized to support any Task-based ticket type.

• Customizable workflow: Built using ServiceNow Flow Designer, allowing administrators to customize the integration workflow to match organizational requirements and processes

• Integrated approval workflow: Approve or deny requests directly from ServiceNow tickets with custom UI actions

• Real-time synchronization: Status updates are synchronized between EPM and ServiceNow

• Comprehensive request details: All relevant request information is captured in the ServiceNow ticket

• Configurable duration control: Set time-limited access approvals with granular duration options

• Automatic ticket closure: Optionally configure the integration to automatically close tickets after a decision has been submitted and processed

Architecture

The integration is implemented as a ServiceNow scoped application that:

• Receives webhook messages from EPM when JIT Application Access or Admin Access tickets are created or updated
• Creates corresponding ServiceNow tickets with all relevant request information in your chosen ticket type
• Provides custom UI actions and forms within ServiceNow for approving/denying requests
• Communicates decisions back to EPM via the management API
• Processes status updates from EPM when decisions are finalized

Prerequisites

Before installing and configuring the integration, ensure you have:

• BeyondTrust EPM: A currently supported version of BeyondTrust Endpoint Privilege Management

• ServiceNow: The application is certified for compatibility with supported ServiceNow versions (check the ServiceNow Store listing for specific version compatibility)

• ServiceNow Administrator access with rights to:

  • Install applications from the ServiceNow Store
  • Create user accounts and assign roles
  • Configure application settings
  • Create and manage tickets in your chosen ticket type

• EPM Administrator access to:

  • Configure API Settings
  • Configure JIT Access Settings
  • Configure Webhook Settings

Legacy app: compatibility and migration

If you are currently using the legacy BeyondTrust Endpoint Privilege Management Integration application for ServiceNow, this section provides important information about migrating to the new application.

Side-by-side compatibility

The new application (BeyondTrust Privilege Management) and the legacy application can coexist in the same ServiceNow instance:

• No Uninstallation Required: You do not need to uninstall the legacy application before installing the new application

• Independent Operation: Both applications operate independently and do not interfere with each other

• Separate Scopes: The applications use different scoped namespaces:

  • Legacy application: x_bmgr_pmc
  • New application: x_bets_pmc_jit

Data retention

If you have historical JIT access request data from the legacy application:

• Keep Legacy App Installed: The legacy application stores request data in custom tables. To maintain access to this historical data, leave the legacy application installed in your ServiceNow instance.

• Data Migration Not Required: Historical data does not need to be migrated to the new application. The new application will create its own records going forward.

• Reporting Considerations: If you have reports or dashboards based on legacy application tables, they will continue to function as long as the legacy application remains installed.

Migration

The migration from the legacy application to the new application is straightforward:

Step 1: Install new application

1. Install the new BeyondTrust Privilege Management application from the ServiceNow Store (see Installation Steps)

2. Complete the configuration steps in the new application (see Configuration)

3. Test the new application to ensure it is functioning correctly

Step 2: Update EPM configuration

The "cut-over" from the legacy application to the new application is a simple configuration change in EPM:

1. Navigate to: EPM → Configuration → Just-in-Time (JIT) Access Settings

2. Under Application Access:

   • In the Choose an Integration dropdown, change from ServiceNow to EPM
   • Click Save Changes

3. If using Admin Access, under Admin Access:

   • Enable JIT Admin Access Integration (if not already enabled)
   • Click Save Changes

4. Configure webhooks in EPM as described in the Configure Webhook Settings section

That's it! New JIT access requests will now be sent to the new application via webhooks instead of the legacy application.

Step 3: (Optional) Monitor both applications

During the migration period:

• New Requests: All new JIT access requests will be created in the new application

• Pending Legacy Requests: Any requests that were pending in the legacy application before the cut-over can still be managed through the legacy application

• Seamless Continuity: Users can continue to approve or deny legacy requests without interruption, ensuring no requests are lost during the migration

Managing legacy requests after migration

Even after switching to the new application in EPM, you can still manage pending requests from the legacy application:

• Access legacy tickets: Navigate to the ticket type used by the legacy application (Incident, Change Request, etc.) and open any pending JIT access requests

• Approval actions available: The legacy application's approval UI actions will continue to function as long as the application is installed

• Decision submission: Approved or denied decisions will be sent to EPM and processed normally

• Historical Reference: Completed legacy requests remain accessible for audit, compliance, and reporting purposes

Post-Migration considerations

After successfully migrating to the new application:

When to uninstall legacy application

You may consider uninstalling the legacy application when:

• All pending legacy requests have been completed (approved, denied, or closed)
• You no longer need access to historical legacy request data
• You have exported or archived any legacy data needed for compliance or reporting

🚧

Important information

Once the legacy application is uninstalled, you can no longer access the historical JIT request data it created.

Best practices

• Test thoroughly: Test the new application in a development or test environment before migrating in production

• Communication: Inform help desk staff and approvers about the migration timeline and any workflow changes

• Monitoring: Monitor both applications during the transition period to ensure smooth operation

• Documentation: Update internal documentation and procedures to reflect the new application

• Training: Provide training to staff on any differences between the legacy and new applications (e.g., new UI, additional features like Admin Access support)

Key differences between legacy and new application

Understanding the differences can help with planning and training:

Migration support

If you need assistance with the migration:

• Review this guide thoroughly before beginning
• Test in a non-production environment first
• Contact BeyondTrust Support if you encounter issues:
  • Email: [email protected]
  • Hours: US Central Time, Monday-Friday, 2:00 AM - 7:00 PM (excluding US holidays)

Installation steps

Step 1: Install the ServiceNow application

1. Navigate to the ServiceNow Store

2. Search for "BeyondTrust Privilege Management"

3. Click Get or Install and follow the prompts to install the application into your ServiceNow instance

4. Wait for the installation to complete

5. Verify the application appears in your ServiceNow navigator under BeyondTrust Privilege Management

Step 2: Create webhook user account

A dedicated user account is required for EPM webhooks to authenticate to ServiceNow.

1. Navigate to User Administration → Users

2. Click New to create a new user

3. Configure the user with the following settings:

   • User ID: pmc_webhook_user (or your preferred username)
   • First name: PMC
   • Last name: Webhook User
   • Email: (optional)
   • Identity Type: Machine (Yokohama patch 6 or later)
   • Web service access only: ✅ Check this box (Yokohama patch 5 or earlier ... see KB2420837 for more information)
   • Active: ✅ Ensure this is checked

4. Click Submit to save the user

5. Reopen the user record and click Set Password

6. Generate or enter a strong password and record it securely for use in EPM webhook configuration

7. Click the Roles tab, then click Edit

8. Add the role x_bets_pmc_jit.api to the user

9. Click Save

ℹ️

This role grants the necessary permissions to create and update tickets via the webhook API endpoint.

Configuration

Configure EPM

1. Configure API Settings

The API account is used by ServiceNow to communicate decisions back to EPM.

1. Navigate to: EPM → Configuration → API Settings

2. Click Create API Account

3. Configure the API account with the following settings:

   • Name: ServiceNow Integration
   • Permissions:
     • JIT: Full Access

4. Click Save

5. Important: Copy and securely store the Client ID and Client Secret values. You will need these when configuring the ServiceNow application.

⚠️

Security note

The Client Secret is only displayed once. Ensure you save it securely before leaving this page.

2. Configure JIT Access Settings

Enable the JIT access integrations that you want to use with ServiceNow.

1. Navigate to: EPM → Configuration → Just-in-Time (JIT) Access Settings

2. Under Application Access, configure the following:

   • ✅ Enable JIT Application Access Integration
   • Choose an Integration: Select EPM
   • Click Save Changes

3. Under Admin Access, configure the following:

   • ✅ Enable JIT Admin Access Integration
   • Click Save Changes

Note: You can enable one or both integration types depending on your requirements. If you only enable one type, you will only need to create two webhooks (create and update) instead of four.

3. Configure webhook settings

You will create webhooks for each event type you want to integrate with ServiceNow.

Webhook URL

The webhook URL for all webhooks will follow this pattern:

https://YOUR-INSTANCE.service-now.com/api/x_bets_pmc_jit/authorization_request_webhook_handler

Replace YOUR-INSTANCE with your actual ServiceNow instance subdomain.

Example: https://acme.service-now.com/api/x_bets_pmc_jit/authorization_request_webhook_handler

Create webhooks

1. Navigate to: EPM → Configuration → Webhook Settings

2. Click Create Webhook

Webhook 1: JIT Admin Ticket Created

Configure the first webhook with the following settings:

• Name: ServiceNow - Admin Access - Create
• URL: https://YOUR-INSTANCE.service-now.com/api/x_bets_pmc_jit/authorization_request_webhook_handler
• Event: JIT Admin Ticket Created
• Content Type: application/json
• Template: Use the template below
• Authentication Type: Basic
• Authentication Username: pmc_webhook_user (or the username you created)
• Authentication Password: The password you set for the webhook user
• Enable Webhook: ✅ Check to enable

Template for JIT Admin Ticket Created:

{
  "EventType": "JIT_ADMIN_TICKET_CREATED",
  "RequestId": "%%RequestId%%",
  "TenantId": "%%TenantId%%",
  "Timestamp": "%%Timestamp%%",
  "ComputerId": "%%ComputerId%%",
  "GroupId": "%%GroupId%%",
  "TicketNumber": "%%TicketNumber%%",
  "Reason": "%%Reason%%",
  "UserId": "%%UserId%%",
  "UserName": "%%UserName%%",
  "DurationRequested": "%%DurationRequested%%"
}

Click Save.

Webhook 2: JIT Admin Decision Updated

Create a second webhook with the following settings:

• Name: ServiceNow - Admin Access - Update
• URL: https://YOUR-INSTANCE.service-now.com/api/x_bets_pmc_jit/authorization_request_webhook_handler
• Event: JIT Admin Decision Updated
• Content Type: application/json
• Template: Use the template below
• Authentication Type: Basic
• Authentication Username: pmc_webhook_user
• Authentication Password: The password you set for the webhook user
• Enable Webhook: ✅ Check to enable

Template for JIT Admin Decision Updated:

{
  "EventType": "JIT_ADMIN_TICKET_UPDATED",
  "RequestId": "%%RequestId%%",
  "TicketNumber": "%%TicketNumber%%",
  "TenantId": "%%TenantId%%",
  "StartTime": "%%StartTime%%",
  "EndTime": "%%EndTime%%",
  "Decision": "%%Decision%%",
  "DecisionTime": "%%DecisionTime%%",
  "DecisionPerformedByUser": "%%DecisionPerformedByUser%%",
  "Duration": "%%Duration%%",
  "DurationRequested": "%%DurationRequested%%",
  "Timestamp": "%%Timestamp%%"
}

Click Save.

Webhook 3: JIT Application Access Ticket Created

Create a third webhook with the following settings:

• Name: ServiceNow - App Access - Create
• URL: https://YOUR-INSTANCE.service-now.com/api/x_bets_pmc_jit/authorization_request_webhook_handler
• Event: JIT Application Access Ticket Created
• Content Type: application/json
• Template: Use the template below
• Authentication Type: Basic
• Authentication Username: pmc_webhook_user
• Authentication Password: The password you set for the webhook user
• Enable Webhook: ✅ Check to enable

Template for JIT Application Access Ticket Created:

{
  "EventType": "URM_Native_Ticket_Created",
  "RequestId": "%%RequestId%%",
  "TenantId": "%%TenantId%%",
  "Timestamp": "%%Timestamp%%",
  "TicketNumber": "%%TicketNumber%%",
  "requestInfo": {
    "applicationType": "%%ApplicationType%%",
    "action": "%%Action%%",
    "workstyle": "%%Workstyle%%",
    "reason": "%%Reason%%",
    "user": "%%User%%",
    "hostName": "%%HostName%%",
    "trustedOwnership": "%%trustedOwnership%%",
    "productDescription": "%%ProductDescription%%",
    "driveType": "%%DriveType%%",
    "btZoneIdentifierExists": "%%BtZoneIdentifierExists%%",
    "productCode": "%%ProductCode%%",
    "upgradeCode": "%%UpgradeCode%%",
    "clsId": "%%ClsId%%",
    "comDisplayName": "%%ComDisplayName%%",
    "token": "%%Token%%",
    "tokenAssignmentIsShell": "%%TokenAssignmentIsShell%%",
    "uacTriggered": "%%UacTriggered%%",
    "downloadSourceUrl": "%%DownloadSourceUrl%%",
    "userLanguage": "%%UserLanguage%%",
    "sha1Hash": "%%Sha1Hash%%",
    "sha256Hash": "%%Sha256Hash%%",
    "filePathObjectId": "%%FilePathObjectId%%",
    "cmdArgs": "%%CmdArgs%%",
    "publisher": "%%Publisher%%",
    "productName": "%%ProductName%%",
    "productVersion": "%%ProductVersion%%",
    "fileVersion": "%%FileVersion%%",
    "workstyle": "%%Workstyle%%",
    "applicationGroup": "%%ApplicationGroup%%",
    "message": "%%Message%%",
    "messageId": "%%MessageId%%",
    "hostType": "%%HostType%%",
    "osName": "%%OsName%%",
    "osVersion": "%%OsVersion%%",
    "ComputerGroup": "%%ComputerGroup%%",
    "GroupId": "%%GroupId%%",
    "requestVersion": "%%RequestVersion%%",
    "hostedFilePath": "%%HostedFilePath%%",
    "parentProcess": "%%ParentProcess%%",
    "storeAppName": "%%StoreAppName%%",
    "serviceName": "%%ServiceName%%",
    "serviceAction": "%%ServiceAction%%",
    "authRequestUri": "%%AuthRequestUri%%",
    "bundleInfoDescription": "%%BundleInfoDescription%%",
    "reputationScoreDateTime": "%%ReputationScoreDateTime%%",
    "reputationScore": "%%ReputationScore%%",
    "reputationIntegrationType": "%%ReputationIntegrationType%%"
  }
}

Click Save.

Webhook 4: JIT Application Access Decision Updated

Create a fourth webhook with the following settings:

• Name: ServiceNow - App Access - Update
• URL: https://YOUR-INSTANCE.service-now.com/api/x_bets_pmc_jit/authorization_request_webhook_handler
• Event: JIT Application Access Decision Updated
• Content Type: application/json
• Template: Use the template below
• Authentication Type: Basic
• Authentication Username: pmc_webhook_user
• Authentication Password: The password you set for the webhook user
• Enable Webhook: ✅ Check to enable

Template for JIT Application Access Decision Updated:

{
  "EventType": "URM_NATIVE_DECISION_UPDATE",
  "RequestId": "%%RequestId%%",
  "TenantId": "%%TenantId%%",
  "TicketNumber": "%%TicketNumber%%",
  "Timestamp": "%%Timestamp%%",
  "requestInfo": {
    "Decision": "%%Decision%%",
    "DecisionTime": "%%DecisionTime%%",
    "DecisionPerformedByUser": "%%DecisionPerformedByUser%%",
    "Duration": "%%Duration%%"
  }
}

Click Save.

Configure ServiceNow application

Configure the application settings

1. Navigate to BeyondTrust Privilege Management → Configuration

2. If you see multiple configuration records, select the one named Default

PM Cloud Instance Settings

Configure the connection to your EPM instance:

🚧

Important information

The PMC Service Host Name must include the -services suffix after your subdomain. For example, if your EPM URL is https://acme.beyondtrustcloud.com, your service hostname should be acme-services.beyondtrustcloud.com (without https://).

Ticket configuration settings

Configure how ServiceNow tickets are created and managed:

🚧

Important information

• Active States: Only tickets in these states will display the JIT access management UI actions. Ensure you include all states where you want users to be able to approve or deny requests.

• Ticket Type: Once you begin using the integration, changing the ticket type may require additional configuration and can affect existing workflows.

3. Click Update to save the configuration

Test the connection

Verify that ServiceNow can communicate with EPM:

1. Navigate to BeyondTrust Privilege Management → Test Connection

2. Click Test

3. You should see a success message: "Connection OK"

4. If you see an error:

   • Verify the PMC Service Host Name is correct (including the -services suffix)
   • Verify the Client ID and Client Secret are correct
   • Check System Logs → Application Logs for detailed error messages
   • Ensure your ServiceNow instance can reach the EPM services endpoint (check firewall/network rules)

Assign user roles

The application includes roles that should be assigned to appropriate users in your ServiceNow instance.

Available roles

Assign roles to users

1. Navigate to User Administration → Users

2. Select a user

3. Click the Roles tab

4. Click Edit

5. Add the appropriate role(s) from the Collection list:

   • x_bets_pmc_jit.admin for administrators
   • x_bets_pmc_jit.user for help desk staff

6. Click Save

⚠️

Security note

Do not assign the x_bets_pmc_jit.api role to regular users. Only assign the role to the dedicated webhook service account.

User interface

ServiceNow ticket form

Once configured, when EPM sends a webhook for a new JIT access request, a ServiceNow ticket is automatically created in your configured ticket type.

Application Access request tickets

Application Access requests include detailed information about the application the user is trying to run:

Request information section:

• User requesting access
• Host name
• Application/file path
• Product name and version
• Publisher
• File hashes (SHA1, SHA256)
• Reason for access
• Command line arguments
• Workstyle and application group
• Additional technical details

Admin Access request tickets

Admin Access requests include information about the privilege elevation request:

Request information section:

• User requesting access (Username and User ID)
• Computer ID
• Group ID
• Duration requested
• Reason for access
• Request timestamp
• Ticket number from EPM

Approval UI actions

Users with the appropriate role will see UI actions on the ticket to manage the JIT access request.

Approve Application Access button

Clicking this button opens a dialog box to approve the application access request:

Decision form fields:

• Decision: Select "Approved"
• Reason: Enter a justification for the approval (required)
• Duration: Choose the access duration:
  • Once: Single-use access (user can run the application one time)
  • Minutes: Specify duration in minutes (5-1440 minutes, or up to 24 hours)
  • Hours: Specify duration in hours (1-24 hours)

Deny Application Access button

Clicking this button opens a dialog box to deny the application access request:

Decision form fields:

• Decision: Select "Denied"
• Reason: Enter a justification for the denial (required)

Approve Admin Access button

Clicking this button opens a dialog to approve the admin access request:

Decision form fields:

• Decision: Select "Approved"
• Reason: Enter a justification for the approval (required)
• Duration: Choose the privilege elevation duration:
  • Once: Single elevation (user can elevate once)
  • Minutes: Specify duration in minutes (5-1440 minutes)
  • Hours: Specify duration in hours (1-24 hours)

Deny Admin Access button

Clicking this button opens a dialog to deny the admin access request:

Decision form fields:

• Decision: Select "Denied"
• Reason: Enter a justification for the denial (required)

Decision validation

The application includes client-side and server-side validation:

• Reason Required: A reason must be provided for all decisions
• Duration Validation: Duration values must be within valid ranges
• State Validation: Decisions can only be made on tickets in configured active states
• One-Time Decision: Once a decision has been submitted and acknowledged by EPM, it cannot be changed

Workflow

1. Create a request

Application access workflow

1. User on a managed endpoint attempts to run an application that requires elevated privileges or matches a JIT policy

2. EPM generates a JIT Application Access request

3. EPM sends a webhook to ServiceNow with event type URM_Native_Ticket_Created

4. ServiceNow receives the webhook and creates an incoming request record

5. ServiceNow Flow processes the request and creates a ticket in the configured ticket type

6. The ticket is assigned based on the configured assignment group (if specified)

7. Approver is notified via standard ServiceNow notifications

Admin Access workflow

1. User on a managed endpoint requests administrative privilege elevation

2. EPM generates a JIT Admin Access request

3. EPM sends a webhook to ServiceNow with event type JIT_ADMIN_TICKET_CREATED

4. ServiceNow receives the webhook and creates an incoming request record

5. ServiceNow Flow processes the request and creates a ticket in the configured ticket type

6. The ticket is assigned based on the configured assignment group (if specified)

7. Approver is notified via standard ServiceNow notifications

2. Approval process

1. Approver opens the ServiceNow ticket

2. Reviews the request details in the ticket form

3. Clicks the appropriate UI action button:

   • Approve Application Access or Approve Admin Access to grant access
   • Deny Application Access or Deny Admin Access to reject access

4. Fills out the decision form:

   • Selects decision (Approved/Denied)
   • Enters a reason (required)
   • If approved, specifies duration or selects "Once" for single-use access

5. Submits the decision

6. ServiceNow validates the decision and makes an API call to EPM

7. EPM processes the decision

8. The ticket form updates to show the decision has been submitted

3. Status updates

1. EPM finalizes the decision and applies it to the policy

2. EPM sends a webhook to ServiceNow with the update event:

   • URM_NATIVE_DECISION_UPDATE for Application Access
   • JIT_ADMIN_TICKET_UPDATED for Admin Access

3. ServiceNow receives the update and records the decision timestamp

4. The ticket form displays the finalized decision information

5. If auto-close is enabled, ServiceNow closes the ticket

6. User receives access (if approved) based on the configured duration

4. Duration-based access

For approved requests with time-limited access:

• Once: User can run the application or elevate privileges one time. The authorization expires after the first use.

• Minutes/Hours: User has access for the specified duration. The authorization automatically expires when the time limit is reached.

After the duration expires:

• The user must submit a new request to regain access
• A new ticket will be created in ServiceNow
• The approval process starts over

Troubleshooting

Common issues

Missing configuration record

Symptoms:

• Error message "Record not found" when navigating to BeyondTrust Privilege Management → Configuration
• Unable to configure the application settings
• Integration appears installed but cannot be configured

Cause:

The default configuration record was not created automatically during installation, or it was accidentally deleted.

Solution:

1. Navigate to BeyondTrust Privilege Management → Create Default Configuration

2. Click Run Fix Script to generate the default configuration record

3. Wait for the confirmation message indicating the configuration was created successfully

4. Navigate back to BeyondTrust Privilege Management → Configuration

5. Verify you can now access the configuration record named Default

ℹ️

The Fix Script that creates the default configuration record normally runs automatically when the application is installed. This manual step is only necessary if the automatic creation failed or if the configuration record was deleted.

Webhooks not received

Symptoms:

• EPM sends webhooks but tickets are not created in ServiceNow
• No incoming request records in ServiceNow

Possible causes and solutions:

1. Webhook URL incorrect

   • Verify the URL matches the pattern: https://YOUR-INSTANCE.service-now.com/api/x_bets_pmc_jit/authorization_request_webhook_handler
   • Check for typos in the instance name
   • Ensure there are no extra spaces or characters

2. Authentication failure

   • Verify the webhook user credentials are correct
   • Confirm the user has the x_bets_pmc_jit.api role
   • Check that the user is active and not locked

3. Network connectivity

   • Verify ServiceNow instance is accessible from EPM
   • Check firewall rules allow inbound HTTPS traffic from EPM services
   • Test connectivity from EPM to ServiceNow URL

4. Content-Type mismatch

   • Ensure webhook Content-Type is set to application/json

Troubleshooting steps:

1. Check EPM webhook delivery logs for errors

2. Navigate to BeyondTrust Privilege Management → Incoming Requests to see if webhooks are being received

3. Check System Logs → Application Logs filtered by source x_bets_pmc_jit for error messages

4. Use ServiceNow's REST API Explorer to test the webhook endpoint manually

Tickets not created

Symptoms:

• Incoming requests appear in ServiceNow but tickets are not created
• Webhooks are received but no tickets in configured ticket type

Possible causes and solutions:

1. Flow execution errors

   • Navigate to Process Automation → Flow Designer → Executions
   • Filter by flow name containing "BeyondTrust" or "PMC"
   • Check for failed executions and review error messages

2. Missing permissions

   • Verify the webhook user has permission to create the configured ticket type
   • Check ACLs for the ticket table

3. Invalid configuration

   • Review configuration at BeyondTrust Privilege Management → Configuration
   • Ensure ticket type is set correctly
   • Verify required fields are populated

Troubleshooting steps:

1. Review Flow execution history for errors

2. Check Application Logs for script errors

3. Verify webhook user permissions on ticket tables

4. Test manual ticket creation with the webhook user account

Approval decisions not working

Symptoms:

• Clicking approve/deny buttons shows errors
• Decisions are made but not sent to EPM
• EPM does not receive decision updates

Possible causes and solutions:

1. EPM API credentials incorrect

   • Verify Client ID and Client Secret in configuration
   • Test connection using BeyondTrust Privilege Management → Test Connection
   • Confirm API account has JIT Full Access permissions

2. EPM service hostname incorrect

   • Verify hostname includes -services suffix
   • Example: acme-services.beyondtrustcloud.com (not acme.beyondtrustcloud.com)

3. Network connectivity to EPM

   • Verify ServiceNow can reach EPM services endpoint
   • Check firewall rules allow outbound HTTPS traffic to EPM

4. Ticket state not in active states list

   • Verify ticket is in one of the configured active states
   • Update active states configuration if needed

Troubleshooting steps:

1. Test connection to EPM from ServiceNow

2. Check Application Logs for API call errors

3. Review EPM audit logs to see if decision API calls are received

4. Verify ticket state matches configuration

Decision validation errors

Symptoms:

• Form validation prevents submitting decision
• Error messages on decision form fields

Common validation errors:

1. "Please enter a reason"

   • Solution: Enter text in the Reason field

2. "Enter a number between 5 and 1440" (Minutes)

   • Solution: Ensure duration value is within range for minutes

3. "Enter a number between 1 and 24" (Hours)

   • Solution: Ensure duration value is within range for hours

4. "You cannot modify the decision because this request is inactive"

   • Solution: Ticket is not in an active state. Move ticket to an active state or update configuration to include current state

5. "The server has accepted the decision. It is now final and cannot be changed"

   • Solution: Decision has already been finalized by EPM. No further action can be taken.

Logging and diagnostics

ServiceNow logs

Application logs:

1. Navigate to System Logs → Application Logs

2. Filter by:

   • Source: x_bets_pmc_jit
   • Level: All (or Error for errors only)

3. Review log entries for errors or warnings

Flow execution logs:

1. Navigate to Process Automation → Flow Designer → Executions

2. Search for flows related to BeyondTrust

3. Review execution details for errors

REST API logs:

1. Navigate to System Web Services → Outbound → REST Message

2. Filter by messages related to PMC/EPM

3. Review request/response details

EPM logs

Webhook delivery logs:

1. Navigate to Configuration → Webhook Settings in EPM

2. Click on a webhook to view delivery history

3. Review status codes and error messages

Audit logs:

1. Navigate to Reporting → Audit in EPM

2. Filter by JIT-related events

3. Review decision updates from ServiceNow

Debug mode

To enable detailed logging:

1. Navigate to System Properties → All

2. Search for properties starting with x_bets_pmc_jit

3. Set any debug-related properties to true

4. Reproduce the issue and review logs

Testing the integration

End-to-end test: Application Access

1. Configure an EPM policy to require JIT approval for a test application

2. From a managed endpoint, attempt to run the test application

3. Verify:

   • User sees "Pending" message from EPM
   • Webhook is received in ServiceNow (check Incoming Requests)
   • Ticket is created in configured ticket type
   • Ticket contains application details from request
   • Ticket state is in active states list

4. Open the ticket in ServiceNow

5. Click Approve Application Access

6. Enter reason and duration

7. Submit decision

8. Verify:

   • Decision is recorded on ticket
   • EPM receives decision (check EPM audit logs)
   • User receives access notification
   • User can run the application
   • Access expires after configured duration

End-to-end test: Admin Access

1. From a managed endpoint, request administrative privilege elevation

2. Verify:

   • User sees request submission confirmation from EPM
   • Webhook is received in ServiceNow (check Incoming Requests)
   • Ticket is created in configured ticket type
   • Ticket contains admin access request details
   • Ticket state is in active states list

3. Open the ticket in ServiceNow

4. Click Approve Admin Access

5. Enter reason and duration

6. Submit decision

7. Verify:

   • Decision is recorded on ticket
   • EPM receives decision (check EPM audit logs)
   • User receives privilege elevation
   • Privileges expire after configured duration

Support

For additional support:

1. Review the troubleshooting section above

2. Check ServiceNow Application Logs and Flow execution history

3. Review EPM webhook delivery logs and audit logs

4. Contact BeyondTrust Support:

   • Email: [email protected]
   • Hours: US Central Time, Monday-Friday, 2:00 AM - 7:00 PM (excluding US holidays)
   • Response Time: Within 24 hours of received support request

When contacting support, provide:

• ServiceNow version
• EPM version
• Application version (from ServiceNow Store)
• Detailed description of the issue
• Relevant log entries from ServiceNow and EPM
• Screenshots if applicable

Security considerations

Authentication and authorization

• Webhook authentication: Uses Basic Authentication with dedicated service account

  • Use strong, unique passwords for webhook user
  • Rotate credentials periodically
  • Do not share webhook user credentials

• API authentication: Uses OAuth 2.0 client credentials flow

  • Store API credentials securely
  • Limit API account permissions to JIT Full Access only
  • Rotate API credentials regularly

• User roles: Follow principle of least privilege

  • Only assign x_bets_pmc_jit.api to webhook service account
  • Assign x_bets_pmc_jit.admin only to integration administrators
  • Assign x_bets_pmc_jit.user to help desk staff who need to approve requests

Network security

• HTTPS required: All communication uses HTTPS/TLS

  • Ensure valid SSL certificates on ServiceNow instance
  • Verify EPM services endpoint uses valid certificate

• Firewall rules:

  • Allow inbound HTTPS from EPM services to ServiceNow webhook endpoint
  • Allow outbound HTTPS from ServiceNow to EPM services

• IP allowlisting: Consider restricting webhook endpoint access to EPM service IP addresses if supported

Data security

• Sensitive data: The integration transmits potentially sensitive information:

  • User names and IDs
  • Computer hostnames
  • File paths and application details
  • Approval decisions and reasons

• Data retention: Configure ServiceNow retention policies for:

  • Incoming request records
  • Application access ticket records
  • Admin ticket records

• Audit trail: The integration maintains audit trails:

  • All decisions are logged in ServiceNow tickets
  • EPM maintains audit logs of all JIT activities
  • Review audit logs regularly for compliance

Compliance

• Access reviews: Regularly review:

  • User role assignments
  • Active tickets and decisions
  • Webhook user permissions

• Monitoring: Set up monitoring for:

  • Failed webhook deliveries
  • Failed API calls to EPM
  • Unusual patterns in approvals/denials

Best practices

Configuration

• Test in non-production: Always test the integration in a development or test environment before deploying to production

• Document your configuration: Keep records of:

  • Webhook URLs and credentials
  • API credentials
  • Ticket type and state configuration
  • Assignment groups and categories

• Use descriptive names: Name webhooks clearly (e.g., "ServiceNow - App Access - Create") to easily identify their purpose

• Configure active states carefully: Include all states where approvers should be able to make decisions, but exclude closed or cancelled states

Operational

• Monitor webhook health: Regularly check EPM webhook delivery logs to ensure webhooks are being delivered successfully

• Review failed requests: Periodically review incoming request records for any that failed to create tickets

• Set up notifications: Configure ServiceNow notifications to alert approvers when new JIT requests arrive

• Define SLAs: Establish service level agreements for JIT request response times and communicate them to users

• Train approvers: Ensure help desk staff understand:

  • How to review JIT requests
  • Appropriate approval criteria
  • Duration guidelines
  • How to use the approval forms

Security

• Regular credential rotation: Rotate webhook user password and API credentials on a regular schedule

• Principle of least privilege: Only grant the minimum necessary permissions to users and service accounts

• Monitor for anomalies: Watch for unusual patterns such as:

  • High volumes of denied requests
  • Requests for unusual applications or privileges
  • After-hours requests

• Audit regularly: Conduct periodic audits of:

  • User role assignments
  • Approval patterns
  • Configuration changes

Maintenance

• Keep current: Regularly update:

  • ServiceNow application to latest version from Store
  • EPM to currently supported version
  • Review release notes for new features or changes

• Test after updates: After updating ServiceNow or the application, test the integration to ensure it continues to function correctly

• Backup configuration: Export and backup your configuration settings before making changes

• Document changes: Maintain documentation of all configuration changes and customizations

Advanced configuration

Custom ticket fields

You can customize the ticket forms to display additional fields or hide default fields:

1. Navigate to the form layout for your ticket type

2. Add or remove fields as needed

3. Consider adding calculated fields to display information in custom formats

Workflow customization

You can customize the approval workflows using ServiceNow Flow Designer:

1. Navigate to Process Automation → Flow Designer

2. Find the flows related to BeyondTrust Privilege Management

3. Clone the flows to create custom versions

4. Modify the flows to add custom logic, notifications, or integrations

ℹ️

Be cautious when modifying flows as changes can affect the integration's functionality. Test thoroughly in a development environment.

Custom Notifications

Configure custom notifications for JIT requests:

1. Navigate to System Notification → Email → Notifications

2. Create new notifications triggered by:

   • Creation of Application Access Ticket or Admin Ticket records
   • Updates to decision fields
   • Changes in ticket state

3. Customize notification content and recipients

Integration with other systems

The integration can be extended to work with other systems:

• SIEM integration: Send JIT request events to your SIEM for security monitoring

• CMDB integration: Link tickets to configuration items for better asset tracking

• Identity management: Integrate with identity systems to validate user information

• Reporting and analytics: Create custom reports and dashboards for JIT activity

Reference

Webhook event types

Ticket type comparison

Duration settings

API permissions required

Useful ServiceNow tables

Additional resources

• ServiceNow Store: Search for "BeyondTrust Privilege Management" for the latest version
• BeyondTrust Documentation: Visit the BeyondTrust documentation portal for EPM configuration guides
• ServiceNow Community: ServiceNow community forums for integration best practices
• BeyondTrust Support Portal: Access knowledge base articles and support resources