PingFederate Server

Policies

You can configure policies, fragments, selectors, policy contracts, and sessions under Authentication > Policies.

An authentication policy is a tree of authentication sources, selector instances, or a combination of them, that defines the decision to route a request through a series of approved authentication sources with an optional authentication policy contract or a local identity profile at the end or to deny the request.

Administrators can enable authentication policies on identity provider (IdP) browser single sign-on (SSO) requests, adapter-to-adapter requests, and browser-based OAuth authorization code and implicit flows. Administrators can also enable authentication policies on service provider (SP)-initiated Browser SSO requests received at the /sp/startSSO.ping endpoint. Individual policies can be disabled, as needed.

The order of authentication policies matters because the policy engine starts from the first policy and works its way down. At runtime, the policy engine derives an authentication tree from the applicable policies and either approves or denies a request.

Policy paths, authentication policy contracts, and local identity profiles

Policy paths

An authentication policy starts with either a selector instance or an authentication source. Authentication sources and most selectors have two results, Success or Fail, Yes or No. Each result forms a policy path.

A policy path is open-ended if it contains only one or more selector instances, without any authentication sources. In this scenario, the policy engine continues to the next applicable authentication policy, if any.

A policy path is closed-ended if it contains one or more authentication sources, with or without any selector instances. A closed-ended path can optionally end with an authentication policy contract or a local identity profile.

A policy path is also closed-ended if it ends with an instance of a custom authentication selector that returns an IdP adapter instance ID or the connection ID of an IdP connection. Because the custom selector returns an authentication source, such a closed-ended path cannot end with an authentication policy contract or a local identity profile. Instead, it must end with an action of Done or Restart.
Authentication policy contracts and local identity profiles

An authentication policy contract can harness attribute values obtained from all authentication sources along the path leading up to it. Administrators can select the same authentication policy contract or local identity profile for different closed-ended paths, in one or more authentication policies, and fulfill them differently to suit the requirements. To enforce the same set of authentication policies in multiple use cases, map the authentication policy contract to the applicable Browser SSO connections and OAuth grant-mapping configuration.

A policy becomes more complex as the number of paths grows with the number of authentication sources and selector instances.

Multiple policies and runtime behavior

A complex policy can cover a lot of ground. However, depending on the authentication requirements, administrators can also create multiple policies to suit their needs.

When a request arrives at PingFederate, the policy engine skips all disabled policies and any closed-ended paths that are inapplicable to the request. A closed-ended path is considered inapplicable to a request in any of the following conditions:

  • The local identity profile at the end of a path is associated with an authentication policy contract that is not mapped to the invoking use case or is blocked by the virtual server ID included in the request.

  • The authentication policy contract at the end of a path is not mapped to the invoking use case or is blocked by the virtual server ID included in the request.

  • The last authentication source at the end of a path, that does not end with an authentication policy contract or a local identity profile, is not mapped to the invoking use case or is blocked by the virtual server ID included in the request.

    Virtual server IDs are not applicable to adapter-to-adapter mappings or OAuth use cases.

After pruning inapplicable policies and paths, the policy engine starts evaluating the request against the first applicable policy. Generally speaking, the policy engine moves on to the next applicable policy when it hits the end of an open-ended path, as indicated by an action of Continue, and stops when it hits the end of a closed-ended path, as indicated by an authentication policy contract or an action of Done or Restart. Depending on the policies, the policy engine might find an authentication source, a series of authentication sources, or no authentication source at all.

Default authentication sources

In the event that a request has only passed through an open-ended path and the policy engine finds no authentication source after evaluating the request through all the applicable policies, it picks the first applicable default authentication source. A default authentication source is considered applicable if it is mapped to the use case of the request.

If the policy engine cannot find a default authentication source and the Fail if policy engine finds no authentication source checkbox is cleared, PingFederate chooses an authentication source based on the following prioritized preferences:

  1. If the request comes with an IdpAdapterId query parameter or a pfidpaid cookie, and if the authentication source specified by the query parameter or the cookie is mapped to the corresponding use case, PingFederate uses the specified authentication source. If the authentication source is not mapped, PingFederate denies the request and returns an error message.

    If the request presents both the IdpAdapterId query parameter and the pfidpaid cookie, the IdpAdapterId query parameter takes precedence.

  2. If the request comes with neither an IdpAdapterId query parameter nor a pfidpaid cookie, and if there is only one authentication source mapping, PingFederate uses the mapped authentication source.

    If there are multiple authentication-source mappings, PingFederate returns the available authentication sources and lets the user authenticate through one of them. If the user selected the Remember selection checkbox and successfully authenticated, PingFederate returns a pfidpaid persistent cookie, identifying the user’s preference.

    If the Fail if policy engine finds no authentication source checkbox is selected, PingFederate denies the request and returns an error message.

    If a request has passed through a closed-ended path, the policy engine has already found at least one authentication source for the user. In this scenario, the policy engine ignores all default authentication sources.

Tracked HTTP request parameters

The policy engine is capable of tracking HTTP request parameters that it receives from the initial request and making them available to authentication sources, selector instances, and contract mappings throughout the policy.

Local identity profiles and authentication policy contracts

PingFederate empowers administrators to deliver a secure and easy-to-use customer authentication, registration, and profile management solution. A typical use case involves an HTML Form Adapter instance, a local identity profile, an authentication policy contract, and an IdP authentication policy. The HTML Form Adapter captures user attributes and maps them into an authentication policy contract through a local identity profile. In terms of configuration, the latter is accomplished by placing a local identity profile at the end of a policy path and completing the Local Identity Mapping > Contract Fulfillment configuration.

Policy enforcement based on OAuth clients

PingFederate can enforce authentication polices based on the requesting OAuth client, among other factors. To do that, you can include an OAuth Client Set Authentication Selector or an Extended Property Authentication Selector in a policy. Learn more in Configuring the OAuth Client Set Authentication Selector and Configuring the Extended Property Authentication Selector

Another option is to leverage the policy enforcement rule that PingFederate ignores authentication policy contract branches that are not mapped to an access token manager (ATM) that the requesting client can access. This rule also applies to policy branches that end on an authentication source. Learn more in Managing access token mappings.

Keep that policy enforcement rule in mind when you configure clients and ATMs. You can configure a client so that it can access only its default ATM. You can also configure an ATM so that only specific clients can access it. Those settings affect the authentication policy. Learn more in Configuring OAuth clients and Access token management.