.. _dynamodb-infrastructure-setup: DynamoDB Setup for Scoped Permissions ===================================== *Draft: the final text is part of the 0.7.0 documentation pass.* ``DynamoDbAssignmentStore`` (``pip install 'auth-middleware[dynamodb]'``, built on `PynamoDB `_) keeps one item per principal and scope in a single table. Creating the table is a deployment concern: the runtime role never needs table-level permissions. Table definition ---------------- .. code-block:: python from auth_middleware.authz.stores import DynamoDbAssignmentStore DynamoDbAssignmentStore.table_definition("authz-assignments") # boto3 create_table kwargs ====================== ======= ====================================== Attribute Type Role ====================== ======= ====================================== ``pk`` S HASH, ``SCOPE##`` ``sk`` S RANGE, ``PRINCIPAL#`` ``gsi1pk`` S GSI ``by-principal`` HASH ``gsi1sk`` S GSI ``by-principal`` RANGE ====================== ======= ====================================== Billing mode ``PAY_PER_REQUEST`` is recommended; the GSI projects ``ALL`` attributes. A Terraform equivalent: .. code-block:: hcl resource "aws_dynamodb_table" "authz" { name = "authz-assignments" billing_mode = "PAY_PER_REQUEST" hash_key = "pk" range_key = "sk" attribute { name = "pk" type = "S" } attribute { name = "sk" type = "S" } attribute { name = "gsi1pk" type = "S" } attribute { name = "gsi1sk" type = "S" } global_secondary_index { name = "by-principal" hash_key = "gsi1pk" range_key = "gsi1sk" projection_type = "ALL" } } IAM policy for the runtime role (least privilege) ------------------------------------------------- .. code-block:: json { "Version": "2012-10-17", "Statement": [{ "Effect": "Allow", "Action": ["dynamodb:GetItem", "dynamodb:PutItem", "dynamodb:UpdateItem", "dynamodb:Query"], "Resource": [ "arn:aws:dynamodb:REGION:ACCOUNT:table/authz-assignments", "arn:aws:dynamodb:REGION:ACCOUNT:table/authz-assignments/index/by-principal" ] }] } No ``Scan``, no ``DeleteItem`` (assignments are revoked, never deleted) and no table-level actions. Consistency caveats ------------------- * ``get_assignment`` (the guard path) always sends ``ConsistentRead=True``: an eventually consistent read could admit a principal that was just revoked. Turning it off (``consistent_read=False``) is an explicit acceptance of that risk. * ``list_assignments`` ("my scopes") uses the GSI, which only supports eventually consistent reads: it may lag by a moment. The guard never calls it. * Every write is conditional on ``revision``; losers get ``RevisionConflictError``. * Throttling that survives botocore's retries raises ``StoreUnavailableError`` so the error policy can answer 503. Configure botocore retries with ``max_retry_attempts``. * Ids may contain any character (the scope id is the last component of every composite key, so ``#`` is unambiguous); assignment attributes are limited to 4 KB of JSON. * Each call runs in a worker thread. By default that is the event loop's default executor, shared with the rest of the application: a slow DynamoDB can occupy it. Pass ``max_workers=N`` to give the store its own bounded pool, and keep ``read_timeout_seconds`` and ``max_retry_attempts`` modest. Tests ----- ``tests/authz/integration/test_dynamodb_store.py`` runs against an in-process ``moto`` server by default. Set ``AUTHZ_TEST_DYNAMODB_ENDPOINT=http://localhost:8000`` to run the same tests against ``amazon/dynamodb-local`` (the CI ``integration-dynamodb`` job does). ``make test-floci`` runs it against Floci too.