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, as well as how to configure resource ordering, authentication policy, and application type.

There are two resource types: standard and virtual. Standard resources exist on the target destination, and users can be directed to them. Virtual resources exist only in PingAccess. When a user attempts to access them, PingAccess generates a specified response.

Note:

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

  1. Click Applications and then go to Applications > Applications.
  2. Click to expand an application you want to modify.
  3. Click the Pencil icon.
  4. Click the Resources tab.
    Note:

    A group containing all global unprotected resources is displayed on the first Resources window. Review this list before adding a resource to ensure that there is no conflict between the new resource's path patterns and any unprotected resource path pattern.

  5. To add a resource, click Add Resource.
    Info:

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

  6. Enter a unique Name up to 64 characters, including special characters and spaces.
  7. Enter a list of URL path patterns, within the context root, that identify this resource.

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

    Info:

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

    1. 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.
    2. If you enable manual path pattern ordering (resource ordering), the use of regular expressions is permitted. When one or more path patterns contain a regular expression, you cannot revert to automatic path pattern ordering unless that path pattern is removed.
      • If you have specified a regular expression, ensure 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 API.
  8. If you have enabled resource ordering, select an option in the Query Parameters section. This option lets you define the resource by query parameters in addition to path patterns.
    • Select Match Any to define the resource without regard to query parameters.
    • Select Match Specific to define the resource using one or more query parameters.

      Check Matches No Parameters to match the result to the resource if no query parameters are present, as well as 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 check Any to match any value for the given name.

  9. Select the type of Resource Authentication:
    • Standard if the resource requires the same authentication as the root application.
    • Anonymous if this resource has no authentication requirements. Identity mappings are still applied if the user is already authenticated. Access Control and Processing rules are applied where applicable.
    • Unprotected if this resource has no authentication requirements. Processing rules are applied where applicable. No application or resource access control policy is applied.
    Note:

    These options are not available for unprotected applications. Web applications types are unprotected when they do not have an associated web session. API applications are unprotected when they are not protected by an authorization server.

  10. 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. Click + Create to create a new authentication challenge policy.
  11. From the Methods list, select one or more methods supported by the resource.

    Leave the asterisk default if the resource supports all 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.

  12. To log information about the transaction to the audit store, select the Audit check box.
  13. 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.

    Important:

    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 will rely on this configuration to determine which processing flow to use.

  14. To enable the resource, select the Enabled check box.
  15. From the Resource Type list, select a resource type:
    • Standard – This resource exists on the target destination.
    • Virtual – This resource only exists in PingAccess. PingAccess generates a response when a user attempts to access the resource.
  16. If you selected the Virtual resource type, from the Type list, select a response generator type:
    • Redirect – Redirect the user to a new URL with the specified response code.
    • Template – Create a response using a specified template.
    • JSON Identity Mapping – Make user attributes available to other applications as a JSON payload.
    • Logout – End the application web session and optionally redirect the user to a specific landing page after logout. All applications using the same web session are logged out.
      Note:

      The Logout virtual resource type can only be used if PingFederate is the configured token provider.

  17. 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. From 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.
  18. If you selected the Template response generator, specify the template parameters.
    1. From 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. From 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
  19. If you selected the JSON Identity Mapping response generator, select Inclusion List or Exclusion List.
    • Inclusion List – This option maps the specified attributes to corresponding property names. If you select this option, enter a corresponding Attribute Name and Property Name on each row. Click + Add Row to add additional rows.
    • Exclusion List – This option exposes all attributes except for those you specify. If you select this option, enter zero or more excluded attributes in the Excluded Attributes field.
  20. If you selected the Logout response generator, specify the logout parameters:
    1. Optional: In the Post-logout Redirect URI field, enter a URI to which the user is directed after logout. The format of this URI determines the logout behavior.
      • No URI: 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.
  21. Click Save.