AWS OIDC Integration

This guide explains how to set up the Teleport AWS OIDC integration.

With the AWS OIDC integration you will no longer need to deploy Teleport agents in AWS manually for most use cases. The following features use an AWS OIDC integration to interact with AWS:

• External Audit Storage
• RDS Auto Discovery
• EC2 Auto Discovery
• Access Graph AWS Sync

It targets users who would prefer a more manual approach or to manage the integration with Infrastructure as Code tools.

As an alternative to this guide, you can use the Teleport Web UI (Access Management / Enroll New Integration).

How it works

Teleport is added as an OpenID Connect identity provider to establish trust with your AWS account and assume a configured IAM role in order to access AWS resources.

For this to work, the openid-configuration and public keys are exposed in a public S3 bucket. The integration requires no extra configuration or services to run.

Initially, no policy is added to the IAM role, but users are asked to add them the first time they are trying to use a given feature. For example, when setting up External Audit Storage, you will be asked to add the required policies to this IAM role.

Prerequisites

• A running Teleport cluster.
• AWS Account with permissions to create public S3 buckets, IAM Identity Providers and roles

Step 1/5. Configure RBAC

To configure the integration you will need the following allow rules in one of your Teleport roles. These are available by default in the preset editor role:

kind: role
version: v7
metadata:
  name: example
spec:
  allow:
    rules:
    - resources:
      - integration
      verbs:
      - create
      - update
      - list
      - read
      - delete
      - use

Step 2/5. Upload public keys to S3

The AWS OIDC integration uses OpenID Connect to grant access to AWS APIs. Configuring OpenID Connect requires exposing the configuration file and the public keys, which AWS fetches to validate the requests.

Those files should be exposed in S3, for which we'll need to pick a bucket s3-bucket and a prefix s3-prefix.

Download the current configuration and public keys:

mkdir .well-known
curl https://teleport.example.com/.well-known/openid-configuration > .well-known/openid-configuration
curl https://teleport.example.com/.well-known/jwks-oidc > .well-known/jwks

Edit the openid-configuration and replace the issuer and jwks_uri fields with with the S3 location:

{
  "issuer": "s3-bucket.s3.amazonaws.com/s3-prefix",
  "jwks_uri": "https://s3-bucket.s3.amazonaws.com/s3-prefix/.well-known/jwks",
  // other fields
}

Upload those files to s3-bucket bucket:

s3-bucket└── s3-prefix    └── .well-known        ├── openid-configuration        └── jwks

Make those objects public (either using Bucket Policies or ACLs):

$ curl https://s3-bucket.s3.amazonaws.com/s3-prefix/.well-known/openid-configuration
$ curl https://s3-bucket.s3.amazonaws.com/s3-prefix/.well-known/jwks

Step 3/5. Configure the Identity Provider in AWS

Navigate to AWS IAM Identity Provider and configure the Identity Provider:

• Provider type: OpenID Connect
• Provider URL:

https://s3-bucket.s3.amazonaws.com/s3-prefix

• Audience: discover.teleport

Step 4/5. Create IAM role

An IAM role must be created to assign the required policies to the integration iam-role.

This IAM role is created without any policy, as those are added depending on the feature you would like to use, for example when setting up Access Graph AWS Sync. However, it must be configured to allow the Identity Provider to assume it. To achieve this, add the following Trust Relationship:

{
	"Version": "2012-10-17",
	"Statement": [
		{
			"Effect": "Allow",
			"Principal": {
				"Federated": "arn:aws:iam::aws-account-id:oidc-provider/s3-bucket.s3.amazonaws.com/s3-prefix"
			},
			"Action": "sts:AssumeRoleWithWebIdentity",
			"Condition": {
				"StringEquals": {
					"s3-bucket.s3.amazonaws.com/s3-prefix:aud": "discover.teleport"
				}
			}
		}
	]
}

It is also required to add the following tags, which are used by Teleport to ensure it can change the IAM role when onboarding new features:

teleport.dev/cluster      cluster-nameteleport.dev/origin       integration_awsoidcteleport.dev/integration  my-integration

Step 5/5. Create integration resource

Create a file called awsoidc-integration.yaml with the following content:

kind: integration
sub_kind: aws-oidc
version: v1
metadata:
  name: my-integration
spec:
  aws_oidc:
    role_arn: "arn:aws:iam::aws-account-id:role/iam-role"
    issuer_s3_uri: s3://s3-bucket/s3-prefix

We specify the IAM role and the S3 URI which has the openid-configuration and public keys.

Create the resource:

tctl create -f awsoidc-integration.yaml
integration 'my-integration' has been created

After the set up is complete, you can now use the "Enroll New Resource" flow in Teleport Web UI, or other integration dependent features.

Next steps

Now that you have an integration, you can use the following features:

• Access Graph AWS Sync
• External Audit Storage