Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ADR - Non Data Resource (NDR) Support #1915

Open
ttschampel opened this issue Feb 12, 2025 · 0 comments
Open

ADR - Non Data Resource (NDR) Support #1915

ttschampel opened this issue Feb 12, 2025 · 0 comments
Labels
adr Architecture Decision Records pertaining to OpenTDF

Comments

@ttschampel
Copy link
Member

ttschampel commented Feb 12, 2025

Background

Obligation User Stories surfaced a need to introduce the concept of a Non Data Resource that may serve as the “Entity” or “Resource” in a decision request.

Related Work

@strantalis's 2024 EBPF Hackathon Project. Implemented EBPF ABAC control of network traffic based on the user/env and target env. Resource Mappings were used as the mechanism to map an IP address as a term to Attribute Value. This mapping was then used to construct a resource attribute FQN list as part of a Decision Request.

Terms:

  • Resource: This is the current state of a Resource as described in the decision request API; a set of data attributes. The resource is what the decision request is permitting access to.
  • Entity: A single entity in the entity chain input to a decision request. An entity can be identified by a set of different types; reference.
  • NDR: A Non Data Resource that may play the role of the “Resource” or “Entity” in a decision request.
    • Entity Role: NDR is in the role of Entity
    • Resource Role: NDR is in the role of a Resource
  • NDR Registry: A registry of NDRs and its identifiers, aliases and Entitlements.

Problem

The platform currently does not support a clear way to request a decision via the Decision Endpoint API for an NDR.
Platform APIs do not support the representation of an NDR as the “Resource” in a decision request or as a specific Entity identifier.

There is not currently a way to retrieve entitlements of an NDR based on a contextual role.

There is also no existing platform service, API or recommendation of how to integrate the idea of an NDR into ABAC policy.

Entity Resources need to have obligation and or attribute value entitlements provisioned by the platform.

Decision

Option 1

This combination provides clear NDR support and less burden from an API/SDK consumer perspective.

The addition of the NDR Registry Service provides an extensible API and default implementation to support NDR entitlement
out of the box.

Option 1 - Update Get Decisions and Get Entitlements API, Add NDR Registry

This option updates:

  • Update the decision request property of the decision request to include a “one of” to include the resource attributes OR entity resource (data type = Entity).
    • This is not strictly speaking a breaking change since in the protobuf world this is just adding new fields to the message and does not change the behavior of the existing fields. However this would obviously break functional contracts between new SDKs hitting an older version of the platform.
  • Update GetEntitlementsRequest to include an optional role of ENTITY|RESOURCE. This role is only used in the case of an NDR entity type.
  • Introduces a new service and implementation; NDR Registry. This service is responsible for:
    • CRUD operations of NDR entries and their associated aliases and Entitlements (by role).
    • Retrieving Entitlements by NDR URN and role.

Pros:

  • Re-use existing ERS service to support Entity Resource specific resolution as needed.
  • Additional Entity Resource entity type(s) allow for explicitly identification of an entity as an Entity Resource.
  • Updated decision request API supports Entity Resource directly as an alternative Resource value in the request.
  • Updated GetEntitlements request API allows for reasoning about entitlements for NDRs for a specific role.

Cons:

  • SDK consumers using this new functionality requires an updated platform instance supporting these features.

Diagram: Updated Get Entitlements Sequence

The updated sequence for a client to get entitlements:

  1. Client using the updated GetEntitlementRequest to request entitlements.
  2. Get Entitlements computes entitlements
  3. If NDR:
    1. asks the NDR registry for entitlements for the given scope
    2. populates a GetEntitlementResponse from the GetNDREntitlementsResponse and returns the value to the client
  4. else:
    1. Processes existing logic as it does today, includes Subject Mappings, ERS
sequenceDiagram
    participant client as Client
    participant entitlements as AuthorizationService - Get Entitlements
    participant registry as NDR Registry - Get Entitlements
    activate client
    activate entitlements
    client->>entitlements: GetEntitlementsRequest
    Note over client,entitlements: Updated request structure <br/> includes role, <br/> updated entity types
    alt If NDR
        entitlements->>registry: GetNDREntitlementsRequest
        note over entitlements,registry: role = request role
        registry->>entitlements: GetNDREntitlementsResponse
        entitlements->>entitlements: GetEntitlementsResponse from GetNDREntitlementsResponse
        entitlements->>client: GetEntitlementsResponse
    else else
        entitlements->>entitlements: existing logic, ERS + Subject Mappings
        entitlements->>client: GetEntitlementsResponse
    end
    deactivate entitlements
    deactivate client
Loading

Figure: Updated Get Decisions Sequence

The updated GetDecisions Sequence:

  1. Client asks for a decision using the new GetDecisionsRequest
  2. If the resource in the decision request is an NDR:
    1. Get entitlements for the NDR using the RESOURCE NDR role
    2. Populates the resource attributes of the decision request with the returned NDR entitlements.
  3. Loops over Entities in the Entity chain as it does now to get entitlements for each Entity in the Entity Chain
  4. Executes the remainder of the enforcement logic as it is today.
sequenceDiagram
    participant client as Client
    participant decision as AuthorizationService - Get Decisions
    participant entitlements as AuthorizationService - Get Entitlements
    activate client
    activate decision
    client->>decision: GetDecisionsRequest
    note over client,decision: updated request structure
    activate entitlements
    alt if request resource is an NDR
        decision->>entitlements: GetEntitlementsRequest
        note over decision,entitlements: Get NDR entitlements
        entitlements->>decision: GetEntitlementResponse
        decision->>decision: populate NDR entitlements into request resource_attributes
    end
    loop every Entity in Entity Chain
        decision->>entitlements: GetEntitlementsRequest
        entitlements->>decision: GetEntitlementResponse
    end
    deactivate entitlements
    decision->>decision: process remainder of existing logic <br/> subject mappings, Access PDP, etc.
    deactivate decision
    deactivate client
Loading

Updated Decision Request

Adds an option to an NDR Entity chain as a resource

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

Updated Entity Type

Adds an ndr_urn entity type for exclusive use as an NDR identifiers.

  • URN format that is self describing wrt the NDR category.
  • NDR Registry is responsible for transforming to/from NDR URN as necessary
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;
    string ndr_urn = 9;
}

Updated GetEntitlements Request

Adds an NDR Role that is optional and only used for a NDR Entity Type. Default for NDR Entity Type is ENTITY

message GetEntitlementsRequest {
   enum NDRRole {
    NDRROLE_UNSPECIFIED = 0;
    NDRROLE_ENTITY = 1;
    NDRROLE_RESOURCE = 2;
  }
  // list of requested entities
  repeated Entity entities = 1;
  // optional attribute fqn as a scope
  optional ResourceAttribute scope = 2;
  // optional parameter to return a full list of entitlements - returns lower hierarchy attributes
  optional bool with_comprehensive_hierarchy = 3;
  // optional NDR role
  NDRRole ndr_role = 4;
}

Option 2 - Leverage existing services as is

This option requires no change to current APIs and leaves it to the Decision Endpoint client to infer the resource attributes
of a decision request for an NDR. The existing entitlement service could be leveraged as part of this solution, but lacks
an NDR role property.

Pros:

  • No API changes

Cons:

  • Clients/PEPS need to infer NDR to Entitlement Mappings. Requires extra API calls at a minimum to get these entitlements
  • Decision logic cannot easily infer if an Entity is an NDR for purposes of Entitlement.
@ttschampel ttschampel added the adr Architecture Decision Records pertaining to OpenTDF label Feb 12, 2025
@ttschampel ttschampel changed the title ADR - Entity Resource Support ADR - Non Data Resource (NDR) Support Feb 13, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
adr Architecture Decision Records pertaining to OpenTDF
Projects
None yet
Development

No branches or pull requests

1 participant