mirror of
https://github.com/gravitational/teleport.git
synced 2026-09-21 05:55:42 +08:00
Paul Gottschling
625f63087a
Replace the `labels` frontmatter field with one called `tags`. Docusaurus supports tag-based navigation out of the box with the `tags` field. The original plan was to implement a separate system that allows for filtering by multiple tags - which Docusaurus does not - but it makes sense to enable the default approach as a first iteration.
256 lines
7.3 KiB
Plaintext
256 lines
7.3 KiB
Plaintext
---
|
|
title: Database Access Getting Started Guide
|
|
description: Getting started with Teleport database access and AWS Aurora PostgreSQL.
|
|
tags:
|
|
- get-started
|
|
- zero-trust
|
|
---
|
|
|
|
(!docs/pages/includes/database-access/db-introduction.mdx dbType="PostgreSQL Amazon Aurora" dbConfigure="with IAM authentication"!)
|
|
|
|
## How it works
|
|
|
|
<Tabs>
|
|
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
|
|
|
|
</TabItem>
|
|
<TabItem scope={["cloud"]} label="Teleport Enterprise Cloud">
|
|
|
|
</TabItem>
|
|
|
|
</Tabs>
|
|
|
|
(!docs/pages/includes/database-access/how-it-works/iam.mdx db="Amazon Aurora" cloud="AWS"!)
|
|
|
|
## Prerequisites
|
|
|
|
(!docs/pages/includes/edition-prereqs-tabs.mdx!)
|
|
|
|
- An AWS account with a PostgreSQL Amazon Aurora database and permissions to create
|
|
and attach IAM policies.
|
|
- A host, e.g., an EC2 instance, where you will run the Teleport Database
|
|
Service.
|
|
- (!docs/pages/includes/tctl.mdx!)
|
|
|
|
## Step 1/5. Set up Aurora
|
|
|
|
In order to allow Teleport connections to an Aurora instance, the instance needs
|
|
to support IAM authentication.
|
|
|
|
If you don't have a database provisioned yet, create an instance of an Aurora
|
|
PostgreSQL in the [RDS control panel](https://console.aws.amazon.com/rds/home).
|
|
Make sure to choose the "Standard create" database creation method and enable
|
|
"Password and IAM database authentication" in the Database Authentication dialog.
|
|
|
|
For existing Aurora instances, the status of IAM authentication is displayed on
|
|
the Configuration tab and can be enabled by modifying the database instance.
|
|
|
|
Next, create the following IAM policy and attach it to the AWS user or service
|
|
account. The Teleport Database Service will need to use the credentials of this
|
|
AWS user or service account in order to use this policy.
|
|
|
|
```json
|
|
{
|
|
"Version": "2012-10-17",
|
|
"Statement": [
|
|
{
|
|
"Effect": "Allow",
|
|
"Action": [
|
|
"rds-db:connect"
|
|
],
|
|
"Resource": [
|
|
"arn:aws:rds-db:<region>:<account-id>:dbuser:<resource-id>/*"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
This policy allows any database account to connect to the Aurora instance specified
|
|
with resource ID using IAM auth.
|
|
|
|
<Admonition
|
|
type="note"
|
|
title="Resource ID"
|
|
>
|
|
The database resource ID is shown on the Configuration tab of a particular
|
|
database instance in the RDS control panel, under "Resource id". For regular
|
|
RDS database it starts with `db-` prefix. For Aurora, use the database
|
|
cluster resource ID (`cluster-`), not the individual instance ID.
|
|
</Admonition>
|
|
|
|
Finally, connect to the database and create a database account with IAM auth
|
|
support (or update an existing one). Once connected, execute the following
|
|
SQL statements to create a new database account and allow IAM auth for it:
|
|
|
|
```sql
|
|
CREATE USER alice;
|
|
GRANT rds_iam TO alice;
|
|
```
|
|
For more information about connecting to the PostgreSQL instance directly,
|
|
see the AWS [documentation](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ConnectToPostgreSQLInstance.html).
|
|
|
|
See the [Automatic User Provisioning](./rbac.mdx) guide for how to configure Teleport to create accounts for your PostgreSQL users on demand.
|
|
|
|
## Step 2/5. Configure the Teleport Database Service
|
|
|
|
(!docs/pages/includes/tctl-token.mdx serviceName="Database" tokenType="db" tokenFile="/tmp/token"!)
|
|
|
|
(!docs/pages/includes/database-access/alternative-methods-join.mdx!)
|
|
|
|
Install Teleport on the host where you will run the Teleport Database Service:
|
|
|
|
(!docs/pages/includes/install-linux.mdx!)
|
|
|
|
<Tabs>
|
|
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
|
|
|
|
On the node where you will run the Teleport Database Service, configure Teleport and
|
|
point it to your Aurora database instance. Make sure to update the database
|
|
endpoint and region appropriately. The `--proxy` flag must point to the
|
|
address of your Teleport Proxy Service.
|
|
|
|
```code
|
|
$ sudo teleport db configure create \
|
|
--token=/tmp/token \
|
|
--name=<Var name="aurora" /> \
|
|
--proxy=<Var name="teleport.example.com" />:443 \
|
|
--protocol=postgres \
|
|
--uri=<Var name="postgres-aurora-instance-1.abcdefghijklm.us-west-1.rds.amazonaws.com"/>:5432 \
|
|
--aws-region=<Var name="us-west-1" /> \
|
|
--output file:///etc/teleport.yaml
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem scope={["cloud"]} label="Teleport Enterprise Cloud">
|
|
|
|
On the node where you will run the Teleport Database Service, configure Teleport and
|
|
point it to your Aurora database instance. Make sure to update the database
|
|
endpoint and region appropriately. The `--proxy` flag must point to the
|
|
address of your Teleport Cloud tenant.
|
|
|
|
```code
|
|
$ sudo teleport db configure create \
|
|
--token=/tmp/token \
|
|
--name=<Var name="aurora" /> \
|
|
--proxy=<Var name="mytenant.teleport.sh" />:443 \
|
|
--protocol=postgres \
|
|
--uri=<Var name="postgres-aurora-instance-1.abcdefghijklm.us-west-1.rds.amazonaws.com"/>:5432 \
|
|
--aws-region=<Var name="us-west-1" /> \
|
|
--output file:///etc/teleport.yaml
|
|
```
|
|
|
|
</TabItem>
|
|
|
|
</Tabs>
|
|
|
|
<Admonition
|
|
type="note"
|
|
title="AWS Credentials"
|
|
>
|
|
The node that connects to the database should have AWS credentials configured
|
|
with the policy from [step 1](#step-15-set-up-aurora).
|
|
</Admonition>
|
|
|
|
## Step 3/5. Start the Database Service
|
|
|
|
Start the Teleport Database Service in your environment:
|
|
|
|
(!docs/pages/includes/start-teleport.mdx service="the Database Service"!)
|
|
|
|
## Step 4/5. Create a user and role
|
|
|
|
Create the role that will allow a user to connect to any database using any
|
|
database account:
|
|
|
|
```code
|
|
$ tctl create <<EOF
|
|
kind: role
|
|
version: v3
|
|
metadata:
|
|
name: db
|
|
spec:
|
|
allow:
|
|
db_labels:
|
|
'*': '*'
|
|
db_names:
|
|
- '*'
|
|
db_users:
|
|
- '*'
|
|
EOF
|
|
```
|
|
|
|
(!docs/pages/includes/create-role-using-web.mdx!)
|
|
|
|
Create the Teleport user assigned the `db` role we've just created:
|
|
|
|
<Tabs>
|
|
<TabItem scope={["oss"]} label="Teleport Community Edition">
|
|
```code
|
|
$ tctl users add --roles=access,db alice
|
|
```
|
|
</TabItem>
|
|
<TabItem scope={["enterprise", "cloud"]} label="Commercial">
|
|
```code
|
|
$ tctl users add --roles=access,requester,db alice
|
|
```
|
|
</TabItem>
|
|
|
|
</Tabs>
|
|
|
|
## Step 5/5. Connect
|
|
|
|
Now that Aurora is configured with IAM authentication, Teleport is running, and
|
|
the local user is created, we're ready to connect to the database.
|
|
|
|
Log in to Teleport with the user we've just created.
|
|
|
|
<Tabs>
|
|
<TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
|
|
|
|
```code
|
|
$ tsh login --proxy=<Var name="teleport.example.com" /> --user=<Var name="alice" />
|
|
```
|
|
|
|
</TabItem>
|
|
<TabItem scope={["cloud"]} label="Teleport Enterprise Cloud">
|
|
|
|
```code
|
|
$ tsh login --proxy=<Var name="mytenant.teleport.sh" /> --user=<Var name="alice" />
|
|
```
|
|
|
|
</TabItem>
|
|
|
|
</Tabs>
|
|
|
|
Now we can inspect available databases:
|
|
|
|
```code
|
|
$ tsh db ls
|
|
```
|
|
|
|
Finally, connect to the database:
|
|
|
|
```code
|
|
$ tsh db connect --db-user=alice --db-name postgres aurora
|
|
```
|
|
|
|
### Auditing
|
|
|
|
(!docs/pages/includes/database-access/db-audit-events.mdx!)
|
|
|
|
## Troubleshooting
|
|
|
|
(!docs/pages/includes/database-access/aws-troubleshooting.mdx!)
|
|
|
|
## Next Steps
|
|
|
|
For the next steps, dive deeper into the topics relevant to your Database
|
|
Access use-case, for example:
|
|
|
|
- Check out configuration [guides](guides/guides.mdx).
|
|
- Learn how to configure [GUI clients](../../connect-your-client/gui-clients.mdx).
|
|
- Learn about database access [role-based access control](./rbac.mdx).
|
|
- See [frequently asked questions](./faq.mdx).
|
|
|