Upload
doankhuong
View
370
Download
20
Embed Size (px)
Citation preview
© 2013 Ping Identity Corporation All Rights Reserved
PingAccess Documentation Home
PingAccess Documentation HomePingAccess is a centralized point of security and access control for Web applicationsand APIs, serving applications and other resources to clients outside an organizationwhile still protecting internal interfaces from unauthorized access. PingAccess sits atthe perimeter of a protected network, applying authorization decisions on inbound APIcalls and Web applications before relaying them to their back-end target endpoints.
Authorization and access control policies can be configured for service endpoints withinPingAccess, providing a single place to make and enforce access decisions. Thesedecisions can be based on the HTTP request context, including inspecting HTTPheaders, date and time, and OAuth scopes and identity attributes.
Out of the box integration with PingFederate leverages the existing OAuth AuthorizationServer and OpenID Connect Provider functionality to issue tokens suitable for securingAPIs and enabling SSO.
PingAccess Concepts
PingAccess Concepts
PingAccess sits between clients (such as browsers or native mobile applications) andResources you want to protect (such as Web applications and APIs). When PingAccessreceives a request, it is handled by a Resource that is mapped to a back-end protectedSite. Access control policies associated with that Resource are then applied to therequest. Once access is granted, the Resource directs the client request to the targetSite including any required Site authentication. This may be as simple as addingidentity-related information to HTTP headers or involving a more complexauthentication mechanism to tighten the security of the connection to the Site.
Resources represent Web applications or APIs to which a request is sent. Theyare defined as a path and virtual server and are mapped to a back-end Sitewhere the requests are fulfilled. Policies are applied to Resources to protectthem. Using the PingAccess administrative console, you define endpoints for theResource, associate a target Site with that Resource, and map policies to theResource that are applied to each request.
© 2013 Ping Identity Corporation All Rights Reserved
Sites are the locations of applications, endpoints, or APIs in your environmentthat you want to protect with PingAccess. Target Web Sites may limit access toonly authenticated clients. PingAccess can integrate with those security modelsusing Site Authenticators.
Policies are Rules applied to a Resource to provide access control and forrequest processing. You define Rules for how and when a client accessesprotected target Sites.
Web Access Management
Web Access Management
With growing numbers of internal and external users, and more and more enterpriseresources available online, it is important to ensure that qualified users can access onlythose resources to which they have permission. PingAccess uses Web accessmanagement (WAM) capabilities to allow organizations to manage access rights toWeb-based resources.
WAM is a form of identity management that controls access to Web resources,providing authentication and policy-based access management. Once a userauthenticates, PingAccess applies the Resource-level policies to the request. Oncepolicy evaluation is passed, any required identity mediation between the back-end Siteand the authenticated user is performed. The user is then granted access to the Site.
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
WAM Session Initiation
Processing Steps:
When a user requests a Web resource from PingAccess, PingAccess inspectsthe request for a .PA TokenIf the PA Token is missing, PingAccess redirects the user to an OpenID ConnectProvider (OP) for authentication.
When using an OP, an OAuth Client must already be configured inPingAccess. For steps on configuring an OAuth Client withinPingFederate, see . To then configure thatConfiguring a ClientOAuth Client within PingAccess, see the Web Session section onthe page.Connect to PingFederate
The OP follows the appropriate authentication process, evaluates domain-levelpolicies, and issues an OpenID Connect (OIDC) to PingAccess.ID TokenPingAccess validates the ID Token and issues a PA Token and sends it to thebrowser in a cookie during a redirect to the original target Resource. Upongaining access to the Resource, PingAccess evaluates Resource-level policiesand optionally audits the request.
© 2013 Ping Identity Corporation All Rights Reserved
4.
5.
6.
PingAccess can perform by exchanging the PAidentity mediationToken for the appropriate security token from the PingFederateSTS or from a cache (if identity mediation occurred recently).
PingAccess sends the request to the Site where the Web resource resides.PingAccess proxies the response from the Site to the browser (step not shown).
See the section for more information.Configure Web Session Settings
Application Scoped Web Sessions
Application Scoped Web Sessions
PingAccess Tokens can be configured to have their Web Sessions scoped to a specificapplication (effectively a set of defined Resources). This improves the security model ofthe session by preventing unrelated applications from impersonating the end user.
Several controls exist to scope the PA Token to an application:
Audience Attribute: The audience attribute defines who the token is applicableto and is represented as a short, unique identifier. Requests are rejected thatcontain a PA Token with an audience that differs from what is configured in theWeb Session associated with the target Resource.Audience Suffix: The audience attribute is also used as a suffix of the cookiename to ensure uniqueness--for example, PA.businessAppAudience.Cookie Domain: The cookie domain can also optionally be set to limit where thePA Token is sent.
In addition to these controls, parameters such as session timeout can beadjusted to match the policy requirements of each application.
Corresponding OAuth clients must be defined in PingFederate for each Web Session.Redirect URL whitelists defined in PIngFederate dictate from which servers anddomains the session can originate. Controlling this within PingFederate enablesflexibility of the attribute contract (and its fulfillment) for that particular application. Thisensures that each application and its associated policies only deal with attributesrelated to it.
© 2013 Ping Identity Corporation All Rights Reserved
Identity Mediation
Identity Mediation
The differing identity needs of Sites across an organization present a number ofchallenges. User identity and credential systems can vary widely, making the task ofmanaging and mapping identity difficult. PingAccess provides identity mediation toaddress these identity requirements.
PingAccess performs identity mediation by acquiring the appropriate security tokenfrom the PingFederate or from a cache (if identity mediation occurred recently).STSThe STS provides security-token validation and creation, exchanging the orPA Tokenan OAuth Bearer Token for the appropriate security token--for example, Oracle AccessManager, OpenToken, or custom tokens. The token exchanged depends on which SiteAuthenticator is configured for the Site within PingAccess. defineSite Authenticatorsthe type of authentication the Site requires.
The following Site Authenticators integrate with a variety of security models, including:
HTTP Basic AuthenticationMutual TLSOAuth Access TokenOpenTokenWeb Access TokensWeb Session Header
Identity Mediation Flow
The following illustration shows an example of identity mediation using PingFederate toexchange a PA Token or OAuth Bearer Token for a different security token.
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
Processing Steps:
A user requests a Resource from PingAccess with a PA Token or OAuth BearerToken.
This example assumes the user has already obtained a PA Tokenor OAuth Bearer Token. See or Web Access Management Using
for details on how usersthe OAuth Authorization Serverauthenticate with PingFederate and obtain a PA Token or OAuthBearer Token.
PingAccess evaluates resource-level policies and performs identity mediation byacquiring the appropriate security token from the PingFederate STS (shown inthe diagram) or from a cache (if identity mediation occurred recently) specified bythe Site Authenticator.PingAccess sends the request to the Site (Web application) with the appropriatetoken.PingAccess returns the response to the client (not shown).
Virtual Hosts
Virtual Hosts
Virtual Hosting enables you to host multiple server or domain names. This allows oneserver to share Resources without requiring all Sites on the server to use the same host
© 2013 Ping Identity Corporation All Rights Reserved
name--for example, you may want to use multiple names on the same server so thateach Site name reflects the services offered rather than the actual server name wherethose Sites are hosted.
PingAccess supports virtual hosting by serving requests bound for a set of definedserver names and mapping them to requested Resources. The target host headerpresented by the client can optionally be rewritten with the appropriate back-end hostname.
For example, say the host configured for Site One is . You configurehr121.internal:80Resource One to use a virtual host of . You associate Site Onehr.mycompany.com:80with Resource One. PingAccess listens for incoming requests for the Site at
. When a client request comes in to ,hr.mycompany.com:80 hr.mycompany.com:80PingAccess sees the request, looks at the name of the domain configured for theback-end Site, and replaces the target Host header with .hr121.internal:80
Resource Evaluation
Resource Evaluation
Resources represent Web applications or APIs to which a request is sent. They aredefined as a path and virtual server and are mapped to a back-end where theSiterequests are fulfilled. Using the PingAccess administrative console, you defineendpoints for the Resource, associate a target Site with that Resource, and mappolicies to the Resource. These configurations are taken into account when a requestcomes in.
The order of the Resources is significant in that when a request comes in, the firstmatching Resource it finds is the Resource used and all other Resources are ignored.For example, a request comes in attempting to match to a path of . Three/barResources are configured and are in the following order:
Resource One
path - /foo
Resource Two
path - /
© 2013 Ping Identity Corporation All Rights Reserved
Resources Three
path - /bar
The request comes in and evaluates Resource One and finds no match. The requestcontinues to Resource Two and because the path for Resource Two is more general,that Resource is matched and all other Resources in the list are ignored. Resourceswith finer-grained configurations should be placed higher up in the Resource list andthose Resources with a wider-scope configuration should be placed lower in the list.For example, ordering the above Resources in the following way allows you to arrive ata very specific processing order and match the correct Resource to the incomingrequest of :/bar
Resource One
path - /foo
Resource Two
path - /bar
Resources Three
path - /
The request comes in and evaluates Resource One and finds no match. The requestcontinues to Resource Two, finds a match, and uses that Resource.
Clustering
Clustering
PingAccess provides clustering features that allow a group of PingAccess servers toappear as a single system. When deployed appropriately, server clustering canfacilitate high availability of critical services. Clustering can also increase performanceand overall system throughput. It is important to understand, however, that availabilityand performance are often at opposite ends of the deployment spectrum. Thus, youmay need to make some configuration tradeoffs that balance availability withperformance to accommodate specific deployment goals.
In a cluster, you can configure each PingAccess engine, or node, as either an
© 2013 Ping Identity Corporation All Rights Reserved
administrative console or a runtime engine in the file. Runtime enginesrun.propertiesservice client requests, while the console server administers policy and configuration forthe entire cluster (via the administrative console). A cluster may contain one or moreruntime nodes, but only one console node. Server-specific configuration data is storedin the PingAccess administrative console server in the file. Informationrun.propertiesneeded to bootstrap an engine is stored in the file on each engine.bootstrap.properties
At startup, a PingAccess engine node in a cluster checks its local configuration andthen makes a call to the administrative console to check for changes. How often eachengine in a cluster checks the console for changes is configurable in the engine
file.run.properties
Configuration information is replicated to all engine nodes. By default, engines do notshare runtime state. For increased performance, you can configure engines to shareruntime state by configuring cluster interprocess communication using the
file (see ).run.properties Cluster Configuration Settings
Runtime state clustering consists solely of a shared cache of securitytokens acquired from the PingFederate STS for useIdentity Mediationcases using the .Token Mediator Site Authenticator
Related Topics
Configure PingAccess Servers Into a Cluster
Using the OAuth Authorization Server
Using the OAuth Authorization Server
PingAccess supports the and the Bearer Token Security Model Validation Grant Typeextension grant and uses an OAuth AS in the following ways:
Works with OAuth Authorization Servers such as the PingFederate toOAuth ASauthorize access to protected Resources.
Protects Resources by requiring an OAuth bearer access token (see Section 2.1of RFC 6750 for supported token transport details).
Acts as an OAuth Resource Server, requesting validation from the OAuth AS forthe bearer access token it receives from a client making a protected-resources
© 2013 Ping Identity Corporation All Rights Reserved
call. The OAuth AS validates the access token and sends token attributes toPingAccess, which evaluates the returned OAuth details against policies set by
.mapping Rules to Resources
Grants access to a Resource based on the use of Rules in combination with theOAuth AS validation.
Groovy
Groovy
PingAccess provides the and Rule types thatGroovy Script OAuth Groovy Scriptenable the use of Groovy, a dynamic programming language for the Java VirtualMachine (see the ). Groovy scripts provide advanced Rule logicGroovy documentationthat extends PingAccess Rule development beyond the capabilities of the packaged
. Groovy scripts have access to important PingAccess runtime objects suchRule Setsas the and objects, which the scripts can interrogate andExchange PolicyContextmodify. Groovy Script Rules are invoked during the request processing phase of anexchange, allowing the script to modify the request before it is sent to the server.Groovy Script Rules are also invoked during the response, allowing the script to modifythe response before it is returned to the client. The diagram below highlights the flow ofRule processing.
© 2013 Ping Identity Corporation All Rights Reserved
During request processing, Rules associated with the are evaluated.ResourceThe request passes through each of the Rules sequentially until it is sent to the
.SiteWhen the response from the returns to PingAccess, the Groovy Rules areSiteevaluated.
See the section for more information.Groovy Scripts
Getting Started
Getting Started
To get started with PingAccess, follow the instructions throughout this section. Being agateway, you would deploy PingAccess in line between your clients and the Web andAPI assets you want to protect and audit. Attention to network design is important toensure that your applications are properly secured (see Use Cases and Deployment
).Architecture
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
To automatically configure PingAccess for demonstrating its basefunctionality, use the PingAccess Quick-Start Application (see the
page).Downloads
To get started with PingAccess:
Install the Oracle JDK if it isn't installed already.Install and start PingAccess on either Windows, Linux, or Mac.Optional. in the file.Change the configuration parameters run.propertiesConfigure within PingAccess. What items you configure first depends onsettingsyour deployment plans.
For help in successfully configuring PingAccess to meet your use case,see .Configuration by Use Case
System Requirements
System Requirements
PingAccess is certified as compatible for deployment and configuration with theminimum system specifications defined below.
Supported Platforms
Windows 2008 Server R2 SP1Windows 2012 Server StandardRed Hat Enterprise Linux ES 5.10Red Hat Enterprise Linux ES 6.4SUSE Linux Enterprise 11 SP3
Java Runtime Environment
Oracle Java 7 update 40 (64-bit)
Supported PingFederate
PingFederate 7.1PingFederate 7.1 R2 (for Authentication Rules support)
Minimum Hardware Requirements
© 2013 Ping Identity Corporation All Rights Reserved
Although it is possible to run PingAccess on less powerful hardware, thefollowing guidelines accommodate disk space for default logging andauditing profiles and CPU resources for a moderate level of concurrentrequest processing.
4 CPU/Cores2 GB of RAM2.1 GB of available hard drive space
Minimum Hardware Recommendations
Multi-CPU/Cores (8 or more)4 GB of RAM2.1 GB of available hard drive space
Supported Browsers
For the PingAccess administrative console:
ChromeFirefoxInternet Explorer (version 9 and higher)
For the end-user desktop:
ChromeFirefoxInternet Explorer (version 8 and higher)Safari
Supported Mobile Client Environments
Android 4.0iOS 7
Audit Event Storage (External Database)
Oracle 11g R2
Install the Oracle JDK
Install the Oracle JDK
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
1.
2.
3.
4.
5.
Oracle Java version 7 of the JDK (update 25 or higher) provides the supportedenvironment for PingAccess.
You must install the Oracle JDK before installing PingAccess.
To install the Oracle JDK for Windows and Linux:
Download and install Oracle JDK version 7 from: .www.oracle.com/technetwork/java/javase/downloads
Set the environment variable to the JDK installation directory path.JAVA_HOMESet the variable at either the system or user level.
Install PingAccess
Install PingAccess
Install PingAccess by extracting the distribution ZIP file.
On Linux you must install and run PingAccess under a local user(non-root) account.
To install PingAccess:
Ensure you are logged on to your system with appropriate privileges to installand run an application.Verify that the JDK is installed and that environment and PATH variables are setcorrectly (see ).Installing the Oracle JDKExtract the distribution ZIP file into an installation directory.Request a license key via the Ping Identity licensing Web page(www.pingidentity.com/support-and-downloads/ ).licensing.cfmSave the license key file in the directory:
<pa_install>/conf
PingAccess does not start without a current license key file storedin the directory./conf
Ensure the file is named:
pingaccess.lic
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
1.
2.
3.
4.
5.
6.
If you are deploying PingAccess in a cluster configuration, see Configure.PingAccess Servers into a Cluster
To uninstall PingAccess (on Windows or Linux):
Make sure that PingAccess is not running (see ).Start and Stop PingAccessDelete the PingAccess installation directory.
Running PingAccess as a Service
You can set up PingAccess to run in the background as a service on Windows running64-bit processors.
Before performing this procedure, ensure that PingAccess runs normallyby manually starting the server (see ).Run PingAccess for the First Time
This installation enables PingAccess to start automatically when Windows is started orrebooted.
To run PingAccess as a Windows service:
Complete the steps above to install PingAccess.
Ensure is set as a system variable (see JAVA_HOME Install the).Oracle JDK
Ensure you are logged on with full Administrator privileges.Start or as an Administrator.PowerShell Command PromptIn or , run the file located in PowerShell Command Prompt install-service.bat
.<pa_install>\sbin\windowsAccess the Windows | | .Control Panel Administrative Tools ServicesRight-click from the list of available services and select PingAccess Service
.Start
The service starts immediately and restarts automatically on reboot. (You canchange the default setting in the dialog.)Start type Properties
Run PingAccess for the First Time
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
5.
Run PingAccess for the First Time
Start PingAccess by running the following script:
(Windows) <pa_install>\bin\run.bat
(Linux) <pa_install>\bin\run.sh
The script requires . To install on SUSE, execute therun.sh bc bcfollowing command: zypper install bc
Wait for the script to finish the startup---The server is started when you see themessage “ ” in the command window.PingAccess running...
If you are using the PingAccess Quick-Start Application, at thispoint there are initialization steps for completing your setup. Seethe Quick-Start Application's ReadMeFirst for more information.
If you have not yet installed a PingAccess license, the server doesnot start up (see for information on obtaining aInstall PingAccesslicense).
Launch your browser and go to:
https://<DNS_NAME>:9000
where is the fully-qualified name of the machine running<DNS_NAME>PingAccess.
Log on with the default username and password supplied with the distribution.
Username: Administrator
Password: 2Access
Read and accept the license agreement.Change the default administrator password on the screen andFirst Time Loginclick .Continue
The new password must be at least six characters and contain atleast one uppercase, one lowercase, and one numeric character.
The PingAccess administrative console appears.
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
1.
2.
1.
2.
Start and Stop PingAccess
Start and Stop PingAccess
Linux
To start PingAccess:
From a command prompt, change directories to .<pa_install>\binExecute the shell script.run.sh
Wait for the script to execute. The server is started when you see the message“PingAccess running...” in the command window.
To shut down PingAccess:Enter in the terminal window.Ctrl+C
Windows
To start PingAccess:
From the > dialog or a command prompt, run the batch file:Start Run
<pa_install>\bin\run.bat
Or:
Open the folder within your PingAccess installation and double-click the bin file.run.bat
Wait for the script to execute.
The server is started when you see the message “PingAccess running...” in thecommand window.
To shut down PingAccess:
Enter in the command-prompt window.Ctrl+CEnter to terminate the batch script when prompted.y
All Platforms
To access the PingAccess administrative console:Launch a Web browser and go to this location:https://<DNS_NAME>:<PORT>where:
<DNS_NAME> is the fully-qualified name of the machine running the PingAccessserver.
<PORT> is the port where the administrative console listens. The default port is
© 2013 Ping Identity Corporation All Rights Reserved
.9000
Configuration by Use Case
Configuration by Use Case
Your next configuration steps depend on what type of deployment you areimplementing. The following sections describe best practices in designing yourarchitecture by .use case
API Access Management DeploymentWeb Access Management DeploymentAuditing and Proxying Deployment
Next Steps
Once you complete the above configuration settings:
Configure the you want to protect.SitesConfigure for your back-end Sites.Site AuthenticatorsConfigure and create for them.Resources Policies
API Access Management Deployment
API Access Management Deployment
The following section describes the important configuration options for deploying an APIGateway (see for specific use caseDeploying for API Access Managementinformation).
Step Description
Configure the connectionto the PingFederateOAuth AuthorizationServer.
PingAccess uses this connection and credentials tovalidate incoming Access Tokens for securing API calls.
Configure the ResourceServer OAuth Client.
The client must be registered with PingFederate and theclient credentials configured in PingAccess to authenticatePingAccess when validating incoming Access Tokens.
© 2013 Ping Identity Corporation All Rights Reserved
Generate or Import KeyPairs and configure
.HTTP Listeners
Defines the certificates and keys used to secure access tothe PingAccess administrative console and secureincoming HTTPS requests at runtime.
Set up your cluster forhigh availability.
Facilitates high availability of critical services, andincreases performance and overall system throughput.
Add trusted CAcertificates.
Defines trust to certificates presented during outboundsecure HTTPS connections.
Create a trustedcertificate group.
Provides a trusted set of anchor certificates for use whenauthenticating outbound secure HTTPS connections.
Define virtual servers forprotected Resources.
Allows one server to share PingAccess Resources withoutrequiring all Sites on the server to use the same hostname.
Web Access Management Deployment
Web Access Management Deployment
The following section describes the important configuration options for a Web AccessManagement deployment (see for specific useDeploying for Web Access Managementcase information).
Step Description
Configure theconnection to thePingFederate OAuthAuthorization Server.
PingAccess uses this connection and credentials to validateincoming Access Tokens for securing Web-based Resourcerequests.
Configure the OpenIDConnect RelyingParty Client forPingAccess.
The client must be registered with PingFederate and theclient credentials configured in PingAccess to identifyPingAccess when requesting authentication for users trying toaccess Web applications.
Configure Websession details toenable protection ofWeb Resources.
Configures settings for secure Web sessions such as timeoutvalues, cookie parameters, and cryptographic algorithms.
© 2013 Ping Identity Corporation All Rights Reserved
Generate or ImportKey Pairs and configure HTTP
.Listeners
Defines the certificates and keys used to secure access tothe PingAccess administrative console and secure incomingHTTPS requests at runtime.
Set up your cluster forhigh availability.
Facilitates high availability of critical services, and increasesperformance and overall system throughput.
Add trusted CAcertificates.
Defines trust to certificates presented during outbound secureHTTPS connections.
Create a trustedcertificate group.
Provides a trusted set of anchor certificates for use whenauthenticating outbound secure HTTPS connections.
Define virtual serversfor protectedResources.
Allows one server to share PingAccess Resources withoutrequiring all Sites on the server to use the same host name.
Auditing and Proxying Deployment
Auditing and Proxying Deployment
The following section describes the important configuration options for an auditing orproxying deployment (see for specific use caseDeploying for Auditing and Proxyinginformation).
Step Description
Generate or Import KeyPairs and configure
.HTTP Listeners
Defines the certificates and keys used to secure access tothe PingAccess administrative console and secure incomingHTTPS requests at runtime.
Set up your cluster forhigh availability.
Facilitates high availability of critical services, and increasesperformance and overall system throughput.
Add trusted CAcertificates.
Defines trust to certificates presented during outboundsecure HTTPS connections.
Create a trustedcertificate group.
Provides a trusted set of anchor certificates for use whenauthenticating outbound secure HTTPS connections.
© 2013 Ping Identity Corporation All Rights Reserved
Define virtual serversfor protectedResources.
Allows one server to share PingAccess Resources withoutrequiring all Sites on the server to use the same host name.
Configuring PingAccess
Configuring PingAccess
Setting up PingAccess for the first time involves several steps:
Configure PingAccess Settings
Connect to a Site
Configure Site Authenticators
Configure a Resource
Define Rules
Map Rules to Resources
Configure PingAccess Settings
Configure PingAccess Settings
The PingAccess Settings pages provide access to a number of globalsettings. Where you go next depends on what type of deployment you are
implementing.
For help in successfully configuring PingAccess to meet your use case,see .Configuration by Use Case
Click a link below for more information:PingFederate---Use this page to configure the connection to the PingFederate OAuthAuthorization Server (AS), to identify the OAuth client for use with PingAccess Websessions, and to identify the PingAccess OAuth client for validating access tokens.Virtual Hosts---Use this page to define the host names of servers where Resourcesare running.Cluster---Use this page to define the administrative console node and to set up engine
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
5.
nodes and grant them access to the administrative console node.Admin Authentication---Use these pages to change the default PingAccessadministrator authentication method.Web Session---Use these pages to configure secure Web Sessions for use withspecific applications and to configure global Web Session settings.Key Pairs---Use this page to manage, import, and generate Key Pairs.HTTPS Listeners---Use this page to assign a Key Pair to a configured HTTPSListener.Certificates---Use this page to import and manage certificates and create and managetrusted certificate groups.Authentication Requirements---Use this page to identify how a user mustauthenticate before access is granted to a protected Web Resource.
Connect to PingFederate
Connect to PingFederate
Use this page to configure the connection to the PingFederate OAuthAuthorization Server (AS) or to identify the Resource Server OAuth client for
validating access tokens (API Access Management use cases).
Expand a section below for configuration steps.
PingFederateTo configure the connection to the PingFederate OAuth AS:
For information on setting PingFederate up as an OAuth AS, see and in theEnabling the OAuth AS Authorization Server Settings
PingFederate documentation.
Enter the name or IP address where PingFederate is running.HostEnter the number for PingFederate.PortSelect the checkbox to log information about the transaction to theAuditaudit store. PingAccess audit logs record a selected subset of transaction loginformation at runtime and are located in the directory of your/logsPingAccess installation (see ).Security Audit LogSelect the checkbox if the Site is expecting HTTPS connections.SecureFrom the list, select the toTrusted Certificate Group group of certificatesuse when authenticating to PingFederate. PingAccess requires that the
© 2013 Ping Identity Corporation All Rights Reserved
5.
1.
2.
3.
certificate in use by PingFederate anchor to a certificate in the associatedTrusted Certificate Group. This field is available only if you select the Securecheckbox.
Once you save this configuration and configure the PingAccessOAuth Resource Server (see the OAuth Resource Serversection, below), a PingFederate Access Validator is available forselection when you define .OAuth-type Rules
OAuth Resource ServerWhen receiving OAuth-protected API calls, PingAccess acts as an OAuth ResourceServer, checking with the PingFederate OAuth AS on the validity of the beareraccess token it receives from a client. In order to validate the token, a valid OAuthclient must exist within the PingFederate OAuth AS. To enter PingAccess OAuthClient settings configured in PingFederate:
This configuration is optional and needed only if you plan to validatePingFederate OAuth access tokens.
You must configure a connection to the PingFederate OAuth ASinstance you plan to use (see the PingFederate section, above).
Enter the unique identifier ( ) assigned when you created theClient IDPingAccess OAuth client within PingFederate (for more information, see
in the PingFederate documentation). PingAccessConfiguring a Clientprovides this information in order to identify itself. This information is includedwith every request PingAccess makes.
When you configure an OAuth client within PingFederate, besure to select as the allowed grantAccess Token Validationtype.
Enter the secret ( ) assigned when you created the PingAccessClient SecretOAuth client within PingFederate.Select the checkbox to retain token details for subsequentCache Tokensrequests. This option reduces the communication between PingAccess and
© 2013 Ping Identity Corporation All Rights Reserved
3.
4.
1.
2.
3.
4.
PingFederate.In the box, enter the attribute you want to use fromSubject Attribute Namethe OAuth access token as the subject for auditing purposes--for example,
. At runtime, the attribute’s value is used as the Subject field in auditusernamelog entries for API Resources with policies that validate access tokens. Theattribute must align with an attribute in the OAuth access token attribute
defined within PingFederate.contract
Configure Virtual Hosts
Configure Virtual Hosts
Virtual Hosting enables you to host multiple server or domain names. Thisallows one server to share Resources without requiring all Sites on the server to usethe same host name--for example, you may want to use multiple names on the sameserver so that each Site name reflects the services offered rather than the actual servername where those Sites are hosted. Use the Virtual Hosts Settings page to define thevirtual host names you want to use with Resources.
You can use wildcards when defining virtual hosts. For example, you have a domainhost and port of . You create a virtual host using wildcards suchhr.mycompany.com:80as . A user requests . The request goes to . This*:80 finance.mycompany.com:80 *:80allows you to funnel any virtual hosts that do not fall within a specific one.
When you configure virtual hosts and the back-end Site is expectingHTTPS, a secure channel between the client and PingAccess must bemediated before PingAccess can adjust the Target Host header. Becausethe SSL/TLS handshake takes place before the expected hostname issent to the server, the server does not know which certificate to present.Use a single certificate that covers multiple names either throughwildcards or the .SubjectAltName extension
To configure a Virtual Host:
Specify the host name and port for which PingAccess is accepting requests---forexample, .hr.mycompany.com:80Click to add it.Click to edit a Virtual Host.
© 2013 Ping Identity Corporation All Rights Reserved
4.
1.
2.
3.
4.
5.
6.
Click to delete a Virtual Host.
Define the Admin Console and Runtime Engine Nodes
Define the Administrative Console and Runtime Engine Nodes
Use this page to define the administrative console node and to set up enginenodes and grant them access to the administrative console node.
Engine Nodes
Define the runtime engine nodes you want to have access to and communicate with theadministrative console.
Set Up an Engine NodeFor each engine node:
Click on the right to configure a new node.NEW ENGINE NODEEnter a for the node. Special characters and spaces are allowed.NameEnter a of the node.DescriptionClick to generate and download a public and privateSAVE & DOWNLOADkey pair into the file for the node. This file is prependedbootstrap.propertieswith the name you give the engine node. Depending on your browserconfiguration, you may be prompted to save the file.
PingAccess automatically populates the Public Keys field onceyou click .Save & Download
Copy each file to the directory of the corresponding engine<pa_install>/confnode in the cluster and rename to . The node uses thisbootstrap.propertiesfile to gain access to and communicate with the administrative console forconfiguration updates.
Generate a new key for an engine at any time by clicking SAVE and replacing the old file& DOWNLOAD bootstrap.properties
with a new one. When that engine starts up and begins usingthe new file, PingAccess deletes the old key.
Start each node.
© 2013 Ping Identity Corporation All Rights Reserved
6.
1.
2.
3.
4.
1.
2.
3.
4.
1.
2.
3.
1.
For information on configuring engine nodes to shareinformation with each other in a cluster, see Configure
.PingAccess Servers into a Cluster
Edit an Engine Node
Access the page by selecting from the menu bar of theCluster SettingsPingAccess administrative console.Click for the Engine Node you want to edit and click Edit. The EditEngine Node page appears.Make your edits.Click .SAVE
Remove an Engine Node's Access to the Administrative Console
Access the page by selecting from the menu bar of theCluster SettingsPingAccess administrative console.Click for the Engine Node you want to edit and click Edit. The EditEngine Node page appears.Click in the Public Keys box to revoke engine access to the administrativeconsole.
Use the SAVE & DOWNLOAD button to create a new key forthe engine. See the steps for setting up a PingAccess enginenode above.
Click .SAVE
Remove an Engine Node
Access the page by selecting from the menu bar of theCluster SettingsPingAccess administrative console.Click for the Engine Node you want to delete and click Delete topermanently remove all references to the engine from the cluster.Click in the confirmation window.DELETE
Administrative Node
Define the PingAccess server you want to use as the administrative console.
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
Enter the host and port for the administrative console. The default is .localhost:9000
Click when you finish.SAVE
Define Admin Authentication Settings
Define Administrator Authentication Settings
The default PingAccess administrator authentication method used to protectthe administrative console is basic authentication (username and password).
Change the default method to any PingAccess supported authentication method usingthe Admin Authentication Settings page.
We recommend changing the default administrator authentication methodto , leveraging the OpenID ConnectSingle Sign-On (SSO) AuthenticationProvider (OP) features of PingFederate to manage multipleadministrators.
Basic Authentication – The authentication default for the PingAccess administrativeconsole is HTTP Basic Authentication. Basic Authentication uses the Authorizationheader to transmit the username and password credentials. The PingAccess serverresponse contains a cookie, which is a signed . SubsequentPA_UI JSON Web TokenHTTP requests use the cookie for authentication rather than the less secure BasicHTTP Authorization header. Basic Authentication supports one user – Administrator. Tochange the Administrator password, click and click Edit to access the Basic
page.Authentication
– Administrators can authenticate to the PingAccessSingle Sign-On (SSO)administrative console using SSO. PingAccess SSO leverages the OpenID ConnectProvider (OP) features of PingFederate, allowing you to use an existing identity storesuch as a corporate LDAP directory to manage one or more administrators. The valueof the provided during login is saved in the cookie, which is sent withID Token PA_UIeach subsequent HTTP request. For steps on how to configure SSO for PingAccess,click and click Edit to access the page.Single Sign-On (SSO) Authentication
– Administrators can enable API authentication using OAuth access tokens for useAPIby scripts or other autonomous systems. This allows you to access the PingAccessAdministrative API using third-party network operation control software or other
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
administrative consoles. For example, you may have a custom program thatpre-provisions Site/Resource/Rule configurations for newly deployed Web applicationswithin your enterprise environment. To authorize the calls your program makes to theAdministrative API, you must configure an OAuth client for validating access tokens.Click and click Edit to access the page to configure the OAuthAPI Authenticationclient for PingAccess.
For more information on the PingAccess Administrative API, see theinteractive documentation at: https://<host>:<port>/admin/api-docs/
Basic Authentication
Basic Authentication
Use this page to change the PingAccess Administrator password used withBasic Authentication.
To change the PingAccess Administrator password:
Enter the current administrator password in the box.Current PasswordEnter the new administrator password in the .New PasswordEnter the new password again to confirm it in the box.Confirm PasswordClick .SAVE
The new password must be at least six characters and contain atleast one uppercase, one lowercase, and one numeric character.
Single Sign-On (SSO) Authentication
Single Sign-On (SSO) Authentication
This page provides example configuration information for enabling SingleSign-On (SSO) for PingAccess administrators. There are several
configuration steps required within the PingFederate Authorization Server (AS) as wellas PingAccess that you must complete to enable SSO. Expand a section to view thoseconfigurations.
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
When you enable SSO Authentication, administrative timeouts arecontrolled by the following settings in the run.properties file:
, , and pa.ui.idleExpirationInMinutes pa.ui.maxExpirationInMinutes (see ).pa.ui.expirationWarningInMinutes Change Configuration Properties
To define a fall back administrator authentication method shouldPingAccess be unreachable, enable the property in theadmin.auth=native
file. This overrides any configured administrativerun.propertiesauthentication to .Basic Authentication
Configuring PingAccessUse the Single Sign-On (SSO) Authentication page in PingAccess to enter the ClientID for the OAuth Client you created in the PingFederate AS.
Be sure to complete the configuration for connecting to thePingFederate OAuth AS on the page as wellConnect to PingFederateas completing the steps below.
To configure SSO Authentication in PingAccess:
Enter the unique identifier ( ) assigned when you created the OAuthClient IDclient for use with SSO (for more information, see in theConfiguring a ClientPingFederate documentation).Select to activate SSO Authentication.EnabledClick when you finish.SAVE
Configuring PingFederateTo enable administrator SSO to PingAccess, configure the following settings within
the PingFederate AS. Click the icon ( ) next to each section heading to access
additional configuration information--for example, click next to Roles and to open a new window and view the Choosing Roles and Protocols pageProtocols
of the PingFederate documentation.
© 2013 Ping Identity Corporation All Rights Reserved
The information below is an example configuration and does not coverall required steps for each PingFederate OAuth Settings pagediscussed, only fields necessary for successful SSO to the PingAccessadministrative console. Fields not mentioned are not necessary for thisconfiguration (see for configurationUsing OAuth Menu Selectionsdetails of the PingFederate OAuth Settings pages).
You must complete the configuration for connecting to thePingFederate OAuth AS instance you plan to use (see Connect to
).PingFederate
Roles and Protocols
Enable the OAuth 2.0 AS role and the OpenID Connect protocol.Enable the IdP Provider role and a protocol.
Password Credential Validator (PCV)
Create a PCV for authenticating administrative users.
Adapters
Create an HTML Form IdP Adapter and specify the PCV you configured.
Authorization Server Settings
Select in the Reuse Existing Persistent Access Grants for GrantImplicitTypes section.
Access Token Management
Select as the Access TokenInternally Managed Reference TokensManagement Type.Extend the contract by adding the Username attribute on the Access TokenAttribute Contract page.
OpenID Connect Policy Management
© 2013 Ping Identity Corporation All Rights Reserved
We recommend creating an OpenID Connect Policy to use specificallyfor PingAccess administrative console authentication.
Delete all of the attributes that appear in the Extend the Contract section ofthe Attribute Contract page. The only required attribute is .subSelect as the Source and as the Value on theAccess Token UsernameContract Fulfillment page.
Client Management
We recommend creating a Client to use specifically for PingAccessadministrative console authentication.
Select for Client Authentication.NoneAdd the location of the PingAccess host as a Redirect URI.
For example: https://localhost:9000/*
Select as an Allowed Grant Type.ImplicitSelect one of the elliptic curve ( ) algorithms as the OpenID ConnectECDSAID Token Signing Algorithm and select the OpenID Connect Policy to use forPingAccess administrative console authentication.
IdP Adapter Mapping
Map the HTML Form IdP Adapter Username value to the USER_KEY and theUSER_NAME contract attributes for the persistent grant and the user'sdisplay name on the authorization page, respectively.
Access Token Mapping
Map values into the token attribute contract by selecting asPersistent Grantthe Source and as the value for the Username attribute. TheseUSER_KEYare the attributes included or referenced in the access token.
API Authentication
API Authentication
Use this page to configure an OAuth Client for use when making API calls tothe PingAccess administrative console using, for example, a script. These
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
1.
2.
3.
1.
API calls are authorized using OAuth access tokens issued by PingFederate.
You must configure a connection to the PingFederate OAuth AS instanceyou plan to use (see ).Connect to PingFederate
To configure API Authentication:
Enter the unique identifier ( ) assigned when you created the OAuthClient IDclient for validating OAuth access tokens (for more information, see Configuring a
in the PingFederate documentation).ClientEnter the secret ( ) assigned when you created the OAuth client forClient Secretvalidating OAuth access tokens (for more information, see inConfiguring a Clientthe PingFederate documentation).Enter the required to successfully access the API--for example, .Scope adminFor more information, see for defining scopes.Authorization Server SettingsSelect to activate API Authentication.Enabled
Configure Web Session Settings
Configure Web Session Settings
Web Sessions define the policy for Web application session creation, lifetime,timeouts, and their scope. Multiple Web Sessions may be configured to
scope the session to meet the needs of a target set of . This improves theResourcessecurity model of the session by preventing unrelated applications from impersonatingthe end user. Use this page to configure secure Web Sessions for use with specificapplications and to configure global Web Session settings.
Manage Web SessionsThis section provides steps for creating, editing, and deleting Web Sessions.To create a new Web Session:
On the Web Session page, click . The NEW WEB SESSION New Web page appears.Session
Enter the requested information on the form.Click . A new card appears for the Web Session on the Web SessionSAVEPage.
To edit a Web Session:
Click on the Web Session you want to edit and click Edit. The Edit Web
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
1.
2.
Session page appears.Make your edits.Click .SAVE
To delete a Web Session:
Click on the Web Session you want to delete and click Delete.Click in the confirmation window.DELETE
If the Web Session is currently associated with a Resource, youcannot delete it.
Manage Global Web Session SettingsThe table below describes the fields for configuring global Web Session settings.
Field Description
Number ofKeys toCache
Indicates the number of keys you want to keep in history forvalidation (the default is ).3Enter how many keys you want to remain valid. For example, if youwant to cache three keys and the key roll interval is every 24 hours,once a key rolls, the previous key is valid for 48 more hours.
SigningKey RollInterval(Hours)
Indicates how often (in hours) PingAccess rolls the signing andencryption keys.Enter how often you want to roll the keys (the default is hours).24Key rollover updates keys at regular intervals to ensure the securityof signed and encrypted .PA Tokens
Issuer A published, unique identifier to be used with the Web session (Thedefault is PingAccess).For example, set the issuer to a value that more closely representsyour company. PingAccess inserts this value as the claim withinissthe PA Token.
© 2013 Ping Identity Corporation All Rights Reserved
SigningAlgorithm
The algorithm used to protect the integrity of the PA Token (thedefault is ).ECDSA using P-256 CurveSelect the signing algorithm you want to use from the list.PingAccess uses the algorithm when creating signed PA Tokens andwhen verifying signed tokens in a request from a user’s browser. Thealgorithm is also used for signing tokens in useIdentity Mediationcases when PA Tokens are encrypted.
EncryptionAlgorithm
The algorithm used to encrypt and protect the integrity of the PAToken (the default is ).AES 128 with CBC and HMAC SHA 256Select the encryption algorithm you want to use from the list.PingAccess uses the algorithm when creating encrypted PA Tokensand when verifying them from a user’s browser.
Higher encryption levels are available if theadministrative console supports it. To enable higherencryption levels, update the administrative consoleJRE to support unlimited strength security policy.
In a clustered environment, be sure to add the securitypolicy changes to the engines as well as theadministrative console for the cluster.
CookieName
The name of the browser cookie to contain the PA Token (the defaultis ).PAEnter a name for the browser cookie.
Create a Web Session
Create a Web Session
Use this page to create a new Web session.
The table below describes the fields used to configure a Web Session. Click SAVEwhen you finish. A new Web Session card appears on the Web Session page.
Field Description
© 2013 Ping Identity Corporation All Rights Reserved
Name The Web Session name.Enter a unique name. Up to 64 characters, including special charactersand spaces, are allowed. This name appears in the Web Session list onthe page.New Resource
CookieDomain
The valid domain where the cookie is stored.Enter a valid domain for the cookie--for example,
.corp.yourcompany.com
If you set the Cookie Domain, all of your Web Resourcesmust reside within that domain. If you do not set theCookie Domain, the is recreated for each hostPA Tokendomain where you access Resources.
CookieType
The type of token you want to create.An token (default) uses authenticated encryption toEncrypted JWTsimultaneously provide confidentiality, integrity, and authenticity of thePA Token.A token uses asymmetric cryptography with aSigned JWTprivate/public key pairing to verify the signed message and to confirmthat the message was not modified during transit.
Audience Defines who the PA Token is applicable to and is represented as ashort, unique identifier.Enter a unique identifier between 1 and 32 characters.Requests are rejected that contain a PA Token with an audience thatdiffers from what is configured in the Web Session associated with thetarget Resource.
© 2013 Ping Identity Corporation All Rights Reserved
OpenIDConnectLoginType
Defines how the user’s identity is verified based on authenticationperformed by an OpenID Provider and how additional profile claims areobtained. Two login profiles are supported: and .Code POSTSelect a login profile.
CodeA standard OpenID Connect login flow that provides confidentiality forsensitive user claims. In this profile the relying party (PingAccess)makes multiple back-channel requests in order to exchange anauthorization code for an ID Token and then exchange an access tokenfor additional profile claims from the UserInfo endpoint at the provider(PingFederate). This login type is recommended for maximum securityand standards interoperability.
POSTA login flow based on OpenID Connect that passes claims from theprovider via the browser. Be sure to select the grant type whenImplicitconfiguring the OAuth Client within PingFederate (see Configuring a
). A form auto-POST response containing the ID Token (includingClientprofile claims) is sent to PingAccess from PingFederate via the browserafter authentication. Back-channel communication between PingAccessand PingFederate is required for key management in order to validate IDTokens. This login type is recommended for maximum performance incases where the exchanged claims do not contain information thatshould be hidden from the end user.
Client ID Assigned when you created the OAuth Relying Party client withinPingFederate (for more information, see in theConfiguring a ClientPingFederate documentation).Enter the unique identifier (Client ID).
ClientSecret
Assigned when you created the OAuth Relying Party Client withinPingFederate. Required when configuring the Login Type.CodeEnter the secret (Client Secret).
The OAuth Client you use with PingAccess Web sessionsmust have an OpenID Connect policy specified (for moreinformation see inConfiguring OpenID Connect Policiesthe PingFederate documentation).
© 2013 Ping Identity Corporation All Rights Reserved
SecureCookie
Indicates that the PingAccess cookie must be sent using only HTTPSconnections. Selected by default.
Setting an invalid Cookie Domain or selecting Secure in a non-HTTPS environment causesCookie
authentication to fail. This results in PingAccessre-directing the user to re-authenticate with PingFederateindefinitely.
HTTP-OnlyCookie
When selected (the default), enables the flag on cookies thatHttpOnlycontain the PA Token. An flagged cookie is not accessibleHttpOnlyusing non-HTTP methods such as calls via JavaScript (for example,referencing ) and therefore cannot be easily stolen viadocument.cookiecross-site scripting.
RequestProfile
When selected (the default), PingAccess requests additional profileattributes from PingFederate when requesting the . To use thisID Tokenfeature, you must have a scope set up in PingFederate (see profile
). The scope is a standard OpenIDConfiguring a Client profileConnect-defined scope that defines extended claims about a user.
The user can access all attributes by examining browsertraces. While they are integrity protected to preventchanges, any sensitive or confidential attributes can beviewed should the user decode the ID Token's value.
MaxTimeout(Minutes)
Defines the maximum amount of time, in minutes, that the PA Tokenremains active (the default is minutes).480Enter, in minutes, the length of time you want the PA Token to remainactive. Once the PA Token expires, an authenticated user mustre-authenticate. This protects against unauthorized use of a Resource,ensuring that a session ends after the specified time and requiring theuser to re-authenticate to continue.
© 2013 Ping Identity Corporation All Rights Reserved
IdleTimeout(Minutes)
Defines the amount of time, in minutes, that the PA Token remainsactive, when no activity is detected by the user (the default is 60minutes).
Enter, in minutes, the length of time you want the PA Token to remainactive when no activity is detected. Defining an idle expiration protectsagainst unauthorized use of the Resource by limiting the amount of timethe session remains active when not being used. For example, idleexpiration is useful when a user is no longer at the computer and doesnot log out of the session. When the idle expiration is reached, thesession automatically terminates.
If there is an existing valid PingFederate session for theuser, an idle time out of the PingAccess session mayresult in its re-establishment without forcing the user to login again.
Manage Key Pairs
Manage Key Pairs
PingAccess provides built-in , which are required for secure HTTPSKey Pairscommunication. A Key Pair includes a private key and an X.509 certificate.
The certificate includes a public key and the metadata about the owner of the privatekey.
PingAccess listens for client requests on the administrative console port and on thePingAccess engine port. To enable these ports for HTTPS, the first time you start upPingAccess, it generates and assigns a Key Pair for each port. These generated KeyPairs are initially assigned on the page.HTTPS Listeners
Additionally, Key Pairs are used by the to authenticateMutual TLS Site AuthenticatorPingAccess to a target Site. When initiating communication, PingAccess presents theclient certificate from a Key Pair to the Site during the mutual TLS transaction. The Sitemust be able to trust this certificate in order for authentication to succeed..
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
1.
2.
3.
Ensure that the administrative console node and engine nodes in a clusterhave the same cryptographic configuration. For example, if you generatean elliptic curve Key Pair on the administrative console and the enginenodes in the cluster are not configured to support elliptic curve Key Pairs,then the engine nodes are not able to use that Key Pair for the engine
or as the Key Pair in a .HTTPS Listener Mutual TLS Site AuthenticatorCryptographic configuration differences are often caused by having aJava Cryptographic Extension with limited strength providers installed(see the for more information).Oracle Java documentation
Use this page to manage Key Pairs and to import or generate additional Key Pairs tosecure access to the PingAccess administrative console and for incoming HTTPSrequests at runtime as well as for use with the Mutual TLS Site Authenticator.
Import or Generate a Key Pair
To Import an Existing Key PairUse this function to import a Key Pair.
Click . The page appears.IMPORT Import a Key PairEnter the requested information on the form.Click . A new card appears for the imported Key Pair on the Key PairsSAVEpage.
To Generate a New Key PairUse this function to generate a Key Pair and the self-signed certificate.
Click . The page appears.NEW KEY PAIR New Key PairEnter the requested information on the form.Click . The new card appears for the generated Key Pair on the KeySAVEPairs page.
Manage Existing Key Pairs
To manage existing Key Pairs, click on a Key Pair card to view the following Key Pairmanagement options:
Download CertDownload a certificate when you need to configure a peer to trust a certificate usedby PingAccess--for example, download the certificate for the Key Pair used by a
and configure the target Site to trust the certificate.Mutual TLS Site Authenticator
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
1.
2.
1.
2.
3.
1.
2.
Click Download Cert. PingAccess automatically downloads the certificatefrom the Key Pair.Save the file on your system.
Generate CSRGenerate a Certificate Signing Request (CSR) to establish more security and trustthan using a self-signed certificate.
Click Generate CSR. PingAccess automatically generates a CSR file.Save the file on your system.
Provide this file to a Certificate Authority (CA). The CA signs the file andprovides a CSR Response (see below) that you can upload and use toreplace the self-signed certificate. If the CA is well known, its certificates areinstalled by default in most browsers, and the user is not prompted to trust anunknown certificate.
CSR ResponseImport a CSR Response to replace the self-signed certificate in a Key Pair.
Click CSR Response. The page appears.Import a CSR ResponseEnter the requested information on the form.Click .UPLOAD
Delete
To delete the Key Pair, click Delete.Click in the confirmation window. PingAccess removes the Key PairDELETEfrom the system.
If a Key Pair is currently in use, you cannot delete it.
Generate a New Key Pair
Generate a New Key Pair
Use this page to generate a new Key Pair.
The table below describes the fields required for the Key Pair. This information is usedas metadata for the self-signed certificate that is generated as part of the Key Pair.Click when you finish. A new Key Pair card appears on the page.SAVE Key Pairs
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
Field Description
Alias A user-defined name that identifies the Key Pair. Special charactersand spaces are allowed. This name identifies the Key Pair on the Key
page and when assigning the Key Pair to various configurationsPairssuch as when creating a .Mutual TLS Site Authenticator
CommonName
The common name (CN) identifying the certificate. This is typically thehost name for PingAccess.
Organization The organization (O) or company name creating the certificate.
OrganizationUnit
Optional. The specific unit within the organization (OU).
City Optional. The city or other primary location (L) where the companyoperates.
State Optional. The state (ST) or other political unit encompassing thelocation.
Country The country (C) where the company is based. Enter the country usingtwo capital letters--for example, .US
Valid Days The number of days the certificate is valid.
KeyAlgorithm
The algorithm used to generate a key. PingAccess uses one of threealgorithms, , , or .EC DSA RSA
Key Size(bits)
The number of bits used in the key (EC- , , or , DSA- or 256 384 521 768, RSA- , , or ).1024 1024 2048 4096
Import a Key Pair
Import a Key Pair
Use this page to import a Key Pair from a file.PKCS#12
To import the Key Pair file:
In the box, enter a name that identifies the Key Pair. Special charactersAliasand spaces are allowed. This name identifies the Key Pair on the pageKey Pairsand when assigning the Key Pair to various configurations such as an HTTPS
.ListenerEnter the used to protect the PKCS#12 file. PingAccess uses thePassword
© 2013 Ping Identity Corporation All Rights Reserved
2.
3.
4.
5.
1.
2.
3.
4.
1.
2.
password to read the file.Click to locate the PKCS#12 file.CHOOSE FILEHighlight the file and click .OpenClick to import the file. A new card appears for the imported Key Pair onSAVEthe page.Key Pairs
Import a CSR Response
Import a CSR Response
Use this page to import a CSR Response to replace the self-signed certificate in a KeyPair.
Before you import the CSR Response, import the signing CA certificateinto PingAccess and add it to a .Trusted Certificate Group
To import a CSR Response:
Select the to use for validating that the certificate inTrusted Certificate Groupthe CSR Response is correctly formed.Click to locate the CSR Response file.CHOOSE FILEHighlight the file and click .OpenClick to upload the file.UPLOAD
Assign Key Pairs to HTTPS Listeners
Assign Key Pairs to HTTPS Listeners
PingAccess listens for client requests on the administrative console port andon the PingAccess engine port. To enable these ports for HTTPS, the first
time you start up PingAccess, it generates and assigns a Key Pair for each port. Usingthe page, you can import or generate additional Key Pairs to secure accessKey Pairsto these ports. These generated Key Pairs are initially assigned on the HTTPSListeners page.
The settings for the ENGINE runtime port only apply when PingAccess isconfigured to use HTTPS in the file.run.properties
To assign a new Key Pair to an HTTPS Listener:
Click for the configured HTTPS Listener you want to edit and click Edit.
© 2013 Ping Identity Corporation All Rights Reserved
2.
3.
1.
2.
3.
4.
From the list, select a different Key Pair you want to use for secure HTTPScommunication.Click when you finish.SAVE
You must restart each PingAccess server, including all engines in aclustered deployment, for changes to take effect.
Manage Trusted Certificate Groups
Manage Trusted Certificate Groups
Administrators import certificates into PingAccess to establish anchors usedto define trust to certificates presented during secure HTTPS connections.
Outbound secure HTTPS connections such as communication with PingFederate forOAuth access token validation, identity mediation, and communication with a target Siterequire a certificate trusted by PingAccess. If one does not exist, communication is notallowed. CA-issued certificates are recommended to simplify trust establishment andminimize routine certificate management operations (see ).Managing Security
A Certificate Group is a trusted set of anchor certificates used when authenticatingoutbound secure HTTPS connections.
The Java Trust Store group contains all the certificates included in the keystore locatedin the Java installation at . This group of certificates$JAVA_HOME/lib/security/cacertscontains well-known, trusted CAs. If you are connecting to Sites that make use ofcertificates signed by a CA in the Java Trust Store, you do not need to create anadditional Trusted Certificate Group for that CA. You cannot manage the Java TrustStore group from the PingAccess administrative console.
Expand a section for steps to import and manage certificates and create and managetrusted certificate groups.
CertificatesThis section provides steps for importing and deleting certificates, and adding to andremoving from Trusted Certificate Groups.Import a Certificate
Click . The New Certificate page appears.Click to locate the certificate.CHOOSE FILEHighlight the file and click .Open
© 2013 Ping Identity Corporation All Rights Reserved
4.
1.
2.
1.
2.
1.
2.
1.
2.
3.
4.
5.
6.
1.
Click to import the certificate. A new certificate row appears on theSAVECertificates page.
Delete a Certificate
Click on the certificate you want to delete and click Delete.Click in the confirmation window.DELETE
If the certificate is associated with a Trusted Certificate Group,you cannot delete it.
Add a Certificate to a Trusted Certificate Group
Hover the cursor over the certificate row you want to move. The move cursorappears.Drag and drop the certificate onto the Trusted Certificate Group.
Remove a Certificate from a Trusted Certificate Group
Expand the Trusted Certificate Group containing the certificate you want toremove.Click on the certificate you want to remove.
Trusted Certificate GroupsThis section provides steps for creating, editing, and deleting Trusted CertificateGroups.Create a Trusted Certificate Group
Click to create a new Trusted Certificate Group.Drag-and-drop a certificate onto the box that appears. A new group appearsat the bottom of the Trusted Certificate Groups list.Enter a name for the group in the box that appears.Drag-and drop more certificates onto the Certificates box for the group.Select the checkbox to set the new group to includeUse Java Trust Store?the Java Trust Store group--for example, if you create your own intermediateCA certificate that is signed by a well-known CA in the Java Trust Store.Click to save the group.
Edit a Trusted Certificate Group
Click for the group you want to edit and click Edit.Edit the group name and optionally set it to include the Java Trust Store
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
1.
2.
group--for example, if you create your own intermediate CA certificatethat is signed by a well-known CA in the Java Trust Store.Expand the group and drag-and-drop certificates onto the Certificatesbox.Click for a certificate you want to remove.Click to exit Edit mode without saving changes.
Click to save your changes.
Delete a Trusted Certificate Group
Click on the group you want to remove and click Delete.Click in the confirmation window.DELETE
Define Authentication Requirements
Define Authentication Requirements
Authentication Requirements are policies that dictate how a user must authenticatebefore access is granted to a protected Web Resource. Authentication methods arestring values and ordered in a list by preference. At runtime, the type of authenticationattempted is determined by the order of the authentication methods.
For example, a user attempts to access a PingAccess Web Resource configured withan authentication requirement list containing the values [password, cert]. PingAccessredirects the user to PingFederate requesting either password or certificate userauthentication. PingFederate authenticates the user based on the password and issuesan OIDC ID Token to PingAccess (containing the authentication method that wasused). PingAccess ensures that the authentication method matched the requirementsand redirects the user to the originally requested Resource with the PA cookie set. Theuser navigates to the Resource and access is granted. When the user attempts toaccess a more sensitive Resource, configured with an authentication requirement listcontaining the value [cert], they are redirected to PingFederate to authenticate with acertificate.
If you configure Resources with authentication requirement lists that have nooverlap--for example, one list has [password], another list [cert]), a user navigatingbetween Resources may be required to authenticate each time they visit a Resource.When configuring authentication requirement lists to protect higher value Resourceswith step-up authentication, consider including stronger forms of authentication whenconfiguring lower value Resources.
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
5.
1.
2.
3.
1.
2.
To configure an Authentication Requirement List:
Enter a unique name for the Authentication Requirements list. Up to 64characters, including special characters and spaces, are allowed.Enter an authentication method--for example, or .cert password
The values you enter here must match the result values defined forthe Requested Authn Context Selector configured withinPingFederate (see Configuring the Requested AuthN Context
).Selector
Click to add the requirement.Continue adding requirements.Click when you finish.SAVE
To edit an Authentication Requirements List:
Click for the list you want to edit and click Edit. The Edit AuthenticationRequirement page appears.Make your changes.
Click to edit an authentication requirement.Order the requirements by dragging and dropping them.Click to save edits.Click to exit Edit mode without saving changes.Click to delete an authentication requirement.
Click when you finish.SAVE
To delete an Authentication Requirements List:
Click for the list you want to delete and click Delete.Click in the confirmation window.DELETE
Connect to a Site
Connect to a Site
Sites are the locations of applications, endpoints, or APIs in yourenvironment that you want to protect with PingAccess. Use this page to
define how to connect to a Site.
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
5.
6.
7.
8.
9.
To connect to a Site:
Enter a unique . Up to 64 characters, including special characters andNamespaces, are allowed. This name appears in the list on the Site New Resourcepage.Specify the name or IP address of the server where the target SiteTarget Hostis running--for example, or . Be sure to omit theBankService.com 192.0.2.128protocol scheme ( ) from the host name.http[s]Specify the number where the target Site is listening--for example, Target Port
.8080Select the checkbox if the Site is expecting HTTPS connections.SecureFrom the list, select the to useTrusted Certificate Group group of certificateswhen authenticating to the Site. PingAccess requires that the certificate in use bythe target Site anchors to a certificate in the associated Trusted CertificateGroup. This field is available only if you select the checkbox.SecureIf the Site requires authentication, click in the box to selectSite Authenticatorsone or more authenticators from the list. Click to remove a Site Authenticator.x
A combination of Site Authenticators is useful when the back-end Site requires aform of service-level authentication, but the application itself expects end-userrelated identity information. For example, combine the Basic Authentication andWeb Session Header Attribute Site Authenticators to have PingAccessauthenticate securely to the back-end Site and relay user and group details viaHTTP headers.
You must first configure Site Authenticators in order to populate thislist (see ).Configure Site Authenticators
Leave the checkbox selected to have PingAccessUse Target Host Headeradjust the header to the Site's Target Host and Target Port rather than theHostVirtual Host configured in the Resource. This is often required by target Webservers to ensure they service the HTTP request with the correct internal virtualserver definition. Clear this checkbox to make no changes to the header.Host(See for more information.)Virtual HostsIn the box, enter how many times you want PingAccess to retry theMax Retriesrequest to the back-end Site before sending an error response back to the client.The default is 5.In the box, enter the number of seconds (in milliseconds)Socket Timeout (ms)you want PingAccess to wait while attempting to establish a connection to the
© 2013 Ping Identity Corporation All Rights Reserved
9.
10.
11.
12.
13.
1.
2.
3.
back-end Site before retrying. The default is milliseconds.10000In the box, enter the time (in milliseconds) an HTTPKeep Alive Timeout (ms)persistent connection to the Site can be idle before PingAccess closes theconnection. The default is milliseconds.3000In the box, enter the maximum number of HTTP persistentMax Connectionsconnections you want PingAccess to have open and maintain for the Site. -1indicates unlimited connections.Leave the checkbox selected to include the Send PingAccess Cookie PA
in the request to the back-end Site. Clear the checkbox to remove the PATokenToken from the request.Click when you finish.SAVE
Configure Site Authenticators
Configure Site Authenticators
When a client attempts to access a target Web Site, that Site may limitaccess to only authenticated clients. PingAccess integrates with those
security models using Site Authenticators.
PingAccess supports a variety of Site Authenticators that range from basicusername/password authentication to certificate and token-based authentication.
Create a Site Authenticator for the type of authentication the Site requires.
To create a Site Authenticator:
Enter a unique . Special characters and spaces are allowed. This nameNameappears in the list on the page.Site Authenticator New SiteSelect the type of authentication from the drop-down list.
Basic Authentication Site Authenticator
Mutual TLS Site Authenticator
OAuth Site Authenticator
Token Mediator Site Authenticator
Web Session Header Site Authenticator
Click when you finish.SAVE
Basic Authentication Site Authenticator
Basic Authentication Site Authenticator
© 2013 Ping Identity Corporation All Rights Reserved
This Site Authenticator uses HTTP Basic authentication(username:password) to authenticate a client requesting access to a Siterequiring Basic authentication.
Obtain the username and password from your target Site provider.
Field Description
Username Defines the username required for access to the protected Site.
Password Defines the password required for access to the protected Site.
Mutual TLS Site Authenticator
Mutual TLS Site Authenticator
This Site Authenticator uses Key Pairs to authenticate PingAccess to a targetSite. When initiating communication, PingAccess presents the client
certificate from a Key Pair to the Site during the mutual TLS transaction. The Site mustbe able to trust this certificate in order for authentication to succeed.
Several setup steps are required for PingAccess certificate managementbefore configuring the Mutual TLS Site Authenticator (see Managing
, , and ).Security Manage Key Pairs Manage Trusted Certificate Groups
Field Description
KeyPair
The imported/generated key pair for client authentication. Select the Key Pairyou want to use to authenticate PingAccess to the target Site (see Manage
).Key Pairs
OAuth Site Authenticator
OAuth Site Authenticator
This Site Authenticator uses an OAuth access token to authenticate a clientrequesting access to a Site that requires OAuth authentication.
© 2013 Ping Identity Corporation All Rights Reserved
Field Description
Long-LivedAccessToken
Defines the long-lived OAuth access token (see Configuring in the PingFederate documentation forReference-Token Management
more information).
Token Mediator Site Authenticator
Token Mediator Site Authenticator
This Site Authenticator uses the PingFederate STS to exchange a PA Tokenfor a security token, such as a or OpenToken, that is valid at theWAM Token
target Site.
Field Description
TokenGeneratorID
Defines the Instance Name of the Token Generator that you want to use.The Token Generator is configured within PingFederate (see Configuring
in the PingFederate documentation).Token Generators
Logged InCookieName
Defines the cookie name containing the token that the target Site isexpecting.
LoggedOffCookieName
Defines the cookie name that the target Site responds with in the event ofan invalid or expired token. If the PA Token is still valid, PingAccessre-obtains a valid WAM Token and makes the request to the Site again. Ifthe Site responds with the cookie set as logged off again, PingAccessresponds to the client with an access denied page.
LoggedOffCookieValue
Defines the value placed in the Logged Off Cookie to detect aninvalid/expired WAM Token event.
SourceToken
Defines the token type exchanged for a security token during identity. Leave for Web access or select mediation PA Cookie OAuth Bearer
for API identity mediation.Token
Web Session Header Site Authenticator
© 2013 Ping Identity Corporation All Rights Reserved
Web Session Header Site Authenticator
This Site Authenticator maps an attribute from the and places it inPA Tokenan HTTP request header to back-end Sites that can leverage it for
authentication. Use the table to configure the attribute names you want to retrieve fromthe PA Token and the HTTP Header variables for those attributes.
To add/remove attributes:
Enter field values.Click to add another row.Click when you finish.SAVETo remove an attribute row, click .
Field Description
AttributeName
Defines the attribute name you want to retrieve from the PA Token--forexample, .sub
PA Token attributes are obtained from the PingFederateOpenID Connect Policy attribute contract (see Configuring
in the PingFederateOpenID Connect Policiesdocumentation).
HeaderName
Defines the HTTP request header that contains the attribute valueretrieved from the PA Token.
The HTTP header you specify here is the actual headername over the HTTP protocol, not an environment variableinterpreted format--for example, enter the User-Agentbrowser type identifying header as , not User-Agent
.HTTP_USER_AGENT
Configure a Resource
Configure a Resource
Resources represent Web applications or APIs to which a request is sent.
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
5.
They are defined as a path and virtual server and are mapped to a back-endSite where the requests are fulfilled. Policies are applied to Resources to protect them.Using the PingAccess administrative console, you define endpoints for the Resource,associate a target Site with that Resource, and map policies to the Resource that areapplied to each request. Use this page to define the inbound endpoint where a clientrequest comes in and the target Site where the Resource ultimately directs thatrequest.
To configure a Resource:
Enter a unique . Up to 64 characters, including special characters andNamespaces, are allowed. This name appears in the column on the Resource Policy
page and is associated with Sites on the page.Manager SitesSelect the name and port or IP address of the server where theVirtual HostResource is running--for example, or .BankServices.com:8080 127.0.0.1:3000Two defaults are included:
localhost:3000 - Select for use with locally-originated requests or for testing.
*:3000 - Select to accept requests for any host.
To populate this drop-down list, add virtual hosts to the Virtual page.Hosts
Enter an optional --for example, . To evaluatePath Prefix /BankServices/account/this path as a regular expression, select the checkbox and enter thePatternregular expression (for example, ). See /resource/(\w+) Resource Path Regex
for more examples.Examples
The path prefix starts at the first forward slash after andhost:portextends to the end of the URL. Be sure to start the path you enterwith a forward slash.
Select the checkbox to evaluate what you enter in the boxPattern Path Prefixas a regular expression.Select the checkbox to indicate that the Resource is mapped to aWeb SessionWeb Site. Leave the checkbox clear to indicate that the Resource is mapped toan API Site.
© 2013 Ping Identity Corporation All Rights Reserved
5.
6.
7.
8.
9.
10.
11.
You must configure a connection to the PingFederate OAuth as well as configure inAuthorization Server Web Session Settings
order for a Web-enabled Resource to function properly.
Select an list to define how a user authenticatesAuthentication Requirementsbefore access is granted to a protected Web Resource. This list box is onlyavailable when you specify a (above) for the Resource (see Web Session Define
).Authentication RequirementsEnter the supported by the Resource. Leave the asterisk default if theMethodsResource supports all HTTP methods, including custom methods. DefiningMethods for a Resource allows more fine-grained access control policies on APIResources. For example, if you have a server optimized for writing data (POST,PUT) and a server optimized for reading data (GET), you may want to segmenttraffic based on the operation being performed.
Method selection is not available for Web Session Resources.
Select the checkbox to log information about the transaction to the auditAuditstore. PingAccess audit logs record a selected subset of transaction loginformation at runtime and are located in the directory of your PingAccess/logsinstallation (see ).Security Audit LogSelect the target where the Resource directs the client request.Site
You can map multiple Resources to one target Site.
Select to indicate the Resource is active and can process requests.EnabledClick when you finish.SAVE
Order Resources
Order Resources
The order of Resources is significant in that when a request comes in, the first matchingResource it finds is the Resource used and all other Resources are ignored. Resources
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
5.
6.
7.
with finer-grained configurations should be placed higher up in the Resource list andthose Resources with a wider-scope configuration should be placed lower in the list.For more information, see Resource Evaluation
To change the Resource order:
Click on the right to change the page view to .TableSelect the virtual host shared by the Resources you want to order from the AllVirtual Hosts list.Click .EDIT ORDERHover the cursor over a Resource row you want to move. The move cursorappears.Drag and drop the Resource to the new location in the table. This enables theSAVE CHANGES button.Click when you finish re-ordering the Resources.SAVE CHANGESClick to return to card view and display all configuredSEE ALL RESOURCESResources.
Resource Path Regex Examples
Resource Path Regex Examples
This page provides regular expression examples for use in the field when Path.configuring a Resource
To work with URLs that use URL parameters, the following regular expression providesa match:
/resource(/?\\?.*)?
This matches URLs such as the following:
/resource?foo=bar&baz=bar
To work with RESTful URLs, consider the following regular expression:
/resource/(\d+)
This matches URLs such as the following:
/resource/123
© 2013 Ping Identity Corporation All Rights Reserved
To work with URLs containing variable content before and after a known value,consider the following regular expression:
.*/resource/.*
This matches URLs such as the following:/foo/resource/bar
Managing Policies
Managing Policies
Mapping Rules and Rule Sets to Resources creates PingAccess policies,defining how and when a client accesses target Sites.
When a client attempts to access a Resource identified in one of the policy's Rules orRule Sets, PingAccess uses the information contained in the policy to resolve whetherthe client can access the Resource and whether any additional actions need to takeplace prior to granting access.
Rules can restrict access in a number of ways--for example, using Web Sessionattributes, between certain periods of time, or for certain IP addresses. For an APIdeployment, this may mean restricting access based on the OAuth scopes associatedwith the incoming access token. This allows administrators a finer control over theirResources.
The page in the PingAccess administrative console is a drag-and-dropPolicy Managerinterface where you can create on the fly, build , and then theseRules Rule Sets mapRules and Rule Sets to Resources--creating policies.
Expressions in Policies
Groovy scripts have access to important PingAccess runtime objects such as the and objects, which the scripts can interrogate and modify.Exchange PolicyContext
These scripts provide advanced Rule logic that extend PingAccess Rule developmentbeyond the capabilities of the packaged Rule Sets.
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
Through Groovy scripts, PingAccess administrators can perform sensitiveoperations that could affect system behavior and security. For moreinformation on Groovy, see .Groovy
To use these objects in a Rule, you must configure the and build theGroovy Script Ruleappropriate expression using the Expression box on the Groovy Script Rule page.
XPath Expressions examine XML representations of requests and determine whetherto grant access to a target Site based on a match found between the specified valueand the resulting value using the XPath Expression.
Define Rules
Define Rules
Rules are applied to a to provide access control and for request processing.ResourceYou can define Rules for how and when a client accesses a Resource as well as how arequest is processed.
When any Rule fails, further Rule evaluation stops.
To create a Rule:
Enter a unique . Up to 64 characters, including special characters andNamespaces, are allowed. This name appears in the column on the Rules Policy
page and associated with Resources on the page.Manager ResourcesSelect the of access control you want to implement. Fields associated withTypethat Rule type appear.Enter the required information for the type of Rule you are creating (see Rule
, below).Type Descriptions and ConfigurationClick when you finish.SAVE
Rule Type Descriptions and Configuration
Access Control Rules Groovy Script RuleHTTP Request RuleNetwork Range RuleOAuth Attribute Value RuleOAuth Groovy Script RuleOAuth Scope Rule
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
Time Range RuleWeb Session Attribute RuleXPath Expression Rule
Processing Rules Rewrite Cookie Domain RuleRewrite Cookie Path RuleRewrite Response Header RuleRewrite URL Rule
Groovy Script Rule
Groovy Script Rule
Determines whether to grant access to a target Site based on the results returned froma Groovy script that evaluates request details. A Groovy script can also be used tomanipulate request and response details.
For more information on Groovy, see the and the PingAccess Groovy documentation page.Groovy
To create a Groovy Script Rule:
Enter the Groovy Script to use for Rule evaluation.
For example, to create an OAuth Scope Rule that matches more than one scope,your Groovy script might look like the following:
hasScopes("access","portfolio")
See for more information.Groovy Scripts
Click when you finish.SAVE
Error-Handling Fields for Rules
You can customize an error message to display as part of the default error pagerendered in the end-user's browser if Rule evaluation fails. This page is among thetemplates you can modify with your own branding or other information (see Customize
). Use the following fields to configure the error handling.User-Facing Pages
Field Description
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
ErrorResponseCode
The HTTP status response code you want to send if Rule evaluationfails--for example, .403
ErrorResponseStatusMessage
The HTTP status response message you want to return if Ruleevaluation fails--for example, .Forbidden
ErrorResponseTemplateFile
The HTML template page for customizing the error message thatdisplays if Rule evaluation fails. This template file is located in the
directory.<pa_install>/conf/template/
ErrorResponseContentType
The type of content for the error response so the client can properlydisplay the response.
HTTP Request Rule
HTTP Request Rule
Examines a request and determines whether to grant access to a target Site based ona match found in the specified source of the HTTP request.
To configure an HTTP Request Rule:
Enter the name you want to match in order to grant or not grant the clientFieldaccess--for example, .HostEnter the for the field (a header value or contents of the request body) youValuewant to match in order to grant or not grant the client access--for example,
.localhost*
If you want to match on the Host header, be sure to include boththe host and port as the or add a wildcard after the hostnameValue( or ) to match what is in the HTTP request.host* host:*
Select if when a match is found, access is not allowed.Negate
© 2013 Ping Identity Corporation All Rights Reserved
3.
4.
5.
Verify what you enter for the attribute. If you enter an attribute thatdoes not exist (for example, misspell it) and you select , theNegaterule will always succeed.
Select the request you want to inspect for a match--- or .Source Header Body
If you want to match more values from the request, create moreHTTP Request Rules or use the Groovy Script Rule.
Click when you finish.SAVE
Error-Handling Fields for Rules
You can customize an error message to display as part of the default error pagerendered in the end-user's browser if Rule evaluation fails. This page is among thetemplates you can modify with your own branding or other information (see Customize
). Use the following fields to configure the error handling.User-Facing Pages
Field Description
ErrorResponseCode
The HTTP status response code you want to send if Rule evaluationfails--for example, .403
ErrorResponseStatusMessage
The HTTP status response message you want to return if Ruleevaluation fails--for example, .Forbidden
ErrorResponseTemplateFile
The HTML template page for customizing the error message thatdisplays if Rule evaluation fails. This template file is located in the
directory.<pa_install>/conf/template/
ErrorResponseContentType
The type of content for the error response so the client can properlydisplay the response.
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
Network Range Rule
Network Range Rule
Examines a request and determines whether to grant access to a target Site based onwhether the IP address falls within a specified range (using Classless Inter-DomainRouting notation).
To configure a Network Range Rule:
Enter a in the box---for example, . PingAccessNetwork Range 127.0.0.1/8supports both IPv4 and IPv6 addresses.Select if when a match is found, access is not allowed.NegateClick when you finish.SAVE
Error-Handling Fields for Rules
You can customize an error message to display as part of the default error pagerendered in the end-user's browser if Rule evaluation fails. This page is among thetemplates you can modify with your own branding or other information (see Customize
). Use the following fields to configure the error handling.User-Facing Pages
Field Description
ErrorResponseCode
The HTTP status response code you want to send if Rule evaluationfails--for example, .403
ErrorResponseStatusMessage
The HTTP status response message you want to return if Ruleevaluation fails--for example, .Forbidden
ErrorResponseTemplateFile
The HTML template page for customizing the error message thatdisplays if Rule evaluation fails. This template file is located in the
directory.<pa_install>/conf/template/
ErrorResponseContentType
The type of content for the error response so the client can properlydisplay the response.
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
5.
6.
OAuth Attribute Value Rule
OAuth Attribute Value Rule
Examines a request and determines whether to grant access to a target Service basedon a match found between the attributes associated with an OAuth access token andattribute values specified in the OAuth Attribute Rule.
To configure an OAuth Attribute Value Rule:
Select the that reflects the Authorization Server (AS) used toAccess Validatorvalidate the OAuth Access token.This list populates when you to the PingFederate OAuthconfigure the connectionAS.Enter metadata returned to the client if a Rule fails---for example,Realm"Company A's Partner API."Enter the you want to match to an attribute associated with anAttribute NameOAuth Access token---for example, Group.In the box, enter a value for the attribute--for example, Sales.Attribute Value
If you want to match more attributes, create more OAuth AttributeValue Rules or use the OAuth Groovy Script Rule.
Select if when a match is found, access is not allowed.Negate
Verify what you enter for the attribute. If you enter an attribute thatdoes not exist (for example, misspell it) and you select , theNegaterule will always succeed.
Click when you finish.SAVE
Error-Handling Fields for OAuth Rules
You can customize an error message to display as part of the default oauth.error.jsonerror page rendered in the end-user's browser if Rule evaluation fails for an OAuth-typeRule-- , , and . This page isOAuth Attribute Value OAuth Groovy Script OAuth Scopeamong the templates you can modify with your own branding or other information (see
).Customize User-Facing Pages
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
The response status code is always with an status message. The 401 Unauthorized header value provides information on the OAuth credential theWWW-Authenticate
client needs to present.
For example:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="test"
Use the following fields to configure the error handling template and content type.
Field Description
ErrorResponseTemplateFile
The template page for customizing the error message that displays ifRule evaluation fails. This template file is located in the
directory.<pa_install>/conf/template/
ErrorResponseContentType
The type of content for the error response so the client can properlydisplay the response.
Related Topics
How does PingAccess use the OAuth Authorization Server?
OAuth Groovy Script Rule
OAuth Groovy Script Rule
Determines whether to grant access to a target Site based on the results returned froma Groovy script that evaluates request details and OAuth details. This Rule allows youto create more sophisticated OAuth Scope and OAuth Attribute Value Rules.
See for more information.Groovy Scripts
To configure an OAuth Groovy Script Rule:
Enter the to use for Rule evaluation.Groovy ScriptSelect the that reflects the Authorization Server (AS) used toAccess Validatorvalidate the OAuth Access token.
© 2013 Ping Identity Corporation All Rights Reserved
2.
3.
4.
This list populates when you to the PingFederate OAuthconfigure the connectionAS.
Enter metadata returned to the client if a Rule fails---for example,Realm"Company A's Partner API."Click when you finish.SAVE
Error-Handling Fields for OAuth Rules
You can customize an error message to display as part of the default oauth.error.jsonerror page rendered in the end-user's browser if Rule evaluation fails for an OAuth-typeRule-- , , and . This page isOAuth Attribute Value OAuth Groovy Script OAuth Scopeamong the templates you can modify with your own branding or other information (see
).Customize User-Facing Pages
The response status code is always with an status message. The 401 Unauthorized header value provides information on the OAuth credential theWWW-Authenticate
client needs to present.
For example:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="test"
Use the following fields to configure the error handling template and content type.
Field Description
ErrorResponseTemplateFile
The template page for customizing the error message that displays ifRule evaluation fails. This template file is located in the
directory.<pa_install>/conf/template/
ErrorResponseContentType
The type of content for the error response so the client can properlydisplay the response.
Related Topics
How does PingAccess use the OAuth Authorization Server?How does PingAccess uses Groovy Scripts?
OAuth Scope Rule
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
5.
OAuth Scope Rule
Examines the contents of the PingFederate validation response and determineswhether to grant access to a back-end target Site on a match found between thescopes of the validation response and scope specified in the OAuth Scope Rule. Forexample, a Resource may require that the OAuth Access Token contain the scope
.superuser
To configure an OAuth Scope Rule:
Select the that reflects the Authorization Server (AS) used toAccess Validatorvalidate the OAuth Access token.
This list populates when you to the PingFederate OAuthconfigure the connectionAS.
Enter metadata returned to the client if a Rule fails---for example,Realm"Company A's Partner API."Enter the you want to match to values returned from the Access Validator.Scope
This is one scope requirement in the set of scopes associated withthe access token.
Select if when a match is found, access is not allowed.NegateClick when you finish.SAVE
Error-Handling Fields for OAuth Rules
You can customize an error message to display as part of the default oauth.error.jsonerror page rendered in the end-user's browser if Rule evaluation fails for an OAuth-typeRule-- , , and . This page isOAuth Attribute Value OAuth Groovy Script OAuth Scopeamong the templates you can modify with your own branding or other information (see
).Customize User-Facing Pages
The response status code is always with an status message. The 401 Unauthorized header value provides information on the OAuth credential theWWW-Authenticate
client needs to present.
For example:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="test"
© 2013 Ping Identity Corporation All Rights Reserved
Use the following fields to configure the error handling template and content type.
Field Description
ErrorResponseTemplateFile
The template page for customizing the error message that displays ifRule evaluation fails. This template file is located in the
directory.<pa_install>/conf/template/
ErrorResponseContentType
The type of content for the error response so the client can properlydisplay the response.
Related Topics
How does PingAccess use the OAuth Authorization Server?
Rewrite Rules Overview
Rewrite Rules Overview
It is sometimes necessary to manipulate requests to Sites and to manipulate theirresponses. PingAccess allows for the manipulation of the Request URI, the cookiedomain, the cookie path, and three of the response headers ( , Location
, and ).Content-Location URI
PingAccess does not perform HTTP body content rewriting. All links topages, images, stylesheets, and other content within the Site must userelative URLs to the path of the page that appears.
For example, a Site is hosted on under . Usershttps://server1.internalsite.com /content/access the Site via the following URL in their browser:
https://server1.internalsite.com/content/
For example purposes, let's say this results in a to an 302 Redirect page as well as setting a domain cookie for .importantContent.html .internalsite.com
If you protect this Site with PingAccess (using the virtual host ) under thepublicsite.comResource , you need to rewrite the content. The information below/importantstuff/discusses an example scenario.
© 2013 Ping Identity Corporation All Rights Reserved
This example assumes that a Virtual Host, a Site, and a Resource arealready configured.
Create a Rewrite URL RuleA Rule alters the Request URI.Rewrite URL
In the Map From field, you enter as the regex of the URL's^/importantstuff/(.*)path and query you want to match.In the Map To field, you enter ./content/$1Add the Rule to the Resource.A query to results in PingAccess routing thathttps://publicsite.com/importantstuff/query to .https://server1.internalsite.com/content/
Create a Rewrite Response Header RuleA Rule alters the response header used in the 302 Redirect.Rewrite Response Header
In the Server-Facing URI field, you enter .https://server1.internalsite.com/content/In the Public Path field, you enter ./importantstuff/Add the Rule to the Resource.
A query resulting in a response containing a 302 Redirect to is rewritten to https://server1.internalsite.com/content/
.https://publicsite.com/importantstuff/
This also works for relative redirects: is rewritten to /content/. It also works for the path beneath the one defined/importantstuff/
in the URI: is rewritten to /content/news/index.html.importantstuff/news/index.htm
Create a Rewrite Cookie Domain RuleA Rule allows the rewriting of the Domain field on cookiesRewrite Cookie Domainwhen they are set by the back-end site.
In the Server-Facing Cookie Domain, you enter .internalsite.comIn the Public-Facing Cookie Domain, you enter .publicsite.comAdd the Rule to the Resource.
Cookies associated with the domain (or ) arepublicsite.com .publicsite.com
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
rewritten to pertain to (or ).internalsite.com .internalsite.com
Create a Rewrite Cookie Path RuleA Rule converts the cookie path returned by the Site into aRewrite Cookie Pathpublic-facing path.
In the Server-Facing Cookie Path field, you enter ./content/In the Public-Facing Cookie Path field, you enter ./importantstuff/Add the Rule to the Resource.
Cookies associated with a cookie path of are rewritten to pertain to /content/./importantstuff/
After configuring the rewrite Rules as discussed above, a user could access the and PingAccess would route that request to https://publicsite.com/importantstuff/
. If the Site sends a redirect to https://server1.internalsite.com/content/, PingAccess would return ahttps://server1.internalsite.com/content/index.html
redirect to . If the Site thenhttps://publicsite.com/importantstuff/index.htmlreturned a cookie with a domain of and a path of ,.internalsite.com /content/PingAccess would rewrite that cookie to be relevant to and .publicsite.com
./importantstuff/
Rewrite Cookie Domain Rule
Rewrite Cookie Domain Rule
Converts the cookie domain returned by the Site into a public-facing domain. Forexample, a Site places a cookie on a cookie domain such as (or internalsite.com
). Using the information configured in the Rewrite Cookie Domain Rule,.internalsite.comPingAccess rewrites the portion of the response header with aDomain Set-Cookiepublic-facing domain such as (or ).publicsite.com .publicsite.com
You should only set the cookie (in the Public-Facing Cookie Domain field)to the virtual host name associated with that Resource or to a domain thatis above--for example, can be set to .myserver.acme.com acme.com
To configure a Rewrite Cookie Domain Rule:
Name the Rule.
© 2013 Ping Identity Corporation All Rights Reserved
2.
3.
4.
5.
1.
2.
3.
4.
5.
Select from the list.Rewrite Cookie DomainIn the box, enter the domain name to use in theServer-Facing Cookie Domaincookie returned by the back-end Site.In the box, enter the domain name you want toPublic-Facing Cookie Domaindisplay in the response from PingAccess.Click when you finish.SAVE
Rewrite Cookie Path Rule
Rewrite Cookie Path Rule
Converts the cookie path returned by the Site into a public-facing path. This enables thedetails of exposed Resources to be managed by PingAccess for security and requestrouting purposes.For example, a Site places a cookie in a server-facing cookie path such as ./content/Using the information configured in the Rewrite Cookie Path Rule, PingAccess rewritesthe portion of the response header with a public-facing cookie pathPath Set-Cookiesuch as ./importantstuff/
To configure a Rewrite Cookie Path Rule:
Name the Rule.Select from the list.Rewrite Cookie PathIn the box, enter the path name where the cookie isServer-Facing Cookie Pathvalid for the back-end Site.In the box, enter the path name you want to displayPublic-Facing Cookie Pathin the response from PingAccess.Click when you finish.SAVE
Rewrite Response Header Rule
Rewrite Response Header Rule
Converts the response header value returned by the Site into a public-facing value.This Rule rewrites one of three response headers: , , and Location Content-Location URI.For example, the server-facing response header includes a path that beginsLocationwith . Using the information configured in the Rewrite Response Header Rule,/test-war/PingAccess rewrites with a public-facing path such as http://private/test-war/
.http://public/path/
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
5.
1.
2.
3.
To configure a Rewrite Response Header Rule:
Name the Rule.Select from the list.Rewrite Response HeaderIn the box, enter the URI of the server sending the response.Server-Facing URIThis must be a URI prefix containing at a minimum the protocol and hostnameport information.For example: or https://server1.internalsite.com/content/http://SiteHostName/path/In the box, enter a valid URI path that you want to write into the URI.Public PathThis must be a valid URI path and begin and end with a slash ( )./For example: or /importantstuff/ /Click when you finish.SAVE
Rewrite URL Rule
Rewrite URL Rule
Examines the URL of every request and determines if a pattern matches--for example,you define a regular expression (regex) in the rule. If a pattern matches, PingAccessuses the information configured in the Rewrite URL Rule and rewrites that portion of theURL into a path that the Site can understand. The following table displays four exampleRewrite URL Rule configurations:
Map From Value Map To Value Example Request Rewrite by PingAccess
/bank/ /resource/ /bank/content.html /resource/content.html
^/bank/(.*) /resource/$1 /bank/content.html /resource/content.html
/bank/index.html /resource/index.jsp /bank/index.html /resource/index.jsp
/bank/index.html /resource/index.jsp /bank/index.html?query=stuff /resource/index.jsp?query=stuff
To configure a Rewrite URL Rule:
Name the Rule.Select from the drop-down list.Rewrite URLIn the box, enter the regex of the URL's path and the query you wantMap Fromto match.For example: ^/bank/(.*)This example illustrates matching the in the request. The Request-Line
begins with (the indicates "begins with") and places theRequest-Line /bank/ ^rest of the URL into the first capture group (for more information on regex
© 2013 Ping Identity Corporation All Rights Reserved
3.
4.
5.
1.
2.
3.
4.
patterns, see the ).Oracle Java DocsIn the box, enter the URL's path and query you want to generate.Map ToFor example: /resource/$1This example defines the replacement string, which generates followed by the/content of the first capture group (to better understand the use of specialcharacters such as \ and in the replacement string, see the ).$ Oracle Java DocsClick when you finish.SAVE
Time Range Rule
Time Range Rule
Examines a request and determines whether to grant access to a back-end target Sitebased on the request falling within a defined time frame. For example, use this Rulewhen you want to restrict access to specific endpoints for certain time periods, such asduring the work day from 8 am to 5 pm.
To configure a Time Range Rule:
Enter the beginning time for the time frame in the box---for example,Start Time8:00 AM.Enter the ending time for the time frame in the box---for example, 5:00End TimePM.
If you are using Internet Explorer or Firefox, you must enter thetime in 24 hour format---for example, 5:00 PM is 17:00.
Select if when a match is found, access is not allowed.NegateClick when you finish.Save
Error-Handling Fields for Rules
You can customize an error message to display as part of the default error pagerendered in the end-user's browser if Rule evaluation fails. This page is among thetemplates you can modify with your own branding or other information (see Customize
). Use the following fields to configure the error handling.User-Facing Pages
Field Description
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
ErrorResponseCode
The HTTP status response code you want to send if Rule evaluationfails--for example, .403
ErrorResponseStatusMessage
The HTTP status response message you want to return if Ruleevaluation fails--for example, .Forbidden
ErrorResponseTemplateFile
The HTML template page for customizing the error message thatdisplays if Rule evaluation fails. This template file is located in the
directory.<pa_install>/conf/template/
ErrorResponseContentType
The type of content for the error response so the client can properlydisplay the response.
Web Session Attribute Rule
Web Session Attribute Rule
Examines a request and determines whether to grant access to a target Site based onan attribute value match found within the .PA Token
To configure a Web Session Attribute Rule:
Enter the that you want to match in order to grant the clientAttribute Nameaccess--for example, .GroupEnter the for the Attribute Name--for example, . If theAttribute Value Salesattribute has multiple values at runtime, the attribute value you specify here mustmatch one of those values.
PA Token attributes are obtained from the PingFederate OpenIDConnect Policy attribute contract (see Configuring OpenID Connect
).Policies
Click to add more attributes.
Click to remove a row.
© 2013 Ping Identity Corporation All Rights Reserved
4.
5.
Select if when a match is found, access is not allowed.Negate
Verify what you enter for the attribute. If you enter an attribute thatdoes not exist (for example, misspell it) and you select , theNegaterule will always succeed.
Click when you finish.SAVE
To use this Rule, we recommend that you leave the Request Profilecheckbox selected (see ), indicating that you wantWeb Session SettingsPingAccess to request additional profile attributes from PingFederatewhen requesting the .ID Token
Error-Handling Fields for Rules
You can customize an error message to display as part of the default error pagerendered in the end-user's browser if Rule evaluation fails. This page is among thetemplates you can modify with your own branding or other information (see Customize
). Use the following fields to configure the error handling.User-Facing Pages
Field Description
ErrorResponseCode
The HTTP status response code you want to send if Rule evaluationfails--for example, .403
ErrorResponseStatusMessage
The HTTP status response message you want to return if Ruleevaluation fails--for example, .Forbidden
ErrorResponseTemplateFile
The HTML template page for customizing the error message thatdisplays if Rule evaluation fails. This template file is located in the
directory.<pa_install>/conf/template/
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
ErrorResponseContentType
The type of content for the error response so the client can properlydisplay the response.
XPath Expression Rule
XPath Expression Rule
Examines an XML representation of a request and determines whether to grant accessto a target Site based on a match found between the specified value and the resultingvalue using the XPath Expression.
To configure an XPAth Expression Rule:
Enter the to be processed against an XML representation ofXPath Expressiona request.Enter the you want to match to the value that results from the XPathValueExpression.For example, to find a match between the Host header in this request and anXPath Expression:
Enter an such as and enter a XPath Expression //header[@name='Host']/text() such as .Value localhost:3000
Select if when a match is found, access is not allowed.NegateClick when you finish.SAVE
Error-Handling Fields for Rules
You can customize an error message to display as part of the default error pagerendered in the end-user's browser if Rule evaluation fails. This page is among the
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
templates you can modify with your own branding or other information (see Customize). Use the following fields to configure the error handling.User-Facing Pages
Field Description
ErrorResponseCode
The HTTP status response code you want to send if Rule evaluationfails--for example, .403
ErrorResponseStatusMessage
The HTTP status response message you want to return if Ruleevaluation fails--for example, .Forbidden
ErrorResponseTemplateFile
The HTML template page for customizing the error message thatdisplays if Rule evaluation fails. This template file is located in the
directory.<pa_install>/conf/template/
ErrorResponseContentType
The type of content for the error response so the client can properlydisplay the response.
Manage Rule Sets
Manage Rule Sets
Rule Sets allow you to group multiple Rules into re-usable sets. Rule Sets tie togetherdifferent Rules used in a single policy. The column displays available RuleRule SetsSets.
To create a Rule Set:
Click at the top of the column.Rule SetsDrag-and-drop a Rule from the column onto the box that appears.RulesEnter a name for the Rule Set in the box that appears. Special characters andspaces are allowed.
Select as the to require all Rules in the set to succeed.Success Criteria
Select to require just one of the Rules in the set to succeed.
© 2013 Ping Identity Corporation All Rights Reserved
4.
5.
6.
7.
1.
2.
1.
2.
When is set to , the first rule establishes theSuccess Criteria Anyerror handling and is flagged with an information icon . When
is set to , the first rule in the set that failsSuccess Criteria Allestablishes the error handling.
When is set to , PingAccess flagsSuccess Criteria AnyProcessing Rules in a Rule Set with a warning icon . This isconsidered a misconfiguration because in an Rule Set, the firstAnyProcessing Rule should succeed, causing all other rules in the setto not be evaluated. If you want to use Processing Rules onprotected Resources as well as handle access control decisionsusing criteria, assign Processing Rules directly to theAnyResource or create a separate Rule Set for the Processing Rulesusing the criteria."All
Click to save the Rule Set.Add more Rules.
Expand the Resource you want to add the Rule Set to and drag the Rule Setonto the box that appears to create a policy.
To edit a Rule Set:
Click on the Rule Set you want to edit and click Edit.Drag a Rule within a Rule Set up or down to re-order the Rules.Click on the Rule you want to remove from a Rule Set.Click to cancel Edit mode without saving changes.
Click to save your changes.
To add a Rule Set to a Resource:
Drag a Rule Set onto the box of an expanded Resource to add it to create apolicy.
To delete a Rule Set:
Click on the Rule Set you want to delete and click Delete.Click in the confirmation window.DELETE
© 2013 Ping Identity Corporation All Rights Reserved
2.
If the Rule Set is associated with a Resource, you cannot delete it.
Groovy Scripts
Groovy Scripts
Groovy scripts provide advanced Rule logic that extends PingAccess Rule developmentbeyond the capabilities of the packaged . Groovy scripts have access toRule Setsimportant PingAccess runtime objects such as the and Exchange PolicyContextobjects, which the scripts can interrogate and modify. Groovy Script Rules are invokedduring the request processing phase of an exchange, allowing the script to modify therequest before it is sent to the server. Groovy Script Rules are also invoked during theresponse, allowing the script to modify the response before it is returned to the client.
Matchers
Groovy scripts must end execution with a Matcher instance. Matchers provide aframework for establishing declarative Rule matching objects. You can use a Matcherfrom the list of or from the .PingAccess matchers Hamcrest library
The following are Hamcrest method examples for constructing access control policieswith the using evaluations such as an OR groupWeb Session Attribute Rulemembership evaluation.
- Matches if the examined object matches ALL of the specified matchers. In thisallOfexample, the user needs to be in both the sales and managers groups for this rule topass.
allOf(containsWebSessionAttribute("group","sales"),containsWebSessionAttribute("group","managers"))
- Matches any of the specified matchers. In this example, the rule passes if theanyOfuser is in any of the specified groups.
anyOf(containsWebSessionAttribute("group","sales"),containsWebSessionAttribute("group","managers"),containsWebSessionAttribute("group","execs"))
- Inverts the logic of a matcher to not match. In this example, the rule fails if thenot
© 2013 Ping Identity Corporation All Rights Reserved
user is in both the sales and the managers groups.
not(allOf(containsWebSessionAttribute("group", "sales"),containsWebSessionAttribute("group", "managers")))
See for more information.Matchers
Objects
The following objects are available in Groovy. Click a link for more information on thatobject.
Exchange Object: Contains the HTTP request and the HTTP response for thetransaction processed by PingAccess.PolicyContext Object: Contains a map of objects needed to perform policydecisions. The contents of the map vary based on the context of the current userflow.Request Object: Contains all information related to the HTTP request made to a
.ResourceResponse Object: Contains all information related to the HTTP response.SiteMethod Object: Contains the HTTP method name from the request made to a
.ResourceHeader Object: Contains the HTTP header information from the request made toa or the HTTP header from a response.Resource SiteBody Object: Contains the HTTP body from the request or the HTTPResourcebody from the response.SiteOAuthToken Object: Contains the OAuth access token and related identityattributes.
Debugging/Troubleshooting
Groovy Script Rules are evaluated when saved to ensure that they are syntacticallyvalid. If a Groovy Script Rule fails to save, check the log for output with the exception
. For example, if you are trying to save a Groovy Script Rulejavax.script.ScriptExceptionthat references the missing method , the following output would be logged:foo()
© 2013 Ping Identity Corporation All Rights Reserved
DEBUG com.pingidentity.synapse.adminui.AdminAPIInterceptor:1585 -javax.script.ScriptException: javax.script.ScriptException: groovy.lang.MissingMethodException: No signatureof method: org.codehaus.groovy.jsr223.GroovyScriptEngineImpl.foo() is applicable forargument types: () values: []Possible solutions: find(), any(), get(java.lang.String),use([Ljava.lang.Object;), is(java.lang.Object), find(groovy.lang.Closure)DEBUG com.pingidentity.synapse.adminui.AdminAPIInterceptor:1399 - Returningerror to UI: [[Error occurred validating policy.], {}]
These error messages are only logged if the DEBUG level output isenabled for the logger.com.pingidentity
Matchers
Matchers
The and the must end execution with aGroovy Script Rule OAuth Groovy Script RuleMatcher instance. This could either be a Matcher from the list of PingAccess matchersor from the (for more information on Hamcrest, see the Hamcrest library Hamcrest
). Tutorial Example 1 - Simple Groovy Rule Inserts a Custom HTTP Header
test = "let's get Groovy!"exc?.response?.header?.add("X-Groovy", "$test")anything()
In the sample rule above, the script ends with a call to the Matcher . The anything() Matcher signals that the rule has passed.anything()
Example 2 - OAuth Groovy Rule Checks the HTTP Method and Confirms the OAuthScope
//Get the HTTP method namedef methodName = exc?.request?.method?.methodName()if (methodName == "POST") { hasScope("WRITE")} else { not(anything())}
In the sample rule above, a Matcher is evaluated at the end of each line of execution.The first Matcher used is the Matcher that confirms if the OAuth AccesshasScope()
© 2013 Ping Identity Corporation All Rights Reserved
token has the scope. If this is true, the rule passes.WRITE
The Matcher combination is evaluated when the does notnot(anything()) methodNameequal . This Matcher combination evaluates to false.POST
PingAccess Matchers
The following table lists the Matchers available for the Groovy Script Rule and theOAuth Groovy Script Rule.
Matcher Description
inIpRange(String cidr) Validates the source IP address of the request against the CIDRparameter.Example: inIpRange("127.0.0.1/8")
inIpRange(java.net.InetAddressipAddress,int prefixSize)
Validates the Resource Request IP address against the andipAddressthe parameters.prefixSizeExample: inIpRange(InetAddress.getByName("0:0:0:0:0:0:0:1"),8)
requestXPathMatches(StringxPathString, String xPathValue)
Validates that the value returned by the parameter is equalxPathStringto the parameter.xPathValueExample: requestXPathMatches("//header[@name='Host']/text()","localhost:3000")
inTimeRange(String startTime,String endTime)
Validates that the current server time is between the and startTime parameters.endTime
Example: inTimeRange("9:00 am","5:00 pm")
inTimeRange24(String startTime,String endTime)
Validates that the current server time is between the specified 24-hourformatted time range between the and parameters.startTime endTimeExample: inTimeRange24("09:00","17:00")
requestHeaderContains(String field,String value)
Validates that the HTTP header field value is equal to the valueparameter.Example: requestHeaderContains("User-Agent", "Mozilla/5.0(Macintosh; Intel Mac OS X 10_8_3) AppleWebKit/537.36 (KHTML, likeGecko) Chrome/27.0.1453.93 Safari/537.36")
© 2013 Ping Identity Corporation All Rights Reserved
requestHeaderDoesntContain(Stringfield, String value)
Validates that the HTTP header field value is not equal to the valueparameter.Example: requestHeaderDoesntContain("User-Agent","InternetExplorer")
requestBodyContains(String value) Validates that the HTTP body contains the value parameter.Example: requestBodyContains("production")
requestBodyDoesntContain(Stringvalue)
Validates that the HTTP body does not contain the value parameter.Example: requestBodyDoesntContain("test")
containsWebSessionAttribute(StringattributeName, String
attributeValue)
Validates that the contains the attribute name and value.PA TokenExample: containsWebSessionAttribute("sub", "sarah")
The following table lists the matchers available to only the OAuth Groovy Rule.
Matcher Description
hasScope(String scope) Validates that the OAuth access token contains thescope parameter.Example: hasScope("access")
hasScopes(String... scopes) Validates that the OAuth access token contains thelist of scopes.Example: hasScopes("access","portfolio")
hasAttribute(String attributeName, StringattributeValue)
Checks for an attribute value within the currentOAuth2 policy context.Example: hasAttribute("account","joe")
Exchange Object
Exchange Object
Accesses the Exchange object in Groovyexc
The Exchange object is available to both the and the regular OAuth Groovy Script Rule. PingAccess makes the Exchange object available to Groovy ScriptGroovy Script Rule
developers to provide request and response information for custom Groovy Rules.
© 2013 Ping Identity Corporation All Rights Reserved
The Exchange object contains both the HTTP request and the HTTP response for thetransaction processed by PingAccess. You can use this object to manipulate therequest prior to it being sent to the . You can also use this object to manipulate theSiteresponse from the Site before it is sent to the client.
An instance of the Exchange object lasts for the lifetime of a single request.ResourceThe Exchange object can be used to store additional information determined by thedeveloper.
Groovy Sample
//Evaluate if the content length of the request is emptyif (exc?.request?.header?.contentLength > -1 )
{ //Set a custom header in the request object exc?.request?.header?.add("X-PINGACCESS-SAMPLE", "SUCCESS") anything("Custom header added to request")}else{ println("Request content is empty") //Debugging statement not(anything("Request has no content"))}
Field Summary
Field Description
requestRequest Obtains the PingAccess representation of the request. This request issent to the with any changes that might be made in a GroovySitescript.
Responseresponse
Obtains the PingAccess representation of the response. If the hasSitenot been called, the response is null.
longtimeReqSent
Obtains the time, in milliseconds, when the request was sent to the .Site
longtimeResReceived
Obtains the time, in milliseconds, when the response was receivedfrom the .Site
Method Summary
© 2013 Ping Identity Corporation All Rights Reserved
Method Description
String getRequestURI() Returns the PingAccess URI that received the request.
MediaTypegetRequestContentType()
Convenience method that returns the request Content-Type.This method works the same as .exc?.request?.contentType
intgetRequestContentLength()
Convenience method that returns the requestContent-Length. This method works the same as
.exc?.request?.contentLength
MediaTypegetResponseContentType()
Convenience method that returns the responseContent-Type. This method works the same as
.exc?.response?.contentType
intgetResponseContentLength()
Convenience method that returns the responseContent-Length. This method works the same as
.exc?.response?.contentLength
Object getProperty(Stringkey)
Returns the value of a custom property.
void setProperty(String key,Object value)
Sets a custom property.
PolicyContext Object
PolicyContext Object
Accesses the Policy Context object in GroovypolicyCtx
The PolicyContext object is a map of objects needed to perform policy decisions. Thecontents of the map vary based on the context of the current user flow. A commonexample is OAuth token information stored in an OAuthToken object contained withinthe context map. In this example, an OAuthToken object is retrieved from the policycontext by using the key. The OAuthToken object is available only for the oauth_token
.OAuth Groovy Script Rule
Groovy Sample
def oauthToken = policyCtx?.context.get("oauth_token")
© 2013 Ping Identity Corporation All Rights Reserved
Field Summary
Field Description
java.util.Map context Container for the .OAuthToken object
Request Object
Request Object
Accesses the Request object in Groovyexc?.request
The Request object contains all information related to the HTTP request made to a . The request instance is sent on to the after the Rules are evaluated.Resource Site
Groovy Sample
//Retrieve the request object from the exchange objectdef request = exc?.request?.isJSON()
//Check to make sure the request body contains JSONif (!request) {not(anything("The request requires a JSON body"))} else { anything("The request contains JSON")}
Field Summary
Field Description
String URI Returns the PingAccess URI that received the request.
Methodmethod
Contains the HTTP method information from the request sent to the .Resource
Headerheader
Contains the HTTP header information from the request sent to the .Resource
Warning: Previously executed custom Rules can modifythese values.
© 2013 Ping Identity Corporation All Rights Reserved
bodyBody Contains the HTTP body information from the request sent to the .Resource
Warning: Previously executed custom Rules can modifythese values.
Method Summary
Method Description
boolean isXML() Returns true if the Content-Type header is set to .xml
boolean isJSON() Returns true if the Content-Type header is set to .application/json
booleanisHTML()
Returns true if the Content-Type header is set to .text/html
booleanisBodyEmpty()
Returns true if the Content-Length header is set to zero or the HTTPbody has zero length.
Response Object
Response Object
Accesses the Response object in Groovyexc?.response
The Response object contains all information related to the Service HTTP response.The response instance is sent on to the User-Agent after the Rules are evaluated.
Groovy Sample
// Intercept a server error (status code = 500) return a failuredef response = exc?.response
if (response.isServerError()) { not(anything("A server error occurred"))}
Field Summary
© 2013 Ping Identity Corporation All Rights Reserved
Field Description
int statusCode Contains the HTTP response status code.
StringstatusMessage
Contains the HTTP response status message.
headerHeader Contains the HTTP header information from the request sent to the .Resource
Warning: Previously executed custom Rules can modifythese values.
bodyBody Contains the HTTP body information from the request sent to the .Resource
Warning: Previously executed custom Rules can modifythese values.
Method Summary
Method Description
booleanisRedirect()
Returns true if the status code is in the 300’s.
booleanisUserError()
Returns true if the status code is in the 400’s.
booleanisServerError()
Returns true if the status code is in the 500’s.
booleanisBodyEmpty()
Returns true if the Content-Length header is set to zero or the HTTPbody has zero length.
Method Object
Method Object
Accesses the Method object in Groovyexc?.request?.method
© 2013 Ping Identity Corporation All Rights Reserved
The Method object contains the HTTP Method name from the request made to a . The HTTP Method is sent on to the after the Rules are evaluated.Resource Site
Groovy Sample
//Retrieve the HTTP Method name and make different decisions based on themethod namedef method = exc?.request?.method?.methodNameswitch (method) { case "GET": println("GET") break; case "POST": println("POST") break; case "PUT": println("PUT") break; case "DELETE": println("DELETE") break;default: println("DEFAULT") pass()}
Field Summary
Field Description
StringmethodName
Returns the name of the HTTP Method (GET, PUT, POST, DELETE,)�.HEAD
Header Object
Header Object
Accesses the Header object in Groovyexc?.request?.headerorexc?.response?.header
The Header object contains the HTTP Header information from the request made to a or the HTTP Header from a response. The HTTP Header isResource Site Request
sent on to the after the Rules are evaluated. The HTTP Header isSite Responsereturned to the client after the response Rules are evaluated.
© 2013 Ping Identity Corporation All Rights Reserved
Use the Header object to add custom HTTP headers for .Site
Groovy Sample
//Set a custom header for the Service requestdef header = exc?.response?.header;header?.add("X-PINGACCESS-SAMPLE", "SUCCESS");anything("Custom header set into request");
Method Summary
Method Description
void add(String key, Stringval)
Sets HTTP header fields for the request.
String getAccept() Returns the acceptable response Content-Types expected bythe User-Agent.
void setAccept(String value) Sets the acceptable response Content-Types expected by theUser-Agent.
String getAuthorization() Returns the authentication credentials for HTTPAuthentication.
void setAuthorization(Stringuser, String password)
Sets authentication credentials for HTTP Authentication.
String getConnection() Returns the connection type preferred by the User-Agent.
void setConnection(Stringconnection)
Sets the connection type preferred by the User-Agent.
int getContentLength() Returns the request body content length.
void setContentLength(intlength)
Sets the request body content length.
boolean hasContentLength() Returns true of the Content-Length header is set.
void setContentType(Stringvalue)
Sets the request body MIME type.
Map getCookies() Returns all cookies sent with the request.
void setCookie(String value) Sets a cookie.
String getFirstCookieValue() Returns the first cookie in the Cookie header.
© 2013 Ping Identity Corporation All Rights Reserved
String getFirstValue(Stringvalue)
Returns the first value of the HTTP header specified by thevalue.
void setDate(Date date) Sets the date of the message in the Date HTTP header.
String getHost() Returns the hostname specified in the request.
void setHost(String value) Sets the hostname for the request to the .Site
String getLocation() Gets the redirect location URL for the response.
void setLocation(Stringvalue)
Sets the redirect location URL for the response.
StringgetProxyAuthorization()
Returns the proxy credentials.
voidsetProxyAuthorization(String
value)
Sets the request proxy credentials.
void setServer(String value) Sets the server name for the response.
String getXForwardedFor() Returns the originating IP address of the client and theproxies, if set.
voidsetXForwardedFor(String
value)
Sets the IP Address for the client and the proxies.
booleanremoveContentEncoding()
Removes the Content-Encoding header value. Returns true ifthe value has been removed.
booleanremoveContentLength()
Removes the Content-Length header value. Returns true ifthe value has been removed.
booleanremoveContentType()
Removes the Content-Type header value. Returns true if thevalue has been removed.
boolean removeExpect() Removes the Expect header value. Returns true if the valuehas been removed.
boolean removeFields(Stringname)
Removes the header value specified by the name parameter.Returns true if the value has been removed.
booleanremoveTransferEncoding()
Removes the Transfer-Encoding header value. Returns true ifthe value has been removed.
Body Object
© 2013 Ping Identity Corporation All Rights Reserved
Body Object
Accesses the Body object in Groovyexc?.request?.bodyorexc?.response?.body
The Body object contains the HTTP body from the Resource request or the HTTP bodyfrom the Site response. The request HTTP body is sent on to the Site after the Rulesare evaluated. The response HTTP body is sent on to the User-Agent after theresponse Rules are evaluated.
Groovy Sample
//Checks the actual length of the body content and set the Content-Lengthresponse headerdef body = exc?.response?.body;def header = exc?.response?.header;header.setContentLength(body.getLength());anything("Content-Length header set");
Method Summary
Method Description
byte[] getContent() Returns the body content of the request or response.
int getLength() Returns the length of the body content.
OAuth Token Object
OAuth Token Object
Accesses the OAuth Token object in GroovypolicyCtx?.context.get("oauth_token")
The OAuthToken object contains the OAuth access token and related identityattributes. The OAuthToken instance is available only for Rules.OAuth Groovy Script
Groovy Sample
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
1.
2.
3.
def user =policyCtx.context.get("oauth_token")?.attributes?.get("user")?.get(0)exc?.request?.header?.add("User", "$user")anything()
Field Summary
Field Description
Date expiresAt Contains the expiration date of the OAuth access token.
Date retrievedAt Contains the date that the OAuth access token was retrieved fromPingFederate.
String tokenType Contains the type of OAuth access token. (Bearer, ).JWT
String clientId Contains the client ID associated with the OAuth access token.
Set scopes Contains the set of scopes associated with the OAuth accesstoken.
Map<String, List>attributes
Contains a map of identity attributes specific to the user.
Map Rules to Resources
Map Rules to Resources
The page is a drag-and-drop interface where you can createPolicy ManagerRules and build Rule Sets, and then map the Rules to Resources--creating
policies.
To map Rules and Rule Sets to a Resource:
Expand the .ResourceDrag and drop Rules and Rule Sets onto the box that appears.
To edit a Resource:
Expand the .ResourceDrag and drop Rules and Rule Sets onto the Policy box.Drag Rules and Rule Sets around in the box to change the order in which Rulesare evaluated at runtime.
© 2013 Ping Identity Corporation All Rights Reserved
3.
4.
1.
2.
a.
b.
a.
b.
c.
d.
Ordering Rules may enhance performance--for example, to failfaster and improve performance as you move through PingAccess.
Click to remove a Rule or Rule Set from a Resource.
Modify Rule Mappings for a Resource
Modify Rule Mappings for a Resource
Update Rules for a Resource by creating more Rules or editing existing Rules using the page and the page.Resources Policy Manager
To add more Rules or edit existing Rules:
On the page, click next to on a Resource card. The Resources Policy Policy page appears for editing Rules and Rule Sets.Manager
On the page:Policy Manager
To map Rules and Rule Sets to a Resource:Expand the .ResourceDrag and drop Rules and Rule Sets onto the box that appears.
To edit a Resource:Expand the .ResourceDrag and drop Rules and Rule Sets onto the Policy box.Drag Rules and Rule Sets around in the box to change the order in whichRules are evaluated at runtime.
Ordering Rules may enhance performance--for example, tofail faster and improve performance as you move throughPingAccess.
Click to remove a Rule or Rule Set from a Resource.
Managing Security
Managing Security
PingAccess provides built-in certificate management to handle secure HTTPS
© 2013 Ping Identity Corporation All Rights Reserved
connections. Certificates contain information about the owner of the certificate alongwith a public key. Digital certificates are issued by a trusted Certificate Authority (CA),which is a service that is a core entity in a public-key infrastructure (PKI).
Certificates used by PingAccess may be issued by a CA or self-signed. CA-issuedcertificates are recommended to simplify trust establishment and minimize routinecertificate management operations. Implementations of an X.509-based PKI (PKIX)typically have a set of root CAs that are trusted, and the root certificates are used toestablish chains of trust to certificates presented by a client or a server duringcommunication.
Individual Certificates
Administrators import certificates into PingAccess to establish a set of trusted root CAsthat are used to establish trust to certificates presented during secure HTTPSconnections. PingAccess interacts with CAs using PKIX. If a target Site is using acertificate not signed by a root CA trusted by PingAccess, communication with thetarget Site is not allowed.
The following formats for X.509 certificates are supported:
Base64 encoded DER (PEM)Binary encoded DER
Certificate Groups
A Certificate Group is a trusted set of anchor certificates used when authenticating atarget Site over HTTPS.
Key Pairs
Key Pairs can be associated with HTTPS listeners used by PingAccess. Thesecurrently include runtime ports that serve Resources over HTTPS and the port used bythe PingAccess administrative console. Additionally, key pairs can be used toauthenticate PingAccess to a Site when using the . YouMutual TLS Site Authenticatorcan use PingAccess to generate key pairs by providing identify information such ascommon name (or host name) for the certificate and the private key algorithm. You canalso create Key Pairs by uploading to PingAccess an existing Key Pair in PKCS#12format.
© 2013 Ping Identity Corporation All Rights Reserved
This requires the password used to encrypt entries in the PKCS#12container.
Certificate Signing Request (CSR)
After generating a key pair, you can use PingAcccess to create a CSR to requestcertificate issuance from a CA. After the CA generates a Certificate Signing Response,you can associate the newly issued certificate with the originally requesting key pairentry. The CA's certificate must be stored in PingAccess or in the Java runtime cacertsstore.
Generate or Import Key Pairs
Generate or Import Key Pairs
To generate or import additional Key Pairs to secure access to the PingAccessadministrative console and for incoming HTTPs requests at runtime as well as for usewith the Mutual TLS Site Authenticator:
Generate Key Pairs
Access the New Key Pair page by selecting and clicking Settings | Key Pairs New.Key Pair
The table below describes the fields required for the Key Pair. This information is usedas metadata for the self-signed certificate that is generated as part of the Key Pair.Click when you finish. A new Key Pair card appears on the page.SAVE Key Pairs
Field Description
Alias A user-defined name that identifies the Key Pair. Special charactersand spaces are allowed. This name identifies the Key Pair on the Key
page and when assigning the Key Pair to various configurationsPairssuch as when creating a .Mutual TLS Site Authenticator
CommonName
The common name (CN) identifying the certificate. This is typically thehost name for PingAccess.
Organization The organization (O) or company name creating the certificate.
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
5.
OrganizationUnit
Optional. The specific unit within the organization (OU).
City Optional. The city or other primary location (L) where the companyoperates.
State Optional. The state (ST) or other political unit encompassing thelocation.
Country The country (C) where the company is based. Enter the country usingtwo capital letters--for example, .US
Valid Days The number of days the certificate is valid.
KeyAlgorithm
The algorithm used to generate a key. PingAccess uses one of threealgorithms, , , or .EC DSA RSA
Key Size(bits)
The number of bits used in the key (EC- , , or , DSA- or 256 384 521 768, RSA- , , or ).1024 1024 2048 4096
Import Key Pairs
Access the Import Key Pair page by selecting and clicking Settings | Key Pairs Import.
To import the Key Pair file:
In the box, enter a name that identifies the Key Pair. Special charactersAliasand spaces are allowed. This name identifies the Key Pair on the pageKey Pairsand when assigning the Key Pair to various configurations such as an HTTPS
.ListenerEnter the used to protect the PKCS#12 file. PingAccess uses thePasswordpassword to read the file.Click to locate the PKCS#12 file.CHOOSE FILEHighlight the file and click .OpenClick to import the file. A new card appears for the imported Key Pair onSAVEthe page.Key Pairs
Secure Access for HTTPS Listeners
Secure Access for HTTPS Listeners
PingAccess listens for client requests on the administrative console port and on the
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
PingAccess engine port. To enable these ports for HTTPS, the first time you start upPingAccess, it generates and assigns a Key Pair for each port. Using the Key Pairspage, you can import or generate additional Key Pairs to secure access to these ports.These generated Key Pairs are initially assigned on the HTTPS Listeners page.
The settings for the ENGINE runtime port only apply when PingAccess isconfigured to use HTTPS in the file.run.properties
To assign a new Key Pair to an HTTPS Listener:
Click for the configured HTTPS Listener you want to edit and click Edit.From the list, select a different Key Pair you want to use for secure HTTPScommunication.Click when you finish.SAVE
You must restart each PingAccess server, including all engines in aclustered deployment, for changes to take effect.
Import a Certificate
Import a Certificate
Administrators import certificates into PingAccess to establish a set of trusted root CAsthat are used to establish trust to certificates presented during secure HTTPSconnections.
To import a certificate:
Click . The New Certificate page appears.Click to locate the certificate.CHOOSE FILEHighlight the file and click .OpenClick to import the certificate. A new certificate row appears on the CertificatesSAVEpage.
Create a Trusted Certificate Group
Create a Trusted Certificate Group
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
A Certificate Group is a trusted set of anchor certificates used when authenticating atarget Site over HTTPS.
To create a Trusted Certificate Group:
Drag-and-drop a certificate into the box to create a new Trusted Certificate Group. A new card for the group appears below the Java Trust Store card.To add more certificates to the group, drag-and-drop each certificate onto thenew group card.
Administering PingAccess
Administering PingAccess
Common administrative tasks for PingAccess are discussed in this section. Use thefollowing links to learn more about these tasks and others.
Change Configuration Properties
Change the Administrator Password
Change Configuration Database Passwords
Configure PingAccess Servers into a Cluster
PingAccess Endpoints
Manage Log Files
Customize User-Facing Pages
Add New Virtual Hosts
Associate a New Resource with a Site
Change Configuration Properties
Change Configuration Properties
The default PingAccess administrative-console and some runtime behavior is controlledin part by configuration properties in the file , located in: run.properties
. The majority of the runtime configuration data is<pingaccess_install>/pingaccess/confstored in the data store--for example, , , . Refer to the file itself forResources Rules Sitesdefault settings not specified here.
© 2013 Ping Identity Corporation All Rights Reserved
When storing passwords in the file, we recommend yourun.propertiesobfuscate them using the utility to mask the passwordobfuscate.bat|shvalue. Locate this utility at the root.<pa_install>
Change these properties as needed. Restart the PingAccess server for the changes totake effect.
Property Description
pa.operational.mode Controls the operational mode of the PingAccess server.Valid values include:STANDALONE - Use this value for a standalone PingAccessinstance that runs both the administrative console and theengine. This is the default.
CLUSTERED_CONSOLE - Use this value for the serverinstance you want to use as the administrative consoleserver.
Only one node in a cluster can run theadministrative console.
CLUSTERED_ENGINE - Use this value to indicate a serverengine.
Admin and Engine Cluster Settings
Define all six of the following properties when is set to pa.operational.mode.STANDALONE
Define only the properties when using mode.admin CLUSTERED_CONSOLEDefine only the properties when using mode.engine CLUSTERED_ENGINE
Property Description
admin.port Defines the TCP port on which the PingAccessadministrative console runs. Default is .9000
© 2013 Ping Identity Corporation All Rights Reserved
admin.acceptors Defines the number of threads servicing . Foradmin.portoptimal performance, this value should be equal to at leasthalf the number of CPUs running on the administrativeconsole server, and no more than the same number ofCPUs. The default is .5
engine.http.port Defines the TCP port on which the engine runs. Default is .3000
engine.http.acceptors Defines the number of threads servicing the engine. Foroptimal performance, this value should be equal to at leasthalf the number of CPUs running on the engine node, andno more than the same number of CPUs. Default is .5
engine.http.secure Defines whether the engine is using HTTPS. Default is .true
admin.ssl.ciphers Defines the type of cryptographic ciphers available for usewith administrative HTTPS ports.
engine.ssl.ciphers Defines the type of cryptographic ciphers available for usewith engine HTTPS ports.
General Administrative Console Settings
Uncomment to enable these properties.
Property Description
admin.auth Overrides the administrator authentication. For example, if ismethod SSO Authentication
enabled and is somehow misconfigured, thisproperty could be used to bypass the databaseconfiguration and use .Basic Authentication
pa.ui.idleExpirationInMinutes Defines the length of time in minutes until aninactive administrative console (or the
console) times out.interactive documentationDefault is minutes.30
pa.ui.maxExpirationInMinutes Defines the length of time in minutes until theadministrative console (active or inactive) timesout. Default is minutes. User may also use 240
to set the max expiration to one year.-1
© 2013 Ping Identity Corporation All Rights Reserved
pa.ui.expirationWarningInMinutes Defines the length of time in minutes that awarning message displays prior to a time out ofthe administrative console. Default is minute.1
pa.ui.legacyBrowserMode Adjusts Administrative console HTTP headerrequirements to be interoperable with legacyWeb browsers (Internet Explorer 9, etc).
Configuration Database and Keystore Settings
Define the username and passwords for the PingAccess andconfiguration databasethe password for the keystore.cacerts
Property Description
pa.jdbc.username Defines the username for accessing the PingAccessconfiguration database. Default is .sa
pa.jdbc.password Defines the password for the database user of thePingAccess configuration database. Default is .2Access
pa.jdbc.filepassword Defines the password used to encrypt the PingAccessconfiguration database. Default is .2Access
pa.keystore.pw Defines the password for the keystore.$JAVA_HOME/lib/security/cacerts
Cluster Configuration Settings
Use the following properties when engine nodes are sharing information:clustered
Property Description
© 2013 Ping Identity Corporation All Rights Reserved
pa.cluster.interprocess.communication Defines how the JGroups clustercommunicates.none (the default): Indicates that nocommunication is configured betweenservers in the cluster.udp: Indicates that the cluster usesMulticast communications to send andreceive information to and frommultiple servers at once.tcp: Indicates that the cluster usesUnicast communications to send andreceive information to and fromindividual servers one at a time.
pa.cluster.auth.pwd Sets the password that each node inthe cluster must use to authenticatewhen joining the group. This preventsunauthorized nodes from joining acluster. (Values: any string or blank)
pa.cluster.encrypt Indicates whether to encrypt networktraffic sent between nodes in acluster. (Values: or [default])true false
pa.cluster.bind.address Defines the IP address to which youbind the TCP or UDP listener. Thedefault is .127.0.0.1
pa.cluster.bind.port The port associated with thebind-address property above. Thedefault is . Whether this is a TCP7600or UPD port depends on the valueconfigured for the pa.cluster.interprocess.communicationproperty (see above).
© 2013 Ping Identity Corporation All Rights Reserved
pa.cluster.failure.detection.bind.port Indicates the bind port of a serversocket that is opened on the givennode and used by other nodes as partof one of the cluster's failure-detectionmechanisms. This port is bound to theaddress determined by
. The default ispa.cluster.bind.address. Whether this is a TCP or UDP7700
port depends on the value configuredfor the pa.cluster.interprocess.communicationproperty (see above).
pa.cluster.mcast.group.address Defines the IP address shared amongnodes in the same cluster for UDPmulticast communication; requiredwhen the interprocess communicationmode is set to . (Range: udp 224.0.0.0to ; note that some239.255.255.255addresses in this range are reservedfor other purposes.) This property isnot used for TCP. All nodes in acluster must use the same address forthis property and the port propertybelow.
pa.cluster.mcast.group.port Defines the UDP port associated withthe pa.cluster.mcast.group.addressproperty above.
pa.cluster.tcp.discovery.initial.hosts Designates the initial hosts to becontacted for group membershipinformation when discovering andjoining the group; required when theinterprocess communication mode isset to . The value is atcpcomma-separated list of host names(or IPs) and ports--for example,
.127.0.0.1[7602]
© 2013 Ping Identity Corporation All Rights Reserved
1.
engine.polling.initialdelay Defines, in milliseconds, how longafter the engine starts up before itbegins to poll the administrativeconsole for configuration information.The default is .500
engine.polling.delay Defines, in milliseconds, how longafter the initial query to theadministrative console that the enginebegins querying for configurationinformation. The default is every 2000milliseconds.
pa.websession.updateTokenWindowInSeconds Defines (in seconds) how long beforean active Web Session token isupdated. The default is every 60seconds.
pa.admin.user.password.regex Defines the regular expression forpassword complexity in administratorpasswords. Valid password mustsatisfy the regular expression.
pa.admin.user.password.error.message Defines the required passwordinformation that displays in apassword error message when a newadministrator attempts to change theirpassword and fails the complexitydefined for the pa.admin.user.password.regexproperty.
Change the Administrator Password
Change the Administrator Password
Change the administrator password using the pageBasic Authenticationwithin Settings.
To change the PingAccess Administrator password:
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
Enter the current administrator password in the box.Current PasswordEnter the new administrator password in the .New PasswordEnter the new password again to confirm it in the box.Confirm PasswordClick .SAVE
The new password must be at least six characters and contain atleast one uppercase, one lowercase, and one numeric character.
Change Configuration Database Passwords
Change Configuration Database Passwords
This page provides the steps to change the file and user passwords of the PingAccessconfiguration database. The server uses the file password to access the encrypteddatabase and the user password to log in to the database after gaining access to thefile. Use the and scripts located at the root todbfilepasswd dbuserpasswd <pa_install>change these passwords to more secure, independent ones.
The default password for both the database file and database user is .2Access
To change the file password:
LinuxFrom a command prompt, execute the shell script.<pa_install>/dbfilepasswd.sh
WindowsFrom the dialog or a command prompt, run the batch file:Start > Run<pa_install>\dbfilepasswd.bat
This script uses the old password and the new password as parameters--for example, and outputs the new password indbfilepasswd.sh old_password new_password
obfuscated format (similar to running ). Set this new obfuscated passwordobfuscated.shas the value for the property in the file (see pa.jdbc.filepassword run.properties Change
).Configuration Properties
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
To change the database user password:
LinuxFrom a command prompt, execute the shell script.<pa_install>/dbuserpasswd.sh
WindowsFrom the dialog or a command prompt, run the batch file:Start > Run<pa_install>\dbuserpasswd.bat
This script uses the database file password, the old password, and the new passwordas parameters--for example, dbuserpasswd.sh file_password old_password
and outputs the new password in obfuscated format (similar to running new_password). Set this new obfuscated password as the value for the obfuscated.bat
property in the file (see pa.jdbc.password run.properties Change Configuration).Properties
Configure PingAccess Servers into a Cluster
Configure PingAccess Servers into a Cluster
Follow the steps below to configure and deploy clustered PingAccessservers. Several of these steps involve changing property values in the
file located in the directory.run.properties <pa_install>/conf
To configure PingAccess servers into a cluster:
For each node in a cluster, follow the PingAccess installation steps (see Install).PingAccess
In the file, change the value from run.properties pa.operational.mode to:STANDALONE
CLUSTERED_CONSOLE on the server you want to use as theadministrative console serverCLUSTERED_ENGINE on each engine node
Runtime engines service client requests, while the consoleserver administers policy and configuration for the entirecluster (via the administrative console). A cluster may containone or more runtime nodes, but only one console node.
© 2013 Ping Identity Corporation All Rights Reserved
3.
4.
5.
6.
7.
8.
9.
a.
b.
c.
d.
If you plan to set up sub-clustering, for you must change the each engine node value from to either or in thepa.cluster.interprocess.communication none udp tcp
file. See for more information on therun.properties Cluster Configuration Settingssettings required for udp and tcp.
udp: Indicates that the cluster uses Multicast communications to send andreceive information to and from multiple servers at once.
tcp: Indicates that the cluster uses Unicast communications to send and receiveinformation to and from individual servers one at a time.
You can use sub-clustering to configure multiple, separatesub-clusters by using different passwords and different individualhosts (with tcp) or different multicast addresses and networksegmentation (with udp).
If you are running multiple engines on the same server, change the property for each clustered engine.engine.http.port
Start PingAccess and access the page within Settings.ClusterIn the Administrative Node section, enter the host name and port for theadministrative console server you designated as the inCLUSTERED_CONSOLEstep two above and click .SAVECreate a new Key Pair and self-signed certificate that includes the newadministrative console host name as the (see Common Name Manage Key
). If you already have a secure certificate for the administrative console,Pairsimport that certificate (see ).Import a Key PairAssign the new certificate to the administrative console (ADMIN) HTTPS Listener(see ).HTTPS Listeners
You must restart the administrative console server for changes totake effect.
Set up the engine nodes you want to communicate with the administrativeconsole on the page.Cluster
For each engine node:Click on the right to configure a new node.NEW ENGINE NODEEnter a for the node. Special characters and spaces are allowed.NameEnter a of the node.Description
© 2013 Ping Identity Corporation All Rights Reserved
9.
d.
e.
f.
Click to generate and download a public andSAVE & DOWNLOADprivate key pair into the file for the node. This file isbootstrap.propertiesprepended with the name you give the engine node. Depending on yourbrowser configuration, you may be prompted to save the file.
PingAccess automatically populates the Public Keys fieldonce you click .Save & Download
Copy each file to the directory of the corresponding<pa_install>/confengine node in the cluster and rename to . The nodebootstrap.propertiesuses this file to gain access to and communicate with the administrativeconsole for configuration updates.
Generate a new key for an engine at any time by clicking and replacing the old SAVE & DOWNLOAD
file with a new one. When that enginebootstrap.propertiesstarts up and begins using the new file, PingAccess deletesthe old key.
Start each node.
Engine Node Properties File
Engine Node Properties File
An administrator uses PingAccess to generate and download the bootstrap.propertiesfile when adding an engine node to a cluster (see Define the Admin Console and
). This file is specific to that engine and is stored with the engineRuntime Engine Nodesin the directory. The engine uses this file to gain access to and communicate with/confthe administrative console for configuration updates.
The following configuration properties are found in the file.bootstrap.properties
Property Description
engine.admin.configuration.host Defines the host where theadministrative console isavailable. The default is localhost
© 2013 Ping Identity Corporation All Rights Reserved
engine.admin.configuration.port Defines the port where theadministrative console isrunning. The default is 9000
engine.admin.configuration.userid Defines the name of the engine.
engine.admin.configuration.keypair Defines an elliptic curve keypair that is in the JSON Web
format.Key (JWK)
engine.admin.configuration.bootstrap.truststore Defines the truststore, in JWKformat, that is used forcommunication with theadministrative console.
PingAccess Endpoints
PingAccess Endpoints
The following endpoints provide a means by which external applications cancommunicate with the PingAccess server and provide complete administrativecapabilities of the product.
System-Service Endpoint--A maintenance endpoint is provided for administratorsto verify that the server is running.
OpenID Connect Endpoints--Endpoints needed for PingFederate to interface withPingAccess using the OpenID Connect (OIDC) protocol are also included.
Administrative API Endpoints--The Administrative API endpoints are used by thePingAccess administrative console. These are REST APIs that can be calledfrom custom applications or using command line tools such as curl.
System-Service Endpoint
System-Service Endpoint
This endpoint applies to the PingAccess server.
/pa/heartbeat.ping
This endpoint returns an browser message and an HTTP status indication if theOK 200PingAccess server is running. If you receive an error, the server associated with theendpoint is down. Load balancers can use this endpoint to determine the status of
© 2013 Ping Identity Corporation All Rights Reserved
PingAccess independently of checks used to determine the status of supportinghardware.
Begin the URL with the fully-qualified server name and port number of thePingAccess runtime port--for example, .http://host:3000/pa/heartbeat.ping
OpenID Connect Endpoints
OpenID Connect Endpoints
This page describes the endpoints needed for PingFederate to interface withPingAcccess using the OpenID Connect (OIDC) protocol.
/pa/oidc/logout
Clears the cookie containing the PA Token. This endpoint enables end users to triggerthe removal of their own PA Cookie from the browser they are using. The Logged Outpage is a template that can be modified (see ).Customize User-Facing Pages
This endpoint simply clears the PA Token from the browser cookie. Itdoes not retain any server-side state to denote log off. Additionally, thisendpoint clears the cookie only from the requested host/domain and maystill exist in requests bound for other hosts/domains.
/pa/oidc/cb
The OIDC callback endpoint that receives the ID Token from PingFederate.
/pa/oidc/JWKS
The JSON Web Key endpoint used by the PingFederate JWT Token Processor forsignature verification.
Administrative API Endpoints
Administrative API Endpoints
PingAccess ships with interactive documentation for both developers andnon-developers to explore the PingAccess API endpoints, view a reference of themetadata for each API, and experiment with API calls.PingAccess APIs are REST APIs that provide complete administrative capabilities ofthe product. They can be called from custom applications or from command line tools
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
1.
2.
3.
4.
such as cURL.
For enhanced API security, you must include X-XSRF-Header: in all requests and use the content type for PingAccess application/json requests.PUT/POST
To access the interactive documentation in PingAccess:
Start PingAccess.Launch your browser and go to:https://<DNS_NAME>:<port>/admin/api-docs/
The port is the value configured in the admin.port run.propertiesfile. When calling the APIs from outside of the interactive APIdocumentation, use
.https://localhost:9000/admin/rest/<api-endpoint>
To test an Administrative API using the interactive documentation:
Click to expand the API endpoint you want to test--for example, ./resourcesExpand the method you want to use--for example, GET.Enter any required parameters.Click . The Request URL, Response Body, Response Code, andTry It OutResponse Headers appear.
Manage Log Files
Manage Log Files
PingAccess logging is handled by the Blitz4j asynchronous logging library, configuredusing the file located in the directory of your PingAccessblitz4j.properties /confinstallation. Blitz4j is an extension of the Log4j framework, so the file isblitz4j.propertiessimilar to a file.log4j.properties
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
1.
2.
Audit logs are also configurable in the file. These logsblitz4j.propertiesrecord a selected subset of transaction log information at runtime plusadditional details (see ).Security Audit Logging
By default, logging information is output to the file located in the pingaccess.log /logsdirectory of your PingAccess installation. Logging to a file is configured to use the
file appender, which allows a log file to be 100 MB before the system starts arollingnew file. PingAccess keeps a maximum of 10 log files, each with a maximum size of100 MB. Once 10 files accumulate, PingAccess deletes the oldest. Configure theseoptions by locating and modifying the following properties in the asynchronous file
section of the file:logging configuration blitz4j.properties
log4j.appender.file.File=./logs/pingaccess.loglog4j.appender.file.MaxFileSize=100MBlog4j.appender.file.MaxBackupIndex=10
Log Levels
You can define log levels for specific package or class names in order to get more (orless) logging from a class or group of classes. For all other classes that do not have aspecific log level defined, the root log level applies.
To set the root level of logging:
Locate this line:
log4j.rootLogger=DEBUG,file
Modify the first value in the comma-separated list to one of the valid log levels: , , , , , .OFF,FATAL ERROR WARN INFO DEBUG TRACE
For example, to apply level logging, change TRACE to log4j.rootLogger=DEBUG,file log4j.rootLogger=TRACE,file
To set the log level for a specific class or package:
Locate the package or class name in the properties file.Set the first value in the comma-separated list to one of the valid log levels: OFF,
, , , , , .FATAL ERROR WARN INFO DEBUG TRACEFor example, to apply level logging for the package,TRACE com.pingidentitylocate the following line:log4j.logger.com.pingidentity=DEBUG,fileand change it to:
© 2013 Ping Identity Corporation All Rights Reserved
2.
log4j.logger.com.pingidentity=TRACE,file
Appending Log Messages to Syslog and to Console
Additional output destinations (called ) are available. Configuration for theappendersconsole and syslog appenders is included in the file, but not enabledblitz4j.propertiesby default. In the file, enable the console or syslog appenders by uncommenting andmodifying the configuration entries for and log4j.appender.console
respectively.log4j.appender.syslog
In addition to defining and configuring the appender using the log4j.appender. properties, you must do the following:AppenderName
Enable a new appenderAdd the appender to the root logger to enable logging not specifically controlledby a package/class name loggerAdd the appender to any of the package/class name specific loggers you wantappended
To enable a new appender:Add the appender name to the comma-separated list of asynchronous appenders--forexample, to enable the console logger, locate the following line:
log4j.logger.asyncAppenders=DEBUG,file
and change to:
log4j.logger.asyncAppenders=DEBUG,file,console
The DEBUG qualifier applied to the does not applyasyncAppendersDEBUG level logging to the appender. This setting exists for compatibilityin configuring Blitz4j on top of Log4j. It is recommended that you do notremove this value.
To add the appender to the root logger:Add the appender name to the rootLogger comma-separated list--for example, to addthe console appender, locate the following line:
log4j.rootLogger=DEBUG,file
and change to:
© 2013 Ping Identity Corporation All Rights Reserved
log4j.rootLogger=DEBUG,file,console
To add the appender to a package/classname specific logger:Add the appender name to a package/classname specific logger--for example, to addthe console appender to the package-specific logger, locate thecom.pingidentityfollowing line:
log4j.logger.com.pingidentity=DEBUG,file
and change to:
log4j.logger.com.pingidentity=DEBUG,file,console
Security Audit Logging
Security Audit Logging
The PingAccess audit logs record a selected subset of transaction log information atruntime plus additional details, intended to facilitate security auditing and regulatorycompliance. The logs are located in the directory of your PingAccess installation./logsElements of the logs are described in the table below and configurable in the
file located in .blitz4j.properties <pa_install>/conf
PingAccess generates these logs that document server events:
pingaccess_engine_audit.log--Records transactions of configured Resources.Additionally, the log records transaction details when PingAccess sends requeststo PingFederate (for example, STS, OAuth2, JWS).
pingaccess_api_audit.log--Records PingAccess administrative API transactions.These transactions represent activity in the PingAccess administrative console.This log also records transaction activity if you are using scripts to configurePingAccess.
Audit Log Configuration
Item Description
%d Transaction time.
© 2013 Ping Identity Corporation All Rights Reserved
AUDIT.authMech Mechanism used for authentication.Engine Auditing - (WAM session), , Cookie OAuth unknown(for example, pass-through or static assets). Pass-throughassets are Resources with no policies or Web sessionconfigured.Admin Auditing - , , , (Basic OAuth Cookie unknown unknowndisplays only in an authentication failure).
AUDIT.client IP address of the requesting client.
AUDIT.failedRuleName Name of the Rule that failed. If no Rule failure occurred, thisfield is blank. This element is applicable only to the
.pingaccess_engine_audit.log
AUDIT.failedRuleType Type of Rule that failed. If no Rule failure occurred, this fieldis blank. This element is applicable only to the
.pingaccess_engine_audit.log
AUDIT.host PingAccess host name or IP address.
AUDIT.method HTTP method of the request--for example, GET.
AUDIT.resource Name of the Resource used to fulfill the request. Thiselement is applicable only to the
.pingaccess_engine_audit.log
AUDIT.responseCode HTTP status code of the response--for example, 200.
AUDIT.requestUri Request URI portion of the request (for example, /foo/bar).
AUDIT.subject Subject of the transaction.
Writing Logs to Other Formats
Writing Logs to Other Formats
PingAccess provides the option of writing the administrative API and engine audit logsto an .Oracle database
To ensure availability of audit log information if database logging fails forany reason, enable both file and database audit logging. An automatedfailover from database to file logging is not currently available.
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
You may also configure PingAccess to write the audit logs to a differently formatted logfile that can easily be digested by .Splunk
Writing Logs to DatabasesWriting Audit Logs for Splunk
Writing Logs to Databases
Writing Logs to Databases
You can enable database logging for the API and engine audit logs in the file located in your PingAccess install. Scripts are provided to createblitz4j.properties
the necessary table(s).
To ensure availability of audit log information if database logging fails forany reason, enable both file and database audit logging. An automatedfailover from database to file logging is not currently available.
Ensure that your database-driver JAR file is installed in the directory. You must restart PingAccess after installing the<pa_install>/lib
driver.
To configure database logging:
In the file locate in the directory of your PingAccess install,blitz4j.properties /confuncomment one of the preset appender configurations listed below (or one fromeach list to configure all logs):For Administrative API audit logging: OracleDbApiAudit
: For Engine audit logging OracleDbEngineAuditReplace the placeholder parameter values for the appender(s) with valid values.
The parameter values provide access to the database. We recommend that theybe tested and validated prior to production deployment.
See the notes in the properties file above the appender for moredetails.
© 2013 Ping Identity Corporation All Rights Reserved
2.
3.
4.
You can obfuscate the password used to access the database byrunning either or , located at the obfuscate.sh obfuscate.bat
root. Use the actual password as an argument and<pa_install>copy the entire result into the value for the password parameter inthe properties file.
Add the appender name to the associated comma-separated list of appenders inthe section.Log Level ConfigurationOracle database API audit log:
Locate the line and add to the list--forlog4j.logger.apiaudit OracleDbApiAuditexample:
log4j.logger.apiaudit=INFO,apiaudit,OracleDbApiAudit
Oracle database engine audit log:
Locate the line and add to thelog4j.logger.engineaudit OracleDbEngineAuditlist--for example:
log4j.logger.engineaudit=INFO,engineaudit,OracleDbEngineAudit
Create database tables.
Scripts to create database tables are provided. The scripts are located in thedirectory:
pingaccess/conf/blitz4j/sql-scripts
The scripts are written to handle the default list of elements for therelevant database log-appender. Any changes to the list requirescorresponding changes to the SQL table-creation script (or to thetable itself if it is already created). For more information on workingwith this script, see the Oracle documentation.
Writing Audit Logs for Splunk
Writing Audit Logs for Splunk
Splunk is enterprise software that allows for monitoring, reporting, and analyzingconsolidated log files. Splunk captures and indexes real-time data into a singlesearchable repository from which reports, graphs, and other data visualization can begenerated.
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
5.
To configure PingAccess to write audit logs to a format for Splunk:
In properties file, uncomment one of the preset log-appender configurations listedbelow (or one from each list to configure all logs):
API audit logging for Splunk: SplunkApiAudit
Engine audit logging for Splunk: SplunkEngineAudit
Add the appender name to the associated comma-separated list of appenders inthe section.Log Level Configuration
API audit log for Splunk:Locate the line and add to the list--forlog4j.logger.apiaudit SplunkApiAuditexample:
log4j.logger.apiaudit=INFO,apiaudit,SplunkApiAudit
Engine audit log for Splunk:
Locate the line and add to thelog4j.logger.engineaudit SplunkEngineAuditlist--for example:
log4j.logger.engineaudit=INFO,engineaudit,SplunkEngineAudit
Save the file and start or restart PingAccess.Download and install the Splunk Universal Forwarder on the machine runningPingAccess.Configure the Universal Forwarder to monitor the
or the in pingaccess_api_audit_splunk.log pingaccess_engine_audit_splunk.log.<pa_install>/logs
For detailed installation and configuration instructions, consult theSplunk documentation accompanying the Universal Forwarder.
Monitoring
Monitoring
You can use an HTTPS call at any time to verify that the PingAccess server is running.
/pa/heartbeat.ping
This endpoint returns an browser message and an HTTP status indication if theOK 200PingAccess server is running. If you receive an error, the server associated with theendpoint is down. Load balancers can use this endpoint to determine the status of
© 2013 Ping Identity Corporation All Rights Reserved
PingAccess independently of checks used to determine the status of supportinghardware.
Begin the URL with the fully-qualified server name and port number of thePingAccess runtime port--for example, .http://host:3000/pa/heartbeat.ping
Customize User-Facing Pages
Customize User-Facing Pages
PingAccess supplies templates to provide information to the end user. These templatepages use the Velocity template engine, an open-source Apache project, and arelocated in the directory.<pa_install>/conf/template
You can modify most of these pages in a text editor to suit the particular branding andinformational needs of your PingAccess installation. (Cascading style sheets andimages for these pages are included in the <pa_install>/conf/static/pa/assetssubdirectory.) Each page contains both Velocity constructs and standard HTML. TheVelocity engine interprets the commands embedded in the template page before theHTML is rendered in the user’s browser. At runtime, the PingAccess server suppliesvalues for the Velocity variables used in the template.
For information about Velocity, refer to the on theVelocity project documentationApache Web site. Changing Velocity or Javascript code is not recommended.
The following variables are the only variables that can be used for rendering theassociated Web-browser page.
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 forrequest.
At runtime, the user's browser is directed to the appropriate page, depending on theoperation being performed and where the related condition occurs (see the table
© 2013 Ping Identity Corporation All Rights Reserved
below). For example, if Rule evaluation fails, the user's browser is directed to the Policyerror-handling page. The following table describes each template.
Template File Name Purpose Type Action
general.error.page.template.html Indicates that an unknownerror has occurred andprovides an error message.
Error Consult yoursystemadministrator.
general.loggedout.page.template.html Displayed when a user logsout of PingAccess.
Normal User shouldclose thebrowser
oauth.error.json Indicates that Rule evaluationhas failed and provides anoptional error message. Tocustomize this information,see Error-Handling Fields for
.OAuth Rules
Error Verify thatyour OAuthcredential isvalid andretry therequest.
policy.error.page.template.html Indicates that Rule evaluationhas failed and provides anoptional error message. Tocustomize this information,see Error-Handling Fields for
.Rules
Error Retry therequest.
The and engine.bootstrap.template.properties site.authenticator.rst.xmlfiles are system templates. We recommend that you do not modify thesefiles.
Add New Virtual Hosts
Add New Virtual Hosts
Add new virtual hosts for using the screen.Resources Settings
Virtual Hosting enables you to host multiple server or domain names. This allows oneserver to share Resources without requiring all Sites on the server to use the same hostname--for example, you may want to use multiple names on the same server so that
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
each Site name reflects the services offered rather than the actual server name wherethose Sites are hosted. Use the Virtual Hosts Settings page to define the virtual hostnames you want to use with Resources.
You can use wildcards when defining virtual hosts. For example, you have a domainhost and port of . You create a virtual host using wildcards suchhr.mycompany.com:80as . A user requests . The request goes to . This*:80 finance.mycompany.com:80 *:80allows you to funnel any virtual hosts that do not fall within a specific one.
When you configure virtual hosts and the back-end Site is expectingHTTPS, a secure channel between the client and PingAccess must bemediated before PingAccess can adjust the Target Host header. Becausethe SSL/TLS handshake takes place before the expected hostname issent to the server, the server does not know which certificate to present.Use a single certificate that covers multiple names either throughwildcards or the .SubjectAltName extension
To configure a Virtual Host:
Specify the host name and port for which PingAccess is accepting requests---forexample, .hr.mycompany.com:80Click to add it.Click to edit a Virtual Host.Click to delete a Virtual Host.
Associate a New Resource with a Site
Associate a New Resource with a Site
Associate a new Resource with a Site by creating the new Resource andthen associating the Site with that new Resource.
To add a new Resource to a Site:
Enter a unique . Up to 64 characters, including special characters and spaces,Nameare allowed. This name appears in the column on the pageResource Policy Managerand is associated with Sites on the page.SitesSelect the name and port or IP address of the server where the ResourceVirtual Host
© 2013 Ping Identity Corporation All Rights Reserved
is running--for example, or . Two defaults areBankServices.com:8080 127.0.0.1:3000included:
localhost:3000 - Select for use with locally-originated requests or for testing.
*:3000 - Select to accept requests for any host.
To populate this drop-down list, add virtual hosts to the Virtual Hostspage.
Enter an optional --for example, . To evaluate thisPath Prefix /BankServices/account/path as a regular expression, select the checkbox and enter the regularPatternexpression (for example, ). See for/resource/(\w+) Resource Path Regex Examplesmore examples.
The path prefix starts at the first forward slash after and extendshost:portto the end of the URL. Be sure to start the path you enter with a forwardslash.
Select the checkbox to evaluate what you enter in the box as aPattern Path Prefixregular expression.Select the checkbox to indicate that the Resource is mapped to a WebWeb SessionSite. Leave the checkbox clear to indicate that the Resource is mapped to an API Site.
You must configure a connection to the PingFederate OAuth as well as configure in orderAuthorization Server Web Session Settings
for a Web-enabled Resource to function properly.
Select an list to define how a user authenticates beforeAuthentication Requirementsaccess is granted to a protected Web Resource. This list box is only available when youspecify a (above) for the Resource (see Web Session Define Authentication
).RequirementsEnter the supported by the Resource. Leave the asterisk default if theMethodsResource supports all HTTP methods, including custom methods. Defining Methods fora Resource allows more fine-grained access control policies on API Resources. Forexample, if you have a server optimized for writing data (POST, PUT) and a serveroptimized for reading data (GET), you may want to segment traffic based on theoperation being performed.
© 2013 Ping Identity Corporation All Rights Reserved
Method selection is not available for Web Session Resources.
Select the checkbox to log information about the transaction to the audit store.AuditPingAccess audit logs record a selected subset of transaction log information at runtimeand are located in the directory of your PingAccess installation (see /logs Security Audit
).LogSelect the target where the Resource directs the client request.Site
You can map multiple Resources to one target Site.
Select to indicate the Resource is active and can process requests.EnabledClick when you finish.SAVE
Deploying PingAccess
Deploying PingAccess
There are many topics to consider when deciding how PingAccess fits into your existingnetwork, from determining the deployment architecture required for your use case andwhether high-availability options are required, to port requirements and clusteringoptions. This section provides information to help you make the right decisions for yourenvironment.
Use Cases and Deployment ArchitecturePort RequirementsPerformance TuningServer Clustering
Use Cases and Deployment Architecture
Use Cases and Deployment Architecture
There are many options for deploying PingAccess in your network environmentdepending on your needs and infrastructure capabilities. For example, you can design adeployment that supports mobile and API access management, Web accessmanagement, or auditing and proxying. For each of these environments, you canchoose a stand-alone deployment for proof of concept or deploy multiple PingAccess
© 2013 Ping Identity Corporation All Rights Reserved
servers in a cluster configuration for high availability, server redundancy, and failoverrecovery.
When designing a deployment architecture, many requirements and components mustbe identified for a successful implementation. Proper network configuration ofrouters/firewalls and DNS ensure that all traffic is routed through PingAccess for theResources it is protecting and that alternative paths (for example, backdoors) are notavailable.
The following sections provide specific use cases and deployment architecturerequirements to assist with designing and implementing your PingAccess environment.
Deploying for API Access ManagementDeploying for Web Access ManagementDeploying for Auditing and Proxying
Deploying for API Access Management
Deploying for API Access Management
A PingAccess API access management deployment enables an organization to quicklyset up an environment that provides a secure method of controlling access to APIswhile integrating with existing identity management infrastructure. Pressure from anever-expanding mobile device and API economy can lead developers to hastily designand expose API’s outside the network perimeter. Standardized API accessmanagement leads to a more consistent, centrally-controlled model that ensuresexisting infrastructure and security policies are followed, thereby safeguarding anorganization’s assets.
PingAccess sits at the perimeter of a protected network between mobile, in-browser, orserver-based client applications and protected APIs and performs the following actions:
Receives inbound API calls requesting protected Resources. OAuth-protectedAPI calls contain previously-obtained access tokens retrieved from PingFederateacting as an OAuth Authorization Server.Evaluates Resource-level policies and validates the tokens in conjunction withPingFederate.Acquires the appropriate target security token from the PingFederate STS orfrom a cache (including attributes and authorized scopes) should an API requireidentity mediation.Makes authorized requests to the APIs and responses are received and
© 2013 Ping Identity Corporation All Rights Reserved
processed.Relays the responses on to the clients.
The following sections describe sample Proof of Concept and Production architecturesfor an API access management use case deployment.
API Access Management POC Deployment ArchitectureAPI Access Management Production Deployment Architecture
API Access Management POC Deployment Architecture
API Access Management Proof of Concept Deployment Architecture
This environment is used to emulate a production environment for development andtesting purposes. In the test environment, PingAccess can be set up with the minimumhardware requirements. Given these conditions, we do not recommend using thisproposed architecture in a production deployment as it does not provide highavailability.
© 2013 Ping Identity Corporation All Rights Reserved
The following table describes the three zones within this proposed architecture.
Zone Description
ExternalZone
External network where incoming API requests originate.
DMZZone
Externally exposing segment where PingAccess is accessible to APIclients. PingAccess is a standalone instance in this environment, servingas both a runtime and an administrative port.
ProtectedZone
Back-end controlled zone in which Sites hosting the protected APIs arelocated. All requests to these APIs must be designed to pass throughPingAccess.PingFederate is accessible to API clients in this zone and is a standaloneinstance, serving as both a runtime and an administrative port.
API Access Management Production Deployment Architecture
API Access Management Production Deployment Architecture
There are many considerations when deploying a Production environment. For highavailability and redundancy, the environment requires clustering and load-balancing.Load balancers are required as part of the networking infrastructure to achieve highavailability by ensuring that requests are sent to available servers they are front-ending.Best practices in network design and security also include firewalls to ensure that onlyrequired ports and protocols are permitted across zones.
The following environment example is a recommended production quality deploymentarchitecture for an API access management use case.
© 2013 Ping Identity Corporation All Rights Reserved
The following table describes the three zones within this proposed architecture.
Zone Description
ExternalZone
External network where incoming API requests originate.
DMZZone
Externally exposing segment where PingAccess is accessible to APIclients. A minimum of two PingAccess engine nodes will be deployed inthe DMZ to achieve high availability. Depending on your scalabilityrequirements, more nodes may be required.
© 2013 Ping Identity Corporation All Rights Reserved
ProtectedZone
Back-end controlled zone in which Sites hosting the protected APIs arelocated. All requests to these APIs must be designed to pass throughPingAccess.PingFederate is accessible to API clients in this zone. A minimum of twoPingFederate engine nodes will be deployed in the protected zone.Administrative nodes for both PingAccess and PingFederate may beco-located on a single machine to reduce hardware requirements
Deploying for Web Access Management
Deploying for Web Access Management
A PingAccess Web access management (WAM) deployment enables an organizationto quickly set up an environment that provides a secure method of managing accessrights to Web-based applications while integrating with existing identity managementinfrastructure. With growing numbers of internal and external users, and more and moreenterprise resources available online, it is important to ensure that qualified users canaccess only those applications to which they have permission. A WAM environmentprovides authentication and policy-based access management while integrating withexisting infrastructure.
Sitting at the perimeter of a protected network between browsers and protectedWeb-based applications, PingAccess performs the following actions:
Receives inbound calls requesting access to Web applications. OAuth-protectedcalls contain previously-obtained access tokens retrieved from PingFederateacting as an OAuth Authorization Server.Evaluates Resource-level policies and validates the tokens in conjunction with anOpenID Connect Policy configured within PingFederate.Acquires the appropriate target security token from the PingFederate STS orfrom a cache (including attributes and authorized scopes) should a Webapplication require identity mediation.Makes authorized requests to the Sites where the Web applications reside andresponses are received and processed.Relays the responses on to the browsers.
The following sections describe sample Proof of Concept and Production architecturesfor a WAM use case deployment.
WAM POC Deployment Architecture
© 2013 Ping Identity Corporation All Rights Reserved
WAM Production Deployment Architecture
WAM POC Deployment Architecture
Web Access Management Proof Of Concept Deployment Architecture
This environment is used to emulate the Production environment for testing purposes.In the test environment, PingAccess can be set up with the minimum hardwarerequirements. This environment example does not provide high availability and is notrecommended for a Production environment.
The following table describes the three zones within this proposed architecture.
Zone Description
ExternalZone
External network where incoming requests for Web applications originate.
DMZZone
Externally exposing segment where PingAccess is accessible to Webbrowsers. PingAccess is a standalone instance in this environment,serving as both a runtime and an administrative port.
© 2013 Ping Identity Corporation All Rights Reserved
ProtectedZone
Back-end controlled zone in which Sites hosting the protected Webapplications are located. All requests to these Web applications must bedesigned to pass through PingAccess.PingFederate is accessible to Web browsers in this zone and is astandalone instance in this environment, serving as both a runtime and anadministrative port. PingFederate requires access to identity managementinfrastructure in order to authenticate users (depicted by the icon in thediagram).
WAM Production Deployment Architecture
Web Access Management Production Deployment Architecture
There are many considerations when deploying a Production environment. For highavailability and redundancy, the environment requires clustering and load-balancing.Load balancers are required as part of the networking infrastructure to achieve highavailability by ensuring that requests are sent to available servers they are front-ending.Best practices in network design and security also include firewalls to ensure that onlyrequired ports and protocols are permitted across zones.
© 2013 Ping Identity Corporation All Rights Reserved
The following table describes the three zones within this proposed architecture.
Zone Description
ExternalZone
External network where incoming requests for Web applications originate.
DMZZone
Externally exposing segment where PingAccess is accessible to Webbrowsers. A minimum of two PingAccess engine nodes will be deployed inthe DMZ to achieve high availability. Depending on your scalabilityrequirements, more nodes may be required.
ProtectedZone
Back-end controlled zone in which Sites hosting the protected Webapplications are located. All requests to these Web applications must bedesigned to pass through PingAccess.PingFederate is accessible to Web browsers in this zone and requiresaccess to identity management infrastructure in order to authenticateusers (depicted by the icon in the diagram). A minimum of twoPingFederate engine nodes will be deployed in the protected zone.Administrative nodes for both PingAccess and PingFederate may beco-located on a single machine to reduce hardware requirements.
Deploying for Auditing and Proxying
Deploying for Auditing and Proxying
A PingAccess deployment for auditing and proxying enables an organization to quicklyset up an environment that provides a secure method of controlling access to back-endSites. With growing numbers of internal and external users, it is important to knowwhich users are accessing applications, from where and when they are accessingthem, and ensuring that they are correctly accessing only those applications to whichthey have permission. A standardized auditing/proxying deployment provides acentrally-controlled model that ensures existing infrastructure and security policies arefollowed, thereby safeguarding an organization’s assets.
Sitting at the perimeter of a protected network between mobile, in-browser, orserver-based client applications and back-end Sites, PingAccess performs the followingactions:
Receives inbound calls requesting access to protected back-end Sites.Audits the request and then makes authorized requests to the back-end Sites.
© 2013 Ping Identity Corporation All Rights Reserved
Receives and processes responses and relays them on to the clients.
The following sections describe sample Proof of Concept and Production architecturesfor an auditing/proxying use case deployment.Audit and Proxy POC Deployment ArchitectureAudit and Proxy Production Deployment Architecture
Audit and Proxy POC Deployment Architecture
Auditing and Proxying Proof of Concept Deployment Architecture
This environment is used to emulate a production environment for development andtesting purposes. In the test environment, PingAccess can be set up with the minimumhardware requirements. Given these conditions, we do not recommend using thisproposed architecture in a production deployment as it does not provide highavailability.
The following table describes the three zones within this proposed architecture.
Zone Description
© 2013 Ping Identity Corporation All Rights Reserved
ExternalZone
External network where incoming requests originate.
DMZZone
Externally exposing segment where PingAccess is accessible to clients.PingFederate and PingAccess are standalone instances in thisenvironment, serving as both runtime and administrative ports.
ProtectedZone
Contains back-end Sites audited and proxied through PingAccess. Auditresults are sent to an audit repository or digested by reporting tools. Manytypes of audit repository/tools are supported such as SIEM/GRC, Splunk,database, and flat files.
Audit and Proxy Production Deployment Architecture
Auditing and Proxying Production Deployment Architecture
There are many considerations when deploying a Production environment. For highavailability and redundancy, the environment requires clustering and load-balancing.Load balancers are required as part of the networking infrastructure to achieve highavailability by ensuring that requests are sent to available servers they are front-ending.Best practices in network design and security also include firewalls to ensure that onlyrequired ports and protocols are permitted across zones.
The following environment example is a recommended production quality deploymentarchitecture for an auditing/proxying use case.
© 2013 Ping Identity Corporation All Rights Reserved
|
The following table describes the three zones within this proposed architecture.
Zone Description
ExternalZone
External network where incoming requests originate.
DMZZone
Externally exposing segment where PingAccess is accessible to clients. Aminimum of two PingAccess engine nodes will be deployed in the DMZ.Depending on your scalability requirements, more nodes may be required.
ProtectedZone
Contains back-end Sites audited and proxied through PingAccess. Auditresults are sent to an audit repository or digested by reporting tools. Manytypes of audit repository tools are supported such as SIEM/GRC, Splunk,database, and flat files.
Port Requirements
Port Requirements
© 2013 Ping Identity Corporation All Rights Reserved
The following table summarizes the ports and protocols that PingAccess uses tocommunicate with external components. This information provides guidance for firewalladministrators to ensure the correct ports are available across network segments.
Inbound refers to the direction from which incoming client requests, suchas those from external visitors, access PingAccess. Outbound refers tothe direction in which PingAccess sends data, such as outbound to theclient's browser.
Service(Type ofTraffic)
Protocol TCP/UDP Port Source Destination Direction
PingAccessAdministrativeConsole
HTTPS TCP 9000 PingAccessAdministrativeworkstations
PingFederateConsole
Inbound
PingAccessEngine
HTTPS TCP 3000 ClientBrowser,MobileDevices,PingFederateEngine
PingFederateEngine
Inbound
© 2013 Ping Identity Corporation All Rights Reserved
PingFederateTraffic
HTTPS TCP 9031 PingAccessEngine
PingFederate Outbound
PingAccessCluster Traffic
JGroups TCP 7600 PingAccessEngine
PingAccessEngine
Inbound
© 2013 Ping Identity Corporation All Rights Reserved
PingAccessCluster Traffic
JGroups TCP 7700 PingAccessEngine
PingAccessEngine
Inbound
PingAccessCluster Traffic
JGroups UDP 7601 PingAccessEngine
PingAccessEngine
Inbound
Performance Tuning
Performance Tuning
While PingAccess has been engineered as a high performance proxy, its defaultconfiguration may not match your deployment goals nor the hardware you haveavailable. Consult the following sections to optimize various aspects of a PingAccessdeployment for maximum performance.
An additional document related to performance, the PingAccess CapacityPlanning Guide, is also available to customers as a performance datareference. This document is available from the (Customer Portal
).https://www.pingidentity.com/support/customer-portal.cfm
Java TuningGarbage Collector Configuration
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
Resource PoolsLogging and Auditing
Java Tuning
Java Tuning
Heap (How much memory)
One of the most important tuning options you can apply to the Java Virtual Machine(JVM) is to configure how much heap (memory for runtime objects) to use. The JVMgrows the heap from a specified minimum to a specified maximum. If you havesufficient memory, best practice is to “fix” the size of the heap by setting minimum andmaximum to the same value. This allows the JVM to reserve its entire heap at startup,optimizing organization and eliminating potentially expensive resizing.
By default, PingAccess fixes the Java heap at 512 megabytes (MB). This is a fairlysmall footprint and not optimal for supporting higher concurrent user loads overextended periods of activity. If you expect your deployment of PingAccess to servemore than 50 concurrent users (per PingAccess node if deploying a cluster), werecommend that you increase the heap size.
Modifying Heap Size
To modify heap size for scripts, do the following:run.sh/run.bat
Edit the run script in the of the PingAccess install: on Linux orbin directory run.sh on Windowsrun.bat
Specify overall heap size by modifying the and MINIMUM_HEAP variables:MAXIMUM_HEAP
- Edit and respectively-Xms512m -Xmx512m- Specify units as (megabytes) or (gigabytes)m gSpecify young generation size by modifying the and MINIMUM_NEW
variables:MAXIMUM_NEW- Edit and , respectively-XX:NewSize=256m -XX:MaxNewSize=256m- Set values to 50% of and , respectivelyMINIMUM_HEAP MAXIMUM_HEAP
Not advisable if selecting the G1 collector (see Garbage Collector for more information).Configuration
Windows Service
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
To modify heap size for Windows Service, do the following:
Edit the file located in the directory of thePingAccessService.conf \sbin\windowsPingAccess install:Specify overall heap size by modifying the and wrapper.java.initmemory
settings.wrapper.java.maxmemory- Set the values (in megabytes) for initial and maximum heap sizes, respectively.Specify young generation size by modifying the and wrapper.java.additional.11
settings.wrapper.java.additional.12- Set the values (in megabytes) for initial and maximum new generation sizes,respectively.Restart. The settings in the file are only applied atPingAccessService.confservice startup.
Not advisable if selecting the G1 collector (see Garbage Collector for more information).Configuration
Garbage Collector Configuration
Garbage Collector Configuration
Selecting the appropriate garbage collector depends on the size of the heap andavailable CPU resources. The following is a table of available collectors and somegeneral guidance on when and how to use them.
GarbageCollector
Description Modifications
Parallel -Best used with heaps 4GBor less-Full stop-the-world copyingand compacting collector-Uses all available CPUs(by default) for garbagecollection
Default collector for server JVM. Nomodification is required to therun.sh/run.bat scripts or the WindowsService configuration file or use.
© 2013 Ping Identity Corporation All Rights Reserved
ConcurrentMarkSweep(CMS)
-Best for heaps larger than4GB with at least 8 CPUcores-Mostly a concurrentcollector-Some stop-the-worldphases-Non-Compacting-Can experienceexpensive, single threaded,full collections due to heapfragmentation
Run.sh/run.bat scripts: Set variable to GARBAGE_COLLECTOR
in the run-XX:+UseConcMarkSweepGCscript.Note: Quote delimiters required in ,run.shnot .run.bat
: Set Windows Service to wrapper.java.additional.10
in the -XX:+UseConcMarkSweepGC file.PingAccessService.conf
GarbageFirst (G1)
-Best for heaps larger than6GB with at least 8 CPUcores-Combination concurrentand parallel collector withsmall stop-the-worldphases-Long-term replacement forCMS collector (does notsuffer heap fragmentationlike CMS)
Run.sh/run.bat scripts: Set variable to GARBAGE_COLLECTOR
in the run script.-XX:+UseG1GC: Quote delimiters required in ,Note run.sh
not .run.batAlso disable and MINIMUM_NEW
tuning. Explicit sizingMAXIMUM_NEWadversely affects pause time goal.To disable, precede variables with in rem
, in .run.bat # run.shWindows Service: Set
to wrapper.java.additional.10 in the -XX:+UseG1GC
file.PingAccessService.confAlso disable wrapper.java.additional.11and . Explicitwrapper.java.additional.12sizing adversely affects pause time goal.To disable, precede lines with .#
Resource Pools
Resource Pools
Acceptor Threads
PingAccess uses a pool of threads to respond to HTTP/S requests made to the TCPport(s) in use. This applies to both administrative and runtime engine listening ports.
© 2013 Ping Identity Corporation All Rights Reserved
Acceptor threads read user requests from the administrative or runtime port and passthe requests to worker threads for processing. A best practice is to use at least twoacceptors for performance. On larger multiple CPU core machines, more acceptors canbe used. We recommend limiting to between two and 1/4th the number of availableCPU cores.
To modify, open the file located in the directory of your PingAccessrun.properties confdeployment and specify the number of acceptors you want to use on the following twolines:
admin.acceptors=Nengine.http.acceptors=N
Where represents the number of acceptor threads.N
Worker Threads
PingAccess uses a pool of “worker” threads to process user requests. Worker threadsreceive user requests from Acceptor threads, process them, respond back to the clientand then return to the pool for reuse. By default, PingAccess starts with a minimum offive worker threads and grows as needed (unbounded by default). You can define theminimum and maximum number of Worker threads in the pool by adding and/ormodifying properties found in the file.run.properties
To set values, open the run.properties file located in the “conf” directory of yourPingAccess deployment. If the properties do not exist in the file. add them:
pa.httptransport.coreThreadPoolSize=Npa.httptransport.maxThreadPoolSize=N
Where represents the number of worker threads.N
Maintenance of the pool is such that if the number of threads in the pool exceeds thevalue of , threads idle for 60 seconds arepa.httptransport.coreThreadPoolSizeterminated and removed from the pool. The idle timeout value is not modifiable.However, if the values of and pa.httptransport.coreThreadPoolSize
are the same, a fixed sized pool is created andpa.httptransport.maxThreadPoolSizeidle threads are not terminated and removed.
Since the pool by default is allowed to grow and shrink based on demand, it isrecommended that you tune the (minimum) topa.httptransport.coreThreadPoolSize
© 2013 Ping Identity Corporation All Rights Reserved
satisfy moderate demand on the system. We recommend a minimum of 10 threads peravailable CPU core as a good value to support up to twice the number of concurrentusers without error or significant degradation in performance.
Backend Server Connections
PingAccess provides a few options to control and optimize connections to the proxiedsite.
Max Connections
Connections to PingAccess are not explicitly connections to the proxied site.PingAccess creates a pool of connections, unlimited in size by default, that aremultiplexed to fulfill client requests. Maintenance of the pool includes creatingconnections to the site when needed (if none are available) and removing connectionswhen the is reached (see Keep Alive Timeout for more details).Keep Alive Timeout
In certain situations it can be advantageous to limit the number of connections in thepool for a given Web site. If, for example, the Web site is limited to the number ofconcurrent connections it can handle or has specific HTTP Keep Alive settings, limitingthe number of connections from PingAccess can improve overall performance by notoverloading the backend server. In the event that all connections in the pool are in use,a requesting thread waits for one to become available. Assuming that response timefrom the backend site is sufficiently fast, the time spent waiting for a connection is likelyto be less than if the system becomes overloaded.
We strongly recommended that you understand the limits and tuning ofthe server application being proxied. Setting the valueMax Connectionstoo low may create a bottleneck to the proxied site, setting the value toohigh (or unlimited) may cause PingAccess to overload the server.
See for information on setting .Connect to a Site Max Connections
Keep Alive Timeout
As mentioned in the previous section, the value controls how longKeep Alive Timeouta connection created to the proxied Site is kept in the pool for use. This value should beset lower than the HTTP Keep Alive timeout of the Site being proxied.
Configuring PingAccess to timeout the connections before the proxied server ensuresthat use of “stale” connections to the Site is not attempted, causing failure and retryoverhead. To improve efficiency, keep the timeout value of PingAccess connections as
© 2013 Ping Identity Corporation All Rights Reserved
close as possible to the timeout value of the proxied server without matching or goingover that value. This depends on the time granularity afforded by the proxied HTTPserver's configuration (time set in minutes, seconds, milliseconds, etc.) and may takesome testing to fully optimize. As a starting point, we suggest 500 milliseconds (half asecond) to one second as PingAccess transactions typically complete in less than ahalf a second on a properly-sized deployment (see for information onConnect to a Sitesetting ).Keep Alive Timeout
Logging and Auditing
Logging and Auditing
PingAccess uses a high performance, asynchronous logging framework to providelogging and auditing services with as low impact to overall application performance aspossible.
Logging
Although logging is handled by a high performance, asynchronous logging framework, itis more efficient to the system overall to log the minimum amount of informationrequired. We highly recommend that you review the section of the documentation forlogging and adjust the level to the lowest, most appropriate level to suit your needs (see
).Manage Log Files
Auditing
As with logging, auditing is provided by the same high performance, asynchronouslogging framework. Furthermore, auditing messages can be written to a databaseinstead of flat files, decreasing file I/O. If you do not require auditing for interactions witha Resource or between PingAccess and PingFederate, it is more efficient to disableaudit logging. However, if you do require auditing services and have access to aRelational Database Management System (RDBMS), we recommend auditing to the
. You will see a decrease in disk I/O, which may result in increaseddatabaseperformance depending on database resources.
Server Clustering
Server Clustering
PingAccess provides clustering features that allow a group of PingAccess servers toappear as a single system. When deployed appropriately, server clustering canfacilitate high availability of critical services. Clustering can also increase performanceand overall system throughput.
© 2013 Ping Identity Corporation All Rights Reserved
1.
2.
3.
4.
5.
6.
7.
Two types of information are shared when using server clustering: configuration dataand runtime state. Configuration data is replicated to all engine states. At startup, aPingAccess engine node in a cluster checks its local configuration and then makes acall to the administrative console to check for changes. How often each engine in acluster checks the console for changes is configurable in the engine file.run.properties
Runtime state clustering consists solely of a shared cache of security tokens acquiredfrom the PingFederate STS for use cases using the Identity Mediation Token Mediator
. For increased performance, you can configure engines to shareSite Authenticatorruntime state by using the configuring cluster interprocess communication
file. By default, engines do not share runtime state.run.properties
Set up Your Cluster for High Availability
The following lists the steps required to facilitate high availability of critical services andincrease performance and overall system throughput with your cluster. For detailedstep information, see .Configure PingAccess Servers into a Cluster
Install PingAccess on multiple machines.Edit the file accordingly for the .run.properties cluster node typeOptional. Edit on each engine node for .run.properties sub-clusteringOptional. a new Key Pair and self-signed certificate or an existingCreate importsecure certificate.Assign the new certificate to the administrative console.Register cluster nodes in the administrative console.Start or restart each node.
Glossary
Glossary
ID Token
A token defined in the standard that represents a set of claims aboutOpenID Connectthe end user.
JSON Web Token (JWT)
A URL-safe way of representing claims (attributes) transferred between two parties.
© 2013 Ping Identity Corporation All Rights Reserved
This format is intended for space-constrained environments such as HTTPAuthorization headers and URI query parameters. For more information, see the JSON
.Web Token Specification
PingAccess (PA) Token
A JWT Token issued by PingAccess that contains user session attributes used to grantaccess to Web Resources and placed within a PingAccess cookie. PA Tokens aredigitally signed using keys that are internally managed. Configure rolling intervals andcache-related settings for these keys on the page within Settings.Web Session
An end user can access all attributes by examining their cookie contents.While they are integrity protected to prevent changes, any sensitive orconfidential attributes can be viewed should the user decode thisJWT-formatted cookie.
PKCS#12
An archive file format for storing many cryptography objects as a single file. It iscommonly used to bundle a private key with its X.509 certificate.
Web Access Management (WAM) Token
A data object by which a client authenticates to a Web server protected by a third partyWeb Access Management system. Typically, a WAM token is transported as a cookiethat represents a user's logged-in session into the system.