Adding custom policies for API services and operations
With an API gateway integration, you can define custom policies that target inbound requests and outbound responses for API services and operations.
Before you begin
If custom policies are not enabled for your API service, enable them by clicking Enable Custom Policies on the API service’s Overview tab.
About this task
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.
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.
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.
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.
For hands-on experience with writing a custom policy for an API operation, see Tutorial 3: Fine-grained API authorization. |
Steps
-
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.
-
In the policy tree, select the Custom policy set nested under the request or response that you want the policy to target:
Choose from:
-
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.
-
-
Click the icon and select Add Policy.
-
In the Name field, enter a name relevant to the business rule that you are modeling.
-
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:
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.For more details about the components used in policies, see Authorization policies.
-
Click Save changes.
-
To deploy the policy, go to Authorization → API Services, and select the corresponding API service.
-
Click Deploy.