Configure SSO for PingFederate

Use the following instructions to configure APEX AIOps Incident Management to allow users to log in with their PingFederate credentials.

Note that the PingFederate SSO setup procedure is complex in some sections and is ideally completed by a PingFederate administrator, or someone who is a PingFederate subject matter expert (SME).

Before you begin

Ensure that your PingFederate SME is available to perform the configuration.
Ensure that the email attribute is present in your IDP SAML assertion.
Ensure that a user with the Owner role generates an API key in your Incident Management UI and keeps a record of it somewhere that you can reference it again.
Familiarize yourself with this procedure for disabling SSO to prevent locking users out of Incident Management if the SSO configuration fails.
Ensure that the email addresses for all users who will log in to Incident Management via SSO are correctly set up in your organization's Identity Provider (in Active Directory, Okta, etc.), and that users have sufficient permissions to retrieve their email addresses from the Identity Provider.
Note that if you receive an "Unauthorized" error when you test the SSO connection, it is likely that users cannot access their email addresses.
To use the same SSO configuration across multiple Incident Management instances, you must complete the SSO setup for one instance and then follow the procedure for supporting multiple tenants to add additional instances.

Configuration overview

The configuration procedure which follows this section includes click-by-click setup instructions. The key elements of the procedure are as follows:

Generate the X.509 certificate in PingFederate and include it in the proper location in Incident Management.
Download the certificate and metadata files from Incident Management and include them in the proper locations in PingFederate.
Set up an SP connection.
Include email address (required) and any attribute you want to use for group information (optional) in your IDP SAML assertion.

If you choose to follow a different procedure, ensure that you complete these items or your SSO configuration will not be successful.

Configure Incident Management

In Incident Management, navigate to Settings > Single Sign On (SSO).
In the PingFederate box, click Configure.
Find your Base URL in PingFederate:
1. In PingFederate, click System at the top of the page, and then click Server in the left-hand navigation.
  The Base URL displays under Protocol Settings on the Federation Info page.
2. Copy the Base URL.
In Incident Management, paste your PingFederate Base URL in the Base URL field.
At the end of the Base URL, add the following:
```
idp/SSO.saml2
```
So, if your base URL was https://mybaseurl.com, your Base URL field would be:
```
https://mybaseurl.com/idp/SSO.saml2
```
Generate the X509 certificate in PingFederate:
1. In PingFederate, click Security at the top of the page, then click Signing & Decryption Keys & Certificates.
2. Click Create New.
3. In the Common Name field, enter a name for the certificate. The name can be anything you choose.
4. In the Organization field, type in the name of your organization.
5. In the Country field, enter a two-letter country code.
  Example: US
6. Click Next, and then click Save on the Create Certificate Summary page.
7. On the page that loads, click Select Action and then click Export on the menu.
8. On the Export Certificate page, select Certificate Only and then click Next.
9. On the Export & Summary page, click Export under Export Certificate.
  The certificate file downloads to your computer.
Open the certificate file with a text editor and copy the contents, including the Begin Certificate and End Certificate lines.
In Incident Management, paste the certificate file contents in the X509 Certificate box.
Under Configured Domains, click Edit Domains.
In the Edit Domains dialog, enter a domain click Add Domain.
Repeat for additional domains.
Then, click Save.
On the Configure PingFederate page, click Download Metadata and Download Certificate.
Save the files. Move the files to location that you will remember. Renaming the files with applicable names may help you locate them later when you need to load them in PingFederate (example: APEXAIOpsIncidentManagementMetadata.xml and APEXAIOpsIncidentManagementMetadataCert.pem).
Important
If you are unable to download the files (the buttons are light blue and unclickable), this is an indication that there is an issue with your configuration on the initial configuration page.

Configure PingFederate

Disclaimer

The setup steps and video demo are provided to help guide you through the implementation and set up of PingFederate SSO for Incident Management, including the required steps inside the PingFederate console. These instructions are based on the APEX AIOps internal implementation of the PingFederate console using Okta as the IDP. Some elements may not apply to your configuration, depending on your version, IDP, or any other existing configuration options in PingFederate.

If you have any questions or need help troubleshooting specific details within PingFederate itself, please contact your PingFederate support team.

In PingFederate, click Applications, and then click SP Connections at the top of the page.
On the SP Connections page, click Create Connection.
On the Connection Template page, keep the default selection and then click Next.
On the Connection Type page, select Browser SSO Profiles.
Under Protocol, select SAML 2.0. Then, click Next.
On the Connection Options page, select Browser SSO, and then click Next.
On the Import Metadata page, select File.
Click Choose File and then select the metadata file that you downloaded from Incident Management (in our example, APEXAIOpsIncidentManagementMetadataMetadata.xml).
Click Next; on the Metadata Summary page click Next; on the General Info page click Next.
On the Browser SSO page, click Configure Browser SSO.
On the SAML Profiles page, select IDP Initiated SSO and SP-Initiated SSO, and then click Next.
On the Assertion Lifetime page, leave the default settings and click Next.
On the Assertion Creation page, click Configure Assertion Creation.
On the Attribute Contract page, select Standard, and then, click Next.
On the Identity Mapping page, make sure SAML_SUBJECT displays with a Subject Name Format of "unspecified."
Example of an unspecified attribute contract format: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
Also on the Identity Mapping page, under Extend the Contract, click inside the box and select email from the list that displays.
Under Attribute Name Format, select "unspecified" as the format for the email attribute.
Example of an unspecified email format: urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified
Click Add.
(Optional) To allow for future SSO role and group mapping within Incident Management, add an attribute in an unspecified format to use for this purpose:
Click inside the empty box under email in the Extend the Contract section, and type an attribute name in the new box. Make sure the Attribute Name Format is also "unspecified."
Example attribute: department
Example attribute name format for department: urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified
Click Add, and then click Next.
On the Authentication Source Mapping page:
- For configurations with an IDP adapter already set up, click Map New Adapter Instance to map your attributes.
  NOTE: Setup for this type of connection is outside of the scope of this documentation. Consult your PingFederate SME for guidance regarding next steps.
- For configurations using IDP connection, click Map New Authentication Policy and continue to the next step.
On the Authentication Policy Contract page, click Select, select or create an authentication policy that supports mappings for the SAML_SUBJECT and email fields. Then, click Next.
On the Mapping Method page, select Use only the authentication policy contract values in the SAML assertion. Then, click Next.

On the Attribute Contract Fulfillment page, make the following selections, and then click Next.

Attribute Contract	Source	Value	Actions
SAML_SUBJECT	Authentication Policy Contract	subject	none available
(Optional) department	Authentication Policy Contract	department	none available
email	Authentication Policy Contract	email	none available

On the Issuance Criteria page, leave the defaults set and click Next.
On the Summary page, check that the subject and email attributes are present, and that any additional attributes you're using are set up correctly.
Click Done.
On the Authentication Source Mapping tab, click Next; at the bottom of the Summary page, click Done; on the Assertion Creation page, click Next.
On the Protocol Settings page, click Configure Protocol Settings.
On the Assertion Consumer URL page, leave the default settings and click Next.
On the Allowable SAML Bindings page, select POST and REDIRECT (clear any other selections). Click Next.
On the Signature Policy page, leave the default settings and click Next; on the Encryption Policy page, leave the default setting (None) and click Next; on the Summary page, click Next; on the next Summary page, click Done.
On the Protocol Settings page, click Next; on the Summary page, click Done; on the Browser SSO page, click Next.
On the Credentials page, click Configure Credentials.
On the Digital Signature Settings page, for Signing Certificate, click Select and select the certificate that you generated from your PingFederate server in step 6.
Make sure RSA SHA256 is selected for Signing Algorithm.
Select Include the Certificate in the Signature <KEYINFO> element, and then click Next.
On the Signature Verification Settings page, click Manage Signature Verification Settings and select Unanchored. Then, click Next.
On the Signature Verification Certificate page, click Manage Certificates, and then click Import.
On the Import Certificate page, click Choose File.
Select the certificate you downloaded from Incident Management (in our example, APEXAIOpsIncidentManagementMetadataCert.pem), and then click Next.
On the Summary page, click Save.
Click Done on the next page, and Next on the page after that.
On the Summary page, click Done; on the Signature Verification Settings page, click Next.
On the Summary page, under Digital Signature Settings, make sure that you have the certificate that you provided to APEX AIOps. Under Signature Verification Certificate, make sure you have the certificate that you downloaded from APEX AIOps.
Then, click Done. On the next page, click Next.
Examine the activation summary. When you have verified everything necessary is included, click Save.
If you are using a PingFederate setup deployed in Kubernetes:
1. In PingFederate, click System at the top of the page, then click Server > Cluster Management in the left-hand navigation.
2. Click Replicate.
  This process synchronizes your primary node with other worker nodes, and replicates the newest SP connection information to all of them.

Enable SSO

In Incident Management, navigate to Settings > Single Sign On (SSO) > PingFederate > Enabling SSO.
Click Enable, and then click Enable Now when prompted.

Test your setup

On the Test page, click Test, and then click Test Now when prompted.

If you see a page confirming the connection works, with the information for user profiles that the application will receive, the connection is working properly.

NOTE: Testing is optional, but recommended. Click Skip Test to proceed without testing.

Configure SSO to support multiple tenants

If you have multiple Incident Management instances and want to use the same SSO configuration with all of them, you must complete an additional procedure for supporting multiple tenants.

Configure additional scopes, role mappings and group mappings

Perform this procedure last, after completing the other configuration steps and confirming that you can log in using SSO.

Keep in mind that if roles are not configured for users, and no default role is set up, then all users who are added to the system via SSO will have administrator permission.

In Incident Management, navigate to Settings > Single Sign On (SSO).
Under Role and Group Mapping (Optional), click Edit Mappings.
Add any additional scopes:
Enter a space-separated list of scopes that Incident Management can request from the external authentication system. This list must include the scopes the system will use for group mapping and any scopes used for other purposes. For example: preferred_contact location department.
Incident Management automatically adds openid email profile if these scopes are not provided.
NOTE: Additional scopes are added to the SP Connection as shown in this step.
Add your role mappings:
Map each claim value to the corresponding Incident Management role.
NOTE: You can create custom roles in Incident Management to map to your SSO roles. See Manage roles for details.
1. Click Add Role Mapping.
2. In the Add Role Mapping dialog, enter the Role Claim Key and the Role Claim Value in the indicated fields.
3. Click Select Role and, from the list that opens, select the Incident Management role to map to the selected Claim Value.
4. Click Add Mapping.
Tip
By default, users with no role are assigned the Admin role. You can select a different default role, and even create a custom role for this purpose.
1. Enter the claim key in the Role Claim Key field.
2. Enter default for the Role Claim Value.
3. Click Select Role and select the role to use as the default from the list.
When users are added that do not have a role assignment, they will now be assigned this default role.
Add your group mappings:
Under Group Mappings, map your group claim values to Incident Management groups. To map an SSO group to a Incident Management group, you must first create the target group in Incident Management. For information on creating user groups for SSO, see Add groups to use with SSO.
1. Click Add Group Mapping.
2. In the Add User Group Mapping dialog, enter the Group Claim Key, and the Group Claim Value in the indicated fields.
3. Click Select User Group and, from the list that opens, select the Incident Management group to map to the selected Claim Value.
4. Click Add Mapping.

In this section: