github.com/danp/terraform@v0.9.5-0.20170426144147-39d740081351/website/source/docs/enterprise/runs/multifactor-authentication.html.md (about)

     1  ---
     2  layout: "enterprise"
     3  page_title: "AWS Multi-Factor Authentication - Runs - Terraform Enterprise"
     4  sidebar_current: "docs-enterprise-runs-multifactor-authentication"
     5  description: |-
     6    Installing custom software on the Terraform Runners.
     7  ---
     8  
     9  # AWS Multi-Factor Authentication for Terraform Runs in Terraform Enterprise
    10  
    11  You can optionally configure Terraform plans and applies to use multi-factor authentication using [AWS Secure Token Service](http://docs.aws.amazon.com/STS/latest/APIReference/Welcome.html).
    12  
    13  This option is disabled by default and can be enabled by an organization owner.
    14  
    15  !> This is an advanced feature that enables changes to active infrastructure
    16  without user confirmation. Please understand the implications to your
    17  infrastructure before enabling.
    18  
    19  ## Setting Up AWS Multi-Factor Authentication
    20  
    21  Before you are able to set up multi-factor authentication in Terraform
    22  Enterprise, you must set up an IAM user in AWS. More details about creating an
    23  IAM user can be found
    24  [here](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa_enable.html).
    25  Setting up an AWS IAM user will provide you with the serial number and access
    26  keys that you will need in order to connect to AWS Secure Token Service.
    27  
    28  In order to set up multi-factor authentication for your organization, you must
    29  have the following environment variables in your configuration:
    30  'AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY", "AWS_MFA_SERIAL_NUMBER". You can
    31  set these variables at `/settings/organization_variables.`
    32  
    33  
    34  ## Enabling AWS Multi-Factor Authentication
    35  
    36  To enable multi-factor authentication, visit the environment settings page:
    37  
    38  ```text
    39  /terraform/:organization/environments/:environment/settings
    40  ```
    41  
    42  Use the drop down labeled "AWS Multi-Factor Authentication ". There are
    43  currently three levels available: "never", "applies only", and "plans and
    44  applies". Once you have selected your desired level, save your settings. All
    45  subsequent runs on the environment will now require the selected level of
    46  authentication.
    47  
    48  ## Using AWS Multi-Factor Authentication
    49  
    50  Once you have elected to use AWS MFA for your Terraform Runs, you will then be
    51  prompted to enter a token code each time you plan or apply the run depending on
    52  your settings. Your one time use token code will be sent to you via the method
    53  you selected when setting up your
    54  [IAM account](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa_enable.html).
    55  
    56  If you have selected "applies only", you will be able to queue and run a plan
    57  without entering your token code. Once the run finishes, you will need to enter
    58  your token code and click "Authenticate" before the applying the plan. Once you
    59  submit your token code, the apply will start, and you will see "Authenticated
    60  with MFA by `user`" in the UI. If for any case there is an error when submitting
    61  your token code, the lock icon in the UI will turn red, and an error will appear
    62  alerting you to the failure.
    63  
    64  If you have selected "plans and applies", you will be prompted to enter your
    65  token before queueing your plan.  Once you enter the token and click
    66  "Authenticate", you will see "Authenticated with MFA by `user`" appear in the UI
    67  logs. The plan will queue and you may run the plan once it is queued. Then,
    68  before applying, you will be asked to authenticate with MFA again. Enter your
    69  token, click Authenticate, and note that "Authenticated with MFA by `user`"
    70  appears in the UI log after the apply begins. If for any case there is an error
    71  authenticating, the lock icon in the UI will turn red, and an error will appear
    72  alerting you to the failure.
    73  
    74  ## Using AWS Multi-Factor Authentication with AWS STS AssumeRole
    75  
    76  The AWS Secure Token Service can be used to return a set of temporary security
    77  credentials that a user can use to access resources that they might not normally
    78  have access to (known as AssumeRole). The AssumeRole workflow is compatible with
    79  AWS multi-factor authentication in Terraform Enterprise.
    80  
    81  To use AssumeRole, you first need to create an IAM role and edit the trust
    82  relationship policy document to contain the following:
    83  
    84  ```json
    85      {
    86    "Version": "2012-10-17",
    87    "Statement": [
    88      {
    89        "Effect": "Allow",
    90        "Principal": {
    91          "AWS": "arn:aws:iam::[INT]:user/[USER]"
    92        },
    93        "Action": "sts:AssumeRole",
    94        "Condition": {
    95          "Bool": {
    96            "aws:MultiFactorAuthPresent": "true"
    97          }
    98        }
    99      }
   100    ]
   101  }
   102  ```
   103  
   104  You can then configure the Terraform AWS provider to assume a given role by specifying the role ARN within the nested assume_role block:
   105  
   106  ```hcl
   107  provider "aws" {
   108    # ...
   109  
   110    assume_role {
   111      role_arn = "arn:aws:iam::[INT]:role/[ROLE]"
   112    }
   113  }
   114  ```