A Terraform run may need to read remote state and deploy cloud resources. Both tasks require authentication: the receiving system must map a request to an identity, such as a user or machine. Authentication establishes who is making the request; authorization determines what that identity may do. section 6.4.4 section 8.5.1
Choose how credentials reach Terraform without unnecessarily putting them in configuration:
- Avoid hardcoding backend credentials in a backend block or configuration file; doing so can be insecure and makes the configuration less portable. section 6.4.4
- Use an external configuration file when the backend supports one. AWS, Azure, and GCP can use files in their default locations. section 6.4.4
- Use environment variables where supported, particularly in CI/CD systems that expose secrets this way. Provider authentication values are also commonly supplied by the shared systems that run Terraform, rather than tracked as ordinary configuration. section 6.4.4 section 5.4.4
Backend authentication differs by backend, so check the chosen backend’s documentation. Do not confuse authentication environment variables with `TF_VAR_` variables: the latter set Terraform input variables, whereas provider credentials often belong outside the tracked configuration. section 6.4.4 section 5.4.4
OpenID Connect (OIDC) offers another pattern for deployment systems. Register the CI/CD platform’s provider URL with the cloud vendor so the vendor can accept identities asserted by that identity provider. For GitHub Actions, the URL is `https://token.actions.githubusercontent.com`. Registration establishes authentication, not permission to deploy: AWS also needs an assumable IAM role, or Azure a mapped service principal. Restrict the relationship to the intended repository and workflows. section 8.5.1
Listing 8.13 Registering an OIDC provider with AWS
locals {
gh_actions_token_url = "https://token.actions.githubusercontent.com" #1
}
data "tls_certificate" "gh_actions" {
url = local.gh_actions_token_url #2
}
resource "aws_iam_openid_connect_provider" "github" { #3
url = local.gh_actions_token_url #4
thumbprint_list = data.tls_certificate.gh_actions.certificates[*].
sha1_fingerprint #5
client_id_list = ["sts.amazonaws.com"] #6
}
#1 This is the URL for the GitHub Actions OIDC token service.
#2 OIDC uses the TLS certificate to verify the identity of the service.
#3 This resource should only be called once per account per url.
#4 These values comes from the GitHub Actions documentation.
#5 This is the SHA1 fingerprint of the certificates attached to the GitHub OIDC service.
#6 For AWS, you will almost always use the security token service as the client.
An AWS OIDC provider resource registers the GitHub Actions token URL. A TLS certificate data source supplies certificate fingerprints, while the provider specifies `sts.amazonaws.com` as a client ID. section 8.5.1
Listing 8.14 Allowing a GitHub Actions workflow to assume a role
jobs:
terraform:
name: Run Terraform against AWS
runs-on: ubuntu-latest
permissions: #1
id-token: write #1
contents: read #1
steps:
- name: Checkout #2
uses: actions/checkout@v4
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v4 #3
with:
role-to-assume: arn:aws:iam::999999999999:role/github-actions-${{
github.repository }} #4
region: us-west-2 #5
#1 The AWS action needs the OIDC token to be accessible.
#2 Checkout our repository.
#3 This action is published by AWS and converts the OIDC token into AWS credentials.
#4 When using OIDC you have to tell AWS what role you want to assume.
#5 AWS requires a region when logging in.
A GitHub Actions job requests access to an OIDC token and uses the AWS credentials action to assume a named role. That role must separately be configured to trust the appropriate identity. section 8.5.1
For an automated run, settle both questions before deployment: how will the backend and provider receive authentication, and which actions will the resulting identity be authorized to perform? An orchestrator’s user authentication and role-based access control are related operational features, not substitutes for configuring cloud access. section 6.4.4 section 8.5.1 section 8.6.1
