pingaccess documentation home - ping identity · pingaccess documentation home ... server and...

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


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.


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.

http://documentation.pingidentity.com/display/PF/Configuring+a+Client


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.


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.

http://documentation.pingidentity.com/display/PF/WS-Trust+STS+Configuration

http://documentation.pingidentity.com/display/PA21/Site+Authenticators


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


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 - /


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


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

http://documentation.pingidentity.com/display/PF/Token+Models

http://documentation.pingidentity.com/display/PF/Grant+Types

http://documentation.pingidentity.com/display/PF/About+OAuth

http://tools.ietf.org/html/rfc6750#section-2.1


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.

http://groovy.codehaus.org/


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

http://documentation.pingidentity.com/display/PA21/Resources

http://documentation.pingidentity.com/display/PA21/Sites



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

http://www.pingidentity.com/support-and-downloads/


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


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

http://www.oracle.com/technetwork/java/javase/downloads

https://www.pingidentity.com/support-and-downloads/licensing.cfm


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


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.


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


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


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.


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.


Facilitates high availability of critical services, and increasesperformance and overall system throughput.


Defines trust to certificates presented during outbound secureHTTPS 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.


Facilitates high availability of critical services, and increasesperformance and overall system throughput.


Defines trust to certificates presented during outboundsecure 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.

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



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


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

http://documentation.pingidentity.com/display/PF/Enabling+the+OAuth+AS

http://documentation.pingidentity.com/display/PF/Authorization+Server+Settings


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




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.

http://documentation.pingidentity.com/display/PF/Defining+the+Access+Token+Attribute+Contract

http://documentation.pingidentity.com/display/PF/Defining+the+Access+Token+Attribute+Contract

http://www.openssl.org/docs/apps/x509v3_config.html#Subject_Alternative_Name_


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.


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.


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


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


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.


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.



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

http://documentation.pingidentity.com/display/PF71/Using+OAuth+Menu+Selections


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


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




http://documentation.pingidentity.com/display/PF/Authorization+Server+Settings


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.


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


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.


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

http://documentation.pingidentity.com/display/PF71/Configuring+a+Client

http://documentation.pingidentity.com/display/PF71/Configuring+a+Client


http://documentation.pingidentity.com/display/PF71/Configuring+OpenID+Connect+Policies


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.



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


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

http://docs.oracle.com/javase/7/docs/technotes/guides/security/SunProviders.html#importlimits


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

http://documentation.pingidentity.com/display/PA2/Manage+Key+Pairs


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


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.


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


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


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.


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.


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.

http://documentation.pingidentity.com/display/PF71R2/Configuring+the+Requested+AuthN+Context+Selector

http://documentation.pingidentity.com/display/PF71R2/Configuring+the+Requested+AuthN+Context+Selector


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


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



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





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.



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



This Site Authenticator uses an OAuth access token to authenticate a clientrequesting access to a Site that requires OAuth authentication.


Field Description

Long-LivedAccessToken

Defines the long-lived OAuth access token (see Configuring in the PingFederate documentation forReference-Token Management

more information).



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


http://documentation.pingidentity.com/display/PF/Configuring+Reference-Token+Management

http://documentation.pingidentity.com/display/PF/Configuring+Reference-Token+Management

http://documentation.pingidentity.com/display/PF/Configuring+Token+Generators

http://documentation.pingidentity.com/display/PF/Configuring+Token+Generators



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



Resources represent Web applications or APIs to which a request is sent.




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.

http://documentation.pingidentity.com/display/PA21/Policy+Manager



http://documentation.pingidentity.com/display/PA2/Configure+Virtual+Hosts



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


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


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.



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





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


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

http://groovy.codehaus.org/Documentation


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


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.





Field Description

ErrorResponseCode










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




Field Description

ErrorResponseCode










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.




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


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


The template page for customizing the error message that displays ifRule evaluation fails. This template file is located in the




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.


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






For example:




Field Description






Related Topics

How does PingAccess use the OAuth Authorization Server?How does PingAccess uses Groovy Scripts?

OAuth Scope Rule


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






For example:





Field Description






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.

http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.3.3


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


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.


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/


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


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




Field Description

http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html

http://docs.oracle.com/javase/6/docs/api/java/util/regex/Matcher.html#replaceAll(java.lang.String)


1.

2.

3.

4.

ErrorResponseCode









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.




4.

5.




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




Field Description

ErrorResponseCode








1.

2.

3.

4.



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


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


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









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.


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


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

http://hamcrest.org/JavaHamcrest/javadoc/1.3/org/hamcrest/CoreMatchers.html


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()

http://documentation.pingidentity.com/display/PA1/Configure+a+Resource


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()

http://hamcrest.org/JavaHamcrest/javadoc/1.3/org/hamcrest/CoreMatchers.html

http://code.google.com/p/hamcrest/wiki/Tutorial

http://code.google.com/p/hamcrest/wiki/Tutorial


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")


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.


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

http://documentation.pingidentity.com/display/PA1/Connect+to+a+Service

http://documentation.pingidentity.com/display/PA1/Request+Object

http://documentation.pingidentity.com/display/PA1/Response+Object


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")


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.


bodyBody Contains the HTTP body information from the request sent to the .Resource


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


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


bodyBody Contains the HTTP body information from the request sent to the .Resource


Method Summary

Method Description

booleanisRedirect()

Returns true if the status code is in the 300’s.

booleanisUserError()


booleanisServerError()


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


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.


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.


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


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


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.



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.



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








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.


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.

http://documentation.pingidentity.com/display/PA2/Manage+Key+Pairs


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


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


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



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.



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


admin.port Defines the TCP port on which the PingAccessadministrative console runs. Default is .9000


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.


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


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


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



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


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]


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 using the pageBasic Authenticationwithin Settings.

To change the PingAccess Administrator password:


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




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


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



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.


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


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


engine.admin.configuration.host Defines the host where theadministrative console isavailable. The default is localhost


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.



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


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


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


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:


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:


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.


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


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


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.


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.


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.


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


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



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

http://velocity.apache.org/engine/releases/velocity-1.4


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

http://documentation.pingidentity.com/display/PA21/OAuth+Rule+Advanced+Fields

http://documentation.pingidentity.com/display/PA21/OAuth+Rule+Advanced+Fields

http://documentation.pingidentity.com/display/PA21/Advanced+Fields

http://documentation.pingidentity.com/display/PA21/Advanced+Fields


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

http://www.openssl.org/docs/apps/x509v3_config.html#Subject_Alternative_Name_




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.



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


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


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.


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.



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.


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


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.


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.


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




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.


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.


Zone Description


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


The following environment example is a recommended production quality deploymentarchitecture for an auditing/proxying use case.


|


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


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


PingFederateTraffic

HTTPS TCP 9031 PingAccessEngine

PingFederate Outbound

PingAccessCluster Traffic

JGroups TCP 7600 PingAccessEngine

PingAccessEngine

Inbound



JGroups TCP 7700 PingAccessEngine

PingAccessEngine

Inbound


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

https://www.pingidentity.com/support/customer-portal.cfm


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


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.


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.


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


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


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.


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.

http://openid.net/connect/


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.

http://tools.ietf.org/html/draft-ietf-oauth-json-web-token

http://tools.ietf.org/html/draft-ietf-oauth-json-web-token

pingaccess documentation home - ping identity · pingaccess documentation home ... server and...

Documents