ADR: Entitlement Policy Deployment Model

[ttschampel]

Entitlement Policy Deployment Model

Context and Problem Statement

The Entitlement Policy (rules, logic, etc.) defines the provisioning of Entitlements to an Entity. The process of determining what entitlements an Entity may have include the processing of Subject Sets against and Entity, the lookup of an Entity from an authoritative source, the inclusion of customer/deployment specific policy as well as interfacing with external federated Entitlement Services.

There is also a need to support the injection and verification of an Entitlement Policy from an external source or configuration.

Decision Drivers

• We don't want to have a high deployment and configuration burden
• We want to reduce friction for Entitlement Policy Authors
• We don't want to re-invent a policy injection, verification and distribution framework
• We want to decouple the platform from Entitlement specific logic and integrations
• We want to support the inclusion of policy and associated integrations dynamically and not known in advance the core platform

Considered Options

• Custom + Configuration Driven
• OPA Configuration Driven
• OPA Bundle with Custom Built-In Functions

Decision Outcome

OPA Bundle with Custom Built-In Functions

This option allows for encapsulation of core capabilities as standard Go code while at the same time leveraging an open standard to allow for extensibility, deployment and verification.

Custom + Configuration Driven

This option includes the custom development of an extensible, shareable policy framework.

Pros/Cons:

• 🔴 Re-Invent policy language, infrastructure
• 🔴 Re-Invent a verifiable, shareable policy mechanism.

OPA Configuration Driven

This option uses OPA and Platform configuration to wire up and initialize an OPA runtime; this is current state. This solution includes Rego implementation of Subject to Entity Mapping interpretation. OPA plugins are known prior to deployment.

Pros/Cons:

• 🟢 Leverages an existing and widely used standard (OPA)
• 🔴 Extensibility friction
• 🔴 Coupling to Policy implementation
• 🔴 OPA/Rego learning curve

OPA Bundle with Custom Built-In Functions

This option uses an OPA Bundle as the deployment unit and consumption into the Entitlement Service. Core platform OPA built-in functions are used to support common core platform functions. Standard OPA external data fetching flows (e.g. Rest Endpoint) are used to support deploy time specific customizations. This allows for decoupling of entitlement logic; both core and extensions; from the platform as well as supports future requirements of distributed, federating and verifying policy artifacts.

This option includes the creation and enforcement of the following design guidelines:

• Custom OPA Build-In Functions are to be used for encapsulating complexity in standard Go modules and thereby reducing Rego complexity and friction.
• IDP specific entity resolution implemented as Services following OPA's Pull Data During Evaluation pattern and integrated through standard OPA http requests.

The implications of this approach:

• The creation of a function to support Subject Set / Entity Representation processing as an OPA Built-In Function.
• A Keycloak Entity Resolution Service reference implementation.
• Reference implementation Rego policy using subject set and http based entity resolution call-out

Pros/Cons:

• 🟢 Leverages an existing and widely used standard (OPA)
• 🟢 Leverages a standard packaging, deployment and distribution flow (including verification)
• 🟢 Extensible and supports decoupling = Support dynamic injection of Policy
• 🟡 OPA/Rego learning curve - mitigated by the use of custom build-in functions to encapsulate complexity in standard Go

[pflynn-virtru]

• Custom + Configuration Driven
  • I agree with the negatives. I haven't imagined a more elegant solution that OPA
• OPA Configuration Driven
  • This seems to work in a lab or development environment. This should not be the solution for a higher-level environment.
• OPA Bundle with Custom Built-In Functions
  • I agree. This should be the solution for a higher-level environment.

[pflynn-virtru]

out-of-scope of this ADR, If "OPA Bundle with Custom Built-In Functions" is selected then creating the OPA bundle could become an function of the admin CLI.

[ttschampel]

I agree - The deployment and updating of a "Bundle" should be as easy as possible from an administrator or policy developer; openTDF CLI makes sense as a place to put some of these commands

[strantalis]

@ttschampel For option three are thinking a single bundle with something like the following?

package opentdf.entitlements

attributes := [attribute |

  entity_representation := resolve.entity(entity_identifiers)
  resolve.mapping(entity_representation)
]

[jrschumacher]

@ttschampel does this mean every customer is obligated to use OPA? For instance if Carta was a customer and they wanted to use their in-house Zanzabar solution would that not be possible?

Could we implement this in a way where the Entitlement Engine is an interface that includes policy deployment and agents. In such a way one could swap it out with any compatible solution such as SpiceDB?

Lastly, as a con to OPA solutions (without extensions) we are forcing OPA on our customers and Carta notes in their blog (linked above) that they chose not to use OPA:

OPA has some downsides. It requires a large set of self-managed infrastructures. Permission checks are also slow. With OPA, the consumer controls the underlying data source. You store policy code in OPA, but policies query domain-level data for access checks. This worked fine for simple permissions, but complex ones caused major issues for us.

Complex permissions often queried several data models and added hundreds of milliseconds to response times. That wasn’t going to work for us.

[jrschumacher]

Also, would the custom solution align with the webhook idea we discussed the other day or would that be a fourth option? (I guess it could also be the 3rd option)

[ttschampel]

The way I see it option3 gives us the following customization levels:

• Subject Mappings (all options have this) - customer + IDP specific mappings can occur via standard policy administration
• IDP or Entity Store Custom integration: Implement a new IDP Webhook (or extend an existing one)
• Custom rule logic; one or both of the following:
  • Define additional rules in Rego.
  • Implement their own Entitlements Endpoint per the Proto Spec

[ttschampel]

Updated to remove incorrect characterization of the IDP external fetching as Webhook

[jakedoublev]

Do we have more documentation on the webhook implementation and the flow with idPs, and/or what the Entity Resolution Service interface looks like?