If custom policies are not enabled for your API service, enable them by clicking Enable Custom Policies on the API service’s Overview tab.

Custom policies control access to APIs in complex authorization scenarios. When you enable custom policies for an API service, PingOne Authorize generates a policy tree for the API service. The tree structure is system-owned and reflects the API service and its operations. You can’t modify the policy sets and policies in the tree, but you can add your own custom policies to Custom policy sets in the tree.

The tree structure is organized as follows.

Screen capture showing the API Service policy set for the Meme Game.

Top-level policy sets include:

  • API Service <Name>: This is the top level policy set for the API service. It serves as a container for everything nested underneath it.
  • API Service and Operations: This policy set ensures that combining algorithms work correctly for AAM rules and policies.

The next level contains the request and response policies and policy sets for each API service.

Screen capture showing the Inbound Request policy set for the Meme Game API Service.

These include:

  • Inbound Request: This policy set is a container for rules and custom policies that target inbound requests for the API service.
    • Basic Rules: This policy is reserved for rules generated by the system that target inbound requests for the API service. The rules are based on the API Service configuration.
    • Custom: This policy set is where you add your own custom policies that target inbound requests for the API service.
  • Outbound Response: This policy set is a container for rules and custom policies that target outbound responses from the API service. Its children have the same structure as the Inbound Request policy set.

Each operation under the API service shares a similar structure.

Screen capture showing the Get Memes of Another User Operation policy set for the Meme Game API Service.

Operation policies and policy sets include:

  • Operation <Name>: This is the top level policy set for the operation. It serves as a container for everything nested underneath it.
  • Inbound Request: This policy set is a container for rules and custom policies that target inbound requests for the specific operation.
    • Basic Rules: This policy stores group and scope-based rules that target inbound requests for the operation. The policy is generated automatically by the system when you add basic rules to an operation.
    • Custom: This policy set is where you add your own custom policies that target inbound requests for the operation.
  • Outbound Response: This policy set is a container for rules and custom policies that target outbound responses from the specific operation. It has nested children for Basic Rules and Custom policies.
Note:

For hands-on experience with writing a custom policy for an API operation, see Tutorial 3: Fine-grained API authorization.

  1. Go to Authorization > Policies, and expand the API Access Management policy tree, then expand the policy tree for your API service.

    For example, consider an API service that protects health records and an API operation to get the records. You want to write a policy that allows a user to view only their own health records.

    Screen capture showing the policy tree with the Health Records API Service policy set expanded to show child policy sets.
  2. In the policy tree, select the Custom policy set nested under the request or response that you want the policy to target:
    • API service Inbound Request: This is for policies that will be executed by any API call to any endpoint in the API service. For example, policies that control access based on user characteristics, such as account status or risk score, or whether certain scopes or claims are present in the access token, or whether requests are from certain IP address ranges.
    • API service Outbound Response: This is for policies that will modify responses to any API call in the API service. For example, a policy that rewrites the value of an attribute that appears in all responses, such as a URL that uses a private host name.
    • Operation Inbound Request: This is for policies that are restricted to specific endpoints. For example, a policy that requires an extra claim in the access token for a POST or PUT request, but not for a GET request, or a policy that constrains a search query to resources owned by the requester, such as allowing a user to view only their own health records.
    • Operation Outbound Response: This is for policies that modify responses to API calls to specific endpoints. For example, a policy that filters the attributes of JSON responses to remove sensitive fields that the API can return, such as information that a user hasn’t consented to sharing with a requester.

    For the health records example, you would select the Custom policy set for inbound requests to the operation.

    Screen capture showing the Custom policy set for inbound requests to the GET Records operation nested under the Health Records API Service policy set.
  3. Click the + icon and select Add Policy.
  4. In the Name field, enter a name relevant to the business rule that you are modeling.
    Screen capture showing the User identity check policy Name and Description fields.
  5. Add rules, conditions, and statements to the policy as needed.

    For the health records example, consider the following API operation to get a user’s health records:

    Screen capture showing the Method and Path for the Get user's health records operation.

    This rule allows access to health records only when the access token’s subject claim matches the user ID in the request path. The attribute on the right hand side of the comparison represents the user ID path parameter in the API operation /records/user/{userId}. For more information about this attribute, see API Access Management attributes. For more information about accessing information about the requesting user from PingOne Directory or an external directory, see API services.

    Screen capture showing the Permit access to user's own records rule with an Applies When condition that compares the access token subject to the user ID path parameter in the decision request.

    For more details about the components used in policies, see Authorization policies.

  6. Click Save changes.
  7. To deploy the policy, go to Authorization > API Services, and select the corresponding API service.
    Screen capture showing the Deploy button on the Overview tab of the Health Records API service.
  8. Click Deploy.