Authentication for Terraform

This document describes how to authenticate to Google Cloud when using Terraform.

Application Default Credentials (ADC) is the recommended way to authenticate to Google Cloud when using Terraform. ADC is a strategy used by the authentication libraries to automatically find credentials based on the application environment. When you use ADC, Terraform can run in either a development or production environment without changing how it authenticates to Google Cloud services and APIs. For information about where ADC looks for credentials and in what order, see How Application Default Credentials works.

Authenticate when using Terraform in a local development environment

When you're using Terraform in a local development environment, such as a development workstation, you can authenticate using the credentials associated with your user account or service account.

Authenticate using a Google Account

To configure ADC with a Google Account, you use the Google Cloud CLI:

1. Install the Google Cloud CLI, then initialize it by running the following command:

   gcloud init

2. If you're using a local shell, then create local authentication credentials for your user account:

   gcloud auth application-default login

   You don't need to do this if you're using Cloud Shell.

   A sign-in screen appears. After you sign in, your credentials are stored in the local credential file used by ADC.

Authenticate using an external account

To configure ADC for a user account managed by an external identity provider:

1. Configure Workforce Identity Federation.

2. Configure the gcloud CLI to use Workforce Identity Federation.

3. Configure ADC by running the following command:

   gcloud auth application-default login

   A sign-in screen appears. After you sign in, your credentials are stored in the local credential file used by ADC.

Authenticate using service account impersonation

You can use service account impersonation to set up a local ADC file. Terraform uses those credentials automatically.

1. Make sure you must have the Service Account Token Creator (roles/iam.serviceAccountTokenCreator) IAM role on the service account you are impersonating. For more information, see Required roles.

2. Use service account impersonation to create a local ADC file by running the following command:

   gcloud auth application-default login --impersonate-service-account SERVICE_ACCT_EMAIL
   

If you want to allow users to use a shared primary authentication source and a variable service account per environment, set the impersonate_service_account field in your Terraform configuration file:

provider "google" {
  impersonate_service_account = "SERVICE_ACCT_EMAIL"
}

Authenticate when running Terraform on Google Cloud

When running Terraform on a Google Cloud cloud-based development environment such as Cloud Shell, the tool uses the credentials you provided when you signed in for authentication.

When using Terraform with Google Cloud services such as Compute Engine, App Engine, and Cloud Run functions, you can attach a user-managed service account to resources. Generally, attaching a service account is supported when that service's resources can run or include application code. When you attach a service account to a resource, the code running on the resource can use that service account as its identity.

Attaching a user-managed service account is the preferred way to provide credentials to ADC for production code running on Google Cloud.

Note: Many of these Google Cloud services also provide a default service account. Using the default service account is not recommended, because by default the default service account is highly privileged, which violates the principle of least privilege.

For help determining the roles that you need to provide to your service account, see Choose predefined roles.

For information about which resources you can attach a service account to, and help with attaching the service account to the resource, see the IAM documentation on attaching a service account.

Set up authentication:

1. Create the service account:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

   Replace SERVICE_ACCOUNT_NAME with a name for the service account.

2. To provide access to your project and your resources, grant a role to the service account:

   gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

   Replace the following:

   • SERVICE_ACCOUNT_NAME: the name of the service account
   • PROJECT_ID: the project ID where you created the service account
   • ROLE: the role to grant
   Note: The --role flag affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
3. To grant another role to the service account, run the command as you did in the previous step.

4. Grant the required role to the principal that will attach the service account to other resources.

   gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser

   Replace the following:

   • SERVICE_ACCOUNT_NAME: the name of the service account
   • PROJECT_ID: the project ID where you created the service account
   • USER_EMAIL: the email address for a Google Account

Authenticate when running Terraform on-premises or on a different cloud provider

If you are running your application outside of Google Cloud, you need to provide credentials that are recognized by Google Cloud to use Google Cloud services.

Authenticate using Workload Identity Federation

The preferred way to authenticate with Google Cloud using credentials from an external IdP is to use Workload Identity Federation. You can create a credential configuration file and set the GOOGLE_APPLICATION_CREDENTIALS environment variable to point to it. This approach is more secure than creating a service account key. For instructions on setting up Workload Identity Federation for ADC, see Workload Identity Federation with other clouds.

Authenticate using service account keys

When running Terraform in a local development environment, on premises, or a different cloud provider, you can create a service account, grant it the IAM roles that your application requires, and create a key for the service account.

Note: Service account keys are a security risk if not managed correctly. You should choose a more secure alternative to service account keys whenever possible. If you must authenticate with a service account key, you are responsible for the security of the private key and for other operations described by Best practices for managing service account keys. If you are prevented from creating a service account key, service account key creation might be disabled for your organization. For more information, see Managing secure-by-default organization resources.

To create a service account key and make it available to ADC:

1. Create a service account with the roles your application needs, and a key for that service account, by following the instructions in Creating a service account key.

   Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

   Example: Linux or macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   Example: Windows

   For PowerShell:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

   For command prompt:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

Authenticate to Cloud Storage backends

Terraform lets you configure Cloud Storage as a backend to store Terraform state files. To authenticate to a Cloud Storage backend, use any of the methods described on this page. For information on configuration variables related to authentication for Cloud Storage backends, see the Terraform backends page for Cloud Storage.

What's next

• Work through the Terraform for Google Cloud quickstart
• Learn about the basic Terraform commands.