PingAccess

Protecting a web application with PingAccess in a gateway deployment

Protect a web application from unwanted access using PingAccess.

Prerequisites

Before configuring your PingAccess deployment to protect a web application:

Steps

Protecting a web application involves:

  1. Configure a virtual host – A virtual host represents the external face of the site you will protect.

  2. Configure a site – A site contains the internal details of the site you will protect, including its actual location.

  3. 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.

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

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

  6. Configure an application – An application joins the other pieces together, giving users access to the site 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 a gateway deployment, the virtual host contains the host name and port that your users use to reach the protected web application.

For more information about this procedure, including optional steps that aren’t 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 used by end users to reach the site, such asmyHost.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, such as 443.

  5. Click Save.

Configuring a site

About this task

A site is only used in a gateway deployment. It contains the target address for the protected web application and any other information necessary to access the application.

For more information about this procedure, including optional steps that aren’t included here, see Adding sites.

Steps

  1. Click Applications and then go to Sites > Sites.

  2. Click Add Site.

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

    This name is used internally.

  4. In the Targets field, enter one or more targets.

    These targets are the actual locations of the site. The format for this is hostname:port or IP address:port, such as www.example.com:80.

  5. Select the Secure check box if the site is expecting HTTPS connections.

    This decision depends on whether the target expects an HTTPS connections from the PingAccess system to the protected web application.

    If you select Secure, you must also select a Trusted Certificate Group from the list, or select Trust Any to trust any certificate presented by the listed targets. The trusted certificate group defines what certificates or issuing certificate authorities PingAccess will trust when acting as a client to the backend server.

    For information about importing a certificate and creating a trusted certificate group, see Importing certificates and Creating trusted certificate groups.

  6. Click Save.

    If the target site can’t be contacted, PingAccess saves the site and displays a warning indicating the reason the site couldn’t be reached.

Configuring a web session

About this task

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

You can find more information about this procedure, including optional steps that aren’t included here, in 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. In the Cookie Type list, select Encrypted JWT.

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

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

  6. In 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.

    Learn more in Configuring a Client in the PingFederate documentation.

  8. In the Client Credentials Type list, select a client credentials type.

    Selecting a client credentials type 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.

      Learn more in 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 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.

  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. In the Type list, 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’s 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 aren’t 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. In 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, such as sub.

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

    The HTTP request 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. Including the virtual host and the site allows PingAccess to route requests directed at the front-end name to the correct back-end resource. 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 aren’t 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.

    The context root represents the context at which the application is accessed at the site and 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. In the Virtual Host list, select the virtual host you created.

  6. In the Application Type section, click Web.

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

  8. In the Destination section, click Site, then select the site you created.

  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.