apointoo.
Request access
HIPAA

How DynamoDB LeadingKeys Conditions Limit Tenant Access

cmsapointoo··9 min read

Short answer: A DynamoDB dynamodb:LeadingKeys condition can constrain requests whose leading key matches an allowed tenant value, but it is not a substitute for application authorization or operation coverage. As of 2026-08-15, AWS documents the condition key, condition expressions, and DynamoDB pricing. The useful claim is that LeadingKeys can reduce the permitted key space when identity, key design, and bypass tests are correct.

AWS service fit and regional boundary

LeadingKeys is a key-based condition, not a tenant-aware database policy. AWS documents it as an IAM policy condition key for fine-grained access. Before using it, document the exact partition-key format, operations, identities, regions, tables, indexes, and privileged paths. A condition that matches a convenient string is useful only if every permitted operation uses that string in the same way.

The region remains a separate boundary. Resolve tenant home region on the server and use an identity or account policy that cannot move protected data to a different region. Do not let a request choose a region based on a browser value. Review logs, backups, queues, keys, and exports as data paths too. A tenant condition in one table does not control an unreviewed copy.

Start with a narrow role. A role used by a tenant-facing service should have only the operations it needs. Separate migration, support, backup, and incident roles. If a policy grants broad read permissions and expects LeadingKeys to make every operation narrow, the policy is difficult to prove. The denied action is part of the design, not a later test.

Layer Question Evidence
Key Is tenant scope the leading key for every allowed item? Schema and generated-key tests
Identity How is the allowed tenant value issued? Membership and token review
Policy Which operations use the condition? IAM simulator and denied calls
Bypass What can Scan, export, admin, or restore do? Separate role tests and audit records

Pair this with DynamoDB tenant partitioning and PostgreSQL RLS versus application filters to compare the proof burden.

Request, data, key, and identity path

The application must derive the LeadingKeys value from authenticated membership. Do not accept a caller’s tenant string and place it directly into an IAM context or item key. The server should resolve principal, tenant, and home region, then issue or select the narrow identity path for that request. If membership is absent or ambiguous, deny before any data operation.

A conceptual item key such as TENANT#A followed by an item sort key makes the policy shape visible. It does not make tenant A safe. A helper must prevent a caller from selecting tenant B, and the IAM policy must prevent a role from using a different leading key. Test case, batch, transaction, index, and conditional write behavior. Record whether denial came from application membership, IAM, or the data operation.

Limit data in every operation. A role that reads a tenant’s generic appointment outcome does not need names, email addresses, phone numbers, service labels, treatment details, or hashed contact identifiers for an approved advertising conversion. Keep the outbound event generic and disabled until tenant-specific legal approval exists. LeadingKeys protects item access; it does not decide what can be disclosed.

caller identity
  -> server membership and home-region lookup
  -> narrow session or service identity
  -> LeadingKeys condition
  -> tenant-scoped DynamoDB operation
  -> minimum result

Use a separate identity for support and restore. Never solve an operational problem by adding a broad policy to the tenant-facing role. That shortcut erases the control boundary and makes the policy impossible to review as a tenant restriction.

Queue, audit, backup, and failure handling

The bypass inventory is the heart of a LeadingKeys review. AWS condition keys constrain only the request context and operation to which they apply. Test Query, GetItem, PutItem, UpdateItem, DeleteItem, BatchGetItem, BatchWriteItem, TransactGetItems, TransactWriteItems, indexes, Scan, export, backup, restore, and administrative APIs used by the workload.

Scan deserves a named stop condition. If the tenant role never needs enumeration, deny Scan explicitly and test that denial. If an operator or report job needs a scan, run it under a separate identity with a documented scope, rate, approval, and redaction path. Do not call a scan safe because the table’s normal items have tenant prefixes.

Use two synthetic tenants and exercise wrong-key attempts. Include a request that changes tenant input, an expired token, a role with missing condition context, a mixed batch, an index query, and a retry after a conditional failure. The expected response should be a denial or a controlled empty result. Capture only the operation, principal, server tenant, decision, and timestamp in audit evidence.

Backups and exports bypass request-time conditions unless their own roles and workflows enforce scope. Restore into an isolated test location and run tenant tests against the restored copy. Inspect dead-letter records and support exports for unnecessary data. The condition is one layer in a chain, not a promise that every copy inherits the same authorization.

Cost and proof gate

LeadingKeys can reduce accidental broad access without changing the DynamoDB billing model. The AWS pricing page should be checked for request, storage, index, backup, and traffic assumptions. A policy design that adds a session or token-vending step may add operational work even if request charges remain similar. Label every cost as an estimate and identify the region and retrieval date.

Price the test suite and policy review. The important cost is often a missed bypass discovered after migration, not one additional request. The gate should include policy simulation, application negative tests, audit review, restore, export, and a role inventory. If a query cannot be expressed with a safe key or policy, stop and redesign rather than widening the role silently.

  • Define leading-key shape and tenant source.
  • Issue tenant scope from server-side membership only.
  • Keep tenant, support, migration, and restore identities separate.
  • Explicitly deny Scan and unused broad operations.
  • Test every index, batch, transaction, export, backup, and restore path.

Runnable proof tests

A passing policy review needs a failing request. Run this matrix with synthetic records and save the operation, role, context, expected result, observed result, and date.

  1. Allow tenant A to read and write its own records.
  2. Attempt tenant B’s leading key as tenant A and confirm denial.
  3. Remove the condition context and confirm fail-closed behavior.
  4. Attempt Scan, index Query, mixed BatchGet, and transaction access.
  5. Run export, backup, and restore with separate operational identities.
  6. Inspect logs and queues for full item leakage.
  7. Repeat after changing item schema, indexes, roles, or deployment region.

Keep the result honest. LeadingKeys may be a strong compensating control, but it is not database-enforced row security. A review record should say which paths remain application-enforced and which require a separate operator approval.

A useful policy review reads the IAM condition beside the item schema and the application code. Verify that every permitted item has the expected leading key, that the condition uses the right value set, and that batch or transaction operations cannot mix scopes accidentally. Then test a missing condition context. If the result is broad access rather than denial, the policy has a fail-open edge that must be fixed or explicitly contained.

Keep operators honest about what the condition proves. LeadingKeys can narrow key-based operations, but it does not inspect a person’s membership, understand a business workflow, or decide whether an outbound event is permitted. Application checks, approval state, audit, backup, and support controls remain necessary. The DynamoDB residency article is a useful companion when regional access is part of the policy.

Re-run the matrix after every change to key format, index, role, session policy, table, account, region, or SDK version. Keep a small synthetic test that attempts tenant substitution, Scan, mixed batch, export, restore, and support access. A policy can look unchanged while a new caller takes a different operation path.

Use a policy simulator or equivalent review for every operation the application can issue. Confirm that the condition is present for point reads, writes, updates, deletes, batches, transactions, and index queries. Then test the same operations through a missing or malformed condition context. A policy that allows an operation when the scope is absent should be treated as a failed gate.

The application still owns membership. The service should resolve principal, tenant, role, and home region before it creates a request context. A client can ask for tenant B, but it cannot issue a tenant B authorization. Keep the source membership record and policy evidence together so a role change can be traced to the resulting allowed scope.

Review support, migration, backup, restore, and export identities separately. They may need broader operational access, but they should not inherit tenant-facing permissions without a reason. Use time-limited approvals, explicit scope, and audit. Test an operator with no membership and a recovery operator with an approved scope.

Run these tests after every key schema, table, index, role, account, region, or SDK change. A new index can change the leading-key behavior. A new batch path can accept mixed tenants. A new report can call Scan. Keep the negative test small and mandatory.

Frequently asked questions

What does LeadingKeys actually limit?

It lets an IAM policy condition compare a request’s leading key values with an allowed pattern. Its effect depends on item-key design, operation, identity context, and policy coverage.

Is LeadingKeys enough for tenant isolation?

No. Membership, key construction, operation restrictions, Scan denial, export and restore controls, support roles, logging, and negative tests remain necessary. It is one layer, not a complete database policy.

Why test Scan separately?

Scan enumerates a table rather than using a tenant-keyed query. If a role can scan, a point-read policy may not prevent broad discovery. Deny it when unused and isolate it when operationally required.

No. Provider documentation and a BAA define platform and contract context. The customer still needs a data map, risk analysis, application controls, and counsel review.

References

Related articles