Protecting a web application with PingAccess

Use Cases

bundle
solution-guides
ft:publication_title
Use Cases
Product_Version_ce
category
ContentType
howtodoc
ContentType_ce
How-to

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.

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

  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.
    Note:

    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.

    Note:

    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 check box.
    6. From the Trusted Certificate Group list, select Trust Any.
      A screen capture of the PingAccess 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.
      Note:

      For maximum security and standards interoperability, use the Code login type. However, other options are available. For information on the available profiles, see OpenID Connect login types.

    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.

      Note:

      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.

    12. 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 PingAccess 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.

    Note:

    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 PingAccess. A session cookie is set in the browser that PingAccess later uses instead of re-authenticating the user. PingAccess processes and forwards the request to the target site, httpbin.org. Identity mapping and PingAccess security policies verify the user should have access to the target site, providing user-centric data in the request. PingAccess 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.
      Note:

      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 check box 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 check box is selected.
    11. Select the Enabled check box.
    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 check box.
    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.
    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 "https://httpbin.org/anything".
    3. Open a new browser window in private browsing or incognito mode and enter https://www.protected.com/anything.
    4. Note the following information:
      • The site displays the information from https://www.httpbin.org/anything.
      • The URL that the browser talks to is listed as https://www.protected.com/anything.
      • A PingAccess cookie, PA.WebSession, is set.
      A screen capture of a browser window displaying protected.com/anything with the url and cookie fields highlighted with a red box. The url field text reads "https://protected.com/anything", and the cookie field shows an identifier for a PingAccess cookie.
  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.
      Note:

      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.

    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.
      There are two new fields following User-Agent: X-Cert and X-Sub.