PingAuthorize

About the Trust Framework

The Trust Framework defines all the entities that your organization can use to build policies. These entities include, for example, the HTTP request attributes that describe API requests protected by PingAuthorize Server and the services that identify the REST APIs themselves.

To understand how PingAuthorize Server uses the Trust Framework, you must understand how PingAuthorize Server interacts with its policy engine, also called the policy decision point (PDP). In general, the flow is:

  1. PingAuthorize Server receives a SCIM 2.0 or API request and translates it to a policy request.

  2. PingAuthorize Server submits the policy request to the PDP for evaluation.

  3. The PDP applies any matching policies to the policy request and then issues a policy decision.

  4. PingAuthorize Server uses the policy decision to determine how to proceed with the request, depending on the decision result (typically PERMIT or DENY) and any statements included with the decision.

Consider these simple examples.

  • A policy decision with a DENY result could cause PingAuthorize Server to reject a request because it originates from an untrusted IP address.

  • A policy decision with the Exclude Attributes statement could cause PingAuthorize Server to remove specific attributes from an API response because the requesting user lacks a necessary entitlement.

Each policy request that PingAuthorize Server generates includes a specific set of attributes. These attributes vary based on the service being used. For more information, see the following topics:

Policy request structure is tightly coupled to the Trust Framework. If the Trust Framework entity definitions do not match the policy requests generated by PingAuthorize Server, then PingAuthorize Server does not function as expected. For this reason, your Trust Framework should always be based on the default policies included with the server installation package in the file resource/policies/defaultPolicies.SNAPSHOT.

For information about working with the Trust Framework to customize your organization’s policies, see Trust Framework.

Trust Framework versions

The policy request structure used by PingAuthorize Server is versioned so that it can evolve across releases of the server. You configure the version in the Policy Decision Service using the trust-framework-version property. PingAuthorize Server always supports a minimum of two Trust Framework versions, the current (and preferred) Trust Framework version and the previous Trust Framework version.

When an instance of PingAuthorize Server is first installed, the Trust Framework version is undefined. The server raises an alarm to indicate this condition and to provide instructions about how to set the preferred version.

You should explicitly set the version to the preferred version. For example, the following dsconfig command configures the Policy Decision Service to form policy requests using Trust Framework version v2.

dsconfig set-policy-decision-service-prop \
  --set trust-framework-version:{TRUST_FRAMEWORK_VERSION}
When the Trust Framework version is set, add the configuration to the server profile that you use to deploy new server instances.

New releases of PingAuthorize Server might introduce changes to the way that the server generates policy requests, potentially in ways that are not backward-compatible with the Trust Framework and policies used in a previous release. In these cases, PingAuthorize Server will prefer the new Trust Framework version and raises an alarm with instructions to move to the new Trust Framework version. Existing policies will continue to work with the older Trust Framework version. However, the older Trust Framework version will be deprecated, so transitioning to the new Trust Framework version is imperative.

For more information about upgrading the Trust Framework version, see Upgrading the Trust Framework and policies.