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)
REDACT_REVISION (stored procedure)	qldb:PartiQLRedact	arn:aws:qldb:region:account-id:ledger/ledger-name/table/table-id
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

Using the console

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.

Tagging tables on creation is currently supported for ledgers in the STANDARD permissions mode only.

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.

Using the console

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 assign the permissions to your users, groups, or roles.

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

Topics

• Prerequisites
• Creating a read-only policy
• Creating a full access policy
• Creating a read-only policy for a specific table
• Assigning permissions

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 administrative 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 column on the left, choose Policies.

   If this is your first time choosing Policies, the Welcome to Managed Policies page appears. Choose Get Started.

3. At the top of the page, 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.

   Note

   You can switch between the Visual editor and JSON tabs any time. However, if you make changes or choose Review policy in the Visual editor tab, IAM might restructure your policy to optimize it for the visual editor. For more information, see Policy restructuring in the IAM User Guide.

7. On the Review policy page, enter a Name and an optional Description 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"
         ]
       }
     ]
   }

Assigning permissions

After creating a QLDB permissions policy, you then assign the permissions as follows.

To provide access, add permissions to your users, groups, or roles:

• Users and groups in AWS IAM Identity Center:

  Create a permission set. Follow the instructions in Create a permission set in the AWS IAM Identity Center User Guide.

• Users managed in IAM through an identity provider:

  Create a role for identity federation. Follow the instructions in Creating a role for a third-party identity provider (federation) in the IAM User Guide.

• IAM users:

  • Create a role that your user can assume. Follow the instructions in Creating a role for an IAM user in the IAM User Guide.

  • (Not recommended) Attach a policy directly to a user or add a user to a user group. Follow the instructions in Adding permissions to a user (console) in the IAM User Guide.