The PagerDuty OnCall integration enables Border0 administrators to use the state of a PagerDuty "service" and its corresponding "escalation policy" in order to grant or deny access to Border0 resources.

In other words, Border0 organizations can pull information from a PagerDuty account to enrich Border0 policies.

Example policy-integration use cases:

• Allow access only to the on-call person for a given PagerDuty service
• Allow access only when there is an ongoing incident for a given PagerDuty service

To integrate with a PagerDuty account, you will first need to gather certain parameters.

PagerDuty OnCall 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) API Key (required)

The integration's "API Key" is the PagerDuty API key. For more information on how to get a PagerDuty API key see PagerDuty's documentation on how to "Generate a General Access REST API Key".

Border0 only needs READ permissions into your account. Please create a read-only API key.

PagerDuty OnCall Integration Policy Usage

PagerDuty OnCall integrations may be referenced in Border0 policies in order for Border0 to dynamically determine whether a given client should be granted or denied access to a service in your Border0 organization based on the state of a PagerDuty service.

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

Once you have an integration in your organization, the policy editor (in the policies page in the portal) will expose the option to add an integration to any given policy.

PagerDuty OnCall Integration Policy Configuration

(1) service_id (required)

The service_id field must be populated with a valid PagerDuty service ID in the PagerDuty account corresponding to the previously configured integration.

(2) require_be_oncall

The require_be_oncall field is a boolean. When set to true it will only allow access if the connecting user is on-call for the escalation policy for the provided service id.

(3) require_incident

The require_incident field is a boolean. When set to true it will only allow access if the service id has an ongoing incident. The incident must be in "Triggered" or "Acknowledged" state; resolving all incidents for the PagerDuty service while the require_incident field is set to true means that new access will be denied and existing sessions to sockets with the policy will be terminated.

🚧

Heads-up!

Neither the require_be_oncall nor the require_incident checks are required as long as at least one of them is populated (otherwise your policy integration is a NO-OP).

📘

Note

You may want to use the policy tester to determine whether your policy configuration behaves as expected.

Example

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

Then we can proceed to add our PagerDuty integration to a policy:

👍

Note

The integration name and type will be pre-populated for you based on the integration you select from the dropdown.