Terraform identity authentication - Terraform - Alibaba Cloud Documentation Center

This topic describes the identity authentication methods of Alibaba Cloud Terraform Provider.

Overview

Before you use Terraform to manage Alibaba Cloud infrastructure resources, you must pass the identity authentication of Alibaba Cloud Terraform Provider. After you pass the identity authentication, you can use Terraform to call Alibaba Cloud API operations and create and manage Alibaba Cloud infrastructure resources.

Alibaba Cloud Terraform Provider supports multiple identity authentication methods. You can select a method based on the environment in which Terraform is installed and run and also based on your scenario. The following table describes the identity authentication methods of Alibaba Cloud Terraform Provider.

Authentication method	Description	Scenario
Static credentials	Define access credentials such as an AccessKey pair in plaintext in a configuration file or specify access credentials by using variables.	Testing and verification of the development environment Continuous integration and continuous delivery (CI/CD) resource management
Environment variables	Store access credentials such as an AccessKey pair in environment variables. If no static credential is defined, Terraform reads access credentials from environment variables.	Testing and verification of the development environment Independent runtime environments such as an Elastic Compute Service (ECS) instance
Resource Access Management (RAM) role of an ECS instance	Obtain the access credentials of a RAM role that is attached to an ECS instance from the metadata of the ECS instance.	Scenario in which Terraform is run on an ECS instance
RAM role	Obtain access credentials by assuming a RAM role.	Multi-account resource management CI/CD resource management
RAM role of an OpenID Connect (OIDC) identity provider (IdP)	Obtain access credentials by assuming the RAM role of an OIDC IdP.	Scenario in which Terraform is run in a Container Service for Kubernetes (ACK) cluster
Shared profile	Configure the preceding identity authentication methods in a unified file by using Alibaba Cloud CLI and obtain access credentials based on the name of the profile to be used.	Multi-account and multi-region resource management Testing and verification of the development environment Multi-environment resource management

Authentication methods

The following sections describe the identity authentication methods of Alibaba Cloud Terraform Provider.

Static credentials

You can define access credentials in the provider code block of a Terraform configuration file. Sample code:

provider "alicloud" {
  access_key = "<Your AccessKey ID>"
  secret_key = "<Your AccessKey secret>"
  # If you use a Security Token Service (STS) token, specify the security_token parameter.
  # security_token = "<Your STS token>"
}

For security purposes, we recommend that you specify access credentials by using variables and do not specify default values for the variables. We recommend that you do not define access credentials in plaintext in a configuration file.

variable "access_key_id" {
  description = "The AccessKey ID for operating your infrastructure"
}
variable "access_key_secret" {
  description = "The AccessKey Secret for operating your infrastructure"
}
variable "security_token" {
  description = "The Security Token for operating your infrastructure"
}
provider "alicloud" {
  access_key = var.access_key_id
  secret_key = var.access_key_secret
  # If you use an STS token, specify the security_token parameter.
  # security_token = var.security_token
}

When you run a Terraform command, you can use the -var option to specify the values of the variables.

$ terraform plan -var access_key_id="<Your AccessKey ID>" -var access_key_secret="<Your AccessKey Secret>" -var security_token="<Your STS token>"

Environment variables

You can store access credentials in specific environment variables. When you run a Terraform command, if no access credential is declared in the configuration file, Terraform can obtain access credentials from environment variables. Sample code for configuring environment variables:

Linux

Important

Temporary environment variables configured using the export command are only valid for the current session. Once the session is exited, the configured environment variables are lost. To retain the environment variables permanently, you can add the export command to the startup configuration file of the operating system.

# AccessKey Id
$ export ALICLOUD_ACCESS_KEY="<Your AccessKey ID>"
# AccessKey Secret
$ export ALICLOUD_SECRET_KEY="<Your AccessKey secret>"
# If you use STS credentials, you must configure security_token.
$ export ALICLOUD_SECURITY_TOKEN="<Your access token>"

Windows

On the Windows desktop, right-click This PC and choose Properties > Advanced system settings > Environment Variables > System variables or User variables

In the System variables or User variables section, click Create to create the following variables:

Variable	Description	Value
ALICLOUD_ACCESS_KEY	AccessKey ID	Example: yourAccessKeyID
ALICLOUD_SECRET_KEY	AccessKey secret	Example: yourAccessKeySecret
ALICLOUD_SECURITY_TOKEN (Optional)	If you use STS credentials, you must configure the security token.	Example: yourSTSToken

After you configure environment variables, you do not need to declare access credentials or you can declare only the region ID in the provider code block of a configuration file.

provider "alicloud" {
  region = "cn-hangzhou"
}

You can also specify the region ID by using the ALICLOUD_REGION environment variable. If no region ID is declared and the ALICLOUD_REGION environment variable is not configured, cn-beijing is used as the default value of the region parameter.

Compared with static credentials, environment variables are easier to use and more secure.

RAM role of an ECS instance

When Terraform is run on an ECS instance to manage Alibaba Cloud resources, you can attach a RAM role to the ECS instance to automatically obtain and refresh the STS token of the RAM role on the ECS instance. In this case, you do not need to expose your AccessKey pair, which reduces the risks of AccessKey pair leaks. You can also use the fine-grained access control of the RAM role to prevent excessive permissions from being granted. For more information, see Instance RAM roles.

To configure the RAM role of an ECS instance for identity authentication, perform the following steps:

Prepare an ECS instance that can access the Internet.
Create a RAM role and attach the RAM role to the ECS instance.
Define the ecs_role_name parameter in the provider code block and specify the name of the RAM role as the value of this parameter.

provider "alicloud" {
  ecs_role_name = "<Name of the RAM role that is attached to the ECS instance>"
}

You can also specify the name of the RAM role by using the ALICLOUD_ECS_ROLE_NAME environment variable.

The RAM role of an ECS instance is more secure. When Terraform is run on an ECS instance, we recommend that you use this authentication method.

RAM role

In most cases, a RAM user or a RAM role assumed by a cloud service such as ECS accesses and manages Alibaba Cloud resources. In this case, the AccessKey pair of the RAM user or the STS token of the RAM role assumed by the cloud service is used as access credentials. Their access permissions are determined by the policies that are attached to the RAM user or the RAM role assumed by the cloud service. If you want to separate the access permissions required by Terraform from the access permissions of the RAM user or the RAM role assumed by the cloud service or access cloud resources across accounts, you can assign a RAM role to the RAM user or the RAM role assumed by the cloud service. Then, the RAM role obtains an STS token to access Alibaba Cloud resources.

The RAM role-based authentication method is implemented based on the AssumeRole operation. Before you configure a RAM role for identity authentication in Terraform, make the following preparations:

Create a RAM user and attach the AliyunSTSAssumeRoleAccess system policy to the RAM user. In this case, the RAM user is granted the permissions to call the AssumeRole operation.
Create an AccessKey pair for the RAM user. The AccessKey pair can be used to call the AssumeRole operation in Terraform to obtain an STS token.
Create a RAM role whose trusted entity is an Alibaba Cloud account, attach the RAM policies of cloud services that you want to access to the RAM role, such as the AliyunOSSFullAccess policy that is used to access Object Storage Service (OSS), and then record the Alibaba Cloud Resource Name (ARN) of the RAM role.
Write a custom RAM policy that is used to access cloud resources based on your business requirements. For example, you can write a custom policy to access all buckets only in the China (Hangzhou) region. This custom policy is used to grant permissions to the RAM role together with the RAM policies of cloud services that are attached in the previous step. This implements fine-grained access control.

After you perform the preceding steps, declare the RAM role for identity authentication in the following provider code block:

provider "alicloud" {
  # The AccessKey ID of the RAM user that is granted the permissions to call the AssumeRole operation.
  access_key = "<AccessKey ID of the RAM user>"
  # The AccessKey secret of the RAM user that is granted the permissions to call the AssumeRole operation.
  secret_key = "<AccessKey secret of the RAM user>"
  assume_role {
    role_arn           = "<ARN of the RAM role>"
    policy             = "<RAM policy>"
    session_name       = "<Custom session name of the RAM role>"
    session_expiration = <Validity period of the STS token>
  }
}

When you configure a RAM role for identity authentication in Terraform, the following parameters are supported:

access_key and secret_key
The access_key and secret_key parameters are required if a RAM user assumes a RAM role. The RAM user must be granted the permissions to call the AssumeRole operation. Otherwise, the RAM user cannot obtain an STS token by calling the AssumeRole operation. You can also specify an AccessKey pair by using environment variables.
assume_role
The assume_role parameter is used to obtain an STS token. This code block contains the following parameters:
1. role_arn: required. The ARN of the RAM role. The value of this parameter is in the following format: acs:ram::<ID of an Alibaba Cloud account>:role/<Name of a RAM role>. Example: acs:ram::151192xxxxxx:role/k8srole.
2. policy: optional. The custom policy that is attached to the RAM role. If you specify this parameter, the permissions of the RAM role are granted by this custom policy and the RAM policies of cloud services that are attached to the RAM role when you make preparations. If you do not specify this parameter, the permissions of the RAM role are granted by the RAM policies of cloud services that are attached to the RAM role when you make preparations.
3. session_name: optional. The session name of the RAM role. The value of this parameter is user-defined and is usually set to the identity of the user who calls API operations, such as the username. If you do not specify this parameter, Alibaba Cloud Terraform Provider sets the default value of this parameter to terraform.
4. session_expiration: optional. The validity period of the STS token. Unit: seconds. The minimum value of this parameter is 900, and the maximum value of this parameter is the value of the MaxSessionDuration parameter of the RAM role. The default value of the MaxSessionDuration parameter is 3600, and the maximum value of the MaxSessionDuration parameter is 43200. You can call the UpdateRole operation to specify the MaxSessionDuration parameter.
5. external_Id: optional. The external ID of the RAM role. The value of this parameter is provided by an external party and is used to prevent the confused deputy issue. For more information, see Use external IDs to prevent the confused deputy issue.

The following sample code shows how to configure a RAM role for identity authentication and grant the permissions to query a list of OSS buckets in the China (Hangzhou) region:

provider "alicloud" {
  # For security purposes, the AccessKey ID and AccessKey secret are specified by using environment variables.
  region = "cn-hangzhou"
  assume_role {
    role_arn           = "acs:ram::11827xxxxxx:role/tf-assume-role"
    policy             = <<EOF
    {
      "Version": "1",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "oss:ListBuckets",
          "Resource": "acs:oss:oss-cn-hangzhou:*:*"
        }
      ]
    }
    EOF
    session_name       = "terraform-assume-role-session"
    session_expiration = 1000
  }
}

Take note that you must attach the AliyunOSSFullAccess policy to the tf-assume-role RAM role before you run the preceding sample code. Otherwise, when you use Terraform to query a list of OSS buckets in the China (Hangzhou) region, an error message is returned to indicate that you do not have the required permissions.

If you do not want to use the policy parameter to implement fine-grained access control, you can directly attach the preceding policy to the tf-assume-role RAM role when you make preparations. In this case, you need to only specify the role_arn parameter in the code block of the assume_role parameter.

If Terraform is run on an ECS instance, you can also attach a RAM role to the ECS instance to prevent AccessKey pair leaks. Sample code:

provider "alicloud" {
  ecs_role_name = "<Name of the RAM role that is attached to the ECS instance>"
  region        = "cn-hangzhou"
  assume_role {
    role_arn           = "acs:ram::11827xxxxxx:role/tf-assume-role"
    policy             = <<EOF
    {
      "Version": "1",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "oss:ListBuckets",
          "Resource": "acs:oss:oss-cn-hangzhou:*:*"
        }
      ]
    }
    EOF
    session_name       = "terraform-assume-role-session"
    session_expiration = 1000
  }
}

In this case, you need to only attach the AliyunSTSAssumeRoleAccess system policy to the RAM role that is attached to the ECS instance to grant the RAM role the permissions to call the AssumeRole operation.

RAM role of an OIDC IdP

You can assign a RAM role to an identity of an OIDC IdP. Then, the RAM role obtains an STS token to access Alibaba Cloud resources. This authentication method is similar to the RAM role-based authentication method. The only difference is that an identity issued by an OIDC IdP is required. For more information, see Manage an OIDC IdP.

The authentication method by using the RAM role of an OIDC IdP is implemented based on the AssumeRoleWithOIDC operation. Before you configure the RAM role of an OIDC IdP for identity authentication in Terraform, make the following preparations:

Create an OIDC IdP, apply for an OIDC token that is issued by an external IdP, and then record the ARN and OIDC token of the OIDC IdP.
Create a RAM role whose trusted entity is an IdP, attach the RAM policies of cloud services that you want to access to the RAM role, such as the AliyunOSSFullAccess policy that is used to access OSS, and then record the ARN of the RAM role.
Write a custom RAM policy that is used to access cloud resources based on your business requirements. For example, you can write a custom policy to access all buckets only in the China (Hangzhou) region. This custom policy is used to grant permissions to the RAM role together with the RAM policies of cloud services that are attached in the previous step. This implements fine-grained access control.

After you perform the preceding steps, declare the RAM role for identity authentication in the following provider code block:

provider "alicloud" {
  assume_role_with_oidc {
    oidc_provider_arn  = "<ARN of the OIDC IdP>"
    oidc_token         = "<OIDC token that is issued by an external IdP>"
    role_arn           = "<ARN of the RAM role>"
    policy             = "<RAM policy>"
    role_session_name  = "<Custom session name of the RAM role>"
    session_expiration = <Validity period of the STS token>
  }
}

When you configure the RAM role of an OIDC IdP for identity authentication in Terraform, the following parameters are supported in the code block of the assume_role_with_oidc parameter:

oidc_provider_arn: required. The ARN of the OIDC IdP. The value of this parameter is in the following format: acs:ram::<ID of an Alibaba Cloud account>:oidc-provider/<Name of a RAM role>. Example: acs:ram::151192xxxxxx:oidc-provider/ackrole. You can view the ARN of the OIDC IdP in the RAM console or query the ARN of the OIDC IdP by calling API operations. You can also specify the ARN of the OIDC IdP by using the ALIBABA_CLOUD_OIDC_PROVIDER_ARN environment variable.
oidc_token: optional. The OIDC token that is issued by an external IdP. The value of this parameter must be 4 to 20,000 characters in length. You must specify one of the oidc_token parameter and the oidc_token_file parameter. You can set the parameter by the ALIBABA_CLOUD_OIDC_TOKEN environment variable.
oidc_token_file: optional. The absolute path of the OIDC token file that is issued by an external IdP. You must specify one of the oidc_token parameter and the oidc_token_file parameter. You can also specify the absolute path of the OIDC token file by using the ALIBABA_CLOUD_OIDC_TOKEN_FILE environment variable.
role_arn: required. The ARN of the RAM role. The value of this parameter is in the following format: acs:ram::<ID of an Alibaba Cloud account>:role/<Name of a RAM role>. Example: acs:ram::151192xxxxxx:role/k8srole. You can also specify the ARN of the RAM role by using the ALIBABA_CLOUD_ROLE_ARN environment variable.
policy: optional. The custom policy that is attached to the RAM role. If you specify this parameter, the permissions of the RAM role are granted by this custom policy and the RAM policies of cloud services that are attached to the RAM role when you make preparations. If you do not specify this parameter, the permissions of the RAM role are granted by the RAM policies of cloud services that are attached to the RAM role when you make preparations.
role_session_name: optional. The session name of the RAM role. The value of this parameter is user-defined and is usually set to the identity of the user who calls API operations, such as the username. If you do not specify this parameter, Alibaba Cloud Terraform Provider sets the default value of this parameter to terraform. You can also specify the session name of the RAM role by using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
session_expiration: optional. The validity period of the STS token. Unit: seconds. The minimum value of this parameter is 900, and the maximum value of this parameter is the value of the MaxSessionDuration parameter of the RAM role. The default value of the MaxSessionDuration parameter is 3600, and the maximum value of the MaxSessionDuration parameter is 43200. You can call the UpdateRole operation to specify the MaxSessionDuration parameter.

Alibaba Cloud ACK allows you to enable the RAM Roles for Service Accounts (RRSA) feature to create OIDC IdPs and issue OIDC tokens. For more information, see Use RRSA to authorize different pods to access different cloud services. After the RRSA feature is enabled, the ack-pod-identity-webhook component automatically injects the configurations of the ALIBABA_CLOUD_OIDC_PROVIDER_ARN, ALIBABA_CLOUD_OIDC_TOKEN_FILE, and ALIBABA_CLOUD_ROLE_ARN environment variables into a pod. In this case, if you run a Terraform command in an ACK cluster, you can use the following simplified sample code to configure the RAM role of an OIDC IdP for identity authentication and grant the permissions to query a list of OSS buckets in the China (Hangzhou) region:

provider "alicloud" {
  region = "cn-hangzhou"
  assume_role_with_oidc {
    policy             = <<EOF
    {
      "Version": "1",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "oss:ListBuckets",
          "Resource": "acs:oss:oss-cn-hangzhou:*:*"
        }
      ]
    }
    EOF
    session_name       = "terraform-assume-role-session"
    session_expiration = 1000
  }
}

Similar to the RAM role-based authentication method, if you do not want to use the policy parameter to implement fine-grained access control, you can directly attach the preceding policy to the RAM role when you make preparations. In this case, the preceding sample code can be further simplified.

provider "alicloud" {
  region = "cn-hangzhou"
  assume_role_with_oidc {
    policy             = <<EOF
    {
      "Version": "1",
      "Statement": [
        {
          "Effect": "Allow",
          "Action": "oss:ListBuckets",
          "Resource": "acs:oss:oss-cn-hangzhou:*:*"
        }
      ]
    }
    EOF
    session_name       = "terraform-assume-role-session"
    session_expiration = 1000
  }
}

Shared profile

The profile feature is provided by Alibaba Cloud CLI to configure multiple credentials that are required to access Alibaba Cloud resources in a unified manner. You can configure access credentials in a profile by using one of the following identity authentication methods: static credentials, the RAM role of an ECS instance, and a RAM role. For more information, see Configure credentials.

After you use Alibaba Cloud CLI to configure multiple access credentials in profiles, you can configure a shared profile for identity authentication in Terraform.

provider "alicloud" {
  region                  = "cn-hangzhou"
  shared_credentials_file = "<Absolute path of the shared profile>"
  profile                 = "<Name of the profile to be used>"
}

When you configure a shared profile for identity authentication in Terraform, the following parameters are supported:

profile: required. The name of the profile to be used for identity authentication.
shared_credentials_file: optional. The storage location of the shared profile. You can specify the storage location of the shared profile by using the --config-path option when you configure a profile by using Alibaba Cloud CLI.

After you configure the shared profile, you can switch between multiple access credentials across multiple environments or accounts. For example, if you want to create Alibaba Cloud resources in the China (Beijing) and China (Hangzhou) regions in the development and test environments, you can use the following sample code to configure identity authentication in multiple provider code blocks of the shared profile:

provider "alicloud" {
  alias   = beijing
  region  = "cn-beijing"
  profile = "bj-test"
}

provider "alicloud" {
  alias   = hangzhou
  region  = "cn-hangzhou"
  profile = "hz-test"
}

Summary

This section summarizes the preceding identity authentication methods.

Priority
In most cases, you configure only one identity authentication method. If you configure multiple identity authentication methods at a time, Terraform selects an identity authentication method based on the priority. The following methods are listed based on the priority in descending order: static credentials, environment variables, static credentials in a profile, the RAM role of an ECS instance, the RAM role of an ECS instance in a profile, the RAM role of an OIDC IdP, and a RAM role.
Security
Different identity authentication methods can be applicable to different scenarios. When Terraform is applied to the production environment, security must be considered. We recommend that you use the following identity authentication methods: the RAM role of an ECS instance, a RAM role, and the RAM role of an OIDC IdP. If you use one of the preceding methods, an STS token is required. In this case, you do not need to directly expose an AccessKey pair, which reduces the risks of AccessKey pair leaks. You can also specify the validity period of an STS token, which effectively controls the exposure scope.
Fine-grained authorization
In the production environment of an enterprise, resource management permissions are strictly controlled based on dimensions such as applications, teams, and projects. In this case, fine-grained access control becomes critical. We recommend that you use the following identity authentication methods to implement fine-grained access control: a RAM role and the RAM role of an OIDC IdP. You can configure different policies based on the infrastructure code of different projects or applications.