ADR: Obligation Support, Updated

[ttschampel]

Background

Two previous ADRs covered Obligation support and another for
the implementation path. There has been confusion on
terminology and role of obligations, unsupported use cases and concerns on implementation path raised since approval of
the support ADR and submission of the implementation path ADR.

Problem

Refine Obligation support to:

• Satisfy the full set of Obligation Requirements. This includes
  • Policy to describe the required obligations for an Entity to perform a given Action against a Resource
  • Policy to describe alternate handling obligations for an Entity handling a Resource for a given Action
  • Architecture to support the enforcement of obligation policy types.
• Define and document expectations of a PEP with regard to the use of Obligations
• Serve as a baseline architecture to support a revised Obligation Policy implementation path follow on ADR

Decision Outcome

• Formalize expected PEP behavior in documentation; PEPs are responsible for consuming obligations returned in API calls and enforcing where applicable.
• Add Obligation Policy and Services as described below
• Update Access PDP Contract and Implementation as described below
• Update the KAS Rewrap endpoint to pass through obligations to the caller
• Update EntityEntitlements to generalize attribute_value_fqns to include obligation value fqns.

The current Decision Request API is provided for reference purposes below. The following terms
are shorthand for these API structures:

• Entity: The Decision Request Entity Chain
• Entity Category: An Entity's category
• Resource: The Decision Request resource_attributes
• Action: The Decision Request actions

Recommended Changes:

Obligation Policy

Introduce new Obligation Policy and Services to support the enforcement of PEP obligations for purposes of access control and / or Resource handling.
The full implementation and design of this policy is out of scope and left to a future ADR; only a description and purpose of these constructs
is described here. This approach is a departure from the original ADR which overloaded Attribute Definitions.

Obligation Definitions define the available obligation values that can be used within the system. There are two types
of Obligations needed to support current requirements: Standard Obligations and Handling Obligations. All obligation
policy types belong to a Namespace.

Authorization policies are enforced such that Obligations can only reference Resource Attribute Values in the same namespace

There may exist future requirements to add additional Obligations types.
In this case additional Obligation Policy types can be introduced and then enforced within the platform using a plugin model.

Obligation Definitions

Defines a parent, child Obligation; much like Attribute Definition->Attribute Value. Obligation Definitions also
need to have an FQN and associated with a namespace.

The FQN uses a naming convention of <namespace>/obl/<obligation name> and <namespace>/obl/<obligation name>/value/<obligation value>
to represent an Obligation Definition or Obligation Value. This naming convention helps disambiguate an obligation FQN
from an Attribute FQN.

Standard Obligation

An obligation that is enforced by the Access PDP validating permitting an Entity of a specified Category to perform an Action on a given Resource.

A Standard Obligation can be defined with the following properties:

• Entity Category: the obligation is scoped to this type of entity. An entity of this type must be present.
• Action: the obligation is scope to this decision request action.
• Resource Attribute Value: The data attribute for which this obligation is scoped.
• Obligation Value: The required obligation value; this is required

The Access PDP is responsible for consuming and enforcing Standard Obligations.

Examples:

• All HIPAA documents must be watermarked on read. This can be represented with a Standard Obligation Policy with:
  • Entity Category = ENVIRONMENT; watermarking must be supported by the environment / client
  • Action = READ
  • Resource = data attribute https://example.com/attr/classification/value/hipaa ~ attr:cls:hipaa
  • Obligation Value = https://example.com/obl/drm/value/watermarking ~ obl:drm:watermarking
• All movies that are rated R should only be read by
  users that are 17 and older. This can be represented with a Standard Obligation Policy with:
  • Entity Category = SUBJECT; a person must meet the obligation criteria
  • Action = READ
  • Resource = Rated R data attribute https://example.com/attr/movierating/value/r ~ attr:mr:r
  • Obligation Value = 17 and older = obligation value https://example.com/obl/age/17andolder ~ obl:age:17andolder

Table: Example Standard Obligation Access Decision Request/Response

Resource	Entity Entitlements Environment	Entity Entitlements SUBJECT	Action	Response Decision	Response Obligation	Comment
attr:cls:hipaa	obl:watermarking		READ	PERMIT	olb:watermarking	Env entity entitled with watermarking
attr:cls:hipaa	obl:watermarking	obl:watermarking	READ	PERMIT	olb:watermarking	Env entity entitled with watermarking
attr:cls:hipaa			READ	DENY		No Env entity entitled with watermarking
attr:mr:r			READ	DENY		No Subject entity entitled with 17 and older
attr:mr:r		obl:age:17andolder	DENY	PERMIT	obl:age:17andolder	Subject entity entitled with 17 and older
attr:mr:r	obl:age:17andolder		READ	DENY		No Subject entity entitled with 17 and older

Handling Obligation

A Handling Obligation defines a condition where an Entity can perform an action on a specified Resource because
the Resource can be handled differently if the calling PEP enforces additional obligations. The Access PDP is responsible
for digesting handling obligation policy and performing what is effectively a Drop/Add for purposes of authorization.

A Handling Obligation can be defined with the following properties:

• Entity Category: the obligation is scoped to this type of entity. An entity of this type must be present.
• Action: the obligation is scope to this decision request action. Care should be taken by administrators of the policy namespace such that action/handling
  obligations do not accidentally reduce the required entitlements to a resource.
• Resource Attribute Value: The data attribute for which this obligation is scoped. This is the "Drop" portion of the policy
• Obligation Value: The required obligation value; this can be None
• Obligation Attribute Value: This is the "Add" portion of the policy. The Resource Attribute Value is dropped
  (or aliased) to this value for purposes of authorization decision. This can be None.

The combination of the above properties can be used to support other handling scenarios.

For example, allow the storage of confidential data anywhere. This is
basically a Drop/No Add; action=STORE, drop (Resource Attribute Value) attr:cls:c, add (Obligation Attribute Value) = None

Example Scenario - Transmit Handle as Confidential

Allow the transmission of data from one network to another for data classified as top secret as long as the target network
is entitled with confidential classification or above with the additional obligation to encrypt the data with fips 140-2.

The Attribute Definition: A hierarchical type definition, fqn = http://example.com/attr/classification (attr:cls),
values = [top secret, secret, confidential, unclassified] = [attr:cls:ts,attr:cls:s,attr:cls:c,attr:cls:u]

An Obligation Definition for encryption , fqn = http://example.com/obl/encryption (obl:enc), with values [fips-140-2] = [obl:enc:fips-140-2]

Handling Obligation Example Request / Response

Resource	Entity Entitlements Environment	Action	Response Decision	Response Obligation	Comment
attr:cls:ts	attr:cls:ts	STORE	PERMIT		Env entity entitled with cls:ts
attr:cls:ts	attr:cls:s	STORE	PERMIT	obl:enc:fips-140-2	Env entity entitled with cls:s; which is >= confidential
attr:cls:ts	attr:cls:c	STORE	PERMIT	obl:enc:fips-140-2	Env entity entitled with cls:c; which is >= confidential
attr:cls:ts	attr:cls:u	STORE	DENY		Env entity is not entitled >= confidential
attr:cls:ts	attr:cls:ts	READ	PERMIT		Env entity NOT entitled with cls:ts
attr:cls:ts	attr:cls:s	READ	DENY		Env entity NOT entitled with cls:ts
attr:cls:ts	attr:cls:c	READ	DENY		Env entity NOT entitled with cls:ts
attr:cls:ts	attr:cls:u	READ	DENY		Env entity NOT entitled with cls:ts

Actions

Update Decision Request Actions to handle missing decision request "verbs" and rename to avoid confusion to the following:

Action	Description
STORE	Can a Resource exist or be present in a target Resource. This would replace the existing TRANSMIT action
READ	Can an entity read a Resource. This would replace the existing DECRYPT action
CREATE	Can an entity create a Resource
UPDATE	Can an entity update a Resource
DELETE	Can an entity delete a Resource

Access PDP

The Access PDP contract is updated to support the enforcement of obligations. This required:

• Add decision request action; pass through of the decision request action to the Access PDP
• Add Obligation Policy/Definitions

Access PDP is updated to enforce the supplied obligation policy and implemented in a way to support future pluggable
obligation type support and enforcement.

References

Decision API - Current

Decision Request

message DecisionRequest {
  repeated policy.Action actions = 1;
  repeated EntityChain entity_chains = 2;
  repeated ResourceAttribute resource_attributes = 3;
}

Decision Response

message DecisionResponse {
  enum Decision {
    DECISION_UNSPECIFIED = 0;
    DECISION_DENY = 1;
    DECISION_PERMIT = 2;
  }
  string entity_chain_id = 1; // ephemeral entity chain id from the request
  string resource_attributes_id = 2; // ephemeral resource attributes id from the request
  policy.Action action = 3; // Action of the decision response
  Decision decision = 4; // The decision response
  repeated string obligations = 5; //optional list of obligations represented in URI format
}

Entity Chain

message EntityChain {
  string id = 1; // ephemeral id for tracking between request and response
  repeated Entity entities = 2;
}

Entity

message Entity {
  string id = 1; // ephemeral id for tracking between request and response
  // Standard entity types supported by the platform
  oneof entity_type {
    // one of the entity options must be set
    string email_address = 2;
    string user_name = 3;
    string remote_claims_url = 4;
    string uuid = 5;
    google.protobuf.Any claims = 6;
    EntityCustom custom = 7;
    string client_id = 8;
  }
  enum Category {
    CATEGORY_UNSPECIFIED = 0;
    CATEGORY_SUBJECT = 1;
    CATEGORY_ENVIRONMENT = 2;
  }
  Category category = 9;
}

[jp-ayyappan]

Just a nit, the healthcare examples should reference HIPAA (Health Insurance Portability and Accountability Act) not hippa

[jakedoublev]

@ttschampel I'm wondering if we should unify STORE/CREATE action verbs, or more specifically articulate the difference (i.e. STORE is a send/transmission and CREATE is a persistence like a bucket)?

[ttschampel]

@ttschampel I'm wondering if we should unify STORE/CREATE action verbs, or more specifically articulate the difference (i.e. STORE is a send/transmission and CREATE is a persistence like a bucket)?

Yes, I will create an action item to capture better descriptions / contrast the differences

[ttschampel]

Just a nit, the healthcare examples should reference HIPAA (Health Insurance Portability and Accountability Act) not hippa

Updated accordingly