From 906f7914b359a705612a71f894de1729587ccda5 Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Fri, 21 Jun 2024 16:15:57 +0100 Subject: [PATCH] [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 * Update docs/pages/machine-id/workload-identity/aws-roles-anywhere.mdx Co-authored-by: Paul Gottschling * 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 * Update docs/pages/machine-id/workload-identity/aws-roles-anywhere.mdx Co-authored-by: Paul Gottschling --------- Co-authored-by: Paul Gottschling --- docs/cspell.json | 1 + docs/pages/machine-id/workload-identity.mdx | 1 + .../workload-identity/aws-roles-anywhere.mdx | 279 ++++++++++++++++++ 3 files changed, 281 insertions(+) create mode 100644 docs/pages/machine-id/workload-identity/aws-roles-anywhere.mdx diff --git a/docs/cspell.json b/docs/cspell.json index 4771d20acd9ee..459dd9cc76d4e 100644 --- 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 index ac2972b3a71a7..781da52f870da 100644 --- 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 new file mode 100644 index 0000000000000..48fd54e6415cb --- /dev/null +++ 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. \ No newline at end of file