Terraform:Terraform identity authentication

Static configuration refers to defining access credentials directly in the provider block of a Terraform configuration file.

Parameters

provider "alicloud" {
  access_key = "<Your AccessKey ID>"
  secret_key = "<Your AccessKey secret>"
  # If you use an STS credential, configure security_token.
  # security_token = "<Your STS token>"
}

Example configuration

For enhanced security, you can pass access credentials as variables instead of hard-coding them in plaintext in the configuration file. Do not set default values for the variables:

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 credential, configure security_token.
  # security_token = var.security_token
}

When you run the terraform command, you can use the -var option to pass variable values:

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

You can store access credentials in environment variables. If credentials are not statically configured in the configuration file, Terraform reads them from the specified environment variables.

Parameters

Example configuration

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

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

When Terraform runs on an ECS instance, you can use an instance RAM role for authentication. If you attach a RAM role to an ECS instance, applications on the instance, including Terraform, can automatically obtain and refresh temporary access credentials. This method eliminates the need to configure an AccessKey, which reduces the risk of key leakage. You can also implement fine-grained permission control using the RAM role. For more information, see Instance RAM roles.

Parameters

Example configuration

1. Prepare an ECS instance that has public network access.

2. Create a RAM role and attach it to the ECS instance.

3. In the provider block, set the ecs_role_name parameter to the name of the RAM role:

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

You can also use the environment variable ALICLOUD_ECS_ROLE_NAME to set this parameter.

Authentication using an instance RAM role for ECS is highly secure. We recommend this method when you run Terraform on an ECS instance.

OIDC role assumption is similar to role assumption (AssumeRole). Both methods obtain temporary credentials by assuming a RAM role to access Alibaba Cloud resources. The difference is that OIDC role assumption uses an identity issued by an OIDC IdP. For more information, see Manage OIDC IdPs.

Parameters

When you configure OIDC role assumption, all related parameters are set in the assume_role_with_oidc block:

Example configuration

OIDC role assumption authentication is implemented by calling the AssumeRoleWithOIDC - Obtain a temporary credential for a RAM role of an OIDC IdP for role-based SSO operation. Before you configure this method, prepare the following information:

1. Create an OIDC IdP, obtain an OIDC token from the external IdP, and record the OIDC IdP's ARN and the OIDC token.

2. Create a RAM role with an identity provider as the trusted entity, grant the role the required permissions (such as AliyunOSSFullAccess), and record the ARN of the role.

3. (Optional) You can write a custom RAM policy, such as one that allows access only to buckets in the China (Hangzhou) region. This policy is combined with the role's permissions for more fine-grained access control.

After you complete the preparations, add the following configuration in the provider block:

provider "alicloud" {
  assume_role_with_oidc {
    oidc_provider_arn  = "<ARN of the OIDC IdP>"
    oidc_token         = "<OIDC token issued by the external IdP>"
    role_arn           = "<ARN of the RAM role>"
    policy             = "<Content of the RAM access policy>"
    role_session_name  = "<Custom role session name>"
    session_expiration = <Maximum validity period of the temporary access credential>
  }
}

Alibaba Cloud Container Service for Kubernetes (ACK) lets you use the RAM Roles for Service Accounts (RRSA) feature to automatically create OIDC IdPs and issue OIDC tokens. For more information, see Use RRSA to authorize different pods to access different cloud services. After you enable the RRSA feature, the ack-pod-identity-webhook component automatically injects the ALIBABA_CLOUD_OIDC_PROVIDER_ARN, ALIBABA_CLOUD_OIDC_TOKEN_FILE, and ALIBABA_CLOUD_ROLE_ARN environment variables into pods. In this environment, if you run Terraform in an ACK pod, the preceding example can be simplified as follows:

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
  }
}

If you do not need to use the policy parameter for fine-grained authorization, you can directly grant the required permissions to the RAM role. In this case, the configuration can be further simplified:

provider "alicloud" {
  region = "cn-hangzhou"
  assume_role_with_oidc {
    session_name = "terraform-assume-role-session"
    session_expiration = 1000
  }
}

Role assumption (AssumeRole) is suitable for scenarios where you need to separate permissions from an identity, such as a RAM user or an ECS instance role, or when you need to access resources across accounts. This method allows an existing identity, such as a RAM user, to assume another RAM role and obtain that role's temporary credentials to access resources.

Parameters

When you configure role assumption, the following parameters are supported:

1. access_key and secret_key: Specifies the AccessKey of the RAM user that assumes the role. The user must have the sts:AssumeRole permission. You can also set these parameters using environment variables.

2. assume_role: A configuration block that includes the following parameters:

Example configuration

Role assumption authentication is implemented by calling the AssumeRole - Obtain a temporary credential for a RAM role operation. Before you configure this method, prepare the following:

1. Create a RAM user and grant the AliyunSTSAssumeRoleAccess policy (or a custom policy that contains the sts:AssumeRole permission).

2. Create an AccessKey for the RAM user.

3. Create a RAM role whose trusted entity is an Alibaba Cloud account, grant it the required permissions (such as AliyunOSSFullAccess), and record its ARN.

4. (Optional) You can write a custom RAM policy. This policy is combined with the role's permissions for more fine-grained access control.

After you complete the preparation, configure the provider block as follows:

provider "alicloud" {
  # The AccessKey ID of the RAM user that calls AssumeRole.
  access_key = "<AccessKey ID of the RAM user>"
  # The AccessKey secret of the RAM user that calls AssumeRole.
  secret_key = "<AccessKey secret of the RAM user>"
  assume_role {
    role_arn           = "<ARN of a RAM role>"
    policy             = "<Content of a RAM access policy>"
    session_name       = "<Custom role session name>"
    session_expiration = <Maximum validity period of the temporary access credential>
  }
}

The following example demonstrates how to obtain permissions to list OSS buckets in the Hangzhou region using role assumption. For security purposes, the access_key and secret_key in the example are set using environment variables and are not written in plaintext in the code:

provider "alicloud" {
  # For security, the access_key and secret_key here are set as 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
  }
}

If you run Terraform on an ECS instance, you can use an ECS instance RAM role to avoid hard-coding an AccessKey. In this case, you only need to grant the AliyunSTSAssumeRoleAccess policy to the RAM role that is attached to the ECS instance. The following code provides an example:

provider "alicloud" {
  ecs_role_name = "<Name of the RAM role 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
  }
}

Obtains a credential by accessing a specified URI.

Parameters

Example configuration

provider "alicloud" {
  region = "cn-hangzhou"
  credentials_url= "http://credentials.uri/"
}