ADR: Attribute Value Scoping

[ttschampel]

Background

ABAC policy enforcement within the Platform is modeled using the constructs of an Entity Chain requesting access to a Resource for one or more Action(s). The response includes a decision containing response (DENY,ACCESS) and corresponding obligations. An Entity Chain is a list of Entities requesting the action and could be a single Person Entity (PE) or a single Non Person Entity (NPE) or a chain of [NPE1..N, PE]. In most use cases (given OIDC flows), the entity chain will contain 2 entities in the entity chain. This is true for On-Behalf-Of flows, even when multiple OBO exchanges take place; where for purposes of enforcement the system cares about the original actor and the requesting actor.

On-Behalf-Of

Only the “original” entity and the calling OBO entity are materialized into the entity chain, unlike the current state which takes all transitive entities. This basically follows the guidance of OIDC Delegation Token Exchange flows: One noteworthy feature of the act claim is its structure as a JSON object. This structural flexibility is significant because it allows the act claim to capture a delegation chain by nesting act claims within one another. However, when making policy decisions, only the outermost act claim should be considered and the nested act claims are to provide information about the delegation chain. This nesting capability is quite important in token-based systems to represent complex delegation scenarios when involving multiple entities.

Problem

There is no mechanism scope attribute values for purposes of policy enforcement to entities in an entity chain.

Decision Outcome

Attribute Value Scope

Add a new Scope to AttributeValue that is one of:

• allOf: All the entities in the chain are required to be entitled to the attribute value
• anyOf: Any of the entities in the chain need to be entitled to the attribute value.

Related Changes:

• AccessPDP needs to be updated to honor this new scope structure.

Example proto changes:

Message AttributeValueScope{
  enum ScopeType{
    SCOPE_YPE_UNSPECIFIED = 0;
    SCOPE_TYPE_ALL = 1;
    SCOPE_TYPE_ANY = 2;
  }
  ScopeType scopeType = 1;
  Value entityAttributeValue = 2; // entitled entity attribute scoping value
}

//update Attribute Value
Message Value {
....
  AttributeValueScope scope = 9;
}

[elizabethhealy]

would it make sense to have it at the attribute level instead of attribute value so like TS, S, C, U for example all behave the same? or are there use cases where we'd want certain values within the same attribute to behave differently?

[ttschampel]

would it make sense to have it at the attribute level instead of attribute value so like TS, S, C, U for example all behave the same? or are there use cases where we'd want certain values within the same attribute to behave differently?

Yes, there are cases were certain attribute values may need to be scoped differently

[jrschumacher]

Should this be part of the attribute or the subject mapping?

If it were part of the subject mapping I could then state the subjects I want to pass entitlement through with precision.

A --> B --> C

A: base entity
B: intermediate entity
C: requesting access

If this was mapped through attributes it would effectively be 1) allow chains 2) disallow chains (with some nuance)

If it's mapped by subject maps then when we are processing the entitlement it could be B and C are marked as "inherit entitlement" for the linked attributes.

It's more work to configure but would prevent:

A --> B --> X --> C

A: base entity
B: intermediate entity
X: mitm attack vector
C: requesting access

[damorris25]

Defining this at the subject mapping level would be incredibly burdensome on the policy administrator, wouldn't it?

[ttschampel]

I think defining the scope of policy enforcement should live along side the rest of the Attribute policy. This makes it clear to the Attribute Admin/Author what the scope is and the enforcement expectations by the Access Engine. Subject Mappings Policy can still be used (and as complicated as needed) to correctly entitle entities.

[jrschumacher]

This makes it clear to the Attribute Admin/Author what the scope is and the enforcement expectations by the Access Engine.

This can be accomplished with visualizations, especially since I cannot imagine an attribute admin will not want insight into the subject mappings.

I have no strong objections where it lives, but if we're fine with less granularity in favor of more convenient management, then that makes sense. If we do end up needing granularity, I would push back against adding more complexity around attributes.

[jakedoublev]

I think my biggest struggle with this is how to effectively communicate to a platform/policy administrator or a PEP developer what deterministic access behavior will look like with these additional scoping rules and entity chaining.

I think the complexity of understanding entity chaining, chained scenarios, and entitlements of the given chains/scenarios is a requirement of an admin as long as there's a concept of entity chains. Use of the allOf scope would still mean entitling individual chained entities via subject mappings, so admins must understand and entitle PEPs/environments/etc in the chain regardless with this approach if they use that scope.

As the platform admin, I expect Alice to be given access given the subject mappings I've configured. However, I find these scenarios:

1. my testing of ERS and demo tooling with her Entity Representation finds that she has access as expected
2. when accessing data within PEP_A, Alice is present in the following entity chain [PEP_A, Alice] and given access as expected
3. when accessing data within PEP_B, Alice is present in the following entity chain [PEP_B, Alice, Environment_1 (a network), Environment_2 (a geolocation)]

Any approach seems to require answering "what are the expected entity chains?".

Then, it seems like the question asked of admins by this scoping approach is: "What are the 'chained' scenarios every attribute may eventually face?" (attribute focus)

Driving a solution to entitle each entity in a chain via subject mappings would ask the question instead of: "How is each entity in a chain entitled and to which attributes?" (entitlement focus)

I think there are merits to both. However, I wonder if the entitlement focus and a solution driven by subject mappings alone may be more durable for PEPs with differing levels of "trust." It seems like there could be a scenario where a very sensitive anyOf-scoped attribute may require a change to allOf upon introduction of a less trusted PEP, and it seems like that change would get challenging downstream.

Whatever the solution, the largest challenge will be effectively communicating (docs/UX) how a policy definition will impact access behavior deterministically in a way that feels correct with the layers of complexity and potential abstraction in the chain.

One definite upside of this scoping approach is that every attribute could be anyOf and admins would therefore not have to entitle each entity in a chain separately, which is the current state today.

[jrschumacher]

@jakedoublev as I interpret your comment, the experience from an admin will be:

Use case

Given:

• attribute: XYZ
• entities:
  • bob (PE1)
  • service A (NPE1)
  • service B (NPE2)

All Of

1. Admin sets scope to allOf on attribute XYZ
2. Admin entitles entities
   1. PE1 to XYZ
   2. NPE1 to XYZ
   3. NPE2 to XYZ

Any Of

1. Admin sets scope to anyOf on attribute XYZ
2. Admin entitles PE1 to XYZ via subject mappings

---

Either way, we'll need significant enhancements in UX to better explain attributes that are accessible via a chain. IMO allOf, being the default behavior, means that we would only need to indicate that the attribute can be entitled via a token exchange.

[ttschampel]

Updating status: waiting on further discussion on overall entity chain / attribute scoping before making a decision,

[ttschampel]

Closing this in favor of https://github.com/opentdf/platform/issues/1181