Manage granular policies

Granular policies allow you to configure row-level security for datasets and objects. They are used by restricted views and object security policies to determine which specific rows or object instances a user has permission to access.

A granular policy is a set of rules and logical operators that compare user attributes, columns or properties, and values to determine which data the user can see. Granular policies are flexible and support a range of comparisons and terms.

Design granular policies

Before creating a granular policy, consider the following questions:

• How do you want to restrict access to the data?
• What user attributes can you use in the policy?
• On which columns or properties could your policy depend?
• Which Markings propagate through the pipeline but could be unmarked when creating the resource?
• How will you grant permissions to new users?

Recommendations

We recommend the following guidelines when designing a granular policy:

• Keep it simple: Before creating a granular policy, write down the policy you want to enforce. Determine the minimum set of conditions required for that policy. The more complex the policy, the harder it will be to manage and verify.
• Make sure policy columns are non-null: Rows with null values in a policy column will be inaccessible to all users. Having null values in the policy column will also cause issues with syncs and downstream processes (such as Phonograph syncs).
• Leverage the pipeline: To reduce the complexity of policies that do not fit well with the current data shape or fields, use the pipeline to compute columns that will make policy writing easier. Try to handle complexity in the pipeline rather than in the granular policy.
• Consider using a dedicated policy column: Changes made to columns in the backing dataset referenced in your policy may break the policy assumptions. To protect a policy from this risk, consider separating out the logic that decides the policy and creating a dedicated column (or columns) for the policy to reference.
• Use attributes: Attribute-based policies can often be the simplest option. Attributes can be pulled from SSO or posted via a user manager.
• Use markings: A granular policy filters which rows a user can read; it does not extend to downstream outputs or exports. A marking on the backing dataset propagates through derivation and keeps data protected as it flows downstream. The two controls serve different purposes and should generally be used together. Do not remove an inherited marking on the assumption that the granular policy already controls access. For the full model, see Access control propagation.

User attributes

Below is a list of supported user attributes in granular policies:

• User ID: A unique ID generated by Foundry for each user.
• Username: A unique ID provided by the user's identity provider at login.
• Group IDs: The IDs of all the groups that have the user as a member (direct and inherited).
• Group names: The names of all the groups that have the user as a member (direct and inherited).
• Authorized group IDs: This is an advanced concept related to scoped sessions. Contact your Palantir administrator if you plan to use granular policies with scoped sessions.
• Organization Marking IDs: The Marking IDs of all organizations that have the user as a member (primary and guest). These Marking IDs are UUIDs, not Organization IDs that start with ri.multipass..organization.
• Marking IDs: The IDs of all Markings that the user has permission to view.
• Custom attributes: Any custom attributes configured by your identity provider in Control Panel.

When referencing a user, group, or organization, the policy requires the unique identifier (UUID) in both the policy column and the policy definition. Specifying names instead of IDs is not supported to prevent renaming-related issues.

Policy comparisons

Granular policies support the following comparison types:

• Equal: Both the left and right side of the comparison must be single-valued (not a collection) and of the same type.
• Intersects: At least one side must be a collection, and both must be of the same type (or collection of that type).
• Subset of: At least the right side must be a collection, and both must be of the same type (or collection of that type).
• Superset of: At least the left side must be a collection, and both must be of the same type (or collection of that type).
• Less Than: Both the left and right side of the comparison must be single-valued (not a collection) and of the same type.
• Less Than or Equal: Both the left and right side of the comparison must be single-valued (not a collection) and of the same type.
• Greater Than or Equal: Both the left and right side of the comparison must be single-valued (not a collection) and of the same type.
• Greater Than: Both the left and right side of the comparison must be single-valued (not a collection) and of the same type.

Policies are defined as templates into which user attributes, group memberships, and data values can be filled. When the consuming application requests data (such as in Contour), the template is converted into a query. This query returns only rows or objects specific to the user's attributes and permissions.

Policy limitations

Granular policies have a maximum total comparison weight of 10,000. Weight depends on the values each condition compares, so counting the conditions alone does not tell you whether a policy is within this limit. The same weight calculation applies to restricted views and object security policies.

Identify the values in a condition

Each condition compares two values. Identify what type each value is:

• Field: A dataset column in a restricted view or an object property in an object security policy. Its value can vary between rows or objects.
• Single value: One value, such as the current user's ID or the specific string Open. The policy comparisons section calls this single-valued.
• Collection: A list or set of values, such as the current user's group IDs, custom attribute values, or a specified list containing Open and Pending.
• Constant: A value specified in the policy. It can be either a single value or a collection.

Determine each condition's weight

Use the following table to determine the weight of each condition:

When you select specific groups, the editor displays group names, but the policy references the selected groups by their IDs.

For field comparisons, the weight depends on whether the value on the other side is a single value or a collection. This applies regardless of which side of the comparison contains the field. A collection remains a collection even when it contains only one value. Its comparison weight does not depend on how many groups the user belongs to or how many entries the list contains.

A weight of 0 does not mean that a condition is ignored. A condition that uses only user attributes and constants can determine access without reading a row or object property. It is evaluated for the user before the remaining field comparisons.

Calculate the total weight

Add the weights of all conditions, including conditions inside nested All (AND) and Any (OR) groups. Both types of group use addition. A NOT operator adds no weight beyond the condition it contains. The restrictions on negating group, marking, or organization membership still apply.

For property security policies, also account for the combined weight of the object and property security policies.

If you receive weight limit errors when constructing policies, contact Palantir Support for assistance.

Policy management

When you manage granular policies, consider two goals:

• Transparency: Anyone responsible for managing data access should know the policies and how the policies interact with data in the platform.
• Robust change management: Policy management should be an orderly, organized process. Always review and manage changes before applying them.

Managing integrity of data pipelines

Granular policies introduce a set of assumptions about the data that backs them. Therefore, granular policies will only correctly control access to data as long as these assumptions are true. Consider whether the use case requires building out machinery to ensure that those assumptions hold and data stays secured if those assumptions are broken.

One way to solve this problem is by introducing a step in the pipeline directly upstream of the resource that checks the assumptions made about the data. These checks might include:

• Invariants: Write a list of invariants that will force the downstream build to fail if they are not true. For example, assume that whenever an event_occurred_in_state has the value NY, another column in the dataset called state_name should have value New York. Have the transform check that this is true before surfacing this data to users.
• Statistics: Define a set of statistics and the range they should always be within. For example, a granular policy may be used to enforce access controls mirroring an organization hierarchy; each user can only see data about individuals below them in the hierarchy. Have the transform assert that if more than 20% of the hierarchy changes from one day's build to the next, something is wrong. At this point, users responsible for policy management should check to ensure everything is correct before surfacing this data to users.

These integrity checks protect the upstream data that the granular policy depends on so that the policy continues to filter rows correctly. They do not extend the policy to downstream outputs or exports. To keep data protected as it flows downstream, pair the granular policy with a marking or Classification-based Access Control on the underlying data. For the full model, see Access control propagation.