From 481baabf72771df827c7155737e72b38d383b1da Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Wed, 20 May 2026 10:52:41 -0700 Subject: [PATCH 1/5] docs(authz): add v2 Authorization API request validation limits Document the hard-coded protovalidate constraints on v2 Authorization API requests (entity chain size, attribute values count, obligation FQNs, batch sizes). These limits were previously only visible in the proto source and auto-generated OpenAPI specs. Refs: opentdf/platform#3500, opentdf/platform#3502 Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Mary Dickson --- .../config/vocabularies/Opentdf/accept.txt | 2 ++ docs/components/authorization.md | 18 ++++++++++++++++++ 2 files changed, 20 insertions(+) diff --git a/.github/vale-styles/config/vocabularies/Opentdf/accept.txt b/.github/vale-styles/config/vocabularies/Opentdf/accept.txt index b7af9005..8d56fba0 100644 --- a/.github/vale-styles/config/vocabularies/Opentdf/accept.txt +++ b/.github/vale-styles/config/vocabularies/Opentdf/accept.txt @@ -39,3 +39,5 @@ OR'd NPEs top_secret AAVs? +performant +protovalidate diff --git a/docs/components/authorization.md b/docs/components/authorization.md index f883645b..eb488c14 100644 --- a/docs/components/authorization.md +++ b/docs/components/authorization.md @@ -145,6 +145,24 @@ Endpoints: - useful for multiple entities - useful for multiple actions +### Request Validation Limits + +The v2 Authorization API enforces request validation limits via [protovalidate](https://github.com/bufbuild/protovalidate) constraints. Requests exceeding these limits are rejected before processing. + +| Field | Min | Max | Endpoints | +|---|---|---|---| +| `EntityIdentifier.entity_chain.entities` | 1 | 10 | `GetDecision`, `GetDecisionMultiResource`, `GetDecisionBulk`, `GetEntitlements` | +| `Resource.attribute_values.fqns` | 1 | 20 | `GetDecision`, `GetDecisionMultiResource`, `GetDecisionBulk` | +| `fulfillable_obligation_fqns` | 0 | 50 | `GetDecision`, `GetDecisionMultiResource` | +| `GetDecisionMultiResourceRequest.resources` | 1 | 1,000 | `GetDecisionMultiResource`, `GetDecisionBulk` | +| `GetDecisionBulkRequest.decision_requests` | 1 | 200 | `GetDecisionBulk` | + +:::note +The effective `attribute_values` limit may be fewer than 20 in practice. PEP components (e.g., the tagging service, default attributes) may automatically add attribute value FQNs to a resource before sending the authorization request. Plan for headroom when assigning user-defined attributes. +::: + +See the [v2 authorization proto](https://github.com/opentdf/platform/blob/main/service/authorization/v2/authorization.proto) for the full validation definitions. + ## v1 (soon to be deprecated) ### GetEntitlements From f443aac709f4a5657d85cec8a74d8ec4e4eb62bc Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Wed, 20 May 2026 11:09:38 -0700 Subject: [PATCH 2/5] fix(authz): address review feedback on validation limits - Add GetDecisionBulk to fulfillable_obligation_fqns endpoints (bulk requests contain GetDecisionMultiResourceRequest objects) - Expand PEP acronym on first use Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Mary Dickson --- docs/components/authorization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/components/authorization.md b/docs/components/authorization.md index eb488c14..bb5935be 100644 --- a/docs/components/authorization.md +++ b/docs/components/authorization.md @@ -153,12 +153,12 @@ The v2 Authorization API enforces request validation limits via [protovalidate]( |---|---|---|---| | `EntityIdentifier.entity_chain.entities` | 1 | 10 | `GetDecision`, `GetDecisionMultiResource`, `GetDecisionBulk`, `GetEntitlements` | | `Resource.attribute_values.fqns` | 1 | 20 | `GetDecision`, `GetDecisionMultiResource`, `GetDecisionBulk` | -| `fulfillable_obligation_fqns` | 0 | 50 | `GetDecision`, `GetDecisionMultiResource` | +| `fulfillable_obligation_fqns` | 0 | 50 | `GetDecision`, `GetDecisionMultiResource`, `GetDecisionBulk` | | `GetDecisionMultiResourceRequest.resources` | 1 | 1,000 | `GetDecisionMultiResource`, `GetDecisionBulk` | | `GetDecisionBulkRequest.decision_requests` | 1 | 200 | `GetDecisionBulk` | :::note -The effective `attribute_values` limit may be fewer than 20 in practice. PEP components (e.g., the tagging service, default attributes) may automatically add attribute value FQNs to a resource before sending the authorization request. Plan for headroom when assigning user-defined attributes. +The effective `attribute_values` limit may be fewer than 20 in practice. Policy Enforcement Point (PEP) components (e.g., the tagging service, default attributes) may automatically add attribute value FQNs to a resource before sending the authorization request. Plan for headroom when assigning user-defined attributes. ::: See the [v2 authorization proto](https://github.com/opentdf/platform/blob/main/service/authorization/v2/authorization.proto) for the full validation definitions. From 5364f9bf6bad1abb88f9af93513f68b47ecf0cf7 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Wed, 20 May 2026 11:10:59 -0700 Subject: [PATCH 3/5] fix(authz): specify Virtru's tagging service in validation limits note MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The tagging service doesn't exist in opentdf — clarify it's Virtru's. Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Mary Dickson --- docs/components/authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/components/authorization.md b/docs/components/authorization.md index bb5935be..499c8af6 100644 --- a/docs/components/authorization.md +++ b/docs/components/authorization.md @@ -158,7 +158,7 @@ The v2 Authorization API enforces request validation limits via [protovalidate]( | `GetDecisionBulkRequest.decision_requests` | 1 | 200 | `GetDecisionBulk` | :::note -The effective `attribute_values` limit may be fewer than 20 in practice. Policy Enforcement Point (PEP) components (e.g., the tagging service, default attributes) may automatically add attribute value FQNs to a resource before sending the authorization request. Plan for headroom when assigning user-defined attributes. +The effective `attribute_values` limit may be fewer than 20 in practice. Policy Enforcement Point (PEP) components (e.g., Virtru's tagging service, default attributes) may automatically add attribute value FQNs to a resource before sending the authorization request. Plan for headroom when assigning user-defined attributes. ::: See the [v2 authorization proto](https://github.com/opentdf/platform/blob/main/service/authorization/v2/authorization.proto) for the full validation definitions. From bf42337e6580a8bd8cffafc1bf6f0df00fc58959 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Wed, 20 May 2026 11:54:38 -0700 Subject: [PATCH 4/5] docs(authz): add validation limits inline to endpoint descriptions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Surface the limits where developers will see them — in the Entity Identifier, Resource, and endpoint descriptions — not just in the summary table below. Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Mary Dickson --- docs/components/authorization.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/components/authorization.md b/docs/components/authorization.md index 499c8af6..800edb63 100644 --- a/docs/components/authorization.md +++ b/docs/components/authorization.md @@ -32,14 +32,14 @@ Version 2 of Authorization Service introduced the following changes: #### Entity Identifier The entity identifier is a request proto object allowing multiple structures representing an entity to stand in as the entity in an Auth Service request: -- an Entity Chain (the response from an `entityresolutionservice.v2.CreateEntityChainsFromTokens` call) +- an Entity Chain (the response from an `entityresolutionservice.v2.CreateEntityChainsFromTokens` call) — **limit: 1–10 entities per chain** - a Token (access token JWT) - the FQN of a Registered Resource Value (e.g. `https://example.com/reg_res/network/value/private`, or `https://reg_res/network/value/private` _DEPRECATED_) #### Resource The resource is a request proto object allowing multiple structures representing a resource to stand in as the resource in an Auth Service Decision request: -- a list of Attribute Values FQNs +- a list of Attribute Values FQNs — **limit: 1–20 FQNs per resource** - the FQN of a Registered Resource Value (e.g. `https://example.com/reg_res/s3_bucket/value/bucket1`, or `https://reg_res/s3_bucket/value/bucket1` _DEPRECATED_) ### GetEntitlements @@ -137,11 +137,13 @@ Endpoints: - one Entity Identifier - one Action (`name` is required) - one Resource + - optional `fulfillable_obligation_fqns` (0–50) 2. `GetDecisionMultiResource`: can this entity take this action on these resources? - one Entity Identifier - one Action (`name` is required) - - multiple Resources -3. `GetDecisionBulk`: more performant batch processing of multiple `GetDecisionMultiResource` requests + - multiple Resources — **limit: 1–1,000 per request** + - optional `fulfillable_obligation_fqns` (0–50) +3. `GetDecisionBulk`: more performant batch processing of multiple `GetDecisionMultiResource` requests — **limit: 1–200 requests per batch** - useful for multiple entities - useful for multiple actions From d36623eb34ef731bf4a879756f4c0c39786ee4d0 Mon Sep 17 00:00:00 2001 From: Mary Dickson Date: Wed, 20 May 2026 12:03:50 -0700 Subject: [PATCH 5/5] docs(authz): note fulfillable_obligation_fqns on GetDecisionBulk MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Each inner GetDecisionMultiResourceRequest carries its own fulfillable_obligation_fqns — make the endpoint breakdown consistent with the summary table. Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Mary Dickson --- docs/components/authorization.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/components/authorization.md b/docs/components/authorization.md index 800edb63..3311c5bc 100644 --- a/docs/components/authorization.md +++ b/docs/components/authorization.md @@ -146,6 +146,7 @@ Endpoints: 3. `GetDecisionBulk`: more performant batch processing of multiple `GetDecisionMultiResource` requests — **limit: 1–200 requests per batch** - useful for multiple entities - useful for multiple actions + - each inner request carries its own `fulfillable_obligation_fqns` (0–50) ### Request Validation Limits