The PagerDuty Events integration enables Border0 to notify on-call responders based whenever there are Border0 sessions or audit events in your Border0 Organization.

Example notification integration use cases:

• Create an incident for a PagerDuty service whenever a Border0 organization is modified (e.g. Identity provider deleted, socket deleted, etc)
• Create an incident for a PagerDuty service whenever a service behind Border0 is accessed (e.g. SSH to your production hosts)

How it Works

Border0 admin API events result in audit logs being generated. Similarly, Border0 service client sessions result in session logs being generated. Note that whether the session is authenticated successfully or not, a session log is always emitted.

Adding a PagerDuty events integration to your Border0 organization means that you will be associating a set of PagerDuty services, each with their own (secret) service integration keys or routing keys, with your Border0 organization.

Once this integration has been set up for your Border0 organization, you will be able to reference the integration by its unique name in Border0 notification configuration. In other words, you will be able to create a Border0 notification rule that uses the integration you created before.

In the configuration for new notifications you will be able to select the types of events (audit events, successful sessions, and/or failed sessions) that result in a notification being emitted.

Whenever a given notification rule is triggered, if the notification configuration references a PagerDuty Events integration, Border0 will enqueue a PagerDuty alert with the details of the underlying trigger.

Requirements

You will need to have an Admin base role for account authorization in the PagerDuty account which you wish to integrate Border0 with. If you do not have this role, please reach out to an Admin or Account Owner within your organization to configure the integration.

If you need help with this integration, please contact [email protected] or check our our help page.

Integration Walkthrough

To integrate your Border0 organization with the PagerDuty Events API you will need to gather certain configuration parameters, namely service integration keys for the PagerDuty services you wish to allow Border0 to push alerts to.

Below is a description of the required parameters in depth, as well as two alternative methods to getting the service integration keys.

PagerDuty Events Integration Configuration

(1) Name (required)

The integration's "name" is a unique identifier for the integration within your Border0 organization. In other words, no two integrations for the same Border0 organization can have the same name.

Name must start with an alphanumeric character [a-zA-Z0-9] and can only consist of alphanumeric characters and dashes ('-') - it must not include spaces.

🚧

Note

Name is the only parameter which can not be changed after creation-time.

(2) Description

The integration's "description" is a short phrase describing what the integration does or what its purpose is.

(3) Service Integration Keys (required)

The integration's "service integration keys" is a map of PagerDuty service IDs to (alert routing) integration keys provided by PagerDuty

To get service integration keys, you may either:

a) Complete the guided integration flow here (you will be redirected to PagerDuty to consent to the integration, then redirected back to the Border0 Portal with the appropriate service integration keys)

OR

b) Follow the steps in the next section to generate service integration keys manually in the PagerDuty console.

🚧

Note

Simply creating a "PagerDuty Events" integration in Border0 will not result in Border0 pushing alerts to PagerDuty. In order for Border0 to send events to PagerDuty on audit or session events, you must also configure a new notification rule in Border0 and reference the "PagerDuty Events" integration there.

Instructions on how to configure a notification for use with a PagerDuty Events integration can be found under the "PagerDuty Events Notification Configuration" section near the end of this page.

In PagerDuty: Manually Generating Service Integration Keys

In order to manually generate service integration keys you should follow the next steps:

• [1] In the PagerDuty console, navigate to the page of the service you want to integrate with Border0 (the service that will receive alerts from Border0)
• [2] Click on "Add an Integration"

• [3] Search for Border0 on the search bar, select the Border0 integration

• [4] Click on "Add"

• [5] Your PagerDuty service should now have a new integration for Border0 along with an integration key. You will need the service ID (7 letter identifier in the URL) and the integration key to integrate Border0 with your PagerDuty service.

PagerDuty Events Notification Usage

PagerDuty Events integrations can be referenced in Border0 notification rules in order for Border0 to notify you via PagerDuty regarding session or audit events by creating an incident against a PagerDuty service.

In order to configure a PagerDuty Events integration for use within notifications, you must first configure at least one PagerDuty Events integration within your Border0 organization.

Once you have an integration in your organization, the notifications page will expose the option to add a PagerDuty Events based notification.

PagerDuty Events Notification Configuration

(1) name (required)

The notification's "name" is a unique identifier for the notification within your Border0 organization. In other words, no two notifications for the same Border0 organization can have the same name.

Name must start with an lowercase alphanumeric character [a-z0-9] and can only consist of lowercase alphanumeric characters and dashes ('-') - it must not include spaces.

🚧

Note

Name is the only parameter which can not be changed after creation-time.

(2) enabled (required)

The notification's "enabled" setting is a boolean which toggles the notification on/off. When false, the notification is not active and acts as if the notification did not exist.

(3) PagerDuty Events Integration Name (required)

The notification's "PagerDuty Events Integration Name" is the name of the PagerDuty Events integration to use for notifications.

(4) PagerDuty Service ID (required)

The notification's "PagerDuty Service ID" is the ID of the PagerDuty service that incidents will be created for when an eligible event occurs.

🚧

Note

There must be a service integration key for this service ID in the configuration of your PagerDuty Events integration.

(6) Notify on the following Events (required)

The notification's "Events" are a list of event types that will trigger the notification. These include "login-success", "login-failure", and "audit-event".

For more information see the general documentation on setting up notifications.

Example

Assume you have configured the following PagerDuty Events integration in your Border0 organization.

Then we can proceed to add a notification referencing our PagerDuty Events integration: