[v16] Workload ID: Configuring AWS Roles Anywhere guide (#43345)

* Add initial structure of AWS roles anywhere guide * More progress on roles anywhere guide * Add more advice on SPIFFE ID structure * Add guidance on updating user or bot roles * Finish off AWS roles anywhere guide * Fix broken link to AWS RA guide * Missing `the` * Add `rolesanywhere` to cspell * Update docs/pages/machine-id/workload-identity/aws-roles-anywhere.mdx Co-authored-by: Paul Gottschling <[email protected]> * Update docs/pages/machine-id/workload-identity/aws-roles-anywhere.mdx Co-authored-by: Paul Gottschling <[email protected]> * Remove mentions of App Access for AWS * Refer explicitly to Teleport Proxy Service * Add how it works header * Make deciding SPIFFE structure part of pre-requisites * Update docs/pages/machine-id/workload-identity/aws-roles-anywhere.mdx Co-authored-by: Paul Gottschling <[email protected]> * Update docs/pages/machine-id/workload-identity/aws-roles-anywhere.mdx Co-authored-by: Paul Gottschling <[email protected]> --------- Co-authored-by: Paul Gottschling <[email protected]>
gravitational · Jun 21, 2024 · 906f791 · 906f791
1 parent c5822d1
commit 906f791
Show file tree

Hide file tree

Showing 3 changed files with 281 additions and 0 deletions.
diff --git a/docs/cspell.json b/docs/cspell.json
@@ -778,6 +778,7 @@
     "reviewee",
     "rffx",
     "roadmap",
+    "rolesanywhere",
     "rolearn",
     "rolebinding",
     "rolebindings",

diff --git a/docs/pages/machine-id/workload-identity.mdx b/docs/pages/machine-id/workload-identity.mdx
@@ -148,6 +148,7 @@ Teleport's Workload Identity currently only supports issuing X.509-SVIDs.
 - [Getting Started](./workload-identity/getting-started.mdx): How to configure Teleport for Workload Identity.
 - [Best Practices](./workload-identity/best-practices.mdx): Best practices for using Workload Identity in Production.
 - [TSH Support](./workload-identity/tsh.mdx): How to use `tsh` with Workload Identity to issue SVIDs to users.
+- [AWS Roles Anywhere](./workload-identity/aws-roles-anywhere.mdx): Configuring AWS to accept Workload ID certificates as authentication using AWS Roles Anywhere.
 
 ### Other resources
 

diff --git a/docs/pages/machine-id/workload-identity/aws-roles-anywhere.mdx b/docs/pages/machine-id/workload-identity/aws-roles-anywhere.mdx
@@ -0,0 +1,279 @@
+---
+title: Configuring Workload ID and AWS Roles Anywhere
+description: Configuring AWS to accept Workload ID certificates as authentication using AWS Roles Anywhere
+---
+
+Teleport Workload Identity issues flexible short-lived identities in X.509
+certificates. AWS Roles Anywhere allows you to use these certificates to
+authenticate to AWS services.
+
+This can be useful in cases where a machine needs to securely authenticate with
+AWS services without the use of a long-lived credential. This is because the
+machine can authenticate with Teleport without using any shared secrets by
+using one of our delegated join methods.
+
+## How it works
+
+This implementation differs from using the Teleport Application Service to protect
+AWS APIs in a few ways:
+
+- Requests to AWS are not proxied through the Teleport Proxy Service, meaning
+  reduced latency but also less visibility, as these requests will not be
+  recorded in Teleport's audit log.
+- Workload ID works with any AWS client, including the command-line tool but also
+  their SDKs
+- Using the Teleport Application Service to access AWS does not work with Machine ID
+  and therefore cannot be used when a machine needs to authenticate with AWS.
+
+Whilst this guide is primarily aimed at allowing a machine to access AWS,
+the `tsh svid issue` command can be used in place of Machine ID to allow a human
+user to authenticate with using AWS Roles Anywhere.
+
+## Prerequisites
+
+(!docs/pages/includes/edition-prereqs-tabs.mdx!)
+
+- (!docs/pages/includes/tctl.mdx!)
+- `tbot` must already be installed and configured on the host where the
+workloads which need to access Teleport Workload Identity will run. For more
+information, see the [deployment guides](../deployment.mdx).
+
+### Deciding on a SPIFFE ID structure
+
+Within Teleport Workload Identity, all identities are represented using a
+SPIFFE ID. This is a URI that uniquely identifies the entity that the identity
+represents. The scheme is always `spiffe://`, and the host will be the name of
+your Teleport cluster. The structure of the path of this URI is up to you.
+
+For the purposes of this guide, we will be granting access to AWS to the
+`spiffe://example.teleport.sh/svc/example-service` SPIFFE ID.
+
+If you have already deployed Teleport Workload Identity, then you will already
+have a SPIFFE ID structure in place. If you have not, then you will need to
+decide on a structure for your SPIFFE IDs.
+
+If you are only using Teleport Workload ID with AWS Roles Anywhere, you way
+structure your SPIFFE IDs so that they explicitly specify the AWS role they are
+allowed to assume. However, it often makes more sense to name the workload or
+person that will use the SPIFFE ID. See the
+[best practices guide](./best-practices.mdx) for further advice.
+
+## Step 1/4. Configure AWS Roles Anywhere
+
+Configuring AWS Roles Anywhere for the first time involves a few steps. Some
+of these may not be necessary if you have previously configured AWS Roles
+Anywhere for your Teleport cluster.
+
+### Configure a Roles Anywhere Trust Anchor
+
+If you have previously configured AWS Roles Anywhere for your Teleport cluster,
+you can skip this step.
+
+First, we must establish trust between your Teleport cluster and your AWS
+Roles Anywhere. This will allow AWS to validate X.509 certificates that are
+issued by your Teleport cluster. This is done by configuring the Teleport
+cluster's SPIFFE certificate authority as the trust anchor for AWS Roles
+Anywhere.
+
+First, you must obtain your Teleport cluster's SPIFFE CA:
+
+```shell
+$ tctl auth export --type spiffe
+```
+
+Now, navigate to "Roles Anywhere" in the AWS console and click "Create a trust
+anchor". You will need to give it a descriptive name, we suggest using the
+name of your Teleport cluster with "spiffe" appended.
+
+Select "External certificate bundle" and then paste the output you received
+from the `tctl` command into the text box.
+
+You can now click the "Create trust anchor" button.
+
+### Create a Role
+
+Next, we must create a role in AWS for your workload to assume. You may also
+modify the trust policy of an existing role if you prefer.
+
+Navigate to the "Roles" section of the AWS IAM console and click "Create role".
+
+For the "Trusted entity type" select "Custom trust policy".
+
+You will now enter the following:
+
+```json
+{
+    "Version": "2012-10-17",
+    "Statement": [
+        {
+            "Effect": "Allow",
+            "Principal": {
+                "Service": "rolesanywhere.amazonaws.com"
+            },
+            "Action": [
+                "sts:AssumeRole",
+                "sts:TagSession",
+                "sts:SetSourceIdentity"
+            ],
+            "Condition": {
+                "StringEquals": {
+                    "aws:PrincipalTag/x509SAN/URI": "spiffe://example.teleport.sh/svc/example-service"
+                },
+                "ArnEquals": {
+                    "aws:SourceArn": "arn:aws:rolesanywhere:us-east-1:12345789:trust-anchor/0000000-0000-0000-0000-000000000000"
+                }
+            }
+        }
+    ]
+}
+```
+
+Replace:
+
+- `spiffe://example.teleport.sh/my-workload` with the SPIFFE ID you have chosen
+  for your workload.
+- `arn:aws:rolesanywhere:us-east-1:12345789:trust-anchor/0000000-0000-0000-0000-000000000000`
+  with the ARN of the trust anchor you created in the previous step.
+
+Click "Next" to proceed to the "Add permissions" page. Now select the
+permissions you wish to grant to your workload on AWS.
+
+Click "Next" to proceed to the "Name, review, and create" page. Give your role
+a descriptive name, e.g "my-workload-roles-anywhere".
+
+Click "Create role".
+
+### Create a Roles Anywhere Profile
+
+Finally, you must create a Roles Anywhere profile.
+
+Navigate back to the "Roles Anywhere" section of the AWS IAM console and click
+"Create a profile".
+
+Give your profile a descriptive name, e.g "my-workload".
+
+Select the role you created in the previous step.
+
+Click "Create profile".
+
+## Step 2/4. Configure Teleport RBAC
+
+Now we need to configure Teleport to allow a X.509 certificate to be issued
+containing the SPIFFE ID we have chosen.
+
+```yaml
+kind: role
+version: v6
+metadata:
+  name: my-workload-roles-anywhere
+spec:
+  allow:
+    spiffe:
+      - path: /svc/example-service
+```
+
+Replace:
+
+- `my-workload-roles-anywhere` with a descriptive name for the role.
+- `/my-workload` with the path part of the SPIFFE ID you have chosen.
+
+If you intend this SPIFFE ID to be issued by a human, you now need to assign
+this role to their user:
+
+```shell
+$ tctl edit user/my-user
+# And add the role to the user's roles list
+```
+
+If you intend this SPIFFE ID to be issued by a machine, you now need to assign
+this role to the bot:
+
+```shell
+$ tctl bots update my-bot --add-roles my-workload-roles-anywhere
+```
+
+## Step 3/4. Issue Workload ID certificates
+
+### For machines using `tbot`
+
+For machines, the `tbot` service can be used to issue and renew SPIFFE SVIDs
+as a background process.
+
+Take your already deployed `tbot` service and configure it to issue SPIFFE SVIDs
+by adding the following to the `tbot` configuration file:
+
+```yaml
+outputs:
+  - type: spiffe-svid
+    destination:
+      type: directory
+      path: /opt/roles-anywhere-svid
+    svid:
+      path: /svc/example-service
+```
+
+Restart your `tbot` service to apply the new configuration.
+
+### For humans using `tsh`
+
+For humans, the `tsh` CLI can be used to issue a SPIFFE SVID using their
+pre-existing authentication session.
+
+The `tsh` command will need to be re-invoked when the SVID expires. By default,
+SVIDs are issued with a TTL of 1 hour, but this can be configured to be up to
+24 hours. It can be convenient to configure this to around 8 hours to allow
+an engineer to run the command once at the start of their working day.
+
+For example, to issue a SPIFFE SVID for `/svc/example-service` with an 8 hour
+TTL:
+
+```shell
+$ tsh svid issue --output /opt/roles-anywhere-svid --svid-ttl 8h /svc/example-service
+```
+
+## Step 4/4. Configure the AWS CLI and SDKs to use Roles Anywhere to authenticate
+
+In order for AWS to use the SVID for authentication, you must also install the
+AWS Roles Anywhere credential helper. This is a small utility that the AWS
+CLI and SDKs will use to exchange the SVID for a temporary AWS credential.
+
+Obtain the latest release of the credential helper from the
+[Obtaining temporary security credentials from AWS Identity and Access Management Roles Anywhere](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/credential-helper.html)
+guide.
+
+Now, you need to configure a profile that leverages this credential helper.
+
+Add the following to your `~/.aws/config` file:
+
+```ini
+[profile use-roles-anywhere]
+credential_process = ./aws_signing_helper credential-process --certificate /opt/roles-anywhere-svid/svid.pem --private-key /opt/roles-anywhere-svid/svid_key.pem --profile-arn $PROFILE_ARN --trust-anchor-arn $TRUST_ANCHOR_ARN --role-arn $ROLE_ARN
+```
+
+Replace $PROFILE_ARN, $TRUST_ANCHOR_ARN, and $ROLE_ARN with the ARNs of the
+profile, trust anchor, and role you created in the previous steps.
+
+You can now use the `use-roles-anywhere` profile with the AWS CLI, for example:
+
+```shell
+$ aws --profile use-roles-anywhere s3 ls
+```
+
+You can also use this profile with the AWS SDKs by setting the `AWS_PROFILE`
+environment variable:
+
+```shell
+$ export AWS_PROFILE=use-roles-anywhere
+$ ./my-app
+```
+
+## Next steps
+
+- [AWS Roles Anywhere documentation](https://docs.aws.amazon.com/rolesanywhere/latest/userguide/introduction.html):
+The official AWS documentation for Roles Anywhere.
+- [Workload Identity Overview](../workload-identity.mdx): Overview of Teleport
+Workload Identity.
+- [Best Practices](./best-practices.mdx): Best practices for using Workload
+Identity in Production.
+- Read the [configuration reference](../reference/configuration.mdx) to explore
+all the available configuration options.