Use Cases

Protecting a web application with PingAccess using PingFederate as the token provider

Configure a proof of concept to protect a web application from unwanted access using PingAccess with PingFederate as the token provider.

There are several ways to set up PingAccess to protect a web application. This use case covers the setup and configuration of PingFederate and PingAccess so PingFederate can act as the token provider. This is intended to be a basic configuration to get PingAccess and PingFederate up and running for a proof of concept. To learn more about other configuration options, see the Protecting a web application with PingAccess.

Components

  • PingFederate 10.1

  • PingAccess 6.1

Setting up PingFederate 10.1

Combine PingFederate 10.1 with PingAccess 6.1 in a basic configuration to perform a proof of concept for protecting web applications. To get started, set up PingFederate.

Before you begin

About this task

To set up PingFederate:

Steps

  1. Install PingFederate on your operating system.

    Choose from:

  2. Start the PingFederate server.

    Choose from:

  3. Open the PingFederate administrative console.

    1. Open a browser and enter https://Your Server Domain:9999/pingfederate/app.

      Your Server Domain is your fully qualified domain name (FQDN).

      If you do not have a DNS set up for an FQDN, you can also use an IP address, but the use of an FQDN long-term is the best practice.

    2. To sign on, in the username field, enter Administrator, and in the password field, enter 2Federate.

    3. To proceed, review the license agreement. Click Accept.

  4. Click No, Set Up Without PingOne for Enterprise, and then click Next.

  5. To import a valid PingFederate license, click Choose File and locate your license file.

    Learn more in Reviewing or importing your license (page 157).

  6. Click Next.

  7. On the Basic Information tab, enter the basic information.

    1. In the Base URL field, verify your base URL. Update as needed.

      The domain portion of the base URL should match the domain name of your organization because it is part of the address where your applications, users, and partners communicate with your PingFederate environment.

      You can add multiple virtual host names at a later time. Learn more in Virtual host names (page 855).

    2. In the Entity ID field, enter your Entity ID if prompted. Click Next.

      This is the unique identifier of your organization. It is how your partners identify you when communicating with you based on SAML 2.0 specifications.

  8. On the Connection tab, in the Directory Type list, select your directory type and provide the required information.

    Learn more about each field in Connecting to a directory (page 158).

  9. Click Next until you reach the Summary tab. Click Done.

    If you are connecting to Active Directory (AD), bypass Kerberos authentication at this time.

  10. On the Administrator Account tab, create an administrative account.

    1. To replace the default value in the Username field, enter a new value.

    2. In the Password and Confirm Password fields, enter a password.

    3. Click Next.

  11. On the Confirmation tab, review your configuration.

  12. To apply the configuration to PingFederate, click Next, and then click Done.

Setting up PingAccess 6.1

Combine PingFederate 10.1 with PingAccess 6.1 in a basic configuration to perform a proof of concept for protecting web applications. To get started, set up PingAccess.

Before you begin

Review and ensure you meet the PingAccess installation requirements (page 33), including the port requirements and required Java version.

About this task

To set up PingAccess:

Steps

  1. Install PingAccess on your operating system.

    Choose from:

  2. Start PingAccess (page 41).

    You can also run PingAccess as a service (page 44).

  3. Go to the administrative console (page 42) and follow the setup wizard.

    Result:

    The PingAccess administrative console landing page opens.

Preparing PingFederate for PingAccess connectivity

Combine PingFederate 10.1 with PingAccess 6.1 in a basic configuration to perform a proof of concept for protecting web applications. To set up this proof of concept, configure PingFederate for PingAccess connectivity.

About this task

To configure PingFederate for PingAccess connectivity, use the PingFederate console.

Steps

  1. To verify PingFederate roles and protocols, go to System → Server → Protocol Settings, and then proceed to Enabling PingFederate roles and protocols.

    In PingFederate 10.1.x, all necessary roles and protocols are turned on by default.

  2. To verify the password credential validator (PCV) created during the setup process in Setting up PingFederate 10.1, go to System → Data & Credential Stores → Password Credential Validators.

    Result:

    You see a PCV that corresponds with the directory that you set up.

    If there is no PCV displayed, see Creating a password credential validator.

  3. To verify the IdP adapter created in the setup process, go to Authentication → Integration → IdP Adapters.

    Result:

    You see an HTML form adapter associated with the PCV in step 2.

    If no IdP adapter is displayed, see Configuring an IdP adapter.

  4. To define the default scope, go to System → OAuth Settings → Scope Management. Proceed to Defining the default scope.

  5. To create an access token manager, go to Applications → OAuth → Access Token Management.

    From Token Management, proceed to Creating an access token manager.

  6. Define an authentication policy contract.

    1. Go to Authentication → Policies → Policy Contracts.

    2. Click Create New Contract.

    3. In the Contract Name field, enter a name for your contract.

    4. Click Next until you reach the Summary section. Click Save.

      Configuring a policy contract instead of configuring an IdP adapter mapping enables more advanced and flexible authentication policies.

  7. Configure a policy contract grant mapping.

    1. Go to Security → Authentication → OAuth → Policy Contract Grant Mapping.

    2. From the Policy Contract list, select the policy you just created. Click Add Mapping.

    3. Click Next until you reach the Contract Fulfillment section.

    4. From the Source list, select Authentication Policy Contract for both User_Key and User_Name contracts.

    5. From the Value list, select Subject for both User_Key and User_Name contracts.

    6. Click Next until you reach the Summary section. Click Save.

  8. To configure an access token mapping, go to Applications → OAuth → Access Token Mapping. Proceed to Configuring an access token mapping.

  9. To create an OpenID Connect policy, go to Applications → OAuth → OpenID Connect Policy Management. Proceed to Creating an OpenID Connect policy.

  10. To create a resource server client, go to Applications → OAuth → Clients. Proceed to Creating a resource server client.

  11. To create a web session client, go to Applications → OAuth → Clients. Proceed to Creating a web session client .

  12. Create and export a certificate from PingFederate to PingAccess.

    1. Go to Security → Certificate & Key Management → SSL Server Certificates.

    2. Click Create New.

    3. In the Common Name field, enter the PingFederate server address.

      This should match the Your Domain Name entry in step 3a in Setting up PingFederate 10.1.

    4. In the Organization field, enter your organization’s name.

    5. In the Country field, enter the two-letter abbreviation for your country.

    6. Complete the remaining fields as required.

    7. Click Next.

    8. Click Save.

    9. In the Action section, click Activate Default for Runtime Server.

    10. In the Action section, click Activate Default for Admin Console.

    11. In the Action section, click Export.

    12. Click Certificate Only. Click Next.

    13. Click Export, and then save the exported certificate.

    14. Click Done.

      To avoid confusion, you can delete the default localhost certificate that appears in the certificate list. In the Action section, select Deactivate, and then click Delete.

Result

You are ready to connect PingAccess to PingFederate.

Connecting PingFederate and PingAccess

Combine PingFederate 10.1 with PingAccess 6.1 in a basic configuration to perform a proof of concept for protecting web applications. After PingFederate has been installed and prepared for PingAccess connectivity, connect PingAccess and PingFederate.

About this task

To connect PingFederate to PingAccess, use the PingAccess administrative console.

Steps

  1. Importing certificates and creating a trusted certificate group.

  2. Configure the token provider.

    1. Click Settings, and then go to System → Token Provider → PingFederate → Runtime.

    2. In the Issuer field, enter the PingFederate issuer name.

    3. From the Trusted Certificate Group list, select the PingFed certificate group.

    4. Optional: Click Show Advanced Settings and select the Skip Hostname Verification checkbox.

    5. Click Save.

    6. Click Settings, and then go to System → Token Provider → PingFederate → Administration.

    7. In the Host field, enter the host name or IP address for the PingFederate Runtime.

      For example, mypingfedserver.

    8. In the Port field, enter the port number for PingFederate Runtime.

      For example, 9031.

    9. In the Admin Username field, enter the username.

      This username only requires auditor, read-only, permissions in PingFederate.

    10. In the Admin Password field, enter the password.

    11. From the Secure list, select Secure.

    12. From the Trusted Certificate Group list, select the PingFed certificate group.

    13. Click Save.

    14. Click Settings, and then go to System → Token Provider → PingFederate → OAuth Resource Server.

    15. In the Client ID field, enter the OAuth Client ID you defined when creating the PingAccess OAuth client in PingFederate.

      For example, pa_rs.

    16. In the Client Credentials Type section, select Secret, then enter the Client Secret assigned when you created the PingAccess OAuth client in PingFederate.

    17. In the Subject Attribute Name field, enter the attribute you want to use from the OAuth access token as the subject for auditing purposes.

      For example, username.

    18. Optional: Select the Send Audience checkbox.

    19. Click Save.

Result

PingAccess can be configured to protect a web application.

Protecting a web application with PingAccess

Use this use case to combine PingFederate 10.1 with PingAccess 6.1 in a basic configuration to perform a proof of concept for protecting web applications.

About this task

To configure PingAccess to protect a web application for a proof of concept, use the PingAccess administrative console.

Steps

  1. To configure PingAccess to listen on port 443, adjust the engine listeners.

    1. Go to Settings → Networking → Engine Listeners and click Add Engine Listener.

    2. Complete the fields.

    3. Click Save.

      Port 443 is commonly restricted to root-level access on certain operating systems. Availability to bind to this port might require root access. Consult your system administrator with any questions about port access.

      Listening on port 443 is not a requirement for using PingAccess, but rather a recommendation for this specific, proof of concept, use case.

  2. Configure a virtual host.

    1. Click Applications, and then go to Applications → Virtual Hosts.

    2. Click Add Virtual Host.

    3. In the Host field, enter the name for the virtual host.

      This is the host name used by end users to reach the site. For example, myHost.com. You can use a wildcard (*) for part or all of the host name. For example, *.example.com matches all host names ending in .example.com, and * matches all host names.

    For this example, add *:443 and localhost:443.

  3. Configure a site.

    For this proof of concept we are using https://www.httpbin.org.

    The site www.httpbin.org is not affiliated with Ping Identity, but is a good example to use when presenting a proof of concept due to its ability to quickly expose the browser’s communication with the protected site. You can choose to protect a different website, substituting instances of www.httpbin.org with your site.

    1. Click Applications, and then go to Sites → Sites.

    2. Click Add Site.

    3. In the Site Name field, enter HTTP Bin.

    4. In the Targets field, enter www.httpbin.org:443.

    5. Select the Secure checkbox.

    6. From the Trusted Certificate Group list, select Trust Any.

      A screen capture of the admin console Add Site screen. The fields contain the information outlined in the substeps for HTTP bin. Name: HTTP bin, Targets: www.httpbin.org:443, Secure is marked No, and Trusted Certificate Group has Trust Any selected.
  4. Configure a web session.

    1. Click Access, and then go to Web Sessions → Web Sessions.

    2. Click Add Web Session.

    3. In the Name field, enter Web Session.

    4. From the Cookie Type list, select Encrypted JWT.

    5. In the Audience field, enter WebSession.

    6. From the OpenID Connect Login Type list, select Code.

      For maximum security and standards interoperability, use the Code login type. However, other options are available. For information on the available profiles, see Creating web sessions.

    7. In the Client ID field, enter pa_wam.

    8. From the Client Credentials Type menu, select Secret.

    9. Enter the client secret for the OAuth client.

    10. In the Idle Timeout field, specify the amount of time, in minutes, that the PingAccess token remains active when no activity is detected by the user.

      The default is 60 minutes.

      If there is an existing valid PingFederate session for the user, an idle timeout of the PingAccess session might result in its re-establishment without forcing the user to sign on again.

    11. In the Max Timeout field, specify the amount of time, in minutes, that the PingAccess token remains active before expiring.

    The default is 240 minutes.

    1. Click Save.

  5. Configure an identity mapping.

    For this proof of concept use case, you do not need to configure rules.

    1. Click Access, and then go to Identity Mappings → Identity Mappings.

    2. Click Add Identity Mapping.

    3. In the Name field, enter General Identity Mapping.

    4. From the Type list, select Header Identity Mapping.

    5. In the Attribute to Header Mapping section, click Subject.

    6. From the Attribute Name list, select sub and in the Header Name field, enter X-SUB.

    7. In the Certificate to Header Mapping section, in the Header Name field, enter X-CERT.

      A screen capture of the admin console General Identity Mapping screen. The fields contain the information outlined in the substeps. Name: General Identity Mapping, Type: Header Identity Mapping is selected, Attribute to Header Mapping: sub is selected for Attribute Name and X-SUB is entered in Header Name, Certificate to Header Mapping: X-CERT is in the Header Name field.
  6. Add a new redirection URI in PingFederate.

    For this proof of concept, we are using www.protected.com.

    The redirection URI is what your end users enter when they are accessing the protected site. In this proof of concept, we are entering https://www.protected.com into the browser, but we are accessing https://www.httpbin.org through this configuration with PingAccess. To understand the relationship between the protected site and the redirection URI, see the following diagram.

    A flow diagram showing a browser request to the virtual host protected.com that generates a web session with . A session cookie is set in the browser that later uses instead of re-authenticating the user. processes and forwards the request to the target site, httpbin.org. Identity mapping and security policies verify the user should have access to the target site, providing user-centric data in the request. presents the protected site’s response to the browser.
    1. From the PingFederate administrative console, go to Applications → OAuth → Clients → pa_wam.

    2. Click Add.

    3. In the URI field, enter https://www.protected.com/pa/oidc/cb.

      If you choose to use a different URI, format your entry as https://Your Site Address/pa/oidc/cb.

  7. Configure an application in PingAccess.

    1. From the PingAccess administrative console, click Applications and then go to Applications → Applications.

    2. Click Add Application.

    3. In the Name field, enter HTTP Bin.

    4. In the Context Root field, enter /.

    5. From the Virtual Host list, select www.protected.com:443.

    6. In the Application Type section, select Web.

    7. Verify that the SPA Support checkbox is unselected.

    8. From the Web Session list, select None.

    9. In the Destination section, select Site, then select HTTP Bin.

    10. Verify that the Require HTTPS checkbox is selected.

    11. Select the Enabled checkbox.

    12. Click Save.

  8. Add a new authentication policy in PingFederate.

    1. From the PingFederate administrative console, go to Authentication → Policies.

    2. Select the IDP Authentication Policies checkbox.

    3. Click Add Policy.

    4. In the Name field, enter a name for your policy.

    5. From the Policy list, select IdP Adapters and then select HTML Form Adapter.

    6. In the Fail section, click Done.

    7. In the Success section, from the Success list, select Policy Contracts and then select Default Policy Contract.

    8. In the Success section, click Contract Mapping.

    9. Click Next until you reach the Contract Fulfillment tab.

    10. From the Source list, select Adapter (HTMLFormAdapter).

    11. From the Value list, select username.

    12. Click Next until you reach the Summary tab. Click Done.

    13. Click Done, and then click Save.

      Result:

      Your policy is saved and enabled.

  9. Optional: Demonstrate the configuration so far.

    1. Open a new browser window in private browsing or incognito mode and enter https://www.httpbin.org/anything.

    2. Note the following information:

      • The URL that the browser talks to is listed as https://www.httpbin.org/anything.

      • No cookies, typically found under the headers section, are set.

        A screen capture of a browser window displaying httpbin.org/anything with the url field highlighted with a red box. The field text reads
    3. Open a new browser window in private browsing or incognito mode and enter https://www.protected.com/anything.

    4. Note the following information:

  10. Set authentication requirements for the protected site.

    1. In the PingAccess administrative console, go to Applications → HTTP Bin and click the Pencil () icon to edit.

    2. From the Web Session list, select Web Session.

    3. Click Save.

    4. Optional: Refresh the browser window where you are accessing https://www.protected.com/anything.

      PingFederate now asks for credentials to access the site.

      If you enter valid credentials from your datastore to access the page, the same information from https://www.httpbin.org/anything is displayed through https://www.protected.com/anything.

      Result:

      PingAccess evaluates the browser’s requests through the authentication requirements you defined.

  11. Configure PingAccess to pass data to the application.

    1. In the PingAccess administrative console, go to Applications → HTTP Bin.

    2. From the Web Identity Mapping list, select General Identity Mapping.

    3. Click Save.

    4. Optional: Refresh the browser window where you are accessing https://www.protected.com/anything.

      Result:

      There are two new fields following User-Agent: X-Cert and X-Sub.