An authentication policy is a tree of authentication sources, selector instances, or a combination of them, on which 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 are based. Administrators can create one or more authentication policies to fulfill their authentication requirements. As needed, individual policies can be disabled.

Administrators can enable authentication policies on IdP Browser SSO requests, adapter-to-adapter requests, and browser-based OAuth authorization code and implicit flows. Administrators can also enable authentication policies on SP-initiated Browser SSO requests received at the /sp/startSSO.ping endpoint.

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.

Note:

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 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 may 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 if any of the following conditions is met:

  • 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.
Note: Virtual server IDs are not applicable to adapter-to-adapter mappings or OAuth uses cases.

Once inapplicable policies and paths are pruned, 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 may 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 no default authentication source can be found and the Fail if policy engine finds no authentication source check box is not selected, 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.
    Note: If both the IdpAdapterId query parameter and the pfidpaid cookie are presented, 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.
    Note: If there are multiple authentication-source mappings, PingFederate returns the available authentication sources and let the user authenticate through one of them. (If the user selected the Remember selection check box and successfully authenticated, PingFederate returns a pfidpaid persistent cookie, identifying the user's preference.)

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

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