Skip to main content
Version: 17.x (unreleased)

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:

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 automatically exposed in your cluster at:

$ curl https://teleport.example.com/.well-known/openid-configuration

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.

AWS resources created by the integration are tagged so that you can search and export them using the AWS Resource Groups / Tag Editor. The following tags are applied:

teleport.dev/cluster      cluster-name
teleport.dev/origin       integration_awsoidc
teleport.dev/integration  my-integration

Prerequisites​

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

Step 1/4. 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/4. Configure the Identity Provider in AWS​

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

  • Provider type: OpenID Connect
  • Provider URL:
https://teleport.example.com
  • Audience: discover.teleport

You should also add the following tags to help you track the resource in the future:

teleport.dev/cluster      cluster-name
teleport.dev/origin       integration_awsoidc
teleport.dev/integration  my-integration

Step 3/4. 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/teleport.example.com"
			},
			"Action": "sts:AssumeRoleWithWebIdentity",
			"Condition": {
				"StringEquals": {
					"teleport.example.com: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-name
teleport.dev/origin       integration_awsoidc
teleport.dev/integration  my-integration

Step 4/4. 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"

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: