terraform/website/source/docs/enterprise/runs/multifactor-authentication.html.md

layout	page_title	sidebar_current	description
enterprise	AWS Multi-Factor Authentication for Terraform Runs in TFE	docs-enterprise-runs-multifactor	Installing custom software on the Terraform Runners.

AWS Multi-Factor Authentication for Terraform Runs in Terraform Enterprise

You can optionally configure Terraform plans and applies to use multi-factor authentication using AWS Secure Token Service.

This option is disabled by default and can be enabled by an organization owner.

This is an advanced feature that enables changes to active infrastructure without user confirmation. Please understand the implications to your infrastructure before enabling.

Setting Up AWS Multi-Factor Authentication

Before you are able to set up multi-factor authentication in Terraform Enterprise, you must set up an IAM user in AWS. More details about creating an IAM user can be found here. Setting up an AWS IAM user will provide you with the serial number and access keys that you will need in order to connect to AWS Secure Token Service.

In order to set up multi-factor authentication for your organization, you must have the following environment variables in your configuration: 'AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_MFA_SERIAL_NUMBER". You can set these variables at /settings/organization_variables.

Enabling AWS Multi-Factor Authentication

To enable multi-factor authentication, visit the environment settings page: terraform/<organization>/environments/<environment>/settings. Use the drop down labeled "AWS Multi-Factor Authentication ". There are currently three levels available: "never", "applies only", and "plans and applies". Once you have selected your desired level, save your settings. All subsequent runs on the environment will now require the selected level of authentication.

Using AWS Multi-Factor Authentication

Once you have elected to use AWS MFA for your Terraform Runs, you will then be prompted to enter a token code each time you plan or apply the run depending on your settings. Your one time use token code will be sent to you via the method you selected when setting up your IAM account.

If you have selected "applies only", you will be able to queue and run a plan without entering your token code. Once the run finishes, you will need to enter your token code and click "Authenticate" before the applying the plan. Once you submit your token code, the apply will start, and you will see "Authenticated with MFA by user" in the UI. If for any case there is an error when submitting your token code, the lock icon in the UI will turn red, and an error will appear alerting you to the failure.

If you have selected "plans and applies", you will be prompted to enter your token before queueing your plan. Once you enter the token and click "Authenticate", you will see "Authenticated with MFA by user" appear in the UI logs. The plan will queue and you may run the plan once it is queued. Then, before applying, you will be asked to authenticate with MFA again. Enter your token, click Authenticate, and note that "Authenticated with MFA by user" appears in the UI log after the apply begins. If for any case there is an error authenticating, the lock icon in the UI will turn red, and an error will appear alerting you to the failure.

Using AWS Multi-Factor Authentication with AWS STS AssumeRole

The AWS Secure Token Service can be used to return a set of temporary security credentials that a user can use to access resources that they might not normally have access to (known as AssumeRole). The AssumeRole workflow is compatible with AWS multi-factor authentication in Terraform Enterprise.

To use AssumeRole, you first need to create an IAM role and edit the trust relationship policy document to contain the following:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::[INT]:user/[USER]"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "Bool": {
          "aws:MultiFactorAuthPresent": "true"
        }
      }
    }
  ]
}

You can then configure the Terraform AWS provider to assume a given role by specifying the role ARN within the nested assume_role block:

provider "aws" {
  ...
  assume_role {
    role_arn = "arn:aws:iam::[INT]:role/[ROLE]"
  }
}