PingAuthorize

Tutorial (optional): Creating SCIM policies

This tutorial demonstrates how to develop fine-grained access control (FGAC) policies for the System for Cross-domain Identity Management (SCIM) REST application programming interface (API) built into PingAuthorize Server.

In the previous section, you used PingAuthorize Server to filter data that an external REST API returned.

While PingAuthorize Server’s API security gateway protects existing REST APIs, PingAuthorize Server’s built-in SCIM service provides a REST API for accessing and protecting identity data that might be contained in datastore like Lightweight Directory Access Protocol (LDAP) and relational databases.

PingAuthorize Server uses SCIM in the following ways:

  • Internally, user identities are represented as SCIM identities by way of one or more SCIM resource types and schemas. This approach includes access token subject (SAML), which are always mapped to a SCIM identity.

  • A SCIM REST API service provides access to user identities through HTTP.

You will now design a set of policies to control access to the SCIM REST API by using OAuth 2 access token rules.

Before proceeding, make a test request to generate a SCIM REST API response using only the default policies. As in the previous section, send a mock access token in the request.

curl --insecure -X GET https://localhost:7443/scim/v2/Me -H 'Authorization: Bearer {"active": true, "sub": "user.1", "scope": "nonexistent.scope", "client_id": "nonexistent.client"}'

Although the precise attributes values might vary, the response returns the SCIM resource that corresponds to user.1.

{"mail":["user.1@example.com"],"initials":["RJV"],"homePhone":["+1 091 438 1890"],
"pager":["+1 472 824 8704"],"givenName":["Romina"],"employeeNumber":"1","telephoneNumber":["+1 319 624 9982"],
"mobile":["+1 650 622 7719"],"sn":["Valerio"],"cn":["Romina Valerio"],
"description":["This is the description for Romina Valerio."],"street":["84095 Maple Street"],
"st":["NE"],"postalAddress":["Romina Valerio$84095 Maple Street$Alexandria, NE  39160"],
"uid":["user.1"],"l":["Alexandria"],"postalCode":["39160"],"entryUUID":"355a133d-58ea-3827-8e8d-b39cf74ddb3e",
"objectClass":["top","person","organizationalPerson","inetOrgPerson"],​"entryDN":"uid=user.1,ou=people,o=yeah",
"meta":{"resourceType":"Users",
"location":"https://localhost:7443/scim/v2/Users/355a133d-58ea-3827-8e8d-b39cf74ddb3e"},
"id":"355a133d-58ea-3827-8e8d-b39cf74ddb3e","schemas":["urn:pingidentity:schemas:store:2.0:UserStoreAdapter"]}

This response is a success response, although it is preferred that it not be one, because it shows that any active access token referencing a valid user can be used to access any data.

Scenario

In this tutorial, you limit the requester’s access to profile data, returning only specific attributes of the profile that granted the access token. This is achieved using the OIDC-like scope email and profile.

Also, you create a scope scimAdmin that has full access to SCIM-based User resources.

Tasks

This tutorial walks you through these tasks.

  1. Create a basic policy structure for scope-based access to SCIM resources.

  2. Create a policy for the email scope that only allows access to the subject’s mail attributes.

  3. Create a policy for the profile scope that only allows access to a few other profile attributes.

  4. Create a policy for the scimAdmin scope that allows access to all attributes.

The following sections provide the details for completing these tasks.

Tutorial: Creating the policy tree

This tutorial describes how to create a tree structure and ensure that your policies apply only to SCIM requests.

About this task

The default policies include the policy named Token Validation. In the PingAuthorize Policy Editor, you can find this policy under Global Decision Point. This policy denies any request using an access token if the token’s active flag is set to false. This policy is augmented with a set of scope-based access control policies.

Steps

  1. To create the tree structure, perform the following steps:

    1. Sign on to the PingAuthorize Policy Editor using the URL and credentials from Accessing the GUIs.

    2. Click Policies.

    3. Select Global Decision Point.

    4. From the menu, select Add Policy Set.

    5. For the name, replace Untitled with SCIM Policy Set.

    6. In the Policies section, set the Combining algorithm to A single deny will override any permit decisions.

      A combining algorithm determines the manner in which the policy set resolves potentially contending decisions from child policies.

    7. Click Applies to.

    8. Click Components.

    9. From the Services list, drag SCIM2 to the Add definitions and targets, or drag from Components box.

      This step ensures that policies in the SCIM policy set apply only to SCIM requests.

    10. Click Save changes.

      Result:

      You should have a screen like the following.

    Screen capture of the SCIM Policy Set with an Applies to target and Combining Algorithm configured as specified

  2. To add a branch under the SCIM policy set to hold SCIM-specific access token policies, go from Components to Policies and perform the following steps:

    1. Select SCIM Policy Set.

    2. From the menu, select Add Policy Set.

    3. For the name, replace Untitled with Token Policies.

    4. In the Policies section, set the Combining algorithm to A single deny will override any permit decisions.

    5. Click Save changes.

  3. To add another branch that holds a policy specific to access token scopes, perform the following steps:

    1. Select Token Policies.

    2. From the menu, select Add Policy Set.

    3. For the name, replace Untitled with Scope Policies.

    4. In the Policies section, set the Combining algorithm to Unless one decision is permit, the decision will be deny.

    5. Click Save changes.

      Result:

      After creating the new branches, they should look like the following.

    Screen capture of the Scope Policies policy set with the Combining Algorithm configured as specified

Tutorial: Creating SCIM access token policies

This tutorial describes how to define access token policies after you define a structure.

In this section, you will define three policies that use a requester’s access token to limit data access.

Tutorial: Creating a policy for role-based access control

This tutorial describes how to create the final policy, which is an access-control rule that can base its authorization decision on an attribute of the requesting identity, rather than on an access token claim.

About this task

When PingAuthorize Server authorizes a request, an access token validator resolves the subject of the access token to a SCIM user and populates a policy request attribute called TokenOwner with the SCIM user’s attributes. In this scenario, build a policy around the employeeType attribute, which must be defined in the Trust Framework.

Steps

  1. Go to Trust Framework and click the Attributes tab. Click TokenOwner.

  2. Click and then Add new Attribute.

  3. For the name, replace Untitled with employeeType.

  4. From the Parent list, select TokenOwner.

  5. In the Resolvers section:

    1. Click Add Resolver.

    2. From the Resolver type list, select Attribute and in the Select an Attribute list, specify a value of TokenOwner.

  6. Click next to Value Processors and then Add Processor.

  7. From the Processor list, select JSON Path and enter the value employeeType.

  8. Set the Value type to Collection.

  9. In the Value Settings section:

    1. Select the Default Value check box and in the Enter a default value field, enter the value [].

      An empty array is specified as the default value because not all users have an employeeType attribute. A default value of [] ensures that policies can safely use this attribute to define conditions.

    2. From the Type list, select Collection.

  10. Click Save changes.

Result

The final attribute configuration should resemble the following image.

A screen capture of the employeeType attribute window with Parent configured as TokenOwner and Resolvers, Value Processors, and Value Settings configured as specified

Next steps

Add a policy that uses the employeeType attribute.

  1. Go to Policies → Policies.

  2. Highlight SCIM Policy Set and click and then Add Policy.

  3. For the name, replace Untitled with Restrict Intern Access.

  4. From the Combining Algorithm list, select Unless one decision is deny, the decision will be permit.

  5. Click Add Rule.

  6. For the name, replace Untitled with Restrict access for interns.

  7. From the Effect list, select Permit.

  8. In the Condition section:

    1. Click Comparison.

    2. In the Select an Attribute list, select TokenOwner.employeeType.

    3. From the middle, comparison-type list, select Contains.

    4. In the Type in constant value field, enter intern.

  9. Within the rule, click Show Advice and Obligations and then click the next to Advice and Obligations.

  10. Click Add Advice → Custom Advice.

  11. For the name, replace Untitled with Restrict attributes visible to interns.

  12. Select the Obligatory check box.

  13. In the Code field, enter exclude-attributes.

  14. From the Applies To list, select Permit.

  15. In the Payload field, enter ["description"].

  16. Click Save changes.

A screen capture of the Restrict Intern Access policy window with the Combining Algorithm and one rule with advice, both configured as specified

Example files

The compressed PingAuthorize Server file at PingAuthorize/resource/policies includes a policy snapshot and deployment package that both contain an example Trust Framework and example policies.

Conclusion

In this tutorial, you set scope-based access to SCIM resources.

You also learned:

  • Like exclude-attributes used in this tutorial, include-attributes filters which attributes can be returned to the caller. include-attributes works more like opt-in, while exclude-attributes works more like opt-out.

  • Multiple attributes can apply from multiple rules or even policies. They are combined by PingAuthorize to include before exclude.