Skip to main content
Version: v3.0

Connect to DynamoDB

Connect to a DynamoDB database through Cyral

These instructions assume you have tracked your DynamoDB database in Cyral and associated it with a Cyral sidecar.

Set up your connection details and credentials

To connect to your DynamoDB database through the sidecar, follow these steps:

  1. Get the sidecar endpoint address and port number associated with your DynamoDB data repository:

    • As a Cyral admin, open the Cyral control plane UI.
    • Click Sidecars and click the name of your sidecar.
    • In the Data Repositories list, find your DynamoDB repository.
    • Copy its hostname and port number from the Sidecar Endpoint column.
  2. Store the endpoint address as the proxy address:

    • In a shell session, set the HTTP_PROXY and HTTPS_PROXY environment variables to the hostname and port of your sidecar. For example, for a sidecar reachable at, and a DynamoDB repository bound to it at port 453, we might assign:

      export HTTP_PROXY=
      export HTTPS_PROXY=
    • If your sidecar runs as an AWS EC2 instance, you must also set the NO_PROXY variable to the IP address of the AWS EC2 instance metadata service, This address does not vary.

      export NO_PROXY=

    Detailed information and settings for configuring the proxy endpoint for different systems is available in the AWS documentation section, Using an HTTP proxy

  3. In your AWS credentials file, add a profile containing a valid (aws_access_key_id) and secret key (aws_secret_access_key) associated with the IAM username that you'll use to connect to DynamoDB. This file is usually found at ~/.aws/credentials.

    In the example below, we create an example profile called mysidecar. You can also use an existing profile that has appropriate credentials.

    [profile mysidecar]

    By default, Cyral treats the aws_access_key_id as the username for logging and policy enforcement.

  4. Add Cyral's certificate authority bundle to the CLI tool. The sidecar intercepts TLS communications between your data users and the DynamoDB instance. To keep the connection secure, the sidecar signs the messages using its own certificate. CLI clients and tools must be able to validate the sidecar's certificate, and this step provides the CA certificate required for that.

    • Download the certificate bundle from the Cyral control plane. The cyral_ca_bundle.pem file is used by the AWS CLI tool to validate the certificate sent by the sidecar. Use the following command to download it, replacing $CYRAL_CONTROL_PLANE_DOMAIN with your control plane domain:

      curl https://$CYRAL_CONTROL_PLANE_DOMAIN/v1/templates/ca_bundle -o cyral_ca_bundle.pem
    • Next, provide the CA bundle to the AWS CLI by setting an environment variable or using a profile configuration. Choose one of these approaches:

      • Set the AWS_CA_BUNDLE environment variable:

        export AWS_CA_BUNDLE=/path/to/cyral_ca_bundle.pem
      • Set it in the profile of your AWS credentials file. Use the profile you created or modified earlier. Add a line setting the ca_bundle parameter:

        [profile mysidecar]
        ca_bundle = /path/to/cyral_ca_bundle.pem
      • Note that if you're using an AWS SDK, e.g. Ruby or Python SDKs, you will be provided with customized configurations for both proxy and certificate bundle inside your client application. See the SDK sections below for some examples.

Connect to DynamoDB

  1. Make sure you have set up your connection details and credentials as shown above.

  2. Connect to DynamoDB using your preferred client. User authentication relies on the credentials you collected from the Cyral control plane UI. If present, Cyral policies are enforced. All traffic is sent through the Cyral sidecar, which logs all data activity to the log location configured in your Cyral installation.

Access DynamoDB using the profile you created earlier. Here's an example using the mysidecar profile:

aws dynamodb --region us-east-1 --profile mysidecar list-tables

Note on other AWS SDKs

AWS offers SDKs for a wide range of programming languages, while here we only show configuration examples for a subset of them. If examples for your programming language are missing from this page, we encourage you to either look for examples in AWS official documentation at, or contact Cyral support for help.

Connect to DynamoDB Streams

  1. Make sure you have set up your connection details and credentials as shown above.

  2. Access DynamoDB Streams using the profile you created earlier. Here's an example using the mysidecar profile:

    > aws dynamodbstreams list-streams --table-name MySampleTable --profile mysidecar

This uses the credentials associated with the profile mysidecar, sending all traffic through the sidecar. Logs are available at the log location configured in your Cyral installation.

Applications leveraging the AWS SDK can also be modified to directly talk to the sidecar by following similar examples as previously presented for DynamoDB.


Cyral policy-based features (for example, access blocking, masking, and alerting) are not available for DynamoDB Streams.