PagerDuty

Before You Begin

Introduction

This document describes how to configure Oracle Identity Cloud Service to provide single sign-on (SSO) and user provisioning for PagerDuty.

About PagerDuty

PagerDuty is an alarm aggregation and dispatching service for system administrators and support teams. It collects alerts from monitoring tools, gives an overall view of all of the user's monitoring alarms, and alerts an on-duty engineer if there's an issue.

After integrating PagerDuty with Oracle Identity Cloud Service:

  • Users can use their Oracle Identity Cloud Service login credentials to access PagerDuty.
  • Users can use the Oracle Identity Cloud Service My Apps console to launch PagerDuty.
  • Administrators can use the Identity Cloud Service console to assign and revoke user access to the PagerDuty app.

What Do You Need?

  • An Oracle Identity Cloud Service account with authorization rights to manage apps and users (by being assigned to the identity domain administrator or application administrator role).
  • A PagerDuty account with authorization rights to configure federated authentication and user provisioning.
  • Identity provider metadata. Use the https://<IDCS-Service-Instance>.identity.oraclecloud.com/fed/v1/metadata URL to access the metadata and save it in a text file. Use this file later to obtain the identity provider certificate in the "Obtaining the Identity Provider Certificate" section.

Prerequisite Step

Before you can register and activate the PagerDuty app, you'll need a domain name. Obtain that domain name from PagerDuty.

The PagerDuty domain name appears in the https://<Domain_Name>.pagerduty.com PagerDuty login URL that you received in an email from PagerDuty.

Obtaining the Identity Provider Certificate

Use this section to obtain the identity provider certificate in a format that's suitable for PagerDuty.

  1. To access the identity provider metadata, use the https://<IDCS-Service-Instance>.identity.oraclecloud.com/fed/v1/metadata URL.

  2. In the metadata file, locate the dsig:X509Certificate tags.

  3. Copy the content between the dsig:X509Certificate tags into a text file. This content is the Oracle Identity Cloud Service signing certificate.

    Image img1.png displays the metadata content with md:IDPSSODescriptor and dsig:X509Certificate tags highlighted.

  4. To format the certificate, access the https://www.samltool.com/format_x509cert.php URL. The Format a X.509 certificate page appears.

  5. In the X.509 cert text box, paste the content, and then click FORMAT X.509 CERTIFICATE. The formatted certificate is displayed in the X.509 cert with header text box.

  6. In the X.509 cert with header text box, copy the certificate and paste it in a text file.

    Tip: Use this certificate content later to configure SSO for PagerDuty in the "Configuring SSO for PagerDuty" section.

Configuring SSO for PagerDuty

  1. Using the https://<Domain_Name>.pagerduty.com URL, access PagerDuty as an administrator. The Incidents on All Teams page appears.

  2. In the header, click the Configuration drop-down list, and then select Account Settings. The Subscription Details page appears.

  3. In the Subscription Details page, click Single Sign-on. The Enable Single Sign-on (SSO) page appears.

  4. Click SAML.

  5. Use the following table to update the federated authentication attributes, and then locate and click Save Changes. A success message is displayed on top of the page, stating that the account settings are updated.

    Attribute Value
    X.509 Certificate Paste the identity provider certificate content that you obtained earlier in the "Obtaining the Identity Provider Certificate" section.
    Login URL Enter the https://<IDCS-Service-Instance>.identity.oraclecloud.com/fed/v1/idp/sso Sign-in URL/SSO Endpoint.
    Require signed authentication requests Locate and select the check box.
    Auto-provision users on first login Select the check box.

  6. Under the SAML section, make a note of the SAML Metadata URL.

    Tip: Use this URL to access the service provider metadata and obtain the PagerDuty certificate in the "Obtaining the Service Provider Signing Certificate in .pem Format" section.

  7. In the header, click the Configuration drop-down list, and then select API Access. The API Access Keys page appears.

  8. Click +Create New API Key. The Create v2 API Key window appears.

  9. Enter Description, and then click Create Key. The New API Key window appears.

  10. Make a note of the API Key, and then click Close.

    Note: Because the API Key appears only once, you should note it immediately. Use this key while enabling user provisioning for the PagerDuty app in Oracle Identity Cloud Service. See the "Enabling Provisioning" section.

Obtaining the Service Provider Signing Certificate in .pem Format

Use this section to obtain the service provider certificate from the service provider metadata.

  1. Access the SAML Metadata URL that you obtained while performing the steps in the "Configuring SSO for PagerDuty" section.

  2. In the metadata file, locate the ds:X509Certificate tag.

  3. Copy the content between the ds:X509Certificate tags into a text file.

    Image img2.png displays the metadata content with ds:X509Certificate and ds:X509Certificate tags highlighted.

  4. At the beginning of the content, add -----BEGIN CERTIFICATE-----.

  5. At the end of the content, add -----END CERTIFICATE-----.

  6. Save the text file in a .pem format. This is the service provider signing certificate.

    Tip: Use this certificate later to register and activate the PagerDuty app in Oracle Identity Cloud Service. See the "Registering and Activating the PagerDuty App" section.

Configuring PagerDuty in Oracle Identity Cloud Service

Use this section to register and activate the PagerDuty app, and to enable provisioning and synchronization for PagerDuty.

Registering and Activating the PagerDuty App

  1. Access the Identity Cloud Service console, select Applications, and then click Add.

  2. Click App Catalog.

  3. Search for PagerDuty, and then click Add.

  4. In the App Details section, enter your PagerDuty domain name, and then click Next.

    Note: You obtained this domain name while performing the steps in the "Prerequisite Step" section.

  5. In the SSO Configuration section, upload the signing certificate of the service provider.

    Note: You obtained this certificate by performing the steps in the "Obtaining the Service Provider Signing Certificate in .pem Format" section.

  6. To enable provisioning and synchronization for PagerDuty, click Next. Oracle Identity Cloud Service displays the Provisioning page.

Enabling Provisioning and Synchronization for PagerDuty

Use this section to enable provisioning and synchronization for managing user accounts in PagerDuty through Oracle Identity Cloud Service.

Enabling Provisioning

  1. In the Provisioning page, select Enable Provisioning.

  2. Under the Configure Connectivity section, enter the API Key.

    Note: You obtained this key while performing the steps in the "Configuring SSO for PagerDuty" section.

  3. Click Test Connectivity. A success message is displayed, stating that the connection is successful.

  4. To view predefined attribute mappings between the user account fields defined in PagerDuty and the corresponding fields defined in Oracle Identity Cloud Service, click Attribute Mapping, and then click OK.

    Note: To add a new attribute for provisioning, click Add Row, specify the attributes in the User and PagerDuty Account columns, and then click OK. For example, if you want to add the External ID field, enter $(user.externalId) in the User column, and then select the corresponding field from the drop-down list in the PagerDuty Account column.

  5. Specify the provisioning operations that you want to enable for PagerDuty:

    Note: By default, the Create Account, Update Account, and Delete Account check boxes are selected.

    Create Account: Automatically creates a PagerDuty account when PagerDuty access is granted to the corresponding user in Oracle Identity Cloud Service.

    Update Account: Automatically updates a PagerDuty account when the corresponding user is edited in Oracle Identity Cloud Service.

    Delete Account: Automatically removes an account from PagerDuty when PagerDuty access is revoked from the corresponding user in Oracle Identity Cloud Service.

Enabling Synchronization

  1. In the Provisioning page, select Enable Synchronization.

  2. From the User Identifier drop-down list, select the Oracle Identity Cloud Service user attribute that you want to match with the corresponding record fetched from PagerDuty:

    Note: By default, the Primary Email Address option is selected from the drop-down list. It's recommended to leave this default attribute for accurate synchronization of user records.

    Primary Email Address: Primary email address of the Oracle Identity Cloud Service user.

    User Name: User name of the Oracle Identity Cloud Service user.

  3. To match a PagerDuty account attribute with the existing Oracle Identity Cloud Service user, select an attribute from the Application Identifier drop-down list.

    Note: By default, the Email option is selected. This option represents the Email attribute of the PagerDuty account. Don't change this default option.    

  4. From the When exact match is found drop-down list, select one of the following actions to be performed when a matching Oracle Identity Cloud Service user is found for an account:

    Link and confirm: Automatically links and confirms the matched account to the corresponding Oracle Identity Cloud Service user based on the defined User Identifier and Application Identifier fields. 

    Link but do not confirm: Automatically links all matched accounts to the corresponding Oracle Identity Cloud Service users based on the defined User Identifier and Application Identifier fields. You need to confirm the linked accounts manually. 

  5. In the Max. number of creates field, enter a number that's greater than or equal to 10. This value limits the number of accounts to be created during the synchronization run.

  6. In the Max. number of deletes field, enter a number that's greater than or equal to 10. This value limits the number of accounts to be deleted during the synchronization run.

    After enabling provisioning and synchronization for PagerDuty, you can synchronize the existing account details from PagerDuty and link them to the corresponding Oracle Identity Cloud Service users. For more information on performing synchronization tasks, see the Importing User Accounts from a Software as a Service Application section in Administering Oracle Identity Cloud Service.

    You can also manage PagerDuty accounts through Oracle Identity Cloud Service. For more information on performing provisioning tasks, see the Managing Oracle Identity Cloud Service Users and Managing Oracle Identity Cloud Service Groups chapters in Administering Oracle Identity Cloud Service.

  7. Click Finish, Activate, and then click Activate Application. Oracle Identity Cloud Service displays a confirmation message.

Verifying the Integration

Use this section to verify that SSO works when initiated from Oracle Identity Cloud Service (an identity-provider-initiated SSO) and PagerDuty (a service-provider-initiated SSO).

Verifying the Identity-Provider-Initiated SSO from Oracle Identity Cloud Service

  1. Using the https://<IDCS-Service-Instance>.identity.oraclecloud.com/ui/v1/myconsole URL, access the Oracle Identity Cloud Service My Profile console.

  2. Log in using credentials for a user that's assigned to the PagerDuty app. Under My Apps, Oracle Identity Cloud Service displays a shortcut to PagerDuty.

  3. Click PagerDuty. The PagerDuty Incidents on All Teams page appears.

  4. In the upper-right corner of the header menu, click the user icon drop-down list, and then confirm that the user that's logged in is the same for both PagerDuty and Oracle Identity Cloud Service.

    This confirms that SSO that's initiated from Oracle Identity Cloud Service works.

Verifying the Service-Provider-Initiated SSO from PagerDuty

  1. Using the https://<Domain_Name>.pagerduty.com/ URL, access PagerDuty. The PagerDuty sign in page appears.

  2. Click Sign In With Your Identity Provider. You're redirected to the Oracle Identity Cloud Service Sign In page.

  3. Log in using credentials for a user that's assigned to the PagerDuty app. The PagerDuty Incidents on All Teams page appears.

  4. In the upper-right corner of the header menu, click the user icon drop-down list, and then confirm that the user that's logged in is the same for both PagerDuty and Oracle Identity Cloud Service.

    This confirms that SSO that's initiated from PagerDuty works.

Troubleshooting

Use this section to locate solutions to common integration issues.

Known Issues

PagerDuty displays the message, "unable to find user <Email_address> in PagerDuty account for <Domain_Name>.pagerduty.com."

Cause 1: The email attribute sent by Oracle Identity Cloud Service during SSO doesn't match any existing user in PagerDuty. If the Auto-provision users on first login check box isn't selected in PagerDuty, then this error might also occur.

Solution 1: Ensure that the user that you assign to the PagerDuty app has an account in both Oracle Identity Cloud Service and PagerDuty with the same email address. Alternatively, select the Auto-provision users on first login check box in PagerDuty.

Oracle Identity Cloud Service displays the message, "You are not authorized to access the app. Contact your system administrator."

Cause 1: The SAML 2.0 integration between the Oracle Identity Cloud Service PagerDuty app and PagerDuty is deactivated.

Solution 1:

  • Access the Identity Cloud Service console, select Applications, and then select PagerDuty.
  • In the App Details section, click Activate, and then click Activate Application. Oracle Identity Cloud Service displays a confirmation message.

Cause 2: The administrator revokes access for the user at the same time that the user tries to access the PagerDuty app using Oracle Identity Cloud Service.

Solution 2:

  • Access the Identity Cloud Service console, select Applications, and then select PagerDuty.
  • In the App Details section, select Users, and then click Assign to reassign the user.

Unknown Issues

For unknown issues, contact Oracle Support:

  1. Go to https://support.oracle.com.

  2. Select Cloud Support, and then sign in with your support credentials.

  3. In the Cloud Dashboard, confirm that there are no planned outages in Oracle Identity Cloud Service, and then click Create Service Request.

  4. Select Oracle Identity Cloud Service as the service type.

  5. Complete your service request.