AWS Security Blog

How to Enable MFA Protection on Your AWS API Calls

Multi-factor authentication (MFA) provides an additional layer of security for sensitive API calls, such as terminating Amazon EC2 instances or deleting important objects stored in an Amazon S3 bucket. In some cases, you may want to require users to authenticate with an MFA code before performing specific API requests, and by using AWS Identity and Access Management (IAM) policies, you can specify which API actions a user is allowed to access. In this blog post, I show how to enable an MFA device for an IAM user and author IAM policies that require MFA to perform certain API actions such as EC2’s TerminateInstances.

Let’s say Alice, an AWS account administrator, wants to add another layer of protection over her users’ access to EC2. Alice wants to allow IAM users to perform RunInstances, DescribeInstances, and StopInstances actions. However, Alice also wants to restrict actions such as TerminateInstances to ensure that users can only perform such API calls if they authenticate with MFA. To accomplish this, Alice must follow the following process’s two parts.

Part 1: Assign an approved authentication device to IAM users

  1. Get an MFA token. Alice can purchase a hardware MFA key fob from Gemalto, a third-party provider. Alternatively, she can install a virtual MFA app for no additional cost, which enables IAM users to use any OATH TOTP–compatible application on their smartphone, tablet, or computer.
  2. Activate the MFA token. Alice must then sign in to the IAM console and follow these steps to activate an MFA device for a user (note that Alice can delegate MFA device activation to her users by granting them access to provision and manage MFA devices):
    1. Click Users in the left pane of the IAM console.
    2. Select a user.
    3. On the Security Credentials tab, choose Manage MFA Device, as shown in the following screenshot.
      Screenshot of Manage MFA Device button
For Virtual MFA devices:
      1. Select A virtual MFA device and choose Next Step.
        Screenshot showing the selection of "A virtual MFA device"
      2. Open the virtual MFA app and choose the option to create a new account.
      3. Use the app to scan the generated QR code. Alternatively, you can select Show secret key for manual configuration (as shown the following screenshot), and then type the secret configuration key in the MFA application.
        Screenshot showing selection of "Show secret key for manual configuration"
      4. Finally, in the Authentication Code 1 box, type the one-time password that currently appears in the virtual MFA device. Wait up to 30 seconds for the device to generate a new one-time password. Then type the second one-time password in the Authentication Code 2 Choose Activate Virtual MFA.For Hardware MFA devices:
For Hardware MFA devices:
      1. Select A hardware MFA device and choose Next Step.
        Screenshot of choosing "A hardware MFA device"
      2. Type the device serial number. The serial number is usually on the back of the device.
        Screenshot of the "Serial Number" box
      3. In the Authentication Code 1 box, type the six-digit number displayed by the MFA device. Wait up to 30 seconds for the device to generate a new one-time password. Then type the second one-time password in the Authentication Code 2 Choose Next Step.

Part 2: Author an IAM policy to grant “Allow” access for MFA-authenticated users

Now, Alice has to author an IAM policy that requires MFA authentication to access EC2’s TerminateInstances API action and attach it to her users. To do that, Alice has to insert a condition key in the IAM policy statement. Alice can choose one of the following condition element keys:

  1. aws:MultiFactorAuthPresent

Alice can select this condition key to verify that the user did authenticate with MFA. This key is present only when the user authenticates with short-term credentials. The following example policy demonstrates how to use this condition key to require MFA authentication for users attempting to call the EC2 TerminateInstances action.

{
  "Version": "2012-10-17",
  "Statement":[
   {
          "Sid": "AllowActionsForEC2",
          "Effect": "Allow",
          "Action": ["ec2:RunInstances",
                     "ec2:DescribeInstances",
                     "ec2:StopInstances "],
          "Resource": "*"
   },
   {
      "Sid": "AllowActionsForEC2WhenMFAIsPresent",
      "Effect":"Allow",
      "Action":"ec2:TerminateInstances",
      "Resource":"*",
      "Condition":{
         "Bool":{"aws:MultiFactorAuthPresent":"true"}
      }
    }
  ]
}
  1. aws:MultiFactorAuthAge

Alice can select this condition key if she wants to grant access to users only within a specific time period after they authenticate with MFA. For instance, Alice can restrict access to EC2’s TerminateInstances API to users who authenticated with an MFA device within the past 300 seconds (5 minutes). Users with short-term credentials older than 300 seconds must reauthenticate to gain access to this API. The following example policy demonstrates how to use this condition key.

{
  "Version": "2012-10-17",
   "Statement":[
    {
            "Sid": "AllowActionsForEC2",
            "Effect": "Allow",
            "Action": ["ec2:RunInstances",
               "ec2:DescribeInstances",
               "ec2:StopInstances "],
            "Resource": "*"
    },
    {
           "Sid": "AllowActionsForEC2WhenMFAIsPresent",
           "Effect":"Allow",
           "Action":"ec2:TerminateInstances",
           "Resource":"*",
           "Condition":{
             " NumericLessThan ":{"aws: MultiFactorAuthAge":"300"}
    }
   }
  ]
}

Summary

In this blog post, I showed how you can use MFA to protect access to AWS API actions and resources. I first showed how to assign a virtual or hardware MFA device to an IAM user and then how to author IAM policies with a condition element key that requires MFA authentication before granting access to AWS API actions. I covered two condition element keys: the MultiFactorAuthPresent condition key, which matches when a user authenticates with an MFA device, and the MultiFactorAuthAge condition key, which matches when a user authenticates with an MFA device within a given time interval.

For more information about MFA-protected API access, see Configuring MFA-Protected API Access. If you have a comment about this post, submit it in the “Comments” section below. If you have implementation questions, please start a new thread on the IAM forum.

– Zaher