AWS Connect

AWS Connect discovers RDS databases in your account and provisions standard database roles directly through Hoop. Use IAM credentials or the Hoop Gateway instance role to grant database access to users.

Be aware that our current implementation resets the master password for RDS instances and stores the new credentials in the Hoop database.Upcoming releases will add AWS Secrets Manager and IAM database authentication support.

Requirements

Access to AWS account with privileges to setup roles and/or IAM credentials
Admin access to the Hoop Gateway instance

Configuration

AWS Connect needs permissions to list resources and modify RDS instances.

Main Account Setup

Create IAM Policy

The policy HoopAWSConnect must be created in your AWS account. It will grant the necessary permissions to the IAM user or role that will be used for the integration.

Go to IAM > Policy > Create Policy

Switch the Policy Editor to JSON and paste the policy below

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": [
                    "organizations:ListAccounts",
                    "rds:DescribeDBInstances",
                    "rds:ModifyDBInstance",
                    "rds:ModifyDBCluster",
                    "ec2:DescribeSecurityGroups",
                    "ec2:AuthorizeSecurityGroupIngress",
                    "ec2:CreateSecurityGroup",
                    "ec2:CreateTags",
                    "sts:AssumeRole"
                ],
                "Resource": "*"
            }
        ]
    }

Click in Next and create it naming the policy as HoopAWSConnect

Create IAM User

Create the IAM user associated with the role created in the previous step to obtain the access key credentials.

Go to IAM > Users > Add user
Enter a user name, e.g., hoop-aws-connect
Select Attach policies directly
Search for the policy HoopAWSConnect created in first step
After creating the user, select the user and go to the Security credentials tab
Click on Create access key
Select the option Third-party service
Add the description as Hoop AWS Connect
Click on Create access key
Copy the Access key ID and Secret access key to use in the next step

If you want to use the instance role instead of IAM credentials, skip this step. You will find instructions below on how to configure the instance role.

This completes the main account setup.

Multi Account Setup

For multi-account setup, configure your IAM user or instance role to access resources across different accounts.

Invite your AWS Account

Hoop lists AWS accounts from your Organization on the integration configuration page. Invite the account you want to provision roles for.

Invite AWS Account

Login to your main account
Go to AWS Organizations > AWS Accounts > Invite an Existent AWS Account
Enter the email address or the account id to invite this account

Accept the Invitation

Login to the invited account
Go to AWS Organizations > AWS Accounts > Invitations
Accept the invitation from your main account

Policy and Role Creation

Create a policy and role in each AWS account you want Hoop to manage. The policy grants permissions that Hoop assumes via the role.

Create IAM Policy

The policy HoopAWSConnect must be created in your AWS account.

Go to IAM > Policy > Create Policy

Switch the Policy Editor to JSON and paste the policy below

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": [
                    "rds:DescribeDBInstances",
                    "rds:ModifyDBInstance",
                    "rds:ModifyDBCluster",
                    "ec2:DescribeSecurityGroups",
                    "ec2:AuthorizeSecurityGroupIngress",
                    "ec2:CreateTags",
                    "ec2:CreateSecurityGroup"
                ],
                "Resource": "*"
            }
        ]
    }

Click in Next and create it naming the policy as HoopAWSConnect

Create IAM Role

This step will grant the necessary permissions to assume the role in your main accountCreate the role that will use the policy created in the previous step.

Go to IAM > Roles > Create Role
In Trusted entity type, select AWS Account
In the input below, select Another AWS Account
Add the account ID of your main account
Select the Policy HoopAWSConnect created in the previous step
Name the role as HoopOrganizationAccountAccessRole

It’s important to name the policy as HoopOrganizationAccountAccessRole because the name is hard-coded in the integration. In future releases, we may allow users to provide a custom role name.

Instance Role

To use the instance role of the Hoop Gateway, you need to configure the environment variable:

INTEGRATION_AWS_INSTANCE_ROLE_ALLOW=true

This allows the integration to use the instance role of the Hoop Gateway to access AWS resources. Make sure to create an IAM role in the account that you’re hosting the Hoop Gateway and associate with the policy HoopAWSConnect. See the step above to create the IAM role.

Web Interface

The web interface lists available AWS accounts and databases ready to provision.

Access Key Credentials

Instance Role

Agent Deployment

The agent connects to your infrastructure to provision and access databases. Deploy an agent in every private network where a database runs.

If you have connectivity with all databases from a single machine, you could deploy the agent in this network to gain access to all databases using a single agent.

Supported Engines

Postgres / Aurora
MySQL / Aurora
SQL Server

Security Group Management

The gateway creates a dedicated security group for each database to enable connectivity between the gateway and your agent. It has the following properties:

Resource Name: hoop-aws-connect-sg-<db-instance-identifier>
Tag: hoop.dev/gateway=<api-hostname>

Manage these security groups directly to customize connectivity settings.

Roles and Connection Management

The provisioner resets the master database credentials with a random password and stores them in Hoop. Subsequent provisioning requests reuse those stored credentials. The provisioner creates three static user roles for each database, depending on the engine:

hoop_ro
hoop_rw
hoop_ddl

Running the process multiple times may remove and recreate some database users. The provisioner creates the role if it doesn’t exist, or updates its password if it does. The final step creates three connections, one per role:

<connection-name-prefix>-ro
<connection-name-prefix>-rw
<connection-name-prefix>-ddl

Database role permissions are static:

ENGINE	READ ONLY	READ WRITE	DDL
Postgres	`SELECT`	`SELECT, INSERT, UPDATE, DELETE`	`SELECT, INSERT, UPDATE, DELETE, TRUNCATE, REFERENCES, TRIGGER`
MySQL	`SELECT`	`SELECT, INSERT, UPDATE, DELETE`	`SELECT, INSERT, UPDATE, DELETE, ALTER, CREATE, DROP`
SQL Server	`db_datareader`	`db_datareader, db_datawriter`	`db_datareader, db_datawriter, db_ddladmin`

Webhooks (Svix)

In the final step of the job, you can send webhooks to an external system. The webhook provider must be configured first; see Svix. The payload matches the GET /api/dbroles/:id endpoint.

{
    "event_type": "dbroles.job.finished",
    "event_payload": {}
}

Refer to the API Reference section in the documentation sidebar for more details about the structure of the event_payload attribute.

Runbook Hook

This feature is available in version 1.35.7+.

As an alternative to Webhook Providers, execute a Python script in the final step of the job. This integrates with any internal workflow using Hoop as a hook system. Requirements for running this hook:

The Runbook must be enabled with a git repository
The specific file path hoop-hooks/aws-connect-post-exec.runbook.py must exist in your git repository to trigger the hook
Note: Output content (stdout, stderr) is limited to 4096 bytes

Use the script below to print both the request and response objects.

hoop-hooks/aws-connect-post-exec.runbook.py

import os, sys, time, json

print('STARTING AWS CONNECT RUNBOOKS HOOK\n')

request = os.getenv('HOOP_AWS_CONNECT_REQUEST')
response = os.getenv('HOOP_AWS_CONNECT_RESPONSE')
if len(response) == 0 or len(request) == 0:
    print('empty request (HOOP_AWS_CONNECT_REQUEST) or response (HOOP_AWS_CONNECT_RESPONSE)')
    sys.exit(1)

req = json.loads(request)

print('REQUEST OBJECT')
print('--------------')

print('request sid: {}'.format(req['sid']))
print('request DB ARN: {}'.format(req['resource_id']))
print('request database tags: {}'.format(req['database_tags']))
print('request database hostname: {}'.format(req['hostname']))
print('request database port: {}'.format(req['port']))
print('request database master username: {}'.format(req['master_user']))
print('request database master password: {}'.format(req['master_password']))
print('request vault provider: {}'.format(req['vault_provider']))

resp = json.loads(response)

print('\nRESPONSE OBJECT')
print('--------------')
print('response status: {}'.format(resp['status']))
print('response message: {}'.format(resp['message']))

print('\nROLES PROVISIONING RESULT')
print('--------------')
result = resp['result'] or []
for r in result:
    cred = r['db_credentials'] or {}
    print('  status ->', r['status'])
    print('  message ->', r['message'])
    print('  completed_at ->', r['completed_at'])
    print('  role_suffix_name ->', r['role_suffix_name'])
    print('  credentials role user ->', cred['user'])
    print('  credentials role password ->', cred['password'])
    print('  credentials secrets manager provider ->', cred['secrets_manager_provider'])
    print('  ---')

Runbook Inputs

The request and response objects are available as environment variables in JSON

Request Object

Environment Variable HOOP_AWS_CONNECT_REQUEST

{
    "org_id": "bb5960f1-37ec-438e-93e0-2547ee4cf6cb",
    "sid": "cd2fe668-2f83-4798-a0ed-41688e1891e9",
    "resource_id": "arn:aws:rds:us-west-2:200070128927:db:pgtest1",
    "hostname": "pgtest1.sakjksqiwuqijs.us-west-2.rds.amazonaws.com",
    "port": "5432",
    "master_user": "<master-user>",
    "master_password": "<master-pwd>",
    "database_type": "postgres",
    "database_tags": [
        {
            "owner": "someone@mycorp.com"
        },
        {
            "cto_email": "cto@mycorp.com"
        },
        {
            "bu": "banking"
        }
    ],
    "vault_provider": {"secret_id": "<id>"},
}

Response Object

Environment Variable HOOP_AWS_CONNECT_REQUEST

{
    "sid": "cd2fe668-2f83-4798-a0ed-41688e1891e9",
    "status": "failed|completed",
    "message": "One or more user roles failed to be provisioned",
    "result": [
        {
            "db_credentials": {
                "host": "pgtest1.sakjksqiwuqijs.us-west-2.rds.amazonaws.com",
                "port": "5432",
                "user": "hoop_ro",
                "password": "PlwL0YAlv6S*N5AnQZPLwCYru",
                "default_database": "postgres",
                "options": {},
                "secrets_manager_provider": "database",
                "secret_id": "",
                "secret_keys": []
            },
            "role_suffix_name": "ro",
            "status": "completed",
            "message": "",
            "completed_at": "2025-04-28T15:26:31.019387233Z"
        },
        {
            "db_credentials": {
                "host": "pgtest1.sakjksqiwuqijs.us-west-2.rds.amazonaws.com",
                "port": "5432",
                "user": "hoop_rw",
                "password": "rO*gDmye3s20P80CjTdMrRsLZ",
                "default_database": "postgres",
                "options": {},
                "secrets_manager_provider": "database",
                "secret_id": "",
                "secret_keys": []
            },
            "role_suffix_name": "rw",
            "status": "completed",
            "message": "",
            "completed_at": "2025-04-28T15:26:35.148832227Z"
        },
        {
            "db_credentials": null,
            "role_suffix_name": "",
            "status": "failed",
            "message": "dial tcp: lookup pgtest1.sakjksqiwuqijs.us-west-2.rds.amazonaws.com on 192.168.5.2:53: no such host",
            "completed_at": "2025-04-28T15:26:39.201632951Z"
        }
    ]
}

Example of how to parse it in python as a dictionary:

import json, os

requestJson = os.getenv('HOOP_AWS_CONNECT_REQUEST')
responseJson = os.getenv('HOOP_AWS_CONNECT_RESPONSE')

request = json.loads(requestJson)
response = json.loads(responseJson)

print('request db arn: ', request['resource_id'])
print('response status: ', response['status'])

Be careful when printing any sensitive information. The content will be available for inspection in the API for adminstrator users.

Vault Secrets Manager

This integration delegates secret management to HashiCorp Vault. When enabled, all provisioned role credentials are stored in Vault. For deployments with connection provisioning, the integration automatically adds the secrets provider reference and secret ID.

For this integration to function properly, the agent must be configured with the correct Vault credentials. For detailed configuration instructions, please refer to the Vault secrets manager documentation.

Introduction

Features

Clients

Quickstart

Setup & Administration

Concepts

Integrations

Requirements

Configuration

Main Account Setup

Multi Account Setup

Invite your AWS Account

Policy and Role Creation

Instance Role

Web Interface

Access Key Credentials

Instance Role

Agent Deployment

Supported Engines

Security Group Management

Roles and Connection Management

Webhooks (Svix)

Runbook Hook

Runbook Inputs

Vault Secrets Manager

Introduction

Features

Clients

Quickstart

Setup & Administration

Concepts

Integrations

​Requirements

​Configuration

​Main Account Setup

​Multi Account Setup

​Invite your AWS Account

​Policy and Role Creation

​Instance Role

​Web Interface

​Access Key Credentials

​Instance Role

​Agent Deployment

​Supported Engines

​Security Group Management

​Roles and Connection Management

​Webhooks (Svix)

​Runbook Hook

​Runbook Inputs

​Vault Secrets Manager

Requirements

Configuration

Main Account Setup

Multi Account Setup

Invite your AWS Account

Policy and Role Creation

Instance Role

Web Interface

Access Key Credentials

Instance Role

Agent Deployment

Supported Engines

Security Group Management

Roles and Connection Management

Webhooks (Svix)

Runbook Hook

Runbook Inputs

Vault Secrets Manager