diff --git a/docs/config.json b/docs/config.json index 568213b5d802a..7b241a9aef625 100644 --- a/docs/config.json +++ b/docs/config.json @@ -931,7 +931,11 @@ "slug": "/application-access/guides/dynamic-registration/" }, { - "title": "AWS DynamoDB", + "title": "Amazon Athena", + "slug": "/application-access/guides/amazon-athena/" + }, + { + "title": "Amazon DynamoDB", "slug": "/application-access/guides/dynamodb/" }, { diff --git a/docs/cspell.json b/docs/cspell.json index 824f4e2724a72..a6abf560dffa0 100644 --- a/docs/cspell.json +++ b/docs/cspell.json @@ -114,6 +114,7 @@ "NOKEY", "NOPASSWD", "NVGJ", + "ODBC", "OIDC", "OTLP", "Obxo", @@ -183,6 +184,7 @@ "XNCK", "XROQ", "XVCJ", + "XshowSettings", "YFUEI", "Ypga", "Yubico", @@ -232,6 +234,7 @@ "automount", "autoscale", "awsapp", + "awsathena", "awscli", "awsconsole", "awsdatabases", @@ -248,6 +251,7 @@ "bluemix", "boto", "buildbox", + "cacerts", "caddef", "categorisation", "cavium", @@ -390,6 +394,7 @@ "httpout", "iamserviceaccount", "idps", + "importcert", "initcontainers", "insecureskipproxytlsverify", "ioreg", @@ -405,6 +410,7 @@ "journalctl", "jqvns", "jsmith", + "jsonencode", "jsonpath", "jumphost", "jwks", @@ -417,6 +423,7 @@ "keypairs", "keyrings", "keytab", + "keytool", "killall", "kinit", "klist", @@ -520,6 +527,7 @@ "nodename", "nohup", "nologin", + "noprompt", "nosql", "nowait", "nvme", diff --git a/docs/img/application-access/guides/athena-dbeaver-main.png b/docs/img/application-access/guides/athena-dbeaver-main.png new file mode 100644 index 0000000000000..8f68cd77a1c5d Binary files /dev/null and b/docs/img/application-access/guides/athena-dbeaver-main.png differ diff --git a/docs/img/application-access/guides/athena-dbeaver-properties.png b/docs/img/application-access/guides/athena-dbeaver-properties.png new file mode 100644 index 0000000000000..b3fd3c0975815 Binary files /dev/null and b/docs/img/application-access/guides/athena-dbeaver-properties.png differ diff --git a/docs/img/application-access/guides/aws-create-iam-role-2.png b/docs/img/application-access/guides/aws-create-iam-role-2.png new file mode 100644 index 0000000000000..2f77ee4e9d3a6 Binary files /dev/null and b/docs/img/application-access/guides/aws-create-iam-role-2.png differ diff --git a/docs/img/application-access/guides/aws-create-iam-role-3.png b/docs/img/application-access/guides/aws-create-iam-role-3.png new file mode 100644 index 0000000000000..c1fd29919b6f6 Binary files /dev/null and b/docs/img/application-access/guides/aws-create-iam-role-3.png differ diff --git a/docs/img/application-access/guides/aws-database-select-iam-role.png b/docs/img/application-access/guides/aws-database-select-iam-role.png new file mode 100644 index 0000000000000..c97ca21a921c4 Binary files /dev/null and b/docs/img/application-access/guides/aws-database-select-iam-role.png differ diff --git a/docs/img/database-access/guides/dynamodb-federated-login.png b/docs/img/database-access/guides/dynamodb-federated-login.png deleted file mode 100644 index 2bedcb182d9a2..0000000000000 Binary files a/docs/img/database-access/guides/dynamodb-federated-login.png and /dev/null differ diff --git a/docs/img/database-access/guides/dynamodb-select-iam-role.png b/docs/img/database-access/guides/dynamodb-select-iam-role.png deleted file mode 100644 index a3f44e6422b27..0000000000000 Binary files a/docs/img/database-access/guides/dynamodb-select-iam-role.png and /dev/null differ diff --git a/docs/pages/application-access/guides.mdx b/docs/pages/application-access/guides.mdx index 15729dd11216f..5b72d220b281a 100644 --- a/docs/pages/application-access/guides.mdx +++ b/docs/pages/application-access/guides.mdx @@ -14,5 +14,6 @@ Manage access to internal applications: - [TCP App Access (Preview)](./guides/tcp.mdx): How to access plain TCP apps with Teleport. - [API Access](./guides/api-access.mdx): How to access REST APIs with Teleport. - [Dynamic Registration](./guides/dynamic-registration.mdx): Register/unregister apps without restarting Teleport. -- [AWS DynamoDB Access](./guides/dynamodb.mdx): How to access AWS DynamoDB as an application. +- [Amazon Athena Access](./guides/amazon-athena.mdx): How to access Amazon Athena with Teleport. +- [Amazon DynamoDB Access](./guides/dynamodb.mdx): How to access Amazon DynamoDB as an application. - [Application Access HA](./guides/ha.mdx): How to configure the Teleport Application Service for high availability. diff --git a/docs/pages/application-access/guides/amazon-athena.mdx b/docs/pages/application-access/guides/amazon-athena.mdx new file mode 100644 index 0000000000000..17ca6972c75b9 --- /dev/null +++ b/docs/pages/application-access/guides/amazon-athena.mdx @@ -0,0 +1,196 @@ +--- +title: Amazon Athena Access +description: How to access Amazon Athena with Teleport +--- + +You can set up secure access to Amazon Athena using Teleport's support for the +[AWS CLI and Console](../cloud-apis/aws-console.mdx). + +This guide will help you to: + +- Install the Teleport Application Service. +- Set up AWS CLI and Console access. +- Connect to your Athena databases. + +## Prerequisites + +(!docs/pages/includes/application-access/aws-database-prerequisites.mdx database="Athena" !) + +## Step 1/5. Create an IAM role for Athena access + +(!docs/pages/includes/application-access/aws-database-create-iam-role.mdx database="Athena" iam-role="ExampleTeleportAthenaRole" managed-policy="AmazonAthenaFullAccess" !) + + +`AmazonAthenaFullAccess` may provide too much access for your intentions. To +use a different IAM policy to reduce permissions, see [Identity and access +management in +Athena](https://docs.aws.amazon.com/athena/latest/ug/security-iam-athena.html) +for more details. + + +## Step 2/5. Configure the Teleport IAM role mapping + +(!docs/pages/includes/application-access/aws-database-role-mapping.mdx role="aws-athena-access" iam-role="ExampleTeleportAthenaRole"!) + +## Step 3/5. Install the Teleport Application Service + +(!docs/pages/includes/application-access/aws-database-start-app-service.mdx!) + +## Step 4/5. Give Teleport permissions to assume roles + +(!docs/pages/includes/application-access/aws-database-agent-permission.mdx!) + +## Step 5/5. Connect + +Once the Application Service has started and joined the cluster, you can start +connecting to your Athena database. + +### Using AWS Management Console + +(!docs/pages/includes/application-access/aws-database-access-console.mdx iam-role="ExampleTeleportAthenaRole" !) + +### Using AWS CLI + +(!docs/pages/includes/application-access/aws-database-access-cli.mdx iam-role="ExampleTeleportAthenaRole" tsh-example="tsh aws athena list-work-groups"!) + +### Using other Athena applications + +First, log into the previously configured AWS app if you haven't already done +so: + +```code +$ tsh apps login --aws-role ExampleTeleportAthenaRole aws +``` + +Connect to Athena with the ODBC or JDBC driver: + + + + Start a local HTTPS proxy: + ```code + $ tsh proxy aws --port 8443 --format athena-odbc + Started AWS proxy on http://127.0.0.1:8443. + + Set the following properties for the Athena ODBC data source: + [Teleport AWS Athena Access] + AuthenticationType = IAM Credentials + UID = (=aws.aws_access_key=) + PWD = (=aws.aws_secret_access_key=) + UseProxy = 1; + ProxyScheme = http; + ProxyHost = 127.0.0.1; + ProxyPort = 8443; + TrustedCerts = + + Here is a sample connection string using the above credentials and proxy settings: + DRIVER=Simba Amazon Athena ODBC Connector;AuthenticationType=IAM Credentials;UID=(=aws.aws_access_key=);PWD=(=aws.aws_secret_access_key=);UseProxy=1;ProxyScheme=http;ProxyHost=127.0.0.1;ProxyPort=8443;TrustedCerts=;AWSRegion=;Workgroup= + ``` + + Use the provided connection string in your Athena application with ODBC + driver. + + + + Start a local HTTPS proxy: + ```code + $ tsh proxy aws --port 8443 --format athena-jdbc + Started AWS proxy on http://127.0.0.1:8443. + + First, add the following certificate to your keystore: + + + For example, to import the certificate using "keytool": + keytool -noprompt -importcert -alias teleport-aws -file -keystore + + Then, set the following properties in the JDBC connection URL: + User = (=aws.aws_access_key=) + Password = (=aws.aws_secret_access_key=) + ProxyHost = 127.0.0.1; + ProxyPort = 8443; + + Here is a sample JDBC connection URL using the above credentials and proxy settings: + jdbc:awsathena://User=(=aws.aws_access_key=);Password=(=aws.aws_secret_access_key=);ProxyHost=127.0.0.1;ProxyPort=8443;AwsRegion=;Workgroup= + ``` + + Follow the printed instructions to add the local certificate to your Java + Keystore. The default Java Keystore is usually located at: + ``` + $ ls $(java -XshowSettings:properties -version 2>&1 | grep 'java.home' | awk '{print $3}')/lib/security/cacerts + ``` + + Then use the provided JDBC connection URL for your Athena application with + JDBC driver. + + + + Start a local HTTPS proxy: + ```code + $ tsh proxy aws --port 8443 --format athena-jdbc + Started AWS proxy on http://127.0.0.1:8443. + + First, add the following certificate to your keystore: + + + For example, to import the certificate using "keytool": + keytool -noprompt -importcert -alias teleport-aws -file -keystore + + Then, set the following properties in the JDBC connection URL: + User = (=aws.aws_access_key=) + Password = (=aws.aws_secret_access_key=) + ProxyHost = 127.0.0.1; + ProxyPort = 8443; + + Here is a sample JDBC connection URL using the above credentials and proxy settings: + jdbc:awsathena://User=(=aws.aws_access_key=);Password=(=aws.aws_secret_access_key=);ProxyHost=127.0.0.1;ProxyPort=8443;AwsRegion=;Workgroup= + ``` + + Note that DBeaver uses its own Java Keystore instead of the default one. For + example, on macOS, the Keystore location is + `/Applications/DBeaver.app/Contents/Eclipse/jre/Contents/Home/lib/security/cacerts`. + + Follow [Importing CA Certificates into + DBeaver](https://dbeaver.com/docs/wiki/Importing-CA-Certificates-into-DBeaver/) + to setup the Keystore for DBeaver. Then follow the printed instruction from + above `tsh proxy aws` command to add the local certificate to the Keystore. + + Start DBeaver and add an "Athena" connection. Enter the username (AWS access + key) and password (AWS secret key) from the `tsh proxy aws` output: + ![DBeaver main](../../../img/application-access/guides/athena-dbeaver-main.png) + + Then fill in the `ProxyHost` and `ProxyPort` settings in "Driver properties": + ![DBeaver main](../../../img/application-access/guides/athena-dbeaver-properties.png) + + Click "Finish". Now you can connect to your Athena database. + + + + + + +By default, `tsh proxy aws` generates random AWS credentials for local +communication for best security and uses several placeholders in the generated +instructions. The following environment variables can be set to overwrite +those values: +- `TELEPORT_AWS_ACCESS_KEY_ID`: sets the local AWS access key. +- `TELEPORT_AWS_SECRET_ACCESS_KEY`: sets the local AWS secret key. +- `TELEPORT_AWS_REGION`: sets the AWS region. +- `TELEPORT_AWS_KEYSTORE`: sets the Java Keystore path. +- `TELEPORT_AWS_WORKGROUP`: sets the Athena workgroup name. + + + +`tsh proxy aws` generates a local certificate authority (CA) for local +communication. The local CA may expire after a new `tsh login` session and a +new CA will be generated. Make sure your Java Keystore is up-to-date by +deleting the alias from your Keystore and adding it again. + + +To log out of the `aws` application and remove credentials: + +```code +$ tsh apps logout aws +``` + +## Next steps +- More information on [AWS Management and API with Teleport Application Access](../../application-access/cloud-apis/aws-console.mdx). +- Learn more about [AWS service endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html). diff --git a/docs/pages/application-access/guides/dynamodb.mdx b/docs/pages/application-access/guides/dynamodb.mdx index 5fbe30bee5a88..7f5e309f3017f 100644 --- a/docs/pages/application-access/guides/dynamodb.mdx +++ b/docs/pages/application-access/guides/dynamodb.mdx @@ -1,9 +1,9 @@ --- -title: AWS DynamoDB using the Teleport Application Service -description: How to access AWS DynamoDB through the Teleport Application Service +title: Amazon DynamoDB using the Teleport Application Service +description: How to access Amazon DynamoDB through the Teleport Application Service --- -Access to AWS DynamoDB can be provided by [**Teleport Application +Access to Amazon DynamoDB can be provided by [**Teleport Application Access**](../../application-access/introduction.mdx) for the AWS Console and API. This is an alternative to accessing DynamoDB through the Teleport Database service, as described in our [Database Access with AWS @@ -29,43 +29,11 @@ This guide will help you to: ## Prerequisites -- AWS account with DynamoDB databases. -- IAM permissions to create IAM roles. -- `aws` Command Line Interface (CLI) tool installed in PATH. -- A host, e.g., an EC2 instance, where you will run the Teleport Application - Service. - -(!docs/pages/includes/edition-prereqs-tabs.mdx!) - -- (!docs/pages/includes/tctl.mdx!) - - -If you have not yet deployed the Auth Service and Proxy Service, you should follow one of our [getting started guides](../getting-started.mdx) or try our Teleport application access [interactive learning track](https://play.instruqt.com/teleport/invite/rgvuva4gzkon). - - -We will assume your Teleport cluster is accessible at `teleport.example.com` and `*.teleport.example.com`. You can substitute the address of your Teleport Proxy Service. (For Teleport Cloud customers, this will be similar to `mytenant.teleport.sh`.) - - -(!docs/pages/includes/dns-app-access.mdx!) - +(!docs/pages/includes/application-access/aws-database-prerequisites.mdx database="DynamoDB" !) ## Step 1/5. Create an IAM role for DynamoDB access -Visit the [Roles page](https://console.aws.amazon.com/iamv2/home#/roles) of -the AWS Console, then press "Create Role". - -Select the "AWS account" option, which creates a default trust policy to allow -other entities in this account to assume this role: - -![Create Role Step 1](../../../img/database-access/guides/dynamodb-create-role-1.png) - -Press "Next". Find the AWS-managed policy `AmazonDynamoDBFullAccess` and then select the policy: - -![Create Role Step 2](../../../img/database-access/guides/dynamodb-create-role-2.png) - -Press "Next". Enter a role name and press "Create role": - -![Create Role Step 3](../../../img/database-access/guides/dynamodb-create-role-3.png) +(!docs/pages/includes/application-access/aws-database-create-iam-role.mdx database="DynamoDB" iam-role="ExampleTeleportDynamoDBRole" managed-policy="AmazonDynamoDBFullAccess" !) `AmazonDynamoDBFullAccess` may provide too much access for your intentions. To @@ -76,130 +44,15 @@ Resources](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/acce ## Step 2/5. Configure the Teleport IAM role mapping -The next step is to give your Teleport users permissions to assume IAM roles in -your Teleport cluster. - -You can do this by creating a Teleport role with the `aws_role_arns` field -listing the IAM role ARN created in the previous step. Create a file called -`aws-dynamodb-access.yaml` with the following content: - -```yaml -kind: role -version: v5 -metadata: - name: aws-dynamodb-access -spec: - allow: - app_labels: - '*': '*' - aws_role_arns: - - arn:aws:iam::123456789000:role/ExampleTeleportDynamoDBRole -``` - -
-The `aws_role_arns` field supports template variables so they can be populated -dynamically based on your users' identity provider attributes. See [Role -Templates](../../access-controls/guides/role-templates.mdx) for details. -
- -Create the new role: - -```code -$ tctl create -f aws-dynamodb-access.yaml -``` - -(!docs/pages/includes/add-role-to-user.mdx role="aws-dynamodb-access"!) +(!docs/pages/includes/application-access/aws-database-role-mapping.mdx role="aws-dynamodb-access" iam-role="ExampleTeleportDynamoDBRole"!) ## Step 3/5. Install the Teleport Application Service -### Generate a token - -A join token is required to authorize a Teleport Application Service instance -to join the cluster. Generate a short-lived join token and save the output of -the command: - -```code -$ tctl tokens add \ - --type=app \ - --app-name=aws-dynamodb \ - --app-uri=https://console.aws.amazon.com/dynamodbv2/home -``` - -On the host where you will run the Teleport Application Service, copy the token -to a file called `/tmp/token`. - - -Replace `https://console.aws.amazon.com` with -`https://console.amazonaws-us-gov.com` for AWS GovCloud (US) regions or -`https://console.amazonaws.cn` for AWS China regions. - - -### Install and start Teleport - -Install Teleport on the host where you will run the Teleport Application -Service. See our [Installation](../../installation.mdx) page for options -besides Linux servers. - -(!docs/pages/includes/install-linux.mdx!) - -Edit the Teleport configuration file (`/etc/teleport.yaml`) to include the -following information, adjusting the value of `proxy_server` to specify the host -and port of your Teleport Proxy Service: - -```yaml -version: v3 -teleport: - join_params: - token_name: "/tmp/token" - method: token - proxy_server: "teleport.example.com:443" -auth_service: - enabled: off -proxy_service: - enabled: off -ssh_service: - enabled: off -app_service: - enabled: true - apps: - - name: aws-dynamodb - uri: https://console.aws.amazon.com/dynamodbv2/home -``` - -(!docs/pages/includes/aws-credentials.mdx service="the Teleport Application Service"!) - -(!docs/pages/includes/start-teleport.mdx service="the Teleport Application Service"!) - - -For non-standard AWS regions such as AWS GovCloud (US) regions and AWS China -regions, please set the corresponding region in the `AWS_REGION` environment -variable or in the AWS credentials file so that the Application Service can use -the correct STS endpoint. - +(!docs/pages/includes/application-access/aws-database-start-app-service.mdx!) ## Step 4/5. Give Teleport permissions to assume roles -Next, attach the following policy to the IAM role or IAM user the Teleport -Application Service instance is using, which allows the Application Service to -assume the IAM roles: - -```yaml -{ - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": "sts:AssumeRole", - "Resource": "*" - } - ] -} -``` - - -You can make the policy more strict by providing specific IAM role resource -ARNs in the "Resource" field instead of using a wildcard. - +(!docs/pages/includes/application-access/aws-database-agent-permission.mdx!) ## Step 5/5. Connect @@ -208,59 +61,19 @@ connecting to your DynamoDB database. ### Using AWS Management Console -First log in to the Teleport Web UI at `https://teleport.example.com` (replace -with your Proxy Service's public address). - -Navigate to the Applications tab in your Teleport cluster's control panel and -click on the Launch button for the AWS DynamoDB application. This will bring up -an IAM role selector: - -![IAM role selector](../../../img/database-access/guides/dynamodb-select-iam-role.png) - -Click on the role you want to assume and you will get redirected to the AWS -Management Console, signed in with the selected role. - -In the console's top-right corner you should see that you're logged in through -federated login and the name of your assumed IAM role: - -![Federated login](../../../img/database-access/guides/dynamodb-federated-login.png) - -Note that your federated login session is marked with your Teleport username. +(!docs/pages/includes/application-access/aws-database-access-console.mdx iam-role="ExampleTeleportDynamoDBRole" !) ### Using AWS CLI -Now, log into the previously configured AWS DynamoDB app on your desktop: - -```code -$ tsh apps login --aws-role ExampleTeleportDynamoDBRole aws-dynamodb -Logged into AWS app aws. Example AWS CLI command: - -$ tsh aws s3 ls -``` - -The `--aws-role` flag allows you to specify the AWS IAM role to assume when -accessing the AWS API. You can either provide a role name like `--aws-role -ExampleTeleportDynamoDBRole` or a full role ARN like -`arn:aws:iam::123456789000:role/ExampleTeleportDynamoDBRole`. - -Now you can use the `tsh aws` command like the native `aws` command-line tool: -```code -$ tsh aws dynamodb list-tables -``` - -To log out of the `aws-dynamodb` application and remove credentials: - -```code -$ tsh apps logout aws-dynamodb -``` +(!docs/pages/includes/application-access/aws-database-access-cli.mdx iam-role="ExampleTeleportDynamoDBRole" tsh-example="tsh aws dynamodb list-tables"!) ### Using other DynamoDB applications -First, log into the previously configured AWS DynamoDB app if you haven't -already done so: +First, log into the previously configured AWS app if you haven't already done +so: ```code -$ tsh apps login --aws-role ExampleTeleportDynamoDBRole aws-dynamodb +$ tsh apps login --aws-role ExampleTeleportDynamoDBRole aws ``` To connect your DynamoDB application, you can start either a local HTTPS proxy @@ -282,7 +95,7 @@ or a local AWS Service Endpoint proxy. Use the following credentials and HTTPS proxy setting to connect to the proxy: AWS_ACCESS_KEY_ID=(=aws.aws_access_key=) AWS_SECRET_ACCESS_KEY=(=aws.aws_secret_access_key=) - AWS_CA_BUNDLE= + AWS_CA_BUNDLE= HTTPS_PROXY=http://127.0.0.1:23456 ``` @@ -295,7 +108,7 @@ or a local AWS Service Endpoint proxy. ```code $ export AWS_ACCESS_KEY_ID=(=aws.aws_access_key=) $ export AWS_SECRET_ACCESS_KEY=(=aws.aws_secret_access_key=) - $ export AWS_CA_BUNDLE= + $ export AWS_CA_BUNDLE= $ export HTTPS_PROXY=http://127.0.0.1:23456 $ python3 >>> import boto3 @@ -317,7 +130,7 @@ or a local AWS Service Endpoint proxy. In addition to the endpoint URL, use the following credentials to connect to the proxy: AWS_ACCESS_KEY_ID=(=aws.aws_access_key=) AWS_SECRET_ACCESS_KEY=(=aws.aws_secret_access_key=) - AWS_CA_BUNDLE= + AWS_CA_BUNDLE= ``` For example, to connect the GUI tool `dynamodb-admin` to the local AWS @@ -325,7 +138,7 @@ or a local AWS Service Endpoint proxy. ```code $ export AWS_ACCESS_KEY_ID=(=aws.aws_access_key=) $ export AWS_SECRET_ACCESS_KEY=(=aws.aws_secret_access_key=) - $ export NODE_EXTRA_CA_CERTS= + $ export NODE_EXTRA_CA_CERTS= $ export DYNAMO_ENDPOINT=https://127.0.0.1:23457 $ dynamodb-admin database endpoint: https://127.0.0.1:23457 @@ -337,10 +150,10 @@ or a local AWS Service Endpoint proxy. -To log out of the `aws-dynamodb` application and remove credentials: +To log out of the `aws` application and remove credentials: ```code -$ tsh apps logout aws-dynamodb +$ tsh apps logout aws ``` ## Next steps diff --git a/docs/pages/includes/application-access/aws-database-access-cli.mdx b/docs/pages/includes/application-access/aws-database-access-cli.mdx new file mode 100644 index 0000000000000..3999653de4a6b --- /dev/null +++ b/docs/pages/includes/application-access/aws-database-access-cli.mdx @@ -0,0 +1,25 @@ +Log into the previously configured AWS app on your desktop: + +```code +$ tsh apps login --aws-role {{ iam-role }} aws +Logged into AWS app aws. Example AWS CLI command: + +$ tsh aws s3 ls +``` + +The `--aws-role` flag allows you to specify the AWS IAM role to assume when +accessing the AWS API. You can either provide a role name like `--aws-role +ExampleTeleportDynamoDBRole` or a full role ARN like +`arn:aws:iam::123456789000:role/{{iam-role}}`. + +Now you can use the `tsh aws` command like the native `aws` command-line tool: + +```code +$ {{ tsh-example }} +``` + +To log out of the `aws` application and remove credentials: + +```code +$ tsh apps logout aws +``` diff --git a/docs/pages/includes/application-access/aws-database-access-console.mdx b/docs/pages/includes/application-access/aws-database-access-console.mdx new file mode 100644 index 0000000000000..1ae85d3eaf1a0 --- /dev/null +++ b/docs/pages/includes/application-access/aws-database-access-console.mdx @@ -0,0 +1,15 @@ +Log in to the Teleport Web UI at `https://teleport.example.com` (replace with +your Proxy Service's public address). + +Navigate to the Applications tab in your Teleport cluster's control panel and +click on the Launch button for the AWS application. This will bring up an IAM +role selector: + +![IAM role selector](../../../img/application-access/guides/aws-database-select-iam-role.png) + +Click on the role `{{ iam-role }}` and you will get redirected to the AWS +Management Console, signed in with the selected role. + +In the console's top-right corner, you should see that you're logged in through +federated login and the name of your assumed IAM role is +`{{ iam-role }}/` where the session name is your Teleport username. diff --git a/docs/pages/includes/application-access/aws-database-agent-permission.mdx b/docs/pages/includes/application-access/aws-database-agent-permission.mdx new file mode 100644 index 0000000000000..150f4fdc85d62 --- /dev/null +++ b/docs/pages/includes/application-access/aws-database-agent-permission.mdx @@ -0,0 +1,21 @@ +Next, attach the following policy to the IAM role or IAM user the Teleport +Application Service instance is using, which allows the Application Service to +assume the IAM roles: + +```yaml +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "sts:AssumeRole", + "Resource": "*" + } + ] +} +``` + + +You can make the policy more strict by providing specific IAM role resource +ARNs in the "Resource" field instead of using a wildcard. + diff --git a/docs/pages/includes/application-access/aws-database-create-iam-role.mdx b/docs/pages/includes/application-access/aws-database-create-iam-role.mdx new file mode 100644 index 0000000000000..06c0973834cde --- /dev/null +++ b/docs/pages/includes/application-access/aws-database-create-iam-role.mdx @@ -0,0 +1,85 @@ +Create an IAM role that provides access to your {{ database }} resources. +Teleport Application Service will assume this IAM role on behalf of the +Teleport user that accesses these {{ database }} resources. + +There are several methods to create an IAM role: + + + +Visit the [Roles page](https://console.aws.amazon.com/iamv2/home#/roles) of +the AWS Console, then press "Create Role". + +Select the "AWS account" option, which creates a default trust policy to allow +other entities in this account to assume this role: + +![Create Role Step 1](../../../img/database-access/guides/dynamodb-create-role-1.png) + +Press "Next". Find the AWS-managed policy `{{ managed-policy }}` and then select the policy: + +![Create Role Step 2](../../../img/application-access/guides/aws-create-iam-role-2.png) + +Press "Next". Enter role name `{{ iam-role }}` and press "Create role": + +![Create Role Step 3](../../../img/application-access/guides/aws-create-iam-role-3.png) + + + +Create a file with the following trust policy. Replace with your AWS Account ID: +```code +$ cat > trust-relationship.json <:root" + }, + "Action": "sts:AssumeRole" + } + ] +} +EOF +``` + +Create an IAM role with name `{{ iam-role }}`: +```code +$ aws iam create-role --role-name {{ iam-role }} --assume-role-policy-document file://trust-relationship.json +``` + +Attach managed policy `{{ managed-policy }}` to the role: +```code +$ aws iam attach-role-policy --role-name {{ iam-role }} --policy-arn arn:aws:iam::aws:policy/{{ managed-policy }} +``` + + + +Add the following resources to your Terraform deployment. Replace with your AWS Account ID: +```code +$ cat > teleport_iam_role_{{ iam-role }}.tf <:root" + } + Action = "sts:AssumeRole" + }, + ] + }) +} +resource "aws_iam_role_policy_attachment" "teleport-{{ iam-role }}-{{ managed-policy }}" { + role = aws_iam_role.teleport-{{ iam-role }}.name + policy_arn = "arn:aws:iam::aws:policy/{{ managed-policy }}" +} +EOF +``` +Then `terraform apply`. + + diff --git a/docs/pages/includes/application-access/aws-database-prerequisites.mdx b/docs/pages/includes/application-access/aws-database-prerequisites.mdx new file mode 100644 index 0000000000000..9c8b9028b0d6d --- /dev/null +++ b/docs/pages/includes/application-access/aws-database-prerequisites.mdx @@ -0,0 +1,19 @@ +- AWS account with {{ database }} databases. +- IAM permissions to create IAM roles. +- `aws` Command Line Interface (CLI) tool installed in PATH. +- A host, e.g., an EC2 instance, where you will run the Teleport Application + Service. + +(!docs/pages/includes/edition-prereqs-tabs.mdx!) + +- (!docs/pages/includes/tctl.mdx!) + + +If you have not yet deployed the Auth Service and Proxy Service, you should follow one of our [getting started guides](../../application-access/getting-started.mdx) or try our Teleport application access [interactive learning track](https://play.instruqt.com/teleport/invite/rgvuva4gzkon). + + +We will assume your Teleport cluster is accessible at `teleport.example.com` and `*.teleport.example.com`. You can substitute the address of your Teleport Proxy Service. (For Teleport Cloud customers, this will be similar to `mytenant.teleport.sh`.) + + +(!docs/pages/includes/dns-app-access.mdx!) + diff --git a/docs/pages/includes/application-access/aws-database-role-mapping.mdx b/docs/pages/includes/application-access/aws-database-role-mapping.mdx new file mode 100644 index 0000000000000..3b64e35b140a4 --- /dev/null +++ b/docs/pages/includes/application-access/aws-database-role-mapping.mdx @@ -0,0 +1,96 @@ +Give your Teleport users permissions to assume IAM roles in your Teleport +cluster. + +You can do this by creating a Teleport role with the `aws_role_arns` field +listing the IAM role ARN created in the previous step. Create a file called +`{{ role }}.yaml` with the following content: + +```code +$ cat > {{ role }}.yaml <:role/{{ iam-role }} +EOF +``` +Remember to replace with your AWS Account ID. + +
+The `aws_role_arns` field supports template variables so they can be populated +dynamically based on your users' identity provider attributes. Here are some +examples: + + + + Use `{{internal.aws_role_arns}}` in the role definition: + ```yaml + kind: role + version: v5 + metadata: + name: {{ role }} + spec: + allow: + app_labels: + '*': '*' + aws_role_arns: ['{{internal.aws_role_arns}}'] + ``` + Then specify the IAM roles through user traits: + ```yaml + kind: user + version: v2 + metadata: + name: alice + spec: + roles: ['{{ role }}'] + traits: + aws_role_arns: ['arn:aws:iam:123456789000:role/role_for_alice'] + --- + kind: user + version: v2 + metadata: + name: bob + spec: + roles: ['{{ role }}'] + traits: + aws_role_arns: ['arn:aws:iam:123456789000:role/role_for_bob'] + ``` + + + Let's assume that an IAM role has been created for each Teleport user, and + the name of the IAM role corresponds to their Email addresses without the + Email domain suffix. + + + Then `aws_role_arns` can be templated with `external.email`: + ```yaml + kind: role + version: v5 + metadata: + name: {{ role }} + spec: + allow: + app_labels: + '*': '*' + aws_role_arns: ['arn:aws:iam:123456789000:role/{{email.local(external.email)}}'] + ``` + + + +See [Role Templates](../../access-controls/guides/role-templates.mdx) for +details. +
+ +Create the new role: + +```code +$ tctl create -f {{ role }}.yaml +``` + +(!docs/pages/includes/add-role-to-user.mdx role="{{ role }}"!) + diff --git a/docs/pages/includes/application-access/aws-database-start-app-service.mdx b/docs/pages/includes/application-access/aws-database-start-app-service.mdx new file mode 100644 index 0000000000000..3c1022a9c0064 --- /dev/null +++ b/docs/pages/includes/application-access/aws-database-start-app-service.mdx @@ -0,0 +1,64 @@ +### Generate a token + +A join token is required to authorize a Teleport Application Service instance +to join the cluster. Generate a short-lived join token and save the output of +the command: + +```code +$ tctl tokens add \ + --type=app \ + --app-name=aws \ + --app-uri=https://console.aws.amazon.com/console/home +``` + +On the host where you will run the Teleport Application Service, copy the token +to a file called `/tmp/token`. + + +Replace `https://console.aws.amazon.com` with +`https://console.amazonaws-us-gov.com` for AWS GovCloud (US) regions or +`https://console.amazonaws.cn` for AWS China regions. + + +### Install and start Teleport + +Install Teleport on the host where you will run the Teleport Application +Service. See our [Installation](../../installation.mdx) page for options +besides Linux servers. + +(!docs/pages/includes/install-linux.mdx!) + +Edit the Teleport configuration file (`/etc/teleport.yaml`) to include the +following information, adjusting the value of `proxy_server` to specify the host +and port of your Teleport Proxy Service: + +```yaml +version: v3 +teleport: + join_params: + token_name: "/tmp/token" + method: token + proxy_server: "teleport.example.com:443" +auth_service: + enabled: off +proxy_service: + enabled: off +ssh_service: + enabled: off +app_service: + enabled: true + apps: + - name: aws + uri: https://console.aws.amazon.com/home/home +``` + +(!docs/pages/includes/aws-credentials.mdx service="the Teleport Application Service"!) + +(!docs/pages/includes/start-teleport.mdx service="the Teleport Application Service"!) + + +For non-standard AWS regions such as AWS GovCloud (US) regions and AWS China +regions, please set the corresponding region in the `AWS_REGION` environment +variable or in the AWS credentials file so that the Application Service can use +the correct STS endpoint. +