SCIM search policy processing

SCIM policy processing involves denying or modifying a search request and then filtering the results.

Policy processing for System for Cross-domain Identity Management (SCIM) searches occurs in the following phases:

Policies deny or modify a search request. For more information, see Search request authorization.
Policies filter the search result set. For more information, see Search response authorization.

Search request authorization

In the first phase, a policy request is issued for the search itself, using the search action. If the policy result is deny, the search is not performed. Otherwise, statements in the policy result are applied to the search filter, giving statements a chance to alter the filter.

You can only use statement types that are written specifically for the search action. For example, you can use the Add Filter statement type to constrain the scope of a search.

You can also use the Combine SCIM Search Authorizations statement type at this point. If you use this statement, search results are authorized by using a special mode, described in Search response authorization.

Search response authorization

After a search is performed, the resulting search response is authorized in one of three ways: default authorization, optimized search response authorization, and no authorization.

Default authorization

The default authorization mode simplifies policy design but can generate a large number of policy requests. For every System for Cross-domain Identity Management (SCIM) resource that the search returns, a policy request is issued by using the retrieve action. If the policy result is deny, the SCIM resource is removed from the search response. Otherwise, statements in the policy result are applied to the SCIM resource, which gives statements a chance to alter the resource. Because the retrieve action is used, policies that are already written for single-resource GET operations are reused and applied to the search response.

Optimized search response authorization

If the search request policy result includes the Combine SCIM Search Authorizations statement type, an optimized authorization mode is used instead. This mode reduces the number of overall policy requests but might require a careful policy design. Instead of generating a policy request for each SCIM resource that the search returns, a single policy request is generated for the entire result set. To distinguish the policy requests that this authorization mode generates, the action search-results is used.

Write policies that target these policy requests to accept an object that contains a Resources array with all matching results. Statements that the policy result returns are applied iteratively to each member of the result set. The input object that is provided to statements also contains a Resources array, but it contains only the single result currently under consideration.

The following JSON provides an example input object:

{
  "Resources": [{
    "name": "Henry Flowers",
    "id": "40424a7d-901e-45ef-a95a-7dd31e4474b0",
    "meta": {
      "location": "https://example.com/scim/v2/Users/40424a7d-901e-45ef-a95a-7dd31e4474b0",
      "resourceType": "Users"
    },
    "schemas": [
      "urn:pingidentity:schemas:store:2.0:UserStoreAdapter"
    ]
   }
  ]
}

The optimized search response authorization mode checks policies efficiently and is typically faster than the default authorization mode. However, the optimized search response authorization mode might be less memory-efficient because the entire result set, as returned by the datastore, is loaded into memory and processed by the policy decision point (PDP).

No authorization

If you do not need policy processing for the search results on a SCIM Resource Type, such as if policies are only used for authorization before the search and not filtering the results, set that SCIM Resource Type’s disable-response-processing property to true. The search results will be returned as they were received from the external server. This behavior can improve performance for requests that return large numbers of search results. This property also affects other SCIM operations.

PingAuthorize