PingAccess

Protecting a web application with PingAccess in an agent deployment

You can protect a web application from unwanted access using PingAccess.

Prerequisites

Before configuring your PingAccess deployment to protect a web application:

Steps

After you have completed the following steps, your web application is protected.

  1. Configure a virtual host – A virtual host represents the site you will protect and contains information about its location.

  2. Configure a web session – A web session defines the details of how user credential information is retained. This lets the token provider authenticate the user when it is required for a protected application.

  3. Configure a rule – Rules control who can access what content under what circumstances.

  4. Configure an identity mapping – An identity mapping lets you share identity information with the protected application as headers.

  5. Configure an application – An application joins the other pieces together, giving users access to the application according to the configured rules.

Configuring a virtual host

About this task

The virtual host is the external-facing portion of a web application. In an agent deployment, the virtual host contains the actual host name and port for the protected web application.

For more information about this procedure, including optional steps that are not included here, see Creating new virtual hosts.

Steps

  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 of the protected web application. 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.

  4. In the Port field, enter the port number for the virtual host. For example, 443.

  5. Click Save.

Configuring a web session

About this task

A web session specifies the details of how user information is stored.

For more information about this procedure, including optional steps that are not included here, see Creating web sessions.

Steps

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

  2. Click Add Web Session.

  3. In the Name field, enter a unique name for the web session, up to 64 characters, including special characters and spaces.

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

  5. In the Audience field, enter the audience that the PA token is applicable to, represented as a short, unique identifier between one and 32 characters.

    PingAccess rejects requests that contain a PA token with an audience that differs from what is configured in the web session associated with the target application.

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

    The Code login type is recommended for maximum security and standards interoperability, but other options are available. Learn more about the available profiles in step 6 of Creating web sessions.

  7. In the Client ID field, enter the unique identifier (client ID) that was assigned when you created the OAuth relying party (RP) client within the token provider (for more information, see Configuring a Client in the PingFederate documentation).

  8. Select a Client Credentials Type. This is required when configuring the Code login type.

    Choose from:

    • Secret

    • Mutual TLS

    • Private Key JWT

      The OAuth client you use with PingAccess web sessions must have an OpenID Connect (OIDC) policy specified (for more information see Configuring OpenID Connect Policies).

  9. Provide the information required for the selected credential type.

    Choose from:

    • Secret – Enter the Client Secret assigned when you created the OAuth relying party client in the token provider.

    • Mutual TLS – Select a configured Key Pair to use for Mutual TLS client authentication.

    • Private Key JWT – No additional information is required.

  10. In the Idle Timeout field, specify the amount of time, in minutes, that the PA 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 PA token remains active before expiring (the default is 240 minutes).

  12. Click Save.

Configuring a rule

About this task

Rules are used to control the circumstances under which users can access the protected web server. Rules can grant or deny access based on criteria such as user parameters from the token provider, header values, network ranges, or web session attributes. You can configure any number of rules in your environment.

You can combine rules into rule sets, which combine multiple rules. You can configure rule sets to allow access to a resource if at least one rule’s criteria is met, or to only allow access if all rules have their criteria met. Access control rules are processed before processing rules. Each type of rule is otherwise processed in the order you specify when you create the rule set.

You can further combine rule sets into rule set groups, which combine multiple rule sets. As with rule sets, rule set groups can allow access if any one rule set’s criteria are met, or only if all rule sets' criteria are met. Rule sets are processed in the order you specify when you create the rule set group.

This example uses an HTTP request header rule to demonstrate how rules are created and used. Each environment has different requirements, and you can use any of the rules explained in the Rule management section according to your needs.

Steps

  1. Click Access and then go to Rules → Rules.

  2. Click Add Rule.

  3. In the Name field, enter a unique name. The name can be up to 64 characters long. Special characters and spaces are allowed.

  4. From the Type menu, select HTTP Request Header.

  5. In the Field column, in the Header field, enter the HTTP header name you want to match in order to grant or not grant the client access.

  6. In the Value field, enter the values for the header you want to match in order to grant or not grant the client access. The wildcard (*) character is supported.

    If you want to match on the Host header, include both the host and port in the Value field, or add a wildcard after the host name ( host* or host:*) to match what is in the HTTP request.

  7. If you need additional header pairs, click Add Row to add an additional row, then repeat steps 5-6.

  8. Click Save.

Configuring an identity mapping

About this task

A header identity mapping can expose one or more attribute values to the protected application in HTTP request headers.

For more information about this procedure, including optional steps that are not included here, see Creating header identity mappings.

Steps

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

  2. Click Add Identity Mapping.

  3. In the Name field, enter a name for the mapping.

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

  5. In the Attribute to Header Mapping section, in the Attribute Name field, enter the name of the attribute to retrieve from the user web session. For example, sub.

  6. In the Header Name field, enter the name of the HTTP requests header to contain the attribute value.

    The header you specify here is the actual header name over the HTTP protocol, not an environment variable interpreted format. For example, enter the User-Agent browser type identifying header as User-Agent, not HTTP_USER_AGENT.

  7. In the Certificate to Header Mapping section, enter the header name included in a PEM-encoded client certificate.

    The row position correlates to the index in the client certificate chain. For example, the first row always maps to the leaf certificate. If you are using a certificate chain, click Add Row to add another row.

  8. Click Save.

Configuring an application

About this task

The application represents the protected web application as a whole. By including the virtual host and the agent, it allows PingAccess to match incoming traffic to the application with the agent managing that application. By including a web session, you specify how user credential data is stored and for how long. After you create the application and its root resource, you can add one or more rules to control access to the protected web application.

Within the application, you can add one or more resources. Resources are specific components that require a different degree of security. You can apply different rules to a resource, letting you apply specific controls to portions of an application. This example procedure does not include resources. For information about adding resources to an application, see Configuring resource ordering in PingAccess.

For more information about this procedure, including optional steps that are not included here, see Adding an application.

Steps

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

  2. Click Add Application.

  3. In the Name field, enter a unique name for the application, up to 64 characters, including special characters and spaces.

  4. In the Context Root field, enter the context root for the application. This represents the context at which the application is accessed at the site.

    The context root must meet the following criteria:

    • It must start with /.

    • It can contain additional / path separators.

    • It must not end with /.

    • It must not contain wildcards or regular expression strings.

    • The combination of the Virtual Host and Context Root must be unique.

  5. From the Virtual Host list, select the virtual host you created.

  6. In the Application Type section, select Web.

  7. From the Web Session list, select the web session you created.

  8. In the Destination section, select Agent, then select the agent that is installed on the same web server as the web application.

  9. Click Save.

  10. Click Applications and then go to Applications → Applications.

  11. Expand the new application in the list and click the pencil icon .

  12. Click the Web Policy tab.

  13. Drag your rule from Available Rules onto the policy bar.

  14. Click Save.