Integration Guide for PingFederate with Beyond Identity Step-Up Authentication

Introduction

This guide provides information on how to:

• Configure Beyond Identity as an OIDC identity provider for first factor authentication; and Beyond Identity step-up ("Allow w/OS Verification") via SAML Connection. 
• Configure PingFederate to use Beyond Identity as a delegate IdP for:
  • First factor - OIDC IdP Connection
  • Second factor - SAML IdP Connection

Prerequisites

Ensure that you have a PingFederate 9.0 or higher instance. All of the examples in this document are from PingFederate 10.1 or higher.

Beyond Identity Configuration

Step 1: Create an OIDC client

1. In the Beyond Identity admin portal, navigate to Integrations -> OIDC Clients, click +Add OIDC Client button
2. Assign a descriptive name. For the Redirect URI field, temporarily assign a value such as:
   https://${PingFederate Base URL}
   Note: The Redirect URI will be updated later, as the relative path of the callback endpoint is automatically generated when the connection is saved in the PingFederate administrator UI.
   Click the Save Changes button.
   
3. Expand the new client and click Edit.
4. Note down the Client ID and Secret, which will be used later while creating the PingFederate IdP Connection.

Step 2: Create a SAML SP Connection

1. Navigate to Integrations -> SAML Connections -> click +Add SAML Connection
2. Input the following values in the form fields:
   Name: PingFederate SAML SP Connection
   SP Single Sign On URL: https://${PingFederate Base URL:Port}/sp/ACS.saml2
   SP Audience URI: This is the "SAML 2.0 Entity ID" setting value in the PingFederate administrative UI located on the same page as the Base URL.
   Name ID Format: <default>
   Subject User Format: <default>
   Request Binding: http_post
3. Click on Save Changes
4. Expand the new connection and right-click the View Metadata hyperlink and copy the link location. This metadata URL will be used later for creating the PingFederate IdP Connection.
   

Step 3: Create a Policy

1.  Navigate to Policy -> Authentication Rules -> click the Add rule button.
2. Under the "If integration is any integration" section, click +Add integration attribute and choose the "SAML Connection is" from the first drop-down list, and choose the PingFederate SAML SP Connection that we just created.
3. On the "Then" section of the policy, choose Allow W/ OS Verification
   
4. Click Add
5. Click and drag the new policy towards the top of the list of policies, at least above any default "Allow" rules.

PingFederate Configuration

Step 1: Create an OIDC IdP Connection

Note: These instructions do not apply if you have already created an OIDC IdP Connection with a connection ID of https://auth.byndid.com/v2. In this case, please proceed to Step 2: Create a SAML IdP Connection.

1.  Navigate to Authentication -> IdP Connections -> click the Create Connection button.
2. On Connection Type, check the Browser SSO Profiles box, and choose OpenID Connect in the Protocol drop-down list, then click Next.
   
3. On Connection Options, leave only the Browser SSO box checked, then click Next.
4. On General Info, input https://auth.byndid.com/v2 in the Issuer text field and click the Load Metadata button. Verify that the "Metadata successfully loaded" message is returned, then input the following values:
   Enable Additional Issuers: disabled (unchecked)
   Connection Name: A descriptive name, such as Beyond Identity OIDC IdP Connection
   Client ID: The client ID from Beyond Identity referenced on "Step 1: Create an OIDC Client"
   Client Secret: The client secret from "Step 1: Create an OIDC Client"
   Base URL: https://auth.byndid.com/v2
   It is recommended to populate the remaining contact fields with relevant information relative to your Beyond Identity tenant. Leave the Error Message and Transaction Logging at the default settings. Click Next.
   
5. On Browser SSO, click the Configure Browser SSO button.
   
6. On User-Session Creation, click the Configure User-Session Creation button.
   
7. On the Target Session Mapping screen, if an error such as "You must configure at least one mapping" is displayed, click on the Identity Mapping tab on the upper left of the screen.
   
8. On Identity Mapping, choose the No Mapping radial button option and click Next.
   
9. On Attribute Contract, no additional attributes other than the 'sub' are required in the ID token, so click Next.
   
10.  On the Summary screen of User-Session Creation, click Done.
11.  Back on the User-Session Creation screen, click Next.
    
12.  On Protocol Settings, click the Configure Protocol Settings button.
    
13.  Because the Load Metadata operation previously discovered the Beyond Identity OIDC well-known configuration endpoint, the Scopes, Authorization Endpoint, OpenID Connect Login Type, Authentication Scheme, and endpoint URLs should already be populated as such. Verify these settings, then click Done.
14.  Back on the Protocol Settings screen, click Next.
    
15. On the Summary screen, click Done.
    
16.  Back on the Browser SSO screen, click Next.
    
17.  On the Activation & Summary page, ensure the slider bar at the top right of the screen is enabled (green), then click Save.
    NOTE: Once the connection is saved, the Redirect URI is automatically generated. This value will be used to overwrite the temporary Redirect URIs value we previously set in Step 1: Create an OIDC Client in the Beyond Identity administrative portal.
18.  In PingFederate, navigate to Authentication -> IdP Connections, and click on the "Beyond Identity OIDC Identity Provider" hyperlink for the connection we just created.
19.  On Activation & Summary, copy the Redirect URI value at the top of the page.
    
20.  In the Beyond Identity administrative portal, navigate to Integations -> OIDC Clients -> {Client Name} -> and click Edit
21.  Paste the Redirect URI value from the PingFederate IdP Connection from step 19 into the Redirect URIs field of the OIDC client, as shown below, and click Save Changes.

Step 2: Create a SAML IdP Connection

1. Navigate to Authentication -> IdP Connections -> click the Create Connection button.
2. On Connection Type, select the Browser SSO Profiles check box and choose SAML 2.0 as the Protocol. Click Next.
   
3. On Connection Options, verify only the Browser SSO check box is selected, and click Next.
4. On Import Metadata, choose the URL radial button, which will load a sub-menu to select a Metadata URL. Click the Manage Partner Metadata URLs button.
   
5. On Partner Metadata URLs, click Add New URL, and enter a descriptive name, such as Beyond Identity SAML Metadata URL, and paste the metadata URL obtained previously in Step 2: Create a SAML SP Connection into the URL field. Uncheck the Validate Metadata Signature checkbox, then click Load Metadata. Click Next.
   
6. On the Metadata URL summary screen, click Save.
   
7. Back on the Partner Metadata URLs screen, click Done, which will return to the Import Metadata screen. On the Metadata URL drop-down list, choose the new Metadata URL. Ensure the Enable Automatic Reloading checkbox is enabled, and click the Load Metadata button, then click Next.
   
8. On General Info, the Partner's Entity ID, Connection Name, and Base URL should already be populated based on the metadata. The Connection Name may be changed to something such as Beyond Identity SAML IdP Connection <ID> to distinguish it from other connections. The remaining fields may be populated with your tenant-specific information. When completed, click Next.
   
9. On Browser SSO, click the Configure Browser SSO button.
   
10.  On SAML Profiles, select only the SP-Initiated SSO check box.
    
11.  On User-Session Creation, click the Configure User-Session Creation button.
    
12.  On Identity Mapping, choose the No Mapping radial button and click Next.
    
13.  On Attribute Contract, optionally add additional SAML assertion attributes under Extend the Contract. Click Next when finished.
    NOTE: Any extended contract attributes may become mandatory to the IdP connection, so these attribute key names must also be added to the corresponding SAML Connection in the Beyond Identity admin portal, for example:
    
14.  On the Summary screen for User-Session Creation, click Done.
    
15.  Back on the User-Session Creation tab, click Next.
    
16. On Protocol Settings, click the Configure Protocol Settings button.
    
17.  On SSO Service URLs, verify that two URLs have been imported from the metadata for the Redirect and POST bindings and click Next.
    
18.  On Allowable SAML Bindings, ensure that only the POST and Redirect checkboxes are selected and click Next.
    
19.  On Overrides, do not input anything on this page, click Next.
20.  On Signature Policy, ensure the Use SAML-Standard Signature Requirements radial button is selected, and click Next.
    
21. On Encryption Policy, ensure the None radial button is selected and click Next.
    
22.  On the Summary screen for Protocol Settings, click Done.
    
23.  Back on the Protocol Settings tab, click Next.
    
24.  On the Summary screen of Browser SSO, click Done.
    
25.  Back on the Browser SSO tab, click Next.
    
26.  On the Credentials tab, a signature verification certificate should have already been imported from the metadata, so verify and click Next.
    
27.  On the Activation & Summary tab, ensure the slider bar is green, and click Save.

Step 3: Create an Authentication Policy

NOTE: The following steps assume a functional knowledge on the creation and operation of PingFederate Authentication Policies, including Selectors, IdP Connections, and Policy Contracts.

Prerequisites for this step:

• Complete steps 1 & 2 under "PingFederate Configuration"
• Create an Authentication Policy Contract (a single "subject" attribute is sufficient)
• Create any type of Authentication Selector. This example uses a Connection Set selector.
• A working SP Connection (SAML, WS-Fed) or OAuth Client (via Policy Contract Grant Mapping). This configuration is not covered in this guide.

1.  Navigate to Authentication -> Policies -> click the Add Policy button.
   
2. Assign a descriptive name, and description.
3. Under the first policy drop-down list, choose Selectors on the sub drop-down list, then choose your selector. This example uses a Connection Set selector named "SAML Test".
   
4. Under the No branch, choose the Continue hyperlink. Under the Yes branch, choose IdP Connections from the drop-down list and choose the Beyond Identity OIDC IdP Connection that was created in Step 1 of the PingFederate configuration above.
   
5. Under the Fail branch, click the Done hyperlink. Under the Success branch, choose the Beyond Identity SAML IdP Connection that was created in Step 2 of the PingFederate configuration above.
   
6. Click on the Options hyperlink beneath the SAML connection, on the Source column choose IdP Connection (https://auth.byndid.com/...) from the drop-down list; choose sub from the Attribute column and click Done.
    
7. On the Fail branch beneath the SAML connection, click the Done hyperlink. On the Success branch, choose Policy Contracts, then choose the contract instance referred to in the prerequisites. In this example, a single-attribute policy named "genericUser" is used.
   
8. Under the Success branch, click on the Contract Mapping hyperlink.
9. On Attribute Sources & User Lookup, click Next.
   NOTE: In this example, a single-attribute Policy Contract is used, but in your environment, there may be additional attributes in the Policy Contract. In this case, it may be necessary to query these attributes from data stores. It would be necessary to click the Add Attribute Source button and follow the wizard for creating an LDAP or JDBC database lookup. These instructions do not cover this configuration, so please refer to PingFederate documentation on how to configure data store lookups.
10. On Contract Fulfillment, select IdP Connection (Beyond Identity OIDC Identity Provider) from the Source drop-down list, and select sub from the Value drop-down menu. Click Next.
    
11.  On Issuance Criteria, nothing will be modified, click Next.
12. On the Summary screen, click Done.
13. Click Done, then click Save on the Policies page.
    NOTE: PingFederate Authentication policies are evaluated iteratively from top to bottom. When saving a new policy, it will be placed at the bottom of the policy branches. If there other policies above this one that fulfill both:
    A) other pre configured authentication selectors' criteria OR the same IdP connections, and;
    B) mapped "Success" to the same policy contract instance,
    then it will be necessary to move this policy above any other colliding policy.
    
14.  Once the Policy has been mapped to Policy Contract, the fulfilled Policy Contract may be used anywhere in PingFederate where an authentication context is required, such as SP Connections, OAuth Policy Contract Grant Mappings, IdP Adapters, etc.