AWS Documentation » AWS Identity and Access Management » Using IAM » IAM Users and Groups » Using Multi-Factor Authentication (MFA) Devices with AWS » Configuring MFA-Protected API Access	« Previous Next »
	Did this page help you? Yes \| No \| Tell us about it...

Configuring MFA-Protected API Access

MFA-protected API access is an optional feature that offers an extra layer of security by requiring users to authenticate with an MFA device before they can use APIs you specify in a policy. Users can authenticate through the AWS Management Console or programmatically through the AWS Security Token Service (STS).

MFA-protected API access is available only to services that support temporary security credentials. For a complete list of these services, and for information about using the AWS STS API for requesting temporary security credentials, see Using Temporary Security Credentials to Access AWS.

If the user is denied access to APIs because of an authorization failure, AWS returns an “Access Denied” error message (as it does for any unauthorized access). With MFA-protected API policies in place, AWS denies access to the APIs specified in the policy if the user attempts to use the APIs without valid MFA authentication, or if the time of the request for the APIs is beyond the duration specified in the policy. The user must re-authenticate with MFA, either through the console, or by requesting new temporary security credentials using an MFA code and device serial number.

Note

MFA-protected API access cannot be applied to root accounts accessing their own resources.

Federated users cannot be assigned an MFA device for use with AWS services, so they cannot access AWS resources controlled by MFA.

Using MFA-Protected APIs Through the Console

AWS evaluates MFA-protected API policies for actions in the console, such as terminating an Amazon EC2 instance. Set up the IAM user with an MFA device and enable an MFA-protected API policy. The user can then simply log into the console with MFA authentication and is subject to the policies for MFA-protected APIs. For users who already have an assigned MFA device, the console experience doesn't change (except for optional time limits on certain MFA-protected APIs that require more frequent re-authentication). For more information on setting up an IAM user with an MFA device, see Setting Up an MFA Device.

Using MFA-Protected APIs Programmatically

MFA-protected API policies also apply to IAM users who access MFA-protected API programmatically, either through their own application or an application provided to them, specifically:

An MFA-protected API policy is attached to a user, group, or resource.
The IAM user acquires temporary security credentials using an MFA code and device serial number, programmatically, in a request to the AWS Security Token Service (STS). The temporary security credentials include the MFA authentication status.
An application can use the STS API and custom code to prompt the user to provide the MFA code and serial number in the application. For information on implementing MFA authentication using STS, see Creating Temporary Security Credentials in Using Temporary Security Credentials.
When the IAM user tries to use an API directly or through an application, AWS uses the condition in the MFA-protected API policy to check whether the IAM user is allowed access to the API.
AWS grants the IAM user access to the MFA-protected API (or prevents access) according to the policy.

Policies for MFA-Protected APIs

MFA-protected API policies are attached to a user, group, or resource, such as an Amazon Simple Storage Service (Amazon S3) bucket, Amazon Simple Queue Service (Amazon SQS) queue, or Amazon Simple Notification Service (Amazon SNS) topic).

MFA-protected API policies include a condition statement (or statements) with the aws:MultiFactorAuthAge key. The policy can use the key in two ways:

Existence—To verify that MFA authentication is present, use an existence check with a Null statement to evaluate whether the aws:MultiFactorAuthAge key exists (is not null, matching the Boolean value "false") or not (is null, matching the Boolean value "true").
Duration—For situations that require control over the duration of the MFA authentication, independent of the lifetime of the temporary security credentials, use a numeric condition type to compare the key's age to a value (such as 3600 seconds). If a policy checks for existence, only, the access is available for the entire authentication session (the default is 12 hours). A numeric condition enables the policy to restrict access to APIs for a user who does not have recent MFA authentication, even if the user's authorization session is still valid. If necessary, an IAM user can refresh their MFA authentication, either through the console, or by requesting new temporary security credentials using an MFA code and device serial number.

For more information on the condition types for aws:MultiFactorAuthAge, see Existence of Condition Keys and Numeric Conditions.

The following policies demonstrate several use-cases that require MFA authentication.

Topics

Example 1: Granting access after MFA authentication

The following example shows a policy attached to a user or group that grants Amazon EC2 access only after valid MFA authentication. Specifically, AWS grants access only when the existence check for a Null value evaluates to false. In other words, the aws:MultiFactorAuthAge key value is not null.

{
  "Version":"2012-10-17",
  "Statement":[{
      "Action":["ec2:*"],
      "Effect":"Allow",
      "Resource":["*"],
      "Condition":{
        "Null":{"aws:MultiFactorAuthAge":"false"}
      }
    }
  ]
}

Example 2: Granting access after recent MFA authentication

The following example shows a policy attached to a user or group that grants Amazon EC2 access only after checking for a valid MFA authentication within an hour of the request. Specifically, AWS grants access only when the aws:MultiFactorAuthAge key value is present and less than 3600 seconds (1 hour).

{
  "Version":"2012-10-17",
  "Statement":[{
      "Action":["ec2:*"],
      "Effect":"Allow",
      "Resource":["*"],
      "Condition":{
        "NumericLessThan":{"aws:MultiFactorAuthAge":"3600"}
      }
    }
  ]
}

Example 3: Denying access to specific APIs without valid MFA authentication

{
  "Version":"2012-10-17",
  "Statement":[
    {
      "Action":["ec2:*"],
      "Effect":"Allow",
      "Resource":["*"]
    },
    {
      "Action":["ec2:StopInstances","ec2:TerminateInstances"],
      "Effect":"Deny",
      "Resource":["*"],
      "Condition":{
        "Null":{"aws:MultiFactorAuthAge":"true"}
      }
    }
  ]
}

Example 4: Denying access to specific APIs without recent valid MFA authentication

The following example shows a policy attached to a user or group that grants access to the entire Amazon EC2 API, but restricts access to StopInstances and TerminateInstances unless valid MFA authentication occurred within the last hour. Specifically, AWS denies access to StopInstances and TerminateInstances when the existence check for a Null value evaluates to true, meaning the aws:MultiFactorAuthAge key value is null. Additionally, AWS denies access to StopInstances and TerminateInstances when aws:MultiFactorAuthAge key value is present and greater than 3600 seconds (1 hour).

Note

MFA-protected API policies using Deny statements that check for the numeric value of aws:MultiFactorAuthAge should include an existence check. AWS evaluates existence and duration independently; evaluating only for duration does not enforce a Deny condition if MFA has not been used at all.

{
  "Version":"2012-10-17",
  "Statement":[
    {
      "Action":["ec2:*"],
      "Effect":"Allow",
      "Resource":["*"]
    },
    {
      "Action":["ec2:StopInstances","ec2:TerminateInstances"],
      "Effect":"Deny",
      "Resource":["*"],
      "Condition":{
        "Null":{"aws:MultiFactorAuthAge":"true"}
      }
    },
    {
      "Action":["ec2:StopInstances","ec2:TerminateInstances"],
      "Effect":"Deny",
      "Resource":["*"],
      "Condition":{
        "NumericGreaterThan":{"aws:MultiFactorAuthAge":"3600"}
      }
    }
  ]
}

Example 5: Granting access to a resource after MFA authentication

MFA-protected API policies can be attached to a resource, as well, such as Amazon S3 bucket policies. The following policy is attached to an Amazon S3 bucket. This policy grants access to the Amazon S3 actions PutObject and DeleteObject only after valid MFA authentication for all IAM users with access to the bucket. Specifically, AWS grants access only when the existence check for a Null value evaluates to false. In other words, the aws:MultiFactorAuthAge key value is not null.

{
  "Version":"2012-10-17",
  "Statement":[
    {
      "Effect":"Allow",
      "Principal":{ 
        "AWS": "111122223333"
      },
      "Action":["s3:PutObject","s3:DeleteObject"],
      "Resource": "arn:aws:s3:::myawsbucket/*",
      "Condition":{
        "Null":{"aws:MultiFactorAuthAge":"false"}
      }
    }
  ]
}

Note

Amazon S3 offers an MFA Delete feature for root account (only) access. You can enable Amazon S3 MFA Delete when you set the versioning state of the bucket. Amazon S3 MFA Delete cannot be applied to an IAM user, and is managed independently from MFA-protected API access. An IAM user with permission to delete a bucket cannot delete a bucket with Amazon S3 MFA Delete enabled. For more information on Amazon S3 MFA Delete, see MFA Delete.

Document Conventions	« Previous Next »
Terms of Use	Did this page help you? Yes \| No \| Tell us about it...