PingAccess

Adding application resources

Add application resources to existing applications in PingAccess.

About this task

An application resource is a component within an application that requires a different level of security. These instructions describe how to add, edit, and delete application resources and how to configure resource ordering, authentication policy, and application type.

There are two resource types: standard and virtual.

Standard resources

Standard resources exist on the target destination, and users can be directed to them.

Virtual resources

Virtual resources exist only in PingAccess. When a user attempts to access them, PingAccess generates a specified response.

Some applications allow you to specify the parameters of a request in the query string or the POST body. If you are managing such an application and are defining its resources using query parameters, use caution when defining the resource to ensure that PingAccess and the application treat the resource in the same way.

Steps

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

  2. Click to expand the application that you want to modify resources on, then click the Pencil icon and click the Resources tab.

    Choose from:

    • To add a resource, click Add Resource.

      A group containing all global unprotected resources is displayed on the first Resources page. Review this list before adding a resource to make sure that there won’t be a conflict between the new resource’s path patterns and any unprotected resource path pattern.

    • To edit a resource, expand the resource and click the Pencil icon.

    • To delete the resource, expand the resource and click the Delete icon.

  3. Enter a unique Name of up to 64 characters, including special characters and spaces.

  4. Enter a list of Uniform Resource Locator (URL) path patterns within the context root that identify this resource.

    If resource ordering is enabled, select the path pattern type, Basic or Regex.

    The path pattern must start with a forward slash (/). It begins after the application context root and extends to the end of the URL.

    If automatic path pattern evaluation ordering is in use (default), patterns can contain one or more wildcard characters (*). No use of wildcards is assumed. For example, there is a difference between /app/ and /app/*. If a request matches more than one resource, the most specific match is used.

    If you enable manual path pattern ordering (resource ordering), you can use regular expressions in the path pattern. When one or more path patterns contain a regular expression, you cannot revert to automatic path pattern ordering unless you remove that path pattern

    If you have specified a regular expression, make sure that you select the Regex path pattern type. If you don’t, the pattern will be interpreted incorrectly as a Basic text string.

    The application reserved path cannot be used as a path pattern when the context root is /. The default application reserved path is /pa(/pa*). You can modify the default application reserved path using the PingAccess Admin application programming interface (API).

    If you selected the Use context root as reserved resource base path check box on your application, you cannot use the application context root as a path pattern either. This check box turns the application context root into a reserved resource, and a reserved application context root cannot be used in an application’s resource paths.

  5. If you have enabled resource ordering, select an option in the Query Parameters section.

    The Query Parameters section lets you define the resource by query parameters in addition to path patterns.

    Choose from:

    • To define the resource without regard to query parameters, select Match Any.

    • To define the resource using one or more query parameters, select Match Specific:

      • Select Matches No Parameters to match the result to the resource if no query parameters are present and if at least one query parameter is present and matches. If this option is deselected, at least one query parameter must be present and must match.

      • Enter one or more Name-Value pairs, or enter a Name and select Any to match any value for the given name.

  6. Select a Resource Authentication type.

    Choose from:

    • If the resource requires the same authentication as the root application, select Standard.

    • If this resource has no authentication requirements, select Anonymous. Identity mappings are still applied if the user is already authenticated. Access control and processing rules are applied where applicable.

    • If this resource has no authentication requirements, select Unprotected. Processing rules are applied where applicable. No application or resource access control policy is applied.

    These options are not available for unprotected applications.

    • Web applications are unprotected when they don’t have an associated web session.

    • API applications are unprotected when they aren’t protected by an authorization server.

  7. If the application is a protected web application with a web session, select an Authentication Challenge Policy to generate authentication challenge responses for the resource or click Create to create a new authentication challenge policy. Otherwise, proceed to the next step.

  8. If you are using the PingOne Protect integration on a protected web application, select a Risk Policy to enforce on the resource or click +Create to create a new risk policy. Otherwise, proceed to the next step.

    You must set up a PingOne connection before you can create a risk policy. For more information on how to set these up through the administrative console, see Adding a PingOne connection and Adding a risk policy. For more information on the capabilities that a risk policy can provide, see PingOne Protect integration.

    A risk policy applied at the resource level takes precedence over one applied at the application level. PingOne risk policies depend on mapping user identity attributes to the risk evaluation requests, so the PingAccess administrative console will prevent you from saving an unprotected application or resource with a risk policy.

  9. Optional: If you’re using an API or Web + API type application and want to configure different DPoP settings for the application resource than the global DPoP settings that you configured in the token provider:

    If you are using PingFederate as the token provider, you must use PingFederate 11.3 or later to configure DPoP support.

    1. Select Override DPoP Settings.

    2. In the DPoP Type list, select the level of OAuth 2.0 Demonstrating Proof of Possession (DPoP) support that you want to enable for access token validation:

      • Off (default): PingAccess doesn’t accept DPoP-bound access tokens, only bearer tokens.

      • Enabled: PingAccess accepts both bearer tokens and DPoP-bound access tokens.

      • Required: PingAccess doesn’t accept bearer tokens, only DPoP-bound access tokens.

    3. To require each DPoP proof to contain a nonce value during validation that was provided by PingAccess when the access token was created, per RFC 9449 section 9, select Require Nonce.

      This check box is cleared by default.

    4. In the DPoP Proof Lifetime (SEC.) field, enter the duration, in seconds, that a DPoP proof should be considered valid after it’s issued.

      As a security best practice, keep this value low and consistent with the DPoP implementation of your API client. The default value is 120 seconds.

  10. In the Methods list, select one or more methods supported by the resource.

    For a complete list of HTTP methods and their definitions, see https://webconcepts.info/concepts/http-method/.

    PingAccess does not support the CONNECT, PRI, or QUERY methods.

    Leave the asterisk default if the resource supports all other HTTP methods, including custom methods.

    Defining methods for a resource allows more fine-grained access control policies on resources. If you have a server optimized for writing data (POST, PUT) and a server optimized for reading data (GET), you might want to segment traffic based on the operation being performed.

  11. To log information about the transaction to the audit store, select the Audit check box.

  12. If the application type is Web + API, and SPA Support is disabled on the root application, indicate whether the application resource should override the fallback type specified for the main application.

    If you select Yes for this option, select the method to be used for the application resource when a request does not contain a web session cookie or OAuth token.

    Carefully consider your configuration when making this selection. Changing the application fallback type can have unexpected effects on resources that do not override the fallback.

    For example, if you configure a Web + API application with a fallback type of Web along with several resources that do not override the fallback type, these resources will emit a 401 response (rather than a 302 to PingFederate) if you later change the fallback type to API on the main application.

    The PingAccess runtime uses fallback type to determine which processing flow (Web or API) to use when the request does not contain a web session or an API OAuth Bearer token. When a request does not contain either of these authentication mechanisms, it relies on this configuration to determine which processing flow to use.

  13. To enable the resource, select the Enabled check box.

  14. In the Resource Type list, select a resource type:

    Choose from:

    • If the resource exists on the target destination, select Standard.

    • If the resource only exists in PingAccess, select Virtual. PingAccess generates a response when a user attempts to access the resource.

  15. If you selected the Virtual resource type, in the Type list, select a response generator type:

    Choose from:

    • To redirect the user to a new URL with the specified response code, select Redirect.

    • To create a response using a specified template, select Template.

    • To make user attributes available to other applications as a JavaScript Object Notation (JSON) payload, select JSON Identity Mapping.

    • To end the application web session and optionally redirect the user to a specific landing page after logout, select Logout. All applications using the same web session are logged out.

      You can only use the Logout virtual resource type if PingFederate is the configured token provider.

  16. If you selected the Redirect response generator, specify the redirect parameters:

    1. In the Redirect URL field, enter a relative or absolute URL to which users should be redirected.

    2. In the Response Code list, select a response code:

      301 – Moved permanently

      This is a permanent redirect that does not require the redirect to maintain the original HTTP method.

      302 – Found

      This is a temporary redirect that does not require the redirect to maintain the original HTTP method.

      307 – Temporary Redirect

      This is a temporary redirect that requires the redirect to maintain the original HTTP method.

      308 – Permanent Redirect

      This is a permanent redirect that requires the redirect to maintain the original HTTP method.

    3. To opt out of automatic URL encoding, deselect the Encode URL check box.

      Learn more in PingAccess 8.1 (June 2024).

  17. If you selected the Template response generator, specify the template parameters:

    1. In the Media Type list, select or enter a media type for the template.

    2. In the Template field, enter a template in Velocity Template Language (VTL).

      When a user accesses the virtual resource, the template is processed and returned as the response.

      The template can include information about the user, resource, and application according to this data model:

      identity.subject

      A string containing the subject name of the identity. This property is only available if the user is authenticated.

      identity.attributes

      An object containing user attributes set by the token provider. For example, identity.attributes.role could contain a role set by the token provider. This property is only available if the user is authenticated.

      identity.trackingID

      A string containing the tracking ID of the identity. This property is only available if the user is authenticated.

      resource.name

      A string containing the name of the requested resource.

      application.name

      A string containing the name of the requested application.

      application.realm

      A string containing the OAuth realm associated with the application. If the realm is not defined by the application, it is inferred to be the requested authority and the application’s context root.

      exchangeId

      A string containing the ID for the current transaction.

    3. In the Response Code list, select a response code:

      • 200 – OK

      • 201 – Created

      • 400 – Bad Request

      • 401 – Unauthorized

      • 403 – Forbidden

      • 404 – Not Found

      • 405 – Method Not Allowed

  18. If you selected the JSON Identity Mapping response generator, select Inclusion List or Exclusion List:

    Choose from:

    • To map the specified attributes to corresponding property names, select Inclusion List. If you select this option, enter a corresponding Attribute Name and Property Name on each row. Click Add Row to add additional rows.

    • To expose all attributes except for those you specify, select Exclusion List. If you select this option, enter zero or more excluded attributes in the Excluded Attributes field.

  19. If you selected the Logout response generator, specify the logout parameters:

    1. Optional: In the Post-logout Redirect URI field, enter a Uniform Resource Identifier (URI) to which the user is directed after logout. The format of this URI determines the logout behavior:

      • No URI: single logout (SLO) defaults to the token provider settings.

      • Absolute URL without variables: The PingAccess session is cleared and SLO is not triggered.

      • URL containing the ${SLO} variable: The ${SLO} variable is replaced with the PingFederate ping_end_session_endpoint, which triggers SLO.

        For example, if the PingFederate ping_end_session_endpoint is https://pingfederate:9031/idp/startSLO.ping, a value of ${SLO}?TargetResource=https://example.com would direct the user to the PingFederate endpoint, trigger SLO, and then redirect the user to https://example.com.

      • Relative path: The relative path is appended to the application path to form the destination and SLO isn’t triggered.

      • PingFederate parameters: The parameters are passed to PingFederate and SLO is triggered. For more information, see IdP endpoints[IdP endpoints].

    2. To opt out of automatic URL encoding, deselect the Encode URL check box.

      Learn more in PingAccess 8.1 (June 2024).

  20. Click Save.