You can modify most of these pages in a text editor to suit the particular branding and informational needs of your PingAccess installation. Cascading style sheets and images for these pages are included in the <PA_HOME>/conf/static/pa/assets subdirectory. Each page contains both Velocity constructs and standard HTML. The Velocity engine interprets the commands embedded in the template page before the HTML is rendered in the user’s browser. At runtime, the PingAccess server supplies values for the Velocity variables used in the template.

Important:

If you have modified the reserved application context root using the PingAccess Admin APIapplication programming interface (API) A specification of interactions available for building software to access an application or service., file system requests to the configured reserved application context root will be translated to /pa. This allows the file system behavior for PingAccess resources to remain unchanged. Thus, if the reserved context root is set to /ping, templates and other resources would still be stored on the file system in the /pa directory, as indicated by this document.

For information about Velocity, see Velocity project documentation on the Apache Web site. Changing Velocity or JavaScript code is not recommended. The following variables are the only variables that can be used for rendering the associated web browser page.

The features documented here are affected by the settings in the configuration file. See the Configuration file reference for more information.

Variable Description

title

The browser tab title for the message. For example, Not Found.

header

The header for the message. For example, Not Found.

info

The information for the message. For example, No Resource configured for request.

exchangeId

A value that identifies the request/response pair. This can be used to locate messages in the PingAccess logs.

trackingId

A value that identifies either the tracking ID, identified with a tid: prefix, or an access token ID, identified with a atid: prefix. This can be used to identify the session in the PingAccess and PingFederate logs.

Customizable page templates

At runtime, the user's browser is directed to the appropriate page, depending on the operation being performed and where the related condition occurs. For example, if rule evaluation fails, the user's browser is directed to the policy error-handling page. The following table describes each template.

Template File Name Purpose Type Action

admin.error.page.template.html

Indicates an error occurred while the admin console was processing a request.

Error

Consult <PA_HOME>/log/pingaccess.log to determine the underlying cause of the issue.

general.error.page.template.html

Indicates that an unknown error has occurred and provides an error message.

Error

Consult <PA_HOME>/log/pingaccess.log to determine the underlying cause of the issue.

general.loggedout.page.template.html

Displayed when a user logs out of PingAccess.

Normal

User should close the browser.

oauth.error.json

Indicates that rule evaluation has failed and provides an optional error message. To customize this information, see Error-Handling Fields for OAuthOAuth A standard framework that enables an application (OAuth client) to obtain access tokens from an OAuth authorization server for the purpose of retrieving protected resources on a resource server. rules documentation.

Normal

If necessary, consult the audit logs in <PA_HOME>/log for details about why the policy denied the request.

policy.error.page.template.html

Indicates that rule evaluation has failed and provides an optional error message. To customize this information, see Error-Handling Fields for rules documentation.

Normal

If necessary, consult the audit logs in <PA_HOME>/log for details about why the policy denied the request.

System Templates

The templates stored in <PA_HOME>/conf/template/system are system templates. Do not modify these templates directly unless directed by Ping. This table shows the purpose and associated action, if any, for each of these files.

File Name Purpose Type Action

admin.loggedout.page.template.html

Displayed when a user completes a single logout (SLO)single logout (SLO)SLO The process of signing a user out of multiple sites where the user has started a single sign-on (SSO) session. initiated from the PingAccess admin console.

Normal

The user's session at the identity provider (IdP)identity provider (IdP)IdP A service that manages identity information and provides authentication services to relying clients or service providers (SPs) within a federated or distributed network. and the PingAccess administrative console has been terminated.

agent.bootstrap.template.properties

Used to generate the agent.properties file for an agent.

Normal

None

engine.bootstrap.template.properties

Used to generate the bootstrap.properties file for an engine.

Normal

None

fragment.preservation.request.html

Used to preserve the fragment from the requested URLURLURL (Uniform Resource Locator) Identifies a resource according to its Internet location. in client-side storage during a PingAccess OpenID Connect (OIDC)OpenID Connect (OIDC)OIDC An authentication protocol built on top of OAuth that authenticates users and enables clients (relying parties) of all types to request and receive information about authenticated sessions and users. OIDC is extensible, allowing clients to use optional features such as encryption of identity data, discovery of OpenID Providers (OAuth authorization servers), and session management. sign-on flow.

Normal

None

fragment.preservation.response.html

Used to restore the fragment from client-side storage for the originally requested URL when a PingAccess OIDCOpenID Connect (OIDC)OIDC An authentication protocol built on top of OAuth that authenticates users and enables clients (relying parties) of all types to request and receive information about authenticated sessions and users. OIDC is extensible, allowing clients to use optional features such as encryption of identity data, discovery of OpenID Providers (OAuth authorization servers), and session management. sign-on flow has completed.

Normal

None

invalid.token.json

Used to challenge a user agent for authentication when the user-agent specifies an Accept header field containing application/json.

Normal

The user agent interacts with the end user to obtain an OAuthOAuth A standard framework that enables an application (OAuth client) to obtain access tokens from an OAuth authorization server for the purpose of retrieving protected resources on a resource server. token.

post.preservation.request.html

Used to preserve the HTML form data from a POST request in client-side storage during a PingAccess OIDC sign-on flow.

Normal

None

post.preservation.response.encoded.html

Used to submit encrypted HTML form data to PingAccess from a previously preserved POST request when a PingAccess OIDC sign-on flow completes.

Normal

None

post.preservation.response.html

Used to reconstruct an HTML form to resubmit restored POST data when a PingAccess OIDC sign-on flow completes.

Normal

None

redirect.response.html

Used to redirect a browser to the token provider for authentication.

Normal

None

replica.bootstrap.template.properties

Used to generate the bootstrap.properties file for a replica admin.

Normal

None

site.authenticator.rst.xml

Used to produce a request to send to the PingFederate Security Token Service (STS)Security Token Service (STS)STS An entity responsible for responding to WS-Trust requests for validation and issuance of security tokens used for SSO authentication to web services. endpointendpoint One end in a communication channel, typically a URI. to exchange a PingAccess cookie or OAuth token for a Web Access Management (WAM) token.

Normal

None

unauthorized.response.html

Used to produce a challenge for authentication to an OAuth client running in a browser-based application.

Normal

None