OIDC
OIDC can be used to safely and securely authenticate to your cloud provider using temporary credentials.
To use OIDC, you will first need to configure your cloud provider to trust the GitHub OIDC as a federated identity. Terrateam can then be configured to authenticate to your cloud provider using OIDC.
See Cloud Provider Setup documentation to learn how to connect the GitHub OpenID Connect Identity Provider to your cloud provider.
Credentials are never stored on our servers.
Configuration
Terrateam Configuration
Terrateam behavior can be configured via a config.yml
. This file is located in
a directory named .terrateam
at the root of your Terraform repository:
.terrateam/config.yml
.
See Configuration documentation for details.
OIDC can be configured using Hooks or Workflows depending on the complexity of your requirements. OIDC configuration blocks are identical in both top-level keys.
Key | Type | Description |
---|---|---|
oidc | List | Initiate an OIDC connection to a cloud provider. |
provider | String | Name of provider: aws . |
role_arn | String | Specifies the ARN of an IAM role that you want to use. |
assume_role_arn | String | Specifies the ARN of an IAM role that you want to assume into. Default is the value of role_arn . |
assume_role_enabled | Boolean | Retrieve a set of temporary security credentials from AWS and set the AWS_ACCESS_KEY_ID , AWS_SECRET_ACCESS_KEY , and AWS_SESSION_TOKEN environment variables. Default is true . |
audience | String | Specifies the AWS audience name to use. Default is sts.amazonaws.com . |
region | String | Specifies the AWS region to use and sets the AWS_REGION environment variable. Default is us-east-1 . |
session_name | String | Specifies the AWS session name. Default is terrateam . |
duration | Integer | Specifies the AWS session duration in seconds. Default is 3600 . |
Example configuration using all keys:
This is a partial configuration. The oidc
block must be configured under top-level keys hooks
or workflows
.
See below for detailed examples.
- type: oidc
provider: aws
role_arn: "arn:aws:iam::123456789012:role/terrateam"
assume_role_arn: "arn:aws:iam::987654321012:role/terrateam"
assume_role_enabled: true
audience: "sts.amazonaws.com"
region: "us-east-1"
session_name: "terrateam"
duration: 3600
Single IAM role
Authenticates using a single IAM role for all Terrateam operations:
hooks:
all:
pre:
- type: oidc
provider: aws
role_arn: "arn:aws:iam::123456789012:role/terrateam"
Separate IAM role per environment
It's possible to use separate IAM roles per environment. In the example Terraform repository layout below, environments are split out by directory:
josh@elmer:~ $ tree terraform/
terraform/
├── production
│ └── app
│ └── frontend
│ └── main.tf
└── staging
└── app
└── frontend
└── main.tf
6 directories, 2 files
josh@elmer:~ $
To use a separate IAM role for the production
and staging
directories/environments, the .terrateam/config.yml
can be configured with the following:
workflows:
- tag_query: dir:staging
plan:
- type: oidc
provider: aws
role_arn: "arn:aws:iam::123456789012:role/terrateam-staging-role"
- type: init
- type: plan
apply:
- type: oidc
provider: aws
role_arn: "arn:aws:iam::123456789012:role/terrateam-staging-role"
- type: init
- type: apply
- tag_query: dir:production
plan:
- type: oidc
provider: aws
role_arn: "arn:aws:iam::123456789012:role/terrateam-production-role"
- type: init
- type: plan
apply:
- type: oidc
provider: aws
role_arn: "arn:aws:iam::123456789012:role/terrateam-production-role"
- type: init
- type: apply
Separate IAM roles per environment and operation
Building off of the previous example, one could use separate IAM roles for Plan and Apply operations.
workflows:
- tag_query: dir:staging
plan:
- type: oidc
provider: aws
role_arn: "arn:aws:iam::123456789012:role/terrateam-staging-plan-role"
- type: init
- type: plan
apply:
- type: oidc
provider: aws
role_arn: "arn:aws:iam::123456789012:role/terrateam-staging-apply-role"
- type: init
- type: apply
- tag_query: dir:production
plan:
- type: oidc
provider: aws
role_arn: "arn:aws:iam::123456789012:role/terrateam-production-plan-role"
- type: init
- type: plan
apply:
- type: oidc
provider: aws
role_arn: "arn:aws:iam::123456789012:role/terrateam-production-apply-role"
- type: init
- type: apply
Assuming into another role
Sometimes it's desired to assume into another role before performing an operation. This
can be achieved with the assume_role_arn
configuration.
Terrateam will retreive a web identity token from AWS using the ARN defined in role_arn
and then perform an aws sts assume-role-with-web-identity
using the specified ARN in
assume_role_arn
which will return temporary credentials for the assume role arn. The
AWS Terraform provider will use the newly created temporary credentials.
workflows:
- tag_query: ""
plan:
- type: oidc
provider: aws
role_arn: "arn:aws:iam::999999999999:role/terrateam-aws-management-account"
assume_role_arn: "arn:aws:iam::123456789012:role/terrateam-operations"
- type: init
- type: plan