Getting started with the standard permissions mode in Amazon QLDB - Amazon Quantum Ledger Database (Amazon QLDB)

Getting started with the standard permissions mode in Amazon QLDB

Use this section to get started with the standard permissions mode in Amazon QLDB. This section provides a reference table to help you when writing an identity-based policy in AWS Identity and Access Management (IAM) for PartiQL actions and table resources in QLDB. It also includes a step-by-step tutorial for creating permissions policies in IAM, and instructions for finding a table ARN and creating table tags in QLDB.

The STANDARD permissions mode

QLDB now supports a STANDARD permissions mode for ledger resources. The standard permissions mode enables access control with finer granularity for ledgers, tables, and PartiQL commands. By default, this mode denies all requests to run any PartiQL commands on any tables in a ledger.

Note

Previously, the only available permissions mode for a ledger was ALLOW_ALL. The ALLOW_ALL mode enables access control with API-level granularity for ledgers, and continues to be supported—but is not recommended—for QLDB ledgers. This mode allows users who have the SendCommand API permission to run all PartiQL commands on any tables in the ledger that is specified by the permissions policy (hence, "allow all" PartiQL commands).

You can change the permissions mode of existing ledgers from ALLOW_ALL to STANDARD. For information, see Migrating to the standard permissions mode.

To allow commands in the standard mode, you must create a permissions policy in IAM for specific table resources and PartiQL actions. This is in addition to the SendCommand API permission for the ledger. To facilitate policies in this mode, QLDB introduced a set of IAM actions for PartiQL commands, and Amazon Resource Names (ARNs) for QLDB tables. For more information about the QLDB data object model, see Core concepts and terminology in Amazon QLDB.

PartiQL permissions reference

The following table lists each QLDB PartiQL command, the corresponding IAM actions that you must grant permissions for to perform the command, and the AWS resources that you can grant the permissions for. You specify the actions in the policy's Action field, and you specify the resource value in the policy's Resource field.

Important
  • IAM policies that grant permissions to these PartiQL commands only apply to your ledger if the STANDARD permissions mode is assigned to the ledger. Such policies are not applicable to ledgers in the ALLOW_ALL permissions mode.

    To learn how to specify the permissions mode when you're creating or updating a ledger, see Basic operations for Amazon QLDB ledgers, or Step 1: Create a new ledger in Getting started with the console.

  • To run any PartiQL commands on a ledger, you must also grant permission to the SendCommand API action for the ledger resource. This is in addition to the PartiQL actions and table resources that are listed in the following table. For more information, see Running data transactions.

Amazon QLDB PartiQL commands and required permissions
Command Required permissions (IAM actions) Resources Dependent actions
CREATE TABLE qldb:PartiQLCreateTable

arn:aws:qldb:region:account-id:ledger/ledger-name/table/*

qldb:TagResource (for tagging on creation)
DROP TABLE qldb:PartiQLDropTable

arn:aws:qldb:region:account-id:ledger/ledger-name/table/table-id

UNDROP TABLE qldb:PartiQLUndropTable

arn:aws:qldb:region:account-id:ledger/ledger-name/table/table-id

CREATE INDEX qldb:PartiQLCreateIndex

arn:aws:qldb:region:account-id:ledger/ledger-name/table/table-id

DROP INDEX qldb:PartiQLDropIndex

arn:aws:qldb:region:account-id:ledger/ledger-name/table/table-id

DELETE qldb:PartiQLDelete

arn:aws:qldb:region:account-id:ledger/ledger-name/table/table-id

qldb:PartiQLSelect
FROM-REMOVE (for entire documents)
INSERT qldb:PartiQLInsert

arn:aws:qldb:region:account-id:ledger/ledger-name/table/table-id

UPDATE qldb:PartiQLUpdate

arn:aws:qldb:region:account-id:ledger/ledger-name/table/table-id

qldb:PartiQLSelect
FROM (INSERT, REMOVE, or SET)

SELECT FROM table_name

qldb:PartiQLSelect

arn:aws:qldb:region:account-id:ledger/ledger-name/table/table-id

SELECT FROM information_schema.user_tables

qldb:PartiQLSelect

arn:aws:qldb:region:account-id:ledger/ledger-name/information_schema/user_tables

SELECT FROM history(table_name)

qldb:PartiQLHistoryFunction

arn:aws:qldb:region:account-id:ledger/ledger-name/table/table-id

For examples of IAM policy documents that grant permissions to these PartiQL commands, proceed to Quick start tutorial: Creating permissions policies or see Identity-based policy examples for Amazon QLDB.

Finding a table ID and ARN

You can find a table ID by using the AWS Management Console or by querying the table information_schema.user_tables. To view table details on the console, or to query this system catalog table, you must have SELECT permission on the system catalog resource. For example, to find the table ID of the Vehicle table, you can run the following statement.

SELECT * FROM information_schema.user_tables WHERE name = 'Vehicle'

This query returns results in a format similar to the following example.

{ tableId: "Au1EiThbt8s0z9wM26REZN", name: "Vehicle", indexes: [ { indexId: "Djg2nt0yIs2GY0T29Kud1z", expr: "[VIN]", status: "ONLINE" }, { indexId: "4tPW3fUhaVhDinRgKRLhGU", expr: "[LicensePlateNumber]", status: "BUILDING" } ], status: "ACTIVE" }

To grant permissions to run PartiQL statements on a table, you specify a table resource in the following ARN format.

arn:aws:qldb:${region}:${account-id}:ledger/${ledger-name}/table/${table-id}

The following is an example of a table ARN for table ID Au1EiThbt8s0z9wM26REZN.

arn:aws:qldb:us-east-1:123456789012:ledger/myExampleLedger/table/Au1EiThbt8s0z9wM26REZN

You can also use the QLDB console to find a table ARN.

To find the ARN of a table (console)

  1. Sign in to the AWS Management Console, and open the Amazon QLDB console at https://console.aws.amazon.com/qldb.

  2. In the navigation pane, choose Ledgers.

  3. In the list of Ledgers, choose the ledger name whose table ARN you want to find.

  4. On the ledger details page, under the Tables tab, locate the table name whose ARN you want to find. To copy the ARN, choose the copy icon ( ) next to it.

Tagging tables

You can tag your table resources. To manage tags for existing tables, use the AWS Management Console or the API operations TagResource, UntagResource, and ListTagsForResource. For more information, see Tagging Amazon QLDB resources.

Note

Table resources don't inherit the tags of their root ledger resource.

You can also define table tags while you're creating the table by using the QLDB console or by specifying them in a CREATE TABLE PartiQL statement. The following example creates a table named Vehicle with the tag environment=production.

CREATE TABLE Vehicle WITH (aws_tags = `{'environment': 'production'}`)

Tagging tables on creation requires access to both the qldb:PartiQLCreateTable and qldb:TagResource actions.

By tagging resources while they're being created, you can eliminate the need to run custom tagging scripts after resource creation. After a table is tagged, you can control access to the table based on those tags. For example, you can grant full access only to tables that have a specific tag. For a JSON policy example, see Full access to all actions based on table tags.

You can also use the QLDB console to define table tags while you're creating the table.

To tag a table on creation (console)

  1. Sign in to the AWS Management Console, and open the Amazon QLDB console at https://console.aws.amazon.com/qldb.

  2. In the navigation pane, choose Ledgers.

  3. In the list of Ledgers, choose the ledger name that you want to create the table in.

  4. On the ledger details page, under the Tables tab, choose Create table.

  5. On the Create table page, do the following:

    • Table name – Enter a table name.

    • Tags – Add metadata to the table by attaching tags as key-value pairs. You can add tags to your table to help organize and identify them.

      Choose Add tag, and then enter any key-value pairs as appropriate.

  6. When the settings are as you want them, choose Create table.

Quick start tutorial: Creating permissions policies

This tutorial guides you through steps to create permissions policies in IAM for an Amazon QLDB ledger in the STANDARD permissions mode. You can then attach the new policies directly to an IAM user. You can also change or remove policies for a user.

For more examples of IAM policy documents that grant permissions to PartiQL commands and table resources, see Identity-based policy examples for Amazon QLDB.

Prerequisites

Before you get started, make sure that you do the following:

  1. Follow the AWS setup instructions in Accessing Amazon QLDB, if you haven't already done so. These steps include signing up for AWS and creating an IAM user.

  2. Create a new ledger and choose the STANDARD permissions mode for the ledger. To learn how, see Step 1: Create a new ledger in Getting started with the console, or Basic operations for Amazon QLDB ledgers.

Creating a read-only policy

To use the JSON policy editor to create a read-only policy for all tables in a ledger in the standard permissions mode, do the following:

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane on the left, choose Policies.

  3. Choose Create policy.

  4. Choose the JSON tab.

  5. Copy and paste the following JSON policy document. This example policy grants read-only access to all tables in a ledger.

    To use this policy, replace us-east-1, 123456789012, and myExampleLedger in the example with your own information.

    { "Version": "2012-10-17", "Statement": [ { "Sid": "QLDBSendCommandPermission", "Effect": "Allow", "Action": "qldb:SendCommand", "Resource": "arn:aws:qldb:us-east-1:123456789012:ledger/myExampleLedger" }, { "Sid": "QLDBPartiQLReadOnlyPermissions", "Effect": "Allow", "Action": [ "qldb:PartiQLSelect", "qldb:PartiQLHistoryFunction" ], "Resource": [ "arn:aws:qldb:us-east-1:123456789012:ledger/myExampleLedger/table/*", "arn:aws:qldb:us-east-1:123456789012:ledger/myExampleLedger/information_schema/user_tables" ] } ] }
  6. Choose Review policy.

  7. On the Review policy page, type a Name and a Description (optional) for the policy that you are creating. Review the policy Summary to see the permissions that are granted by your policy. Then choose Create policy to save your work.

Creating a full access policy

To create a full access policy for all tables in a QLDB ledger in the standard permissions mode, do the following:

  • Repeat the previous steps using the following policy document. This example policy grants access to all PartiQL commands for all tables in a ledger, by using wildcards (*) to cover all PartiQL actions and all resources under a ledger.

    Warning

    This is an example of using a wildcard character (*) to allow all PartiQL actions, including administrative and read/write operations on all tables in a QLDB ledger. Instead, it's a best practice to explicitly specify each action to be granted, and only what that user, role, or group needs.

    To use this policy, replace us-east-1, 123456789012, and myExampleLedger in the example with your own information.

    { "Version": "2012-10-17", "Statement": [ { "Sid": "QLDBSendCommandPermission", "Effect": "Allow", "Action": "qldb:SendCommand", "Resource": "arn:aws:qldb:us-east-1:123456789012:ledger/myExampleLedger" }, { "Sid": "QLDBPartiQLFullPermissions", "Effect": "Allow", "Action": [ "qldb:PartiQL*" ], "Resource": [ "arn:aws:qldb:us-east-1:123456789012:ledger/myExampleLedger/table/*", "arn:aws:qldb:us-east-1:123456789012:ledger/myExampleLedger/information_schema/user_tables" ] } ] }

Creating a read-only policy for a specific table

To create a read-only access policy for a specific table in a QLDB ledger in the standard permissions mode, do the following:

  1. Find the ARN for the table by using the AWS Management Console or by querying the system catalog table information_schema.user_tables. For instructions, see Finding a table ID and ARN.

  2. Use the table ARN to create a policy that allows read-only access to the table. To do this, repeat the previous steps using the following policy document.

    This example policy grants read-only access to the specified table only. In this example, the table ID is Au1EiThbt8s0z9wM26REZN. To use this policy, replace us-east-1, 123456789012, myExampleLedger, and Au1EiThbt8s0z9wM26REZN in the example with your own information.

    { "Version": "2012-10-17", "Statement": [ { "Sid": "QLDBSendCommandPermission", "Effect": "Allow", "Action": "qldb:SendCommand", "Resource": "arn:aws:qldb:us-east-1:123456789012:ledger/myExampleLedger" }, { "Sid": "QLDBPartiQLReadOnlyPermissions", "Effect": "Allow", "Action": [ "qldb:PartiQLSelect", "qldb:PartiQLHistoryFunction" ], "Resource": [ "arn:aws:qldb:us-east-1:123456789012:ledger/myExampleLedger/table/Au1EiThbt8s0z9wM26REZN" ] } ] }

Adding permissions by attaching policies directly to the user

Attaching policies affects the user immediately.

To add permissions to a user by directly attaching managed policies

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. Choose Users in the navigation pane, choose the name of the user whose permissions you want to modify, and then choose the Permissions tab.

  3. Choose Add permissions, and then choose Attach existing policies directly to user.

  4. Select one or more check boxes for the managed policies that you want to attach to the user. For a list of AWS managed policies for QLDB, see AWS managed policies for Amazon QLDB.

    You can also create a new managed policy by choosing Create policy. If you do, return to this browser tab or window when the new policy is done. Choose Refresh; and then select the check box for the new policy to attach it to your user. For more information, see Creating IAM policies in the IAM User Guide.

  5. Choose Next: Review to see the list of policies that are to be attached to the user. Then choose Add permissions.

Editing a permissions policy attached to a user

Changing permissions affects the user immediately.

To edit a user's attached managed policies

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Users.

  3. Choose the name of the user whose permissions policy you want to change.

  4. Choose the Permissions tab. If necessary, open the Permissions policies section.

  5. Choose the name of the policy that you want to edit to view details about the policy. Choose the Used as tab to view other entities that might be affected if you edit the policy.

  6. Choose the Permissions tab and review the permissions granted by the policy. Then choose Edit policy.

  7. Edit the policy using the Visual editor tab or the JSON tab and resolve any policy validation recommendations. For more information, see Editing IAM policies in the IAM User Guide.

  8. Choose Review policy, review the policy summary, and then choose Save changes.

Removing a permissions policy from a user

Removing a policy affects the user immediately.

To revoke permissions for IAM users

  1. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

  2. In the navigation pane, choose Users.

  3. Choose the name of the user whose permissions boundary you want to remove.

  4. Choose the Permissions tab.

  5. If you want to revoke permissions by removing an existing policy, view the Policy type to understand how the user is getting that policy before choosing X to remove the policy:

    • If the policy applies because of group membership, then choosing X removes the user from the group. Remember that you might have multiple policies attached to a single group. If you remove a user from a group, the user loses access to all policies that it received through that group membership.

    • If the policy is a managed policy attached directly to the user, then choosing X detaches the policy from the user. This does not affect the policy itself or any other entity that the policy might be attached to.

    • If the policy is an inline embedded policy, then choosing X removes the policy from IAM. Inline policies that are attached directly to a user exist only on that user.