# AWS Multi-factor authentication in IAM For increased security, we recommend that you configure multi-factor authentication (MFA) to help protect your AWS resources. You can enable MFA for the AWS account root user of all AWS accounts, including standalone accounts, management accounts, and member accounts, as well as for your IAM users. We recommend that you use phishing-resistant MFA such as passkeys and security keys whenever possible. These FIDO-based authenticators use public key cryptography and are resistant to phishing, man-in-the-middle, and replay attacks, providing a stronger level of security than TOTP-based options. MFA is enforced for all account types for their root user. For more information, see [Secure your AWS Organizations account root user credentials](root-user-best-practices.md#ru-bp-organizations). When you enable MFA for the root user, it affects only the root user credentials. IAM users in the account are distinct identities with their own credentials, and each identity has its own MFA configuration. For more information about using MFA to protect the root user, see [Multi-factor authentication for AWS account root user](enable-mfa-for-root.md). Your AWS account root user and IAM users can register up to eight MFA devices of any type. Registering multiple MFA devices can provide flexibility and help you reduce the risk of access interruption if a device is lost or broken. You only need one MFA device to sign in to the AWS Management Console or create a session through the AWS CLI. **Note** We recommend that you require your human users to use temporary credentials when accessing AWS. Have you considered using AWS IAM Identity Center? You can use IAM Identity Center to centrally manage access to multiple AWS accounts and provide users with MFA-protected, single sign-on access to all their assigned accounts from one place. With IAM Identity Center, you can create and manage user identities in IAM Identity Center or easily connect to your existing SAML 2.0 compatible identity provider. For more information, see [What is IAM Identity Center?](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html) in the *AWS IAM Identity Center User Guide*. MFA adds extra security that requires users to provide unique authentication from an AWS supported MFA mechanism in addition to their sign-in credentials when they access AWS websites or services. ## MFA types AWS supports the following MFA types: **Contents** + [ ### Passkeys and security keys ](#passkeys-security-keys-for-iam-users) + [ ### Virtual authenticator applications ](#virtual-auth-apps-for-iam-users) + [ ### Hardware TOTP tokens ](#hardware-totp-token-for-iam-users) ### Passkeys and security keys AWS Identity and Access Management supports passkeys and security keys for MFA. Based on FIDO standards, passkeys use public key cryptography to provide strong, phishing-resistant authentication that is more secure than passwords. AWS supports two types of passkeys: device-bound passkeys (security keys) and synced passkeys. + **Security keys**: These are physical devices, like a YubiKey, used as a second factor for authentication. A single security key can support multiple root user accounts and IAM users. + **Synced passkeys**: These use credential managers from providers such as Google, Apple, Microsoft accounts, and third-party services like 1Password, Dashlane, and Bitwarden as a second factor. You can use built-in biometric authenticators, like Touch ID on Apple MacBooks, to unlock your credential manager and sign in to AWS. Passkeys are created with your chosen provider using your fingerprint, face, or device PIN. You can also use a cross-device authentication (CDA) passkey from one device, like a mobile device or hardware security key, to sign in on another device like a laptop. For more information, see [cross-device authentication](https://passkeys.dev/docs/reference/terms/#cross-device-authentication-cda) (CDA). You can sync passkeys across your devices to facilitate sign-ins with AWS, enhancing usability and recoverability. For more information about enabling passkeys and security keys, see [Enable a passkey or security key for the root user (console)](enable-fido-mfa-for-root.md). The FIDO Alliance maintains a list of all [FIDO Certified products](https://fidoalliance.org/certification/fido-certified-products/) that are compatible with FIDO specifications. ### Virtual authenticator applications A virtual authenticator application runs on a phone or other device and emulates a physical device. Virtual authenticator apps implement the [time-based one-time password (TOTP) algorithm](https://datatracker.ietf.org/doc/html/rfc6238) and support multiple tokens on a single device. The user must type a valid code from the device when prompted during sign-in. Each token assigned to a user must be unique. A user can't type a code from another user's token to authenticate. We recommend that you use phishing-resistant MFA such as [passkeys or security keys](#passkeys-security-keys-for-iam-users) for the strongest protection. If you are not yet able to use passkeys or security keys, we recommend that you use a virtual MFA device as an interim measure while waiting for hardware purchase approval or while you wait for your hardware to arrive. For a list of a few supported apps that you can use as virtual MFA devices, see [Multi-Factor Authentication (MFA)](https://aws.amazon.com/iam/features/mfa/?audit=2019q1). For instructions on setting up a virtual MFA device for an IAM user, see [Assign a virtual MFA device in the AWS Management Console](id_credentials_mfa_enable_virtual.md). **Note** Unassigned virtual MFA devices in your AWS account are deleted when you’re adding new virtual MFA devices either via the AWS Management Console or during the sign-in process. Unassigned virtual MFA devices are devices in your account but not used by account root user or IAM users for the sign-in process. They’re deleted so new virtual MFA devices can be added to your account. It also allows you to reuse device names. To view unassigned virtual MFA devices in your account, you can use either the [list-virtual-mfa-devices](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/list-virtual-mfa-devices.html) AWS CLI command or [API](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListVirtualMFADevices.html) call. To deactivate a virtual MFA device, you can use either the [deactivate-mfa-device](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/deactivate-mfa-device.html) AWS CLI command or [API](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeactivateMFADevice.html) call. The device will become unassigned. To attach an unassigned virtual MFA device to your AWS account root user or IAM users, you'll need the authentication code generated by the device along with either the [enable-mfa-device](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/enable-mfa-device.html) AWS CLI command or [API](https://docs.aws.amazon.com/IAM/latest/APIReference/API_EnableMFADevice.html) call. ### Hardware TOTP tokens A hardware device generates a six-digit numeric code based on the [time-based one-time password (TOTP) algorithm](https://datatracker.ietf.org/doc/html/rfc6238). The user must type a valid code from the device on a second webpage during sign-in. These tokens are used exclusively with AWS accounts. You can only use tokens that have their unique token seeds shared securely with AWS. Token seeds are secret keys generated at the time of token production. Tokens purchased from other sources will not function with IAM. To ensure compatibility, you must purchase your hardware MFA device from one of the following links: [OTP token](https://www.amazon.com/SafeNet-IDProve-Time-based-6-Digit-Services/dp/B002CRN5X8) or [OTP display card](https://www.amazon.com/SafeNet-IDProve-Card-Amazon-Services/dp/B00J4NGUO4). + Each MFA device assigned to a user must be unique. A user cannot type a code from another user's device to be authenticated. For information on supported hardware MFA devices, see [Multi-Factor Authentication (MFA)](https://aws.amazon.com/iam/features/mfa/?audit=2019q1). + If you want to use a physical MFA device, we recommend that you use security keys as an alternative to hardware TOTP devices. Security keys have no battery requirements, are phishing resistant, and support multiple users on a single device. You can enable a passkey or security key from the AWS Management Console only, not from the AWS CLI or AWS API. Before you can enable a security key, you must have physical access to the device. For instructions on setting up a hardware TOTP token for an IAM user, see [Assign a hardware TOTP token in the AWS Management Console](id_credentials_mfa_enable_physical.md). **Note** **SMS text message-based MFA** – AWS ended support for enabling SMS multi-factor authentication (MFA). We recommend that customers who have IAM users that use SMS text message-based MFA switch to one of the following alternative methods: [Passkey or security key](id_credentials_mfa_enable_fido.md), [virtual (software-based) MFA device](id_credentials_mfa_enable_virtual.md), or [hardware MFA device](id_credentials_mfa_enable_physical.md). You can identify the users in your account with an assigned SMS MFA device. In the IAM console, choose **Users** from the navigation pane, and look for users with **SMS** in the **MFA** column of the table. ## MFA recommendations To help secure your AWS identities, follow these recommendations for MFA authentication. + We recommend that you use phishing-resistant MFA, such as [passkeys and security keys](#passkeys-security-keys-for-iam-users), as your MFA device. These FIDO-based authenticators provide the strongest protection against attacks such as phishing. + We recommend that you enable multiple MFA devices to the AWS account root user and IAM users in your AWS accounts. This allows you to raise the security bar in your AWS accounts and simplify managing access to highly privileged users, such as the AWS account root user. + You can register up to **eight** MFA devices of any combination of the [ currently supported MFA types](https://aws.amazon.com/iam/features/mfa/) with your AWS account root user and IAM users. With multiple MFA devices, you only need one MFA device to sign in to the AWS Management Console or create a session through the AWS CLI as that user. An IAM user must authenticate with an existing MFA device to enable or disable an additional MFA device. + In the event of a lost, stolen, or inaccessible MFA device you can use one of the remaining MFA devices to access the AWS account without performing the AWS account recovery procedure. If an MFA device is lost or stolen, it should be disassociated from the IAM principal with which it is associated. + The use of multiple MFAs allows your employees in geographically dispersed locations or working remotely to use hardware-based MFA to access AWS without having to coordinate the physical exchange of a single hardware device between employees. + The use of additional MFA devices for IAM principals allows you to use one or more MFAs for everyday usage, while also maintaining physical MFA devices in a secure physical location such as a vault or safe for backup and redundancy. **Notes** You cannot pass the MFA information for a security key or passkey to AWS STS API operations to request temporary credentials. You can obtain credentials for use with the AWS CLI and AWS SDKs when using a security key or passkey by running the `aws login` command. You cannot use AWS CLI commands or AWS API operations to enable [FIDO security keys](id_credentials_mfa_enable_fido.md). You cannot use the same name for more than one root user or IAM MFA device. ## Additional resources The following resources can help you learn more about MFA. + For more information about using MFA to access AWS, see [MFA enabled sign-in](console_sign-in-mfa.md). + You can leverage IAM Identity Center to enable secure MFA access to your AWS access portal, IAM Identity Center integrated apps, and the AWS CLI. For more information, see [Enable MFA in IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/mfa-getting-started.html). # Assign a passkey or security key in the AWS Management Console Passkeys are a type of [multi-factor authentication (MFA) device](id_credentials_mfa.md) that you can use to protect your AWS resources. AWS supports synced passkeys and device-bound passkeys also known as security keys. Synced passkeys allow IAM users to access their FIDO sign-in credentials on many of their devices, even new ones, without having to re-enroll every device on every account. Synced passkeys include first-party credential managers like Google, Apple, and Microsoft and third-party credential managers such as 1Password, Dashlane, and Bitwarden as a second factor. You can also use on-device biometrics (e.g., TouchID, FaceID) to unlock your chosen credential manager to use passkeys. Alternatively, device-bound passkeys are bound to a FIDO security key that you plug into a USB port on your computer and then tap when prompted to securely complete the sign-in process. If you already use a FIDO security key with other services, and it has an [AWS supported configuration](id_credentials_mfa_fido_supported_configurations.md) (for example, the YubiKey 5 Series from Yubico), you can also use it with AWS. Otherwise, you need to purchase a FIDO security key if you want to use WebAuthn for MFA in AWS. Additionally, FIDO security keys can support multiple IAM or root users on the same device, enhancing their utility for account security. For specifications and purchase information for both device types, see [Multi-Factor Authentication](http://aws.amazon.com/iam/details/mfa/). You can register up to **eight** MFA devices of any combination of the [currently supported MFA types](https://aws.amazon.com/iam/features/mfa/) with your AWS account root user and IAM users. With multiple MFA devices, you only need one MFA device to sign in to the AWS Management Console or create a session through the AWS CLI as that user. We recommend that you register multiple MFA devices. For example, you can register a built-in authenticator and also register a security key that you keep in a physically secure location. If you’re unable to use your built-in authenticator, then you can use your registered security key. For authenticator applications, we also recommend enabling the cloud backup or sync feature in those apps to help you avoid losing access to your account if you lose or break your device with the authenticator apps. **Note** We recommend that you require your human users to use temporary credentials when accessing AWS. Your users can federate into AWS with an identity provider where they authenticate with their corporate credentials and MFA configurations. To manage access to AWS and business applications, we recommend that you use IAM Identity Center. For more information, see the [IAM Identity Center User Guide](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html). **Topics** + [ ## Permissions required ](#enable-fido-mfa-for-iam-user-permissions-required) + [ ## Enable a passkey or security key for your own IAM user (console) ](#enable-fido-mfa-for-own-iam-user) + [ ## Enable a passkey or security key for another IAM user (console) ](#enable-fido-mfa-for-iam-user) + [ ## Replace a passkey or security key ](#replace-fido-mfa) + [ # Supported configurations for using passkeys and security keys ](id_credentials_mfa_fido_supported_configurations.md) ## Permissions required To manage a FIDO passkey for your own IAM user while protecting sensitive MFA-related actions, you must have the permissions from the following policy: **Note** The ARN values are static values and are not an indicator of what protocol was used to register the authenticator. We have deprecated U2F, so all new implementations use WebAuthn. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowManageOwnUserMFA", "Effect": "Allow", "Action": [ "iam:DeactivateMFADevice", "iam:EnableMFADevice", "iam:GetUser", "iam:ListMFADevices", "iam:ResyncMFADevice" ], "Resource": "arn:aws:iam::*:user/${aws:username}" }, { "Sid": "DenyAllExceptListedIfNoMFA", "Effect": "Deny", "NotAction": [ "iam:EnableMFADevice", "iam:GetUser", "iam:ListMFADevices", "iam:ResyncMFADevice" ], "Resource": "*", "Condition": { "BoolIfExists": { "aws:MultiFactorAuthPresent": "false" } } } ] } ``` ------ ## Enable a passkey or security key for your own IAM user (console) You can enable a passkey or security key for your own IAM user from the AWS Management Console only, not from the AWS CLI or AWS API. Before you can enable a security key, you must have physical access to the device. **To enable a passkey or security key for your own IAM user (console)** 1. Use your AWS account ID or account alias, your IAM user name, and your password to sign in to the [IAM console](https://console.aws.amazon.com/iam). **Note** For your convenience, the AWS sign-in page uses a browser cookie to remember your IAM user name and account information. If you previously signed in as a different user, choose **Sign in to a different account** near the bottom of the page to return to the main sign-in page. From there, you can type your AWS account ID or account alias to be redirected to the IAM user sign-in page for your account. To get your AWS account ID, contact your administrator. 1. In the navigation bar on the upper right, choose your user name, and then choose **Security credentials**. ![\[AWS Management Console Security credentials link\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/images/security-credentials-user.shared.console.png) 1. On the selected IAM user's page, choose the **Security credentials** tab. 1. Under **Multi-factor authentication (MFA)**, choose **Assign MFA device**. 1. On the **MFA device name** page, enter a **Device name**, choose **Passkey or Security Key**, and then choose **Next**. 1. On **Set up device**, set up your passkey. Create a passkey with biometric data like your face or fingerprint, with a device pin, or by inserting the FIDO security key into your computer's USB port and tapping it. 1. Follow the instructions on your browser and then choose **Continue**. You have now registered your passkey or security key for use with AWS. For information about using MFA with the AWS Management Console, see [MFA enabled sign-in](console_sign-in-mfa.md). ## Enable a passkey or security key for another IAM user (console) You can enable a passkey or security for another IAM user from the AWS Management Console only, not from the AWS CLI or AWS API. **To enable a passkey or security for another IAM user (console)** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Users**. 1. Under **Users**, choose the name of the user for whom you want to enable MFA. 1. On the selected IAM user page, choose the **Security Credentials** tab. 1. Under **Multi-factor authentication (MFA)**, choose **Assign MFA device**. 1. On the **MFA device name** page, enter a **Device name**, choose **Passkey or Security Key**, and then choose **Next**. 1. On **Set up device**, set up your passkey. Create a passkey with biometric data like your face or fingerprint, with a device pin, or by inserting the FIDO security key into your computer's USB port and tapping it. 1. Follow the instructions on your browser and then choose **Continue**. You have now registered a passkey or security key for another IAM user to use with AWS. For information about using MFA with the AWS Management Console, see [MFA enabled sign-in](console_sign-in-mfa.md). ## Replace a passkey or security key You can have up to eight MFA devices of any combination of the [ currently supported MFA types](https://aws.amazon.com/iam/features/mfa/) assigned to a user at a time with your AWS account root user and IAM users. If the user loses a FIDO authenticator or needs to replace it for any reason, you must first deactivate the old FIDO authenticator. Then you can add a new MFA device for the user. + To deactivate the device currently associated with an IAM user, see [Deactivate an MFA device](id_credentials_mfa_disable.md). + To add a new FIDO security key for an IAM user, see [Enable a passkey or security key for your own IAM user (console)](#enable-fido-mfa-for-own-iam-user). If you don't have access to a new passkey or security key, you can enable a new virtual MFA device or hardware TOTP token. See one of the following for instructions: + [Assign a virtual MFA device in the AWS Management Console](id_credentials_mfa_enable_virtual.md) + [Assign a hardware TOTP token in the AWS Management Console](id_credentials_mfa_enable_physical.md) # Supported configurations for using passkeys and security keys You can use FIDO2 device-bound passkeys, also known as security keys, as a multi-factor authentication (MFA) method with IAM using currently supported configurations. These include FIDO2 devices supported by IAM and browsers that support FIDO2. Before you register your FIDO2 device, check that you’re using the latest browser and operating system (OS) version. Features may behave differently across different browsers, authenticators, and OS clients. If your device registration fails on one browser, you can try to register with another browser. FIDO2 is an open authentication standard and an extension of FIDO U2F, offering the same high level of security based on public key cryptography. FIDO2 consists of the W3C Web Authentication specification (WebAuthn API) and the FIDO Alliance Client-to-Authenticator Protocol (CTAP), an application layer protocol. CTAP enables communication between client or platform, like a browser or operating system, with an external authenticator. When you enable a FIDO Certified authenticator in AWS, the security key creates a new key pair for use with only AWS. First, you enter your credentials. When prompted, you tap the security key, which responds to the authentication challenge issued by AWS. To learn more about the FIDO2 standard, see the [FIDO2 Project](https://en.wikipedia.org/wiki/FIDO2_Project). ## FIDO2 devices supported by AWS IAM supports FIDO2 security devices that connect to your devices through USB, Bluetooth, or NFC. IAM also supports platform authenticators such as TouchID or FaceID. IAM does not support local passkey registration for Windows Hello. To create and use passkeys, Windows users should use [cross-device authentication](https://passkeys.dev/docs/reference/terms/#cross-device-authentication-cda) where you use a passkey from one device like a mobile device or hardware security key to sign in on another device like a laptop. **Note** AWS requires access to the physical USB port on your computer to verify your FIDO2 device. Security keys will not work with a virtual machine, a remote connection, or a browser's incognito mode. The FIDO Alliance maintains a list of all [FIDO2 products](https://fidoalliance.org/certification/fido-certified-products/) that are compatible with FIDO specifications. ## Browsers that support FIDO2 The availability of FIDO2 security devices that run in a web browser depends on the combination of browser and operating system. The following browsers currently support the use of security keys: **** | Web browser | macOS 10.15\$1 | Windows 10 | Linux | iOS 14.5\$1 | Android 7\$1 | | --- | --- | --- | --- | --- | --- | | Chrome | Yes | Yes | Yes | Yes | No | | Safari | Yes | No | No | Yes | No | | Edge | Yes | Yes | No | Yes | No | | Firefox | Yes | Yes | No | Yes | No | **Note** Most Firefox versions that currently support FIDO2 don't enable support by default. For instructions on enabling FIDO2 support in Firefox, see [Troubleshoot Passkeys and FIDO Security Keys](troubleshoot_mfa-fido.md). Firefox on macOS may not fully support cross-device authentication workflows for passkeys. You may get a prompt to touch a security key instead of proceeding with cross-device authentication. We recommend using a different browser, such as Chrome or Safari, for signing in with passkeys on macOS. For more information about browser support for a FIDO2-Certified device like YubiKey, see [Operating system and web browser support for FIDO2 and U2F](https://support.yubico.com/hc/en-us/articles/360016615020-Operating-system-and-web-browser-support-for-FIDO2-and-U2F). ### Browser plugins AWS supports only browsers that natively support FIDO2. AWS doesn't support using plugins to add FIDO2 browser support. Some browser plugins are incompatible with the FIDO2 standard and can cause unexpected results with FIDO2 security keys. For information on disabling browser plugins and other troubleshooting tips, see [I can't enable my FIDO security key](troubleshoot_mfa-fido.md#troubleshoot_mfa-fido-cant-enable). ## Device certifications We capture and assign device-related certifications, such as FIPS validation and FIDO certification level, only during the registration of a security key. Your device certification is retrieved from the [FIDO Alliance Metadata Service (MDS)](https://fidoalliance.org/metadata/). If the certification status or level of your security key changes, it will not be reflected in the device tags automatically. To update the certification information of a device, register the device again to fetch the updated certification information. AWS provides the following certification types as condition keys during device registration, obtained from the FIDO MDS: FIPS-140-2, FIPS-140-3, and FIDO certification levels. You have the ability to specify the registration of specific authenticators in their IAM policies, based on your preferred certification type and level. For more information, see the policies below. ### Example policies for device certifications The following use cases show sample policies that allow you to register MFA devices with FIPS certifications. **Topics** + [ #### Use case 1: Allow registering only devices that have FIPS-140-2 L2 certifications ](#id_credentials_mfa_fido_certifications_policies_use_case_1) + [ #### Use case 2: Allow registering devices that have FIPS-140-2 L2 and FIDO L1 certifications ](#id_credentials_mfa_fido_certifications_policies_use_case_2) + [ #### Use case 3: Allow registering devices that have either FIPS-140-2 L2 or FIPS-140-3 L2 certifications ](#id_credentials_mfa_fido_certifications_policies_use_case_3) + [ #### Use case 4: Allow registering devices that have FIPS-140-2 L2 certification and support other MFA types like virtual authenticators and hardware TOTP ](#id_credentials_mfa_fido_certifications_policies_use_case_4) #### Use case 1: Allow registering only devices that have FIPS-140-2 L2 certifications ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [{ "Effect": "Allow", "Action": "iam:EnableMFADevice", "Resource": "*", "Condition": { "StringEquals": { "iam:RegisterSecurityKey" : "Create" } } }, { "Effect": "Allow", "Action": "iam:EnableMFADevice", "Resource": "*", "Condition": { "StringEquals": { "iam:RegisterSecurityKey" : "Activate", "iam:FIDO-FIPS-140-2-certification": "L2" } } } ] } ``` ------ #### Use case 2: Allow registering devices that have FIPS-140-2 L2 and FIDO L1 certifications ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [{ "Effect": "Allow", "Action": "iam:EnableMFADevice", "Resource": "*", "Condition": { "StringEquals": { "iam:RegisterSecurityKey" : "Create" } } }, { "Effect": "Allow", "Action": "iam:EnableMFADevice", "Resource": "*", "Condition": { "StringEquals": { "iam:RegisterSecurityKey" : "Activate", "iam:FIDO-FIPS-140-2-certification": "L2", "iam:FIDO-certification": "L1" } } } ] } ``` ------ #### Use case 3: Allow registering devices that have either FIPS-140-2 L2 or FIPS-140-3 L2 certifications ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [{ "Effect": "Allow", "Action": "iam:EnableMFADevice", "Resource": "*", "Condition": { "StringEquals": { "iam:RegisterSecurityKey" : "Create" } } }, { "Effect": "Allow", "Action": "iam:EnableMFADevice", "Resource": "*", "Condition": { "StringEquals": { "iam:RegisterSecurityKey" : "Activate", "iam:FIDO-FIPS-140-2-certification": "L2" } } }, { "Effect": "Allow", "Action": "iam:EnableMFADevice", "Resource": "*", "Condition": { "StringEquals": { "iam:RegisterSecurityKey" : "Activate", "iam:FIDO-FIPS-140-3-certification": "L2" } } } ] } ``` ------ #### Use case 4: Allow registering devices that have FIPS-140-2 L2 certification and support other MFA types like virtual authenticators and hardware TOTP ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "iam:EnableMFADevice", "Resource": "*", "Condition": { "StringEquals": { "iam:RegisterSecurityKey": "Create" } } }, { "Effect": "Allow", "Action": "iam:EnableMFADevice", "Resource": "*", "Condition": { "StringEquals": { "iam:RegisterSecurityKey": "Activate", "iam:FIDO-FIPS-140-2-certification": "L2" } } }, { "Effect": "Allow", "Action": "iam:EnableMFADevice", "Resource": "*", "Condition": { "Null": { "iam:RegisterSecurityKey": "true" } } } ] } ``` ------ ## AWS CLI and AWS API AWS supports using passkeys and security keys only in the AWS Management Console. Using passkeys and security keys for MFA is not supported in the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/) and [AWS API](https://aws.amazon.com/tools/), or for access to [MFA-protected API operations](id_credentials_mfa_configure-api-require.md). ## Additional resources + For more information on using passkeys and security keys in AWS, see [Assign a passkey or security key in the AWS Management Console](id_credentials_mfa_enable_fido.md). + For help with troubleshooting passkeys and security keys in AWS, see [Troubleshoot Passkeys and FIDO Security Keys](troubleshoot_mfa-fido.md). + For general industry information on FIDO2 support, see [FIDO2 Project](https://en.wikipedia.org/wiki/FIDO2_Project). # Assign a virtual MFA device in the AWS Management Console **Important** AWS recommends that you use a passkey or security key for MFA to AWS, wherever possible. For more information, see [Assign a passkey or security key in the AWS Management Console](id_credentials_mfa_enable_fido.md). You can use a phone or other device as a virtual multi-factor authentication (MFA) device. To do this, install a mobile app that is compliant with [RFC 6238, a standards-based TOTP (time-based one-time password) algorithm](https://datatracker.ietf.org/doc/html/rfc6238). These apps generate a six-digit authentication code. Because authenticators can run on unsecured mobile devices, and the codes could potentially be shared with unauthorized parties, TOTP-based MFA does not provide the same level of security as phishing-resistant options such as [FIDO2](https://en.wikipedia.org/wiki/FIDO_Alliance#FIDO2) security keys and passkeys. We recommend that you use passkeys or security keys for MFA for the strongest protection against attacks such as phishing. If you are not yet able to use passkeys or security keys, we recommend that you use a virtual MFA device as an interim measure while you wait for any hardware purchase approvals or for your hardware to arrive. Most virtual MFA apps support creating multiple virtual devices, allowing you to use the same app for multiple AWS accounts or users. You can register up to **eight** MFA devices of any combination of [MFA types](https://aws.amazon.com/iam/features/mfa/) with your AWS account root user and IAM users. You only need one MFA device to sign in to the AWS Management Console or create a session through the AWS CLI. We recommend that you register multiple MFA devices. For authenticator applications, we also recommend enabling the cloud backup or sync feature to help you avoid losing access to your account if you lose or break your device. AWS requires a virtual MFA app that produces a six-digit OTP. For a list of virtual MFA apps that you can use, see [Multi-Factor Authentication](https://aws.amazon.com/iam/features/mfa/?audit=2019q1). **Topics** + [ ## Permissions required ](#mfa_enable_virtual_permissions-required) + [ ## Enable a virtual MFA device for an IAM user (console) ](#enable-virt-mfa-for-iam-user) + [ ## Replace a virtual MFA device ](#replace-virt-mfa) ## Permissions required To manage virtual MFA devices for your IAM user, you must have the permissions from the following policy: [AWS: Allows MFA-authenticated IAM users to manage their own MFA device on the Security credentials page](reference_policies_examples_aws_my-sec-creds-self-manage-mfa-only.md). ## Enable a virtual MFA device for an IAM user (console) You can use IAM in the AWS Management Console to enable and manage a virtual MFA device for an IAM user in your account. You can attach tags to your IAM resources, including virtual MFA devices, to identify, organize, and control access to them. You can tag virtual MFA devices only when you use the AWS CLI or AWS API. To enable and manage an MFA device using the AWS CLI or AWS API, see [Assign MFA devices in the AWS CLI or AWS API](id_credentials_mfa_enable_cliapi.md). For more information about tagging IAM resources, see [Tags for AWS Identity and Access Management resources](id_tags.md). **Note** You must have physical access to the hardware that will host the user's virtual MFA device in order to configure MFA. For example, you might configure MFA for a user who will use a virtual MFA device running on a smartphone. In that case, you must have the smartphone available in order to finish the wizard. Because of this, you might want to let users configure and manage their own virtual MFA devices. In that case, you must grant users the permissions to perform the necessary IAM actions. For more information and for an example of an IAM policy that grants these permissions, see the [IAM tutorial: Permit users to manage their credentials and MFA settings](tutorial_users-self-manage-mfa-and-creds.md) and example policy [AWS: Allows MFA-authenticated IAM users to manage their own MFA device on the Security credentials page](reference_policies_examples_aws_my-sec-creds-self-manage-mfa-only.md). **To enable a virtual MFA device for an IAM user (console)** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Users**. 1. In the **Users** list, choose the name of the IAM user. 1. Choose the **Security Credentials** tab. Under **Multi-factor authentication (MFA)**, choose **Assign MFA device**. 1. In the wizard, type a **Device name**, choose **Authenticator app**, and then choose **Next**. IAM generates and displays configuration information for the virtual MFA device, including a QR code graphic. The graphic is a representation of the "secret configuration key" that is available for manual entry on devices that do not support QR codes. 1. Open your virtual MFA app. For a list of apps that you can use for hosting virtual MFA devices, see [Multi-Factor Authentication](http://aws.amazon.com/iam/details/mfa/). If the virtual MFA app supports multiple virtual MFA devices or accounts, choose the option to create a new virtual MFA device or account. 1. Determine whether the MFA app supports QR codes, and then do one of the following: + From the wizard, choose **Show QR code**, and then use the app to scan the QR code. This might be a camera icon or **Scan code** option that uses the device's camera to scan the code. + From the wizard, choose **Show secret key**, and then type the secret key into your MFA app. When you are finished, the virtual MFA device starts generating one-time passwords. 1. On the **Set up device** page, in the **MFA 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 into the **MFA code 2** box. Choose **Add MFA**. **Important** Submit your request immediately after generating the codes. If you generate the codes and then wait too long to submit the request, the MFA device successfully associates with the user but the MFA device is out of sync. This happens because time-based one-time passwords (TOTP) expire after a short period of time. If this happens, you can [resync the device](id_credentials_mfa_sync.md). The virtual MFA device is now ready for use with AWS. For information about using MFA with the AWS Management Console, see [MFA enabled sign-in](console_sign-in-mfa.md). **Note** Unassigned virtual MFA devices in your AWS account are deleted when you’re adding new virtual MFA devices either via the AWS Management Console or during the sign-in process. Unassigned virtual MFA devices are devices in your account but not used by account root user or IAM users for the sign-in process. They’re deleted so new virtual MFA devices can be added to your account. It also allows you to reuse device names. To view unassigned virtual MFA devices in your account, you can use either the [list-virtual-mfa-devices](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/list-virtual-mfa-devices.html) AWS CLI command or [API](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListVirtualMFADevices.html) call. To deactivate a virtual MFA device, you can use either the [deactivate-mfa-device](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/deactivate-mfa-device.html) AWS CLI command or [API](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeactivateMFADevice.html) call. The device will become unassigned. To attach an unassigned virtual MFA device to your AWS account root user or IAM users, you'll need the authentication code generated by the device along with either the [enable-mfa-device](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/iam/enable-mfa-device.html) AWS CLI command or [API](https://docs.aws.amazon.com/IAM/latest/APIReference/API_EnableMFADevice.html) call. ## Replace a virtual MFA device Your AWS account root user and IAM users can register up to **eight** MFA devices of any combination of MFA types. If the user loses a device or needs to replace it for any reason, deactivate the old device. Then you can add the new device for the user. + To deactivate the device currently associated with another IAM user, see [Deactivate an MFA device](id_credentials_mfa_disable.md). + To add a replacement virtual MFA device for another IAM user, follow the steps in the procedure [Enable a virtual MFA device for an IAM user (console)](#enable-virt-mfa-for-iam-user) above. + To add a replacement virtual MFA device for the AWS account root user, follow the steps in the procedure [Enable a virtual MFA device for the root user (console)](enable-virt-mfa-for-root.md). # Assign a hardware TOTP token in the AWS Management Console **Important** AWS recommends that you use a passkey or security key for MFA to AWS, wherever possible. For more information, see [Assign a passkey or security key in the AWS Management Console](id_credentials_mfa_enable_fido.md). A hardware TOTP token generates a six-digit numeric code based upon a time-based one-time password (TOTP) algorithm. The user must type a valid code from the device when prompted during the sign-in process. Each MFA device assigned to a user must be unique; a user cannot type a code from another user's device to be authenticated. MFA devices cannot be shared across accounts or users. Hardware TOTP tokens and [FIDO security keys](id_credentials_mfa_enable_fido.md) are both physical devices that you purchase. Hardware MFA devices generate TOTP codes for authentication when you sign in to AWS. They rely on batteries, which may need replacement and resynchronization with AWS over time. FIDO security keys, which utilize public key cryptography, do not require batteries and offer a seamless authentication process. We recommend using FIDO security keys for their phishing resistance, which provides a more secure alternative to TOTP devices. Additionally, FIDO security keys can support multiple IAM or root users on the same device, enhancing their utility for account security. For specifications and purchase information for both device types, see [Multi-Factor Authentication](http://aws.amazon.com/iam/details/mfa/). You can enable a hardware TOTP token for an IAM user from the AWS Management Console, the command line, or the IAM API. To enable an MFA device for your AWS account root user, see [Enable a hardware TOTP token for the root user (console)](enable-hw-mfa-for-root.md). You can register up to **eight** MFA devices of any combination of the [ currently supported MFA types](https://aws.amazon.com/iam/features/mfa/) with your AWS account root user and IAM users. With multiple MFA devices, you only need one MFA device to sign in to the AWS Management Console or create a session through the AWS CLI as that user. **Important** We recommend that you enable multiple MFA devices for your users for continued access to your account in case of a lost or inaccessible MFA device. **Note** If you want to enable the MFA device from the command line, use [https://docs.aws.amazon.com/cli/latest/reference/iam/enable-mfa-device.html](https://docs.aws.amazon.com/cli/latest/reference/iam/enable-mfa-device.html). To enable the MFA device with the IAM API, use the [https://docs.aws.amazon.com/IAM/latest/APIReference/API_EnableMFADevice.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_EnableMFADevice.html) operation. **Topics** + [ ## Permissions required ](#enable-hw-mfa-for-iam-user-permissions-required) + [ ## Enable a hardware TOTP token for your own IAM user (console) ](#enable-hw-mfa-for-own-iam-user) + [ ## Enable a hardware TOTP token for another IAM user (console) ](#enable-hw-mfa-for-iam-user) + [ ## Replace a physical MFA device ](#replace-phys-mfa) ## Permissions required To manage a hardware TOTP token for your own IAM user while protecting sensitive MFA-related actions, you must have the permissions from the following policy: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowManageOwnUserMFA", "Effect": "Allow", "Action": [ "iam:DeactivateMFADevice", "iam:EnableMFADevice", "iam:GetUser", "iam:ListMFADevices", "iam:ResyncMFADevice" ], "Resource": "arn:aws:iam::*:user/${aws:username}" }, { "Sid": "DenyAllExceptListedIfNoMFA", "Effect": "Deny", "NotAction": [ "iam:EnableMFADevice", "iam:GetUser", "iam:ListMFADevices", "iam:ResyncMFADevice" ], "Resource": "arn:aws:iam::*:user/${aws:username}", "Condition": { "BoolIfExists": { "aws:MultiFactorAuthPresent": "false" } } } ] } ``` ------ ## Enable a hardware TOTP token for your own IAM user (console) You can enable your own hardware TOTP token from the AWS Management Console. **Note** Before you can enable a hardware TOTP token, you must have physical access to the device. **To enable a hardware TOTP token for your own IAM user (console)** 1. Use your AWS account ID or account alias, your IAM user name, and your password to sign in to the [IAM console](https://console.aws.amazon.com/iam). **Note** For your convenience, the AWS sign-in page uses a browser cookie to remember your IAM user name and account information. If you previously signed in as a different user, choose **Sign in to a different account** near the bottom of the page to return to the main sign-in page. From there, you can type your AWS account ID or account alias to be redirected to the IAM user sign-in page for your account. To get your AWS account ID, contact your administrator. 1. In the navigation bar on the upper right, choose your user name, and then choose **Security credentials**. ![\[AWS Management Console Security credentials link\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/images/security-credentials-user.shared.console.png) 1. On the **AWS IAM credentials** tab, in the **Multi-factor authentication (MFA)** section, choose **Assign MFA device**. 1. In the wizard, type a **Device name**, choose **Hardware TOTP token**, and then choose **Next**. 1. Type the device serial number. The serial number is usually on the back of the device. 1. In the **MFA code 1** box, type the six-digit number displayed by the MFA device. You might need to press the button on the front of the device to display the number. ![\[IAM Dashboard, MFA Device\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/images/MFADevice.png) 1. Wait 30 seconds while the device refreshes the code, and then type the next six-digit number into the **MFA code 2** box. You might need to press the button on the front of the device again to display the second number. 1. Choose **Add MFA**. **Important** Submit your request immediately after generating the authentication codes. If you generate the codes and then wait too long to submit the request, the MFA device successfully associates with the user but the MFA device becomes out of sync. This happens because time-based one-time passwords (TOTP) expire after a short period of time. If this happens, you can [resync the device](id_credentials_mfa_sync.md). The device is ready for use with AWS. For information about using MFA with the AWS Management Console, see [MFA enabled sign-in](console_sign-in-mfa.md). ## Enable a hardware TOTP token for another IAM user (console) You can enable a hardware TOTP token for another IAM user from the AWS Management Console. **To enable a hardware TOTP token for another IAM user (console)** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Users**. 1. Choose the name of the user for whom you want to enable MFA. 1. Choose the **Security Credentials** tab. Under **Multi-factor authentication (MFA)**, choose **Assign MFA device**. 1. In the wizard, type a **Device name**, choose **Hardware TOTP token**, and then choose **Next**. 1. Type the device serial number. The serial number is usually on the back of the device. 1. In the **MFA code 1** box, type the six-digit number displayed by the MFA device. You might need to press the button on the front of the device to display the number. ![\[IAM Dashboard, MFA Device\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/images/MFADevice.png) 1. Wait 30 seconds while the device refreshes the code, and then type the next six-digit number into the **MFA code 2** box. You might need to press the button on the front of the device again to display the second number. 1. Choose **Add MFA**. **Important** Submit your request immediately after generating the authentication codes. If you generate the codes and then wait too long to submit the request, the MFA device successfully associates with the user but the MFA device becomes out of sync. This happens because time-based one-time passwords (TOTP) expire after a short period of time. If this happens, you can [resync the device](id_credentials_mfa_sync.md). The device is ready for use with AWS. For information about using MFA with the AWS Management Console, see [MFA enabled sign-in](console_sign-in-mfa.md). ## Replace a physical MFA device You can have up to eight MFA devices of any combination of the [currently supported MFA types](https://aws.amazon.com/iam/features/mfa/) assigned to a user at a time with your AWS account root user and IAM users. If the user loses a device or needs to replace it for any reason, you must first deactivate the old device. Then you can add the new device for the user. + To deactivate the device currently associated with a user, see [Deactivate an MFA device](id_credentials_mfa_disable.md). + To add a replacement hardware TOTP token for an IAM user, follow the steps in the procedure [Enable a hardware TOTP token for another IAM user (console)](#enable-hw-mfa-for-iam-user) earlier in this topic. + To add a replacement hardware TOTP token for the AWS account root user, follow the steps in the procedure [Enable a hardware TOTP token for the root user (console)](enable-hw-mfa-for-root.md) earlier in this topic. # Assign MFA devices in the AWS CLI or AWS API You can use AWS CLI commands or AWS API operations to enable a virtual MFA device for an IAM user. You cannot enable an MFA device for the AWS account root user with the AWS CLI, AWS API, Tools for Windows PowerShell, or any other command line tool. However, you can use the AWS Management Console to enable an MFA device for the root user. When you enable an MFA device from the AWS Management Console, the console performs multiple steps for you. If you instead create a virtual device using the AWS CLI, Tools for Windows PowerShell, or AWS API, then you must perform the steps manually and in the correct order. For example, to create a virtual MFA device, you must create the IAM object and extract the code as either a string or a QR code graphic. Then you must sync the device and associate it with an IAM user. See the **Examples** section of [New-IAMVirtualMFADevice](https://docs.aws.amazon.com/powershell/latest/reference/Index.html?page=New-IAMVirtualMFADevice.html&tocid=New-IAMVirtualMFADevice) for more details. For a physical device, you skip the creation step and go directly to syncing the device and associating it with the user. You can attach tags to your IAM resources, including virtual MFA devices, to identify, organize, and control access to them. You can tag virtual MFA devices only when you use the AWS CLI or AWS API. An IAM user using the SDK or CLI can enable an additional MFA device by calling [https://docs.aws.amazon.com/IAM/latest/APIReference/API_EnableMFADevice.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_EnableMFADevice.html) or deactivate an existing MFA device by calling [https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeactivateMFADevice.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeactivateMFADevice.html). To do this successfully, they must first call [https://docs.aws.amazon.com/STS/latest/APIReference/API_GetSessionToken.html](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetSessionToken.html) and submit MFA codes with an existing MFA device. This call returns temporary security credentials that can then be used to sign API operations that require MFA authentication. For an example request and response, see [`GetSessionToken`—temporary credentials for users in untrusted environments](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#api_getsessiontoken). **To create the virtual device entity in IAM to represent a virtual MFA device** These commands provide an ARN for the device that is used in place of a serial number in many of the following commands. + AWS CLI: [https://docs.aws.amazon.com/cli/latest/reference/iam/create-virtual-mfa-device.html](https://docs.aws.amazon.com/cli/latest/reference/iam/create-virtual-mfa-device.html) + AWS API: [https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateVirtualMFADevice.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_CreateVirtualMFADevice.html) **To enable an MFA device for use with AWS** These commands synchronize the device with AWS and associate it with a user. If the device is virtual, use the ARN of the virtual device as the serial number. **Important** Submit your request immediately after generating the authentication codes. If you generate the codes and then wait too long to submit the request, the MFA device successfully associates with the user but the MFA device becomes out of sync. This happens because time-based one-time passwords (TOTP) expire after a short period of time. If this happens, you can resynchronize the device using the commands described below. + AWS CLI: [https://docs.aws.amazon.com/cli/latest/reference/iam/enable-mfa-device.html](https://docs.aws.amazon.com/cli/latest/reference/iam/enable-mfa-device.html) + AWS API: [https://docs.aws.amazon.com/IAM/latest/APIReference/API_EnableMFADevice.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_EnableMFADevice.html) **To deactivate a device** Use these commands to disassociate the device from the user and deactivate it. If the device is virtual, use the ARN of the virtual device as the serial number. You must also separately delete the virtual device entity. + AWS CLI: [https://docs.aws.amazon.com/cli/latest/reference/iam/deactivate-mfa-device.html](https://docs.aws.amazon.com/cli/latest/reference/iam/deactivate-mfa-device.html) + AWS API: [https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeactivateMFADevice.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeactivateMFADevice.html) **To list virtual MFA device entities** Use these commands to list virtual MFA device entities. + AWS CLI: [https://docs.aws.amazon.com/cli/latest/reference/iam/list-virtual-mfa-devices.html](https://docs.aws.amazon.com/cli/latest/reference/iam/list-virtual-mfa-devices.html) + AWS API: [https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListVirtualMFADevices.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListVirtualMFADevices.html) **To tag a virtual MFA device** Use these commands to tag a virtual MFA device. + AWS CLI: [https://docs.aws.amazon.com/cli/latest/reference/iam/tag-mfa-device.html](https://docs.aws.amazon.com/cli/latest/reference/iam/tag-mfa-device.html) + AWS API: [https://docs.aws.amazon.com/IAM/latest/APIReference/API_TagMFADevice.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_TagMFADevice.html) **To list tags for a virtual MFA device** Use these commands to list the tags attached to a virtual MFA device. + AWS CLI: [https://docs.aws.amazon.com/cli/latest/reference/iam/list-mfa-device-tags.html](https://docs.aws.amazon.com/cli/latest/reference/iam/list-mfa-device-tags.html) + AWS API: [https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListMFADeviceTags.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ListMFADeviceTags.html) **To untag a virtual MFA device** Use these commands to remove tags attached to a virtual MFA device. + AWS CLI: [https://docs.aws.amazon.com/cli/latest/reference/iam/untag-mfa-device.html](https://docs.aws.amazon.com/cli/latest/reference/iam/untag-mfa-device.html) + AWS API: [https://docs.aws.amazon.com/IAM/latest/APIReference/API_UntagMFADevice.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_UntagMFADevice.html) **To resynchronize an MFA device** Use these commands if the device is generating codes that are not accepted by AWS. If the device is virtual, use the ARN of the virtual device as the serial number. + AWS CLI: [https://docs.aws.amazon.com/cli/latest/reference/iam/resync-mfa-device.html](https://docs.aws.amazon.com/cli/latest/reference/iam/resync-mfa-device.html) + AWS API: [https://docs.aws.amazon.com/IAM/latest/APIReference/API_ResyncMFADevice.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ResyncMFADevice.html) **To delete a virtual MFA device entity in IAM** After the device is disassociated from the user, you can delete the device entity. + AWS CLI: [https://docs.aws.amazon.com/cli/latest/reference/iam/delete-virtual-mfa-device.html](https://docs.aws.amazon.com/cli/latest/reference/iam/delete-virtual-mfa-device.html) + AWS API: [https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteVirtualMFADevice.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeleteVirtualMFADevice.html) **To recover a virtual MFA device that is lost or not working** Sometimes, a user's device that hosts the virtual MFA app is lost, replaced, or not working. When this happens, the user can't recover it on their own. The user must contact an administrator to deactivate the device. For more information, see [Recover an MFA protected identity in IAM](id_credentials_mfa_lost-or-broken.md). # Check MFA status Use the IAM console to check whether an AWS account root user or IAM user has a valid MFA device enabled. **To check the MFA status of a root user** 1. Sign in to the AWS Management Console with your root user credentials and then open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation bar on the upper right, choose your user name, and then choose **Security credentials**. 1. Check under **Multi-factor Authentication (MFA)** to see whether MFA is enabled or disabled. If MFA has not been activated, an alert symbol (![\[Alert icon\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/images/console-alert-icon.console.png)) is displayed. If you want to enable MFA for the account, see one of the following: + [Enable a virtual MFA device for the root user (console)](enable-virt-mfa-for-root.md) + [Enable a passkey or security key for the root user (console)](enable-fido-mfa-for-root.md) + [Enable a hardware TOTP token for the root user (console)](enable-hw-mfa-for-root.md) **To check the MFA status of IAM users** 1. Open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Users**. 1. If necessary, add the **MFA** column to the users table by completing the following steps: 1. Above the table on the far right, choose the settings icon (![\[Settings icon\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/images/console-settings-icon.console.png)). 1. In **Manage Columns**, select **MFA**. 1. (Optional) Clear the checkbox for any column headings that you do not want to appear in the users table. 1. Choose **Close** to return to the list of users. 1. The **MFA** column tells you about the MFA device that is enabled. If no MFA device is active for the user, the console displays **None**. If the user has an MFA device enabled, the **MFA** column shows the type of device that is enabled with a value of **Virtual**, **Security key**, **Hardware**, or **SMS**. **Note** AWS ended support for enabling SMS multi-factor authentication (MFA). We recommend that customers who have IAM users that use SMS text message-based MFA switch to one of the following alternative methods: [virtual (software-based) MFA device](id_credentials_mfa_enable_virtual.md), [FIDO security key](id_credentials_mfa_enable_fido.md), or [hardware MFA device](id_credentials_mfa_enable_physical.md). You can identify the users in your account with an assigned SMS MFA device. To do so, go to the IAM console, choose **Users** from the navigation pane, and look for users with **SMS** in the **MFA** column of the table. 1. To view additional information about the MFA device for a user, choose the name of the user whose MFA status you want to check. Then choose the **Security credentials** tab. 1. If no MFA device is active for the user, the console displays **No MFA devices. Assign an MFA device to improve the security of your AWS environment** in the **Multi-factor authentication (MFA)** section. If the user has MFA devices enabled, the **Multi-factor authentication (MFA)** section shows details about the devices: + The device name + The device type + The identifier for the device, such as a serial number for a physical device or the ARN in AWS for a virtual device + When the device was created To remove or resync a device, choose the radio button next to the device and choose **Remove** or **Resync**. For more information on enabling MFA, see the following: + [Assign a virtual MFA device in the AWS Management Console](id_credentials_mfa_enable_virtual.md) + [Assign a passkey or security key in the AWS Management Console](id_credentials_mfa_enable_fido.md) + [Assign a hardware TOTP token in the AWS Management Console](id_credentials_mfa_enable_physical.md) # Resynchronize virtual and hardware MFA devices You can use AWS to resynchronize your virtual and hardware multi-factor authentication (MFA) devices. If your device is not synchronized when you try to use it, the sign-in attempt fails and IAM prompts you to resynchronize the device. **Note** FIDO security keys do not go out of sync. If a FIDO security key is lost or broken, you can deactivate it. For instructions on deactivating any MFA device type, see [To deactivate an MFA device for another IAM user (console)](id_credentials_mfa_disable.md#deactivate-mfa-for-user). As an AWS administrator, you can resynchronize your IAM users' virtual and hardware MFA devices if they get out of synchronization. If your AWS account root user MFA device is not working, you can resynchronize your device using the IAM console with or without completing the sign-in process. If you aren’t able to successfully resynchronize your device, you may need to de-associate and re-associate it. For more information on how to do this, see [Deactivate an MFA device](id_credentials_mfa_disable.md) and [AWS Multi-factor authentication in IAM](id_credentials_mfa.md). **Topics** + [ ## Permissions required ](#id_credentials_mfa_sync_console-permissions-required) + [ ## Resynchronizing virtual and hardware MFA devices (IAM console) ](#id_credentials_mfa_sync_console) + [ ## Resynchronizing virtual and hardware MFA devices (AWS CLI) ](#id_credentials_mfa_sync_cli) + [ ## Resynchronizing virtual and hardware MFA devices (AWS API) ](#id_credentials_mfa_sync_api) ## Permissions required To resynchronize virtual or hardware MFA devices for your own IAM user, you must have the permissions from the following policy. This policy does not allow you to create or deactivate a device. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "AllowListActions", "Effect": "Allow", "Action": [ "iam:ListVirtualMFADevices" ], "Resource": "*" }, { "Sid": "AllowUserToViewAndManageTheirOwnUserMFA", "Effect": "Allow", "Action": [ "iam:ListMFADevices", "iam:ResyncMFADevice" ], "Resource": "arn:aws:iam::*:user/${aws:username}" }, { "Sid": "BlockAllExceptListedIfNoMFA", "Effect": "Deny", "NotAction": [ "iam:ListMFADevices", "iam:ListVirtualMFADevices", "iam:ResyncMFADevice" ], "Resource": "*", "Condition": { "BoolIfExists": { "aws:MultiFactorAuthPresent": "false" } } } ] } ``` ------ ## Resynchronizing virtual and hardware MFA devices (IAM console) You can use the IAM console to resynchronize virtual and hardware MFA devices. **To resynchronize a virtual or hardware MFA device for your own IAM user (console)** 1. Use your AWS account ID or account alias, your IAM user name, and your password to sign in to the [IAM console](https://console.aws.amazon.com/iam). **Note** For your convenience, the AWS sign-in page uses a browser cookie to remember your IAM user name and account information. If you previously signed in as a different user, choose **Sign in to a different account** near the bottom of the page to return to the main sign-in page. From there, you can type your AWS account ID or account alias to be redirected to the IAM user sign-in page for your account. To get your AWS account ID, contact your administrator. 1. In the navigation bar on the upper right, choose your user name, and then choose **Security credentials**. ![\[AWS Management Console Security credentials link\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/images/security-credentials-user.shared.console.png) 1. On the **AWS IAM credentials** tab, in the **Multi-factor authentication (MFA)** section, choose the radio button next to the MFA device and choose **Resync**. 1. Type the next two sequentially generated codes from the device into **MFA code 1** and **MFA code 2**. Then choose **Resync**. **Important** Submit your request immediately after generating the codes. If you generate the codes and then wait too long to submit the request, the request appears to work but the device remains out of sync. This happens because time-based one-time passwords (TOTP) expire after a short period of time. **To resynchronize a virtual or hardware MFA device for another IAM user (console)** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Users**, and then choose the name of the user whose MFA device needs to be resynchronized. 1. Choose the **Security credentials** tab. In the **Multi-factor authentication (MFA)** section, choose the radio button next to the MFA device and choose **Resync**. 1. Type the next two sequentially generated codes from the device into **MFA code 1** and **MFA code 2**. Then choose **Resync**. **Important** Submit your request immediately after generating the codes. If you generate the codes and then wait too long to submit the request, the request appears to work but the device remains out of sync. This happens because time-based one-time passwords (TOTP) expire after a short period of time. **To resynchronize your root user MFA before signing in (console)** 1. On the **Amazon Web Services Sign In With Authentication Device** page, choose **Having problems with your authentication device? Click here**. **Note** You might see different text, such as **Sign in using MFA** and **Troubleshoot your authentication device**. However, the same features are provided. 1. In the **Re-Sync With Our Servers** section, type the next two sequentially generated codes from the device into **MFA code 1** and **MFA code 2**. Then choose **Re-sync authentication device**. 1. If necessary, type your password again and choose **Sign in**. Then complete the sign-in using your MFA device. **To resynchronize your root user MFA device after signing in (console)** 1. Sign in to the [IAM console](https://console.aws.amazon.com/iam/) as the account owner by choosing **Root user** and entering your AWS account email address. On the next page, enter your password. **Note** As the root user, you can't sign in to the **Sign in as IAM user** page. If you see the **Sign in as IAM user** page, choose **Sign in using root user email** near the bottom of the page. For help signing in as the root user, see [Signing in to the AWS Management Console as the root user](https://docs.aws.amazon.com/signin/latest/userguide/introduction-to- root-user-sign-in-tutorial.html) in the *AWS Sign-In User Guide*. 1. On the right side of the navigation bar, choose on your account name, and then choose **Security credentials**. If necessary, choose **Continue to Security credentials**. ![\[Security credentials in the navigation menu\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/images/security-credentials-root.shared.console.png) 1. Expand the **Multi-factor authentication (MFA)** section on the page. 1. Choose the radio button next to the device and choose **Resync**. 1. In the **Resync MFA device** dialog box, type the next two sequentially generated codes from the device into **MFA code 1** and **MFA code 2**. Then choose **Resync**. **Important** Submit your request immediately after generating the codes. If you generate the codes and then wait too long to submit the request, the MFA device is successfully associated with the user, but the MFA device is out of sync. This happens because time-based one-time passwords (TOTP) expire after a short period of time. ## Resynchronizing virtual and hardware MFA devices (AWS CLI) You can resynchronize virtual and hardware MFA devices from the AWS CLI. **To resynchronize a virtual or hardware MFA device for an IAM user (AWS CLI)** At a command prompt, issue the [aws iam resync-mfa-device](https://docs.aws.amazon.com/cli/latest/reference/iam/resync-mfa-device.html) command: + Virtual MFA device: Specify Amazon Resource Name (ARN) of device as the serial number. ``` aws iam resync-mfa-device --user-name Richard --serial-number arn:aws:iam::123456789012:mfa/RichardsMFA --authentication-code1 123456 --authentication-code2 987654 ``` + Hardware MFA device: Specify hardware device's serial number as serial number. The format is vendor-specific. For example, you can purchase a gemalto token from Amazon. Its serial number is typically four letters followed by four numbers. ``` aws iam resync-mfa-device --user-name Richard --serial-number ABCD12345678 --authentication-code1 123456 --authentication-code2 987654 ``` **Important** Submit your request immediately after generating the codes. If you generate the codes and then wait too long to submit the request, the request fails because the codes expire after a short time. ## Resynchronizing virtual and hardware MFA devices (AWS API) IAM has an API call that performs synchronization. In this case, we recommend that you give your virtual and hardware MFA device users permission to access this API call. Then build a tool based on that API call so your users can resynchronize their devices whenever they need to. **To resynchronize a virtual or hardware MFA device for an IAM user (AWS API)** + Send the [ResyncMFADevice](https://docs.aws.amazon.com/IAM/latest/APIReference/API_ResyncMFADevice.html) request. # Deactivate an MFA device If you are having trouble signing in with a multi-factor authentication (MFA) device as an IAM user, contact your administrator for help. As an administrator, you can deactivate the device for another IAM user. This allows the user to sign in without using MFA. You might do this as a temporary solution while the MFA device is replaced, or if the device is temporarily unavailable. However, we recommend that you enable a new device for the user as soon as possible. To learn how to enable a new MFA device, see [AWS Multi-factor authentication in IAM](id_credentials_mfa.md). **Note** If you use the API or AWS CLI to delete a user from your AWS account, you must deactivate or delete the user's MFA device. You make this change as part of the process of removing the user. For more information about removing users, see [Remove or deactivate an IAM user](id_users_remove.md). **Topics** + [ ## Deactivating MFA devices (console) ](#deactive-mfa-console) + [ ## Deactivating MFA devices (AWS CLI) ](#deactivate-mfa-cli) + [ ## Deactivating MFA devices (AWS API) ](#deactivate-mfa-api) ## Deactivating MFA devices (console) **To deactivate an MFA device for another IAM user (console)** 1. Sign in to the AWS Management Console and open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. In the navigation pane, choose **Users**. 1. To deactivate the MFA device for a user, choose the name of the user whose MFA you want to remove. 1. Choose the **Security credentials** tab. 1. Under **​Multi-factor authentication (MFA)**, choose the radio button next to the MFA device, choose **Remove**, and then choose **Remove**. The device is removed from AWS. It cannot be used to sign in or authenticate requests until it is reactivated and associated with an AWS user or AWS account root user. **To deactivate the MFA device for your AWS account root user (console)** 1. Sign in to the [IAM console](https://console.aws.amazon.com/iam/) as the account owner by choosing **Root user** and entering your AWS account email address. On the next page, enter your password. **Note** As the root user, you can't sign in to the **Sign in as IAM user** page. If you see the **Sign in as IAM user** page, choose **Sign in using root user email** near the bottom of the page. For help signing in as the root user, see [Signing in to the AWS Management Console as the root user](https://docs.aws.amazon.com/signin/latest/userguide/introduction-to- root-user-sign-in-tutorial.html) in the *AWS Sign-In User Guide*. 1. On the right side of the navigation bar, choose on your account name, and then choose **Security credentials**. If necessary, choose **Continue to Security credentials**. ![\[Security credentials in the navigation menu\]](http://docs.aws.amazon.com/IAM/latest/UserGuide/images/security-credentials-root.shared.console.png) 1. In the **Multi-factor authentication (MFA)** section, choose the radio button next the MFA device that you want to deactivate and choose **Remove**. 1. Choose **Remove**. The MFA device is deactivated for the AWS account. Check the email that is associated with your AWS account for a confirmation message from Amazon Web Services. The email informs you that your Amazon Web Services multi-factor authentication (MFA) has been deactivated. The message will come from `@amazon.com` or `@aws.amazon.com`. **Note** Unassigned virtual MFA devices in your AWS account are deleted when you’re adding new virtual MFA devices either via the AWS Management Console or during the sign-in process. Unassigned virtual MFA devices are devices in your account but not used by account root user or IAM users for the sign-in process. They’re deleted so new virtual MFA devices can be added to your account. It also allows you to reuse device names. ## Deactivating MFA devices (AWS CLI) **To deactivate an MFA device for an IAM user (AWS CLI)** + Run this command: [https://docs.aws.amazon.com/cli/latest/reference/iam/deactivate-mfa-device.html](https://docs.aws.amazon.com/cli/latest/reference/iam/deactivate-mfa-device.html) ## Deactivating MFA devices (AWS API) **To deactivate an MFA device for an IAM user (AWS API)** + Call this operation: [https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeactivateMFADevice.html](https://docs.aws.amazon.com/IAM/latest/APIReference/API_DeactivateMFADevice.html) # Recover an MFA protected identity in IAM If your [virtual MFA device](id_credentials_mfa_enable_virtual.md) or [hardware TOTP token](id_credentials_mfa_enable_physical.md) appears to be functioning properly, but you can't use it to access your AWS resources, it might be out of synchronization with AWS. For information about synchronizing a virtual MFA device or hardware MFA device, see [Resynchronize virtual and hardware MFA devices](id_credentials_mfa_sync.md). [FIDO security keys](id_credentials_mfa_enable_fido.md) do not go out of sync. If the [MFA device](id_credentials_mfa.md) for a AWS account root user is lost, damaged, or not working, you can recover access to your account. IAM users must contact an administrator to deactivate the device. **Important** We recommend that you activate multiple MFA devices. Registering multiple MFA devices helps ensure continued access if a device is lost or broken. Your AWS account root user and IAM users can register up to eight MFA devices of any type. ## Prerequisite – Use another MFA device If your [multi-factor authentication (MFA) device](id_credentials_mfa.md) is lost, damaged, or not working, you can sign in using another MFA device registered to the same root user or IAM user. **To sign in using another MFA device** 1. Sign in to the [AWS Management Console](url-comsole-domain;iam) with your AWS account ID or account alias and password. 1. On the **Additional verification required** page or **Multi-factor authentication** page, choose **Try another MFA method**. 1. Authenticate with the type of MFA device that you selected. 1. The next step varies based on whether you successfully signed in with an alternate MFA device. + If you have successfully signed in, you can [Resynchronize virtual and hardware MFA devices](id_credentials_mfa_sync.md), which may resolve the issue. If your MFA device is lost or broken, you can deactivate it. For instructions on deactivating any MFA device type, see [Deactivate an MFA device](id_credentials_mfa_disable.md). + If you can't sign in with MFA, use the steps in [Recovering a root user MFA device](#root-mfa-lost-or-broken) or [Recovering an IAM user MFA device](#iam-user-mfa-lost-or-broken) to recover your MFA protected identity. ## Recovering a root user MFA device If you can't sign in with MFA, you can use alternative methods of authentication to sign in by verifying your identity using the email and the primary contact phone number registered with your account. Confirm you are able to access the email and primary contact phone number associated with your account before you use alternative authentication factors to sign in as a root user. If you need to update the primary contact phone number, sign in as an IAM user with *Administrator* access instead of the root user. For additional instructions on updating the account contact information, see [Editing contact information](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-update-contact-primary.html) in the *AWS Billing User Guide*. If you do not have access to an email and primary contact phone number, you must contact [AWS Support](https://support.aws.amazon.com/#/contacts/aws-mfa-support). **Important** We recommend that you keep the email address and contact phone number linked to your root user up to date for a successful account recovery. For more information, see [Update the primary contact for your AWS account](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-update-contact-primary.html) in the *AWS Account Management Reference Guide*. **To sign in using alternative factors of authentication as an AWS account root user** 1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/) as the account owner by choosing **Root user** and entering your AWS account email address. On the next page, enter your password. 1. On the **Additional verification required** page, select an MFA method to authenticate with and choose **Next**. **Note** You might see alternative text, such as **Sign in using MFA**, **Troubleshoot your authentication device**, or **Troubleshoot MFA**, but the functionality is the same. If you can't use alternative authentication factors to verify your account email address and primary contact phone number, contact [AWS Support](https://support.aws.amazon.com/#/contacts/aws-mfa-support) to deactivate your MFA device. 1. Depending on the type of MFA you are using, you will see a different page, but the **Troubleshoot MFA** option functions the same. On the **Additional verification required** page or **Multi-factor authentication** page, choose **Troubleshoot MFA**. 1. If required, type your password again and choose **Sign in**. 1. On the **Troubleshoot your authentication device** page, in the **Sign in using alternative factors of authentication** section, choose **Sign in using alternative factors**. 1. On the **Sign in using alternative factors of authentication** page, authenticate your account by verifying the email address, choose **Send verification email**. 1. Check the email that is associated with your AWS account for a message from Amazon Web Services (recover-mfa-no-reply@verify.signin.aws). Follow the directions in the email. If you don't see the email in your account, check your spam folder, or return to your browser and choose **Resend the email**. 1. After you verify your email address, you can continue authenticating your account. To verify your primary contact phone number, choose **Call me now**. 1. Answer the call from AWS and, when prompted, enter the 6-digit number from the AWS website on your phone keypad. If you don't receive a call from AWS, choose **Sign in **to sign in to the console again and start over. Or see [Lost or unusable Multi-Factor Authentication (MFA) device](https://support.aws.amazon.com/#/contacts/aws-mfa-support) to contact support for help. 1. After you verify your phone number, you can sign in to your account by choosing **Sign in to the console**. 1. The next step varies depending on the type of MFA you are using: + For a virtual MFA device, remove the account from your device. Then go to the [AWS Security Credentials](https://console.aws.amazon.com/iam/home?#security_credential) page and delete the old MFA virtual device entity before you create a new one. + For a FIDO security key, go to the [AWS Security Credentials](https://console.aws.amazon.com/iam/home?#security_credential) page and deactivate the old FIDO security key before enabling a new one. + For a hardware TOTP token, contact the third-party provider for help with fixing or replacing the device. You can continue to sign in using alternative factors of authentication until you receive your new device. After you have the new hardware MFA device, go to the [AWS Security Credentials](https://console.aws.amazon.com/iam/home?#security_credential) page and delete the old MFA device. **Note** You don't have to replace a lost or stolen MFA device with the same type of device. For example, if you break your FIDO security key and order a new one, you can use virtual MFA or a hardware TOTP token until the new FIDO key arrives. **Important** If your MFA device is missing or stolen, change your root user password after signing in and establishing your replacement MFA device. An attacker may have stolen the authentication device and might also have your current password. For more information, see [Change the password for the AWS account root user](root-user-password.md). ## Recovering an IAM user MFA device If you are an IAM user that can't sign in with MFA, you can't recover an MFA device by yourself. You must contact an administrator to deactivate the device. Then you can enable a new device. **To get help for an MFA device as an IAM user** 1. Contact the AWS administrator or other person who gave you the user name and password for the IAM user. The administrator must deactivate the MFA device as described in [Deactivate an MFA device](id_credentials_mfa_disable.md) so that you can sign in. 1. The next step varies depending on the type of MFA you are using: + For a virtual MFA device, remove the account from your device. Then enable the virtual device as described in [Assign a virtual MFA device in the AWS Management Console](id_credentials_mfa_enable_virtual.md). + For a FIDO security key, contact the third-party provider for help with replacing the device. When you receive the new FIDO security key, enable it as described in [Assign a passkey or security key in the AWS Management Console](id_credentials_mfa_enable_fido.md). + For a hardware TOTP token, contact the third-party provider for help with fixing or replacing the device. After you have the new physical MFA device, enable the device as described in [Assign a hardware TOTP token in the AWS Management Console](id_credentials_mfa_enable_physical.md). **Note** You don't have to replace a lost or stolen MFA device with the same type of device. You can have up to eight MFA devices of any combination. For example, if you break your FIDO security key and order a new one, you can use virtual MFA or a hardware TOTP token until the new FIDO key arrives. 1. If your MFA device is missing or stolen, also change your password in case an attacker has stolen the authentication device and might also have your current password. For more information, see [Manage passwords for IAM users](id_credentials_passwords_admin-change-user.md) # Secure API access with MFA With IAM policies, you can specify which API operations a user is allowed to call. You can apply additional security by requiring users to authenticate with multi-factor authentication (MFA) before you allow them to perform particularly sensitive actions. For example, you might have a policy that allows a user to perform the Amazon EC2 `RunInstances`, `DescribeInstances`, and `StopInstances` actions. But you might want to restrict a destructive action like `TerminateInstances` and ensure that users can perform that action only if they authenticate with an AWS MFA device. **Topics** + [ ## Overview ](#MFAProtectedAPI-overview) + [ ## Scenario: MFA protection for cross-account delegation ](#MFAProtectedAPI-cross-account-delegation) + [ ## Scenario: MFA protection for access to API operations in the current account ](#MFAProtectedAPI-user-mfa) + [ ## Scenario: MFA protection for resources that have resource-based policies ](#MFAProtectedAPI-resource-policies) ## Overview Adding MFA protection to API operations involves these tasks: 1. The administrator configures an AWS MFA device for each user who must make API requests that require MFA authentication. For more information, see [AWS Multi-factor authentication in IAM](id_credentials_mfa.md). 1. The administrator creates policies for the users that include a `Condition` element that checks whether the user authenticated with an AWS MFA device. 1. The user calls one of the AWS STS API operations that support the MFA parameters: [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) or [GetSessionToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetSessionToken.html). As part of the call, the user includes the device identifier for the device that's associated with the user. The user also includes the time-based one-time password (TOTP) that the device generates. In either case, the user gets back temporary security credentials that the user can then use to make additional requests to AWS. **Note** MFA protection for a service's API operations is available only if the service supports temporary security credentials. For a list of these services, see [ Using Temporary Security Credentials to Access AWS](https://docs.aws.amazon.com/STS/latest/UsingSTS/UsingTokens.html). If authorization fails, 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 API operations specified in the policies if the user attempts to call an API operation without valid MFA authentication. The operation is also denied if the time stamp of the request for the API operation is outside of the allowed range specified in the policy. The user must be reauthenticated with MFA by requesting new temporary security credentials with an MFA code and device serial number. ### IAM policies with MFA conditions Policies with MFA conditions can be attached to the following: + An IAM user or group + A resource such as an Amazon S3 bucket, Amazon SQS queue, or Amazon SNS topic + The trust policy of an IAM role that can be assumed by a user You can use an MFA condition in a policy to check the following properties: + Existence—To simply verify that the user did authenticate with MFA, check that the `aws:MultiFactorAuthPresent` key is `True` in a `Bool` condition. The key is only present when the user authenticates with short-term credentials. Long-term credentials, such as access keys, do not include this key. + Duration—If you want to grant access only within a specified time after MFA authentication, use a numeric condition type to compare the `aws:MultiFactorAuthAge` key's age to a value (such as 3600 seconds). Note that the `aws:MultiFactorAuthAge` key is not present if MFA was not used. The following example shows the trust policy of an IAM role that includes an MFA condition to test for the existence of MFA authentication. With this policy, users from the AWS account specified in the `Principal` element (replace `ACCOUNT-B-ID` with a valid AWS account ID) can assume the role that this policy is attached to. However such users can only assume the role if the user is authenticated using MFA. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Effect": "Allow", "Principal": {"AWS": "ACCOUNT-B-ID"}, "Action": "sts:AssumeRole", "Condition": {"Bool": {"aws:MultiFactorAuthPresent": "true"}} } } ``` ------ For more information on the condition types for MFA, see [AWS global condition context keys](reference_policies_condition-keys.md), [Numeric condition operators](reference_policies_elements_condition_operators.md#Conditions_Numeric), and [Condition operator to check existence of condition keys](reference_policies_elements_condition_operators.md#Conditions_Null). ### Choosing between GetSessionToken and AssumeRole AWS STS provides two API operations that let users pass MFA information: `GetSessionToken` and `AssumeRole`. The API operation that the user calls to get temporary security credentials depends on which of the following scenarios applies. **Use `GetSessionToken` for the following scenarios:** + Call API operations that access resources in the same AWS account as the IAM user who makes the request. Note that temporary credentials from a `GetSessionToken` request can access IAM and AWS STS API operations *only* if you include MFA information in the request for credentials. Because temporary credentials returned by `GetSessionToken` include MFA information, you can check for MFA in individual API operations made by the credentials. + Access to resources that are protected with resource-based policies that include an MFA condition. The purpose of the `GetSessionToken` operation is to authenticate the user using MFA. You cannot use policies to control authentication operations. **Use `AssumeRole` for the following scenarios:** + Call API operations that access resources in the same or a different AWS account. The API calls can include any IAM or AWS STS API. Note that to protect access you enforce MFA at the time when the user assumes the role. The temporary credentials returned by `AssumeRole` do not include MFA information in the context, so you cannot check individual API operations for MFA. This is why you must use `GetSessionToken` to restrict access to resources protected by resource-based policies. **Note** AWS CloudTrail logs will contain MFA information when the IAM user sign in with MFA. If the IAM user assumes an IAM role, CloudTrail will also log `mfaAuthenticated: true` in the `sessionContext` attributes for actions performed using the assumed role. However, CloudTrail logging is separate from what IAM requires when API calls are made with the assumed role's credentials. For more information, see [CloudTrail userIdentity Element](https://docs.aws.amazon.com//awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html). Details about how to implement these scenarios are provided later in this document. ### Important points about MFA-protected API access It's important to understand the following aspects of MFA protection for API operations: + MFA protection is available only with temporary security credentials, which must be obtained with `AssumeRole` or `GetSessionToken`. + You cannot use MFA-protected API access with AWS account root user credentials. + You cannot use MFA-protected API access with U2F security keys. + Federated users cannot be assigned an MFA device for use with AWS services, so they cannot access AWS resources controlled by MFA. (See next point.) + Other AWS STS API operations that return temporary credentials do not support MFA. For `AssumeRoleWithWebIdentity` and `AssumeRoleWithSAML`, the user is authenticated by an external provider and AWS cannot determine whether that provider required MFA. For `GetFederationToken`, MFA is not necessarily associated with a specific user. + Similarly, long-term credentials (IAM user access keys and root user access keys) cannot be used with MFA-protected API access because they don't expire. + `AssumeRole` and `GetSessionToken` can also be called without MFA information. In that case, the caller gets back temporary security credentials, but the session information for those temporary credentials does not indicate that the user authenticated with MFA. + To establish MFA protection for API operations, you add MFA conditions to policies. A policy must include the `aws:MultiFactorAuthPresent` condition key to enforce the use of MFA. For cross-account delegation, the role's trust policy must include the condition key. + When you allow another AWS account to access resources in your account, the security of your resources depends on the configuration of the trusted account (the other account, not yours). This is true even when you require multi-factor authentication. Any identity in the trusted account that has permission to create virtual MFA devices can construct an MFA claim to satisfy that part of your role's trust policy. Before you allow members of another account access to your AWS resources that require multi-factor authentication, you should ensure that the trusted account's owner follows security best practices. For example, the trusted account should restrict access to sensitive API operations, such as MFA device-management API operations, to specific, trusted identities. + If a policy includes an MFA condition, a request is denied if users have not been MFA authenticated, or if they provide an invalid MFA device identifier or invalid TOTP. ## Scenario: MFA protection for cross-account delegation In this scenario, you want to delegate access to IAM users in another account, but only if the users are authenticated with an AWS MFA device. For more information about cross-account delegation, see [Roles terms and concepts](id_roles.md#id_roles_terms-and-concepts). Imagine that you have account A (the trusting account that owns the resource to be accessed), with the IAM user Anaya, who has administrator permission. She wants to grant access to user Richard in account B (the trusted account), but wants to make sure that Richard is authenticated with MFA before he assumes the role. 1. In the trusting account A, Anaya creates an IAM role named `CrossAccountRole` and sets the principal in the role's trust policy to the account ID of account B. The trust policy grants permission to the AWS STS `AssumeRole` action. Anaya also adds an MFA condition to the trust policy, as in the following example. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": { "Effect": "Allow", "Principal": {"AWS": "ACCOUNT-B-ID"}, "Action": "sts:AssumeRole", "Condition": {"Bool": {"aws:MultiFactorAuthPresent": "true"}} } } ``` ------ 1. Anaya adds a permissions policy to the role that specifies what the role is allowed to do. The permissions policy for a role with MFA protection is no different than any other role-permission policy. The following example shows the policy that Anaya adds to the role; it allows an assuming user to perform any Amazon DynamoDB action on the table `Books` in account A. This policy also allows the `dynamodb:ListTables` action, which is required to perform actions in the console. **Note** The permissions policy does not include an MFA condition. It is important to understand that the MFA authentication is used only to determine whether a user can assume the role. Once the user has assumed the role, no further MFA checks are made. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "TableActions", "Effect": "Allow", "Action": "dynamodb:*", "Resource": "arn:aws:dynamodb:*:111122223333:table/Books" }, { "Sid": "ListTables", "Effect": "Allow", "Action": "dynamodb:ListTables", "Resource": "*" } ] } ``` ------ 1. In trusted account B, the administrator makes sure that IAM user Richard is configured with an AWS MFA device and that he knows the ID of the device. The device ID is the serial number if it's a hardware MFA device, or the device's ARN if it's a virtual MFA device. 1. In account B, the administrator attaches the following policy to user Richard (or a group that he's a member of) that allows him to call the `AssumeRole` action. The resource is set to the ARN of the role that Anaya created in step 1. Notice that this policy does not contain an MFA condition. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "sts:AssumeRole" ], "Resource": [ "arn:aws:iam::111122223333:role/CrossAccountRole" ] } ] } ``` ------ 1. In account B, Richard (or an application that Richard is running) calls `AssumeRole`. The API call includes the ARN of the role to assume (`arn:aws:iam::ACCOUNT-A-ID:role/CrossAccountRole`), the ID of the MFA device, and the current TOTP that Richard gets from his device. When Richard calls `AssumeRole`, AWS determines whether he has valid credentials, including the requirement for MFA. If so, Richard successfully assumes the role and can perform any DynamoDB action on the table named `Books` in account A while using the role's temporary credentials. For an example of a program that calls `AssumeRole`, see [Calling AssumeRole with MFA authentication](id_credentials_mfa_sample-code.md#MFAProtectedAPI-example-assumerole). ## Scenario: MFA protection for access to API operations in the current account In this scenario, you should ensure that a user in your AWS account can access sensitive API operations only when the user is authenticated using an AWS MFA device. Imagine that you have account A that contains a group of developers who need to work with EC2 instances. Ordinary developers can work with the instances, but they are not granted permissions for the `ec2:StopInstances` or `ec2:TerminateInstances` actions. You want to limit those "destructive" privileged actions to just a few trusted users, so you add MFA protection to the policy that allows these sensitive Amazon EC2 actions. In this scenario, one of those trusted users is user Sofía. User Anaya is an administrator in account A. 1. Anaya makes sure that Sofía is configured with an AWS MFA device and that Sofía knows the ID of the device. The device ID is the serial number if it's a hardware MFA device, or the device's ARN if it's a virtual MFA device. 1. Anaya creates a group named `EC2-Admins` and adds user Sofía to the group. 1. Anaya attaches the following policy to the `EC2-Admins` group. This policy grants users permission to call the Amazon EC2 `StopInstances` and `TerminateInstances` actions only if the user has authenticated using MFA. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [{ "Effect": "Allow", "Action": [ "ec2:StopInstances", "ec2:TerminateInstances" ], "Resource": ["*"], "Condition": {"Bool": {"aws:MultiFactorAuthPresent": "true"}} }] } ``` ------ 1. **Note** For this policy to take effect, users must first sign out and then sign in again. If user Sofía needs to stop or terminate an Amazon EC2 instance, she (or an application that she is running) calls `GetSessionToken`. This API operation passes the ID of the MFA device and the current TOTP that Sofía gets from her device. 1. User Sofía (or an application that Sofía is using) uses the temporary credentials provided by `GetSessionToken` to call the Amazon EC2 `StopInstances` or `TerminateInstances` action. For an example of a program that calls `GetSessionToken`, see [Calling GetSessionToken with MFA authentication](id_credentials_mfa_sample-code.md#MFAProtectedAPI-example-getsessiontoken) later in this document. ## Scenario: MFA protection for resources that have resource-based policies In this scenario, you are the owner of an S3 bucket, an SQS queue, or an SNS topic. You want to make sure that any user from any AWS account who accesses the resource is authenticated by an AWS MFA device. This scenario illustrates a way to provide cross-account MFA protection without requiring users to assume a role first. In this case, the user can access the resource if three conditions are met: The user must be authenticated by MFA, be able to get temporary security credentials from `GetSessionToken`, and be in an account that is trusted by the resource's policy. Imagine that you are in account A and you create an S3 bucket. You want to grant access to this bucket to users who are in several different AWS accounts, but only if those users are authenticated with MFA. In this scenario, user Anaya is an administrator in account A. User Nikhil is an IAM user in account C. 1. In account A, Anaya creates a bucket named `Account-A-bucket`. 1. Anaya adds the bucket policy to the bucket. The policy allows any user in account A, account B, or account C to perform the Amazon S3 `PutObject` and `DeleteObject` actions in the bucket. The policy includes an MFA condition. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [{ "Effect": "Allow", "Principal": {"AWS": [ "ACCOUNT-A-ID", "ACCOUNT-B-ID", "ACCOUNT-C-ID" ]}, "Action": [ "s3:PutObject", "s3:DeleteObject" ], "Resource": ["arn:aws:s3:::ACCOUNT-A-BUCKET-NAME/*"], "Condition": {"Bool": {"aws:MultiFactorAuthPresent": "true"}} }] } ``` ------ **Note** Amazon S3 offers an MFA Delete feature for *root* account access (only). 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 permissions 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](https://docs.aws.amazon.com/AmazonS3/latest/dev/MultiFactorAuthenticationDelete.html). 1. In account C, an administrator makes sure that user Nikhil is configured with an AWS MFA device and that he knows the ID of the device. The device ID is the serial number if it's a hardware MFA device, or the device's ARN if it's a virtual MFA device. 1. In account C, Nikhil (or an application that he is running) calls `GetSessionToken`. The call includes the ID or ARN of the MFA device and the current TOTP that Nikhil gets from his device. 1. Nikhil (or an application that he is using) uses the temporary credentials returned by `GetSessionToken` to call the Amazon S3 `PutObject` action to upload a file to `Account-A-bucket`. For an example of a program that calls `GetSessionToken`, see [Calling GetSessionToken with MFA authentication](id_credentials_mfa_sample-code.md#MFAProtectedAPI-example-getsessiontoken) later in this document. **Note** The temporary credentials that `AssumeRole` returns won't work in this case. Although the user can provide MFA information to assume a role, the temporary credentials returned by `AssumeRole` don't include the MFA information. That information is required in order to meet the MFA condition in the policy. # Sample code: Requesting credentials with multi-factor authentication The following examples show how to call `GetSessionToken` and `AssumeRole` operations and pass MFA authentication parameters. No permissions are required to call `GetSessionToken`, but you must have a policy that allows you to call `AssumeRole`. The credentials returned are then used to list all S3 buckets in the account. ## Calling GetSessionToken with MFA authentication The following example shows how to call `GetSessionToken` and pass MFA authentication information. The temporary security credentials returned by the `GetSessionToken` operation are then used to list all S3 buckets in the account. The policy attached to the user who runs this code (or to a group that the user is in) provides the permissions for the returned temporary credentials. For this example code, the policy must grant the user permission to request the Amazon S3 `ListBuckets` operation. The following code examples show how to use `GetSessionToken`. ------ #### [ CLI ] **AWS CLI** **To get a set of short term credentials for an IAM identity** The following `get-session-token` command retrieves a set of short-term credentials for the IAM identity making the call. The resulting credentials can be used for requests where multi-factor authentication (MFA) is required by policy. The credentials expire 15 minutes after they are generated. ``` aws sts get-session-token \ --duration-seconds 900 \ --serial-number "YourMFADeviceSerialNumber" \ --token-code 123456 ``` Output: ``` { "Credentials": { "AccessKeyId": "ASIAIOSFODNN7EXAMPLE", "SecretAccessKey": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYzEXAMPLEKEY", "SessionToken": "AQoEXAMPLEH4aoAH0gNCAPyJxz4BlCFFxWNE1OPTgk5TthT+FvwqnKwRcOIfrRh3c/LTo6UDdyJwOOvEVPvLXCrrrUtdnniCEXAMPLE/IvU1dYUg2RVAJBanLiHb4IgRmpRV3zrkuWJOgQs8IZZaIv2BXIa2R4OlgkBN9bkUDNCJiBeb/AXlzBBko7b15fjrBs2+cTQtpZ3CYWFXG8C5zqx37wnOE49mRl/+OtkIKGO7fAE", "Expiration": "2020-05-19T18:06:10+00:00" } } ``` For more information, see [Requesting Temporary Security Credentials](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html#api_getsessiontoken) in the *AWS IAM User Guide*. + For API details, see [GetSessionToken](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sts/get-session-token.html) in *AWS CLI Command Reference*. ------ #### [ PowerShell ] **Tools for PowerShell V4** **Example 1: Returns an `Amazon.RuntimeAWSCredentials` instance containing temporary credentials valid for a set period of time. The credentials used to request temporary credentials are inferred from the current shell defaults. To specify other credentials, use the -ProfileName or -AccessKey/-SecretKey parameters.** ``` Get-STSSessionToken ``` **Output:** ``` AccessKeyId Expiration SecretAccessKey SessionToken ----------- ---------- --------------- ------------ EXAMPLEACCESSKEYID 2/16/2015 9:12:28 PM examplesecretaccesskey... SamPleTokeN..... ``` **Example 2: Returns an `Amazon.RuntimeAWSCredentials` instance containing temporary credentials valid for one hour. The credentials used to make the request are obtained from the specified profile.** ``` Get-STSSessionToken -DurationInSeconds 3600 -ProfileName myprofile ``` **Output:** ``` AccessKeyId Expiration SecretAccessKey SessionToken ----------- ---------- --------------- ------------ EXAMPLEACCESSKEYID 2/16/2015 9:12:28 PM examplesecretaccesskey... SamPleTokeN..... ``` **Example 3: Returns an `Amazon.RuntimeAWSCredentials` instance containing temporary credentials valid for one hour using the identification number of the MFA device associated with the account whose credentials are specified in the profile 'myprofilename' and the value provided by the device.** ``` Get-STSSessionToken -DurationInSeconds 3600 -ProfileName myprofile -SerialNumber YourMFADeviceSerialNumber -TokenCode 123456 ``` **Output:** ``` AccessKeyId Expiration SecretAccessKey SessionToken ----------- ---------- --------------- ------------ EXAMPLEACCESSKEYID 2/16/2015 9:12:28 PM examplesecretaccesskey... SamPleTokeN..... ``` + For API details, see [GetSessionToken](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*. **Tools for PowerShell V5** **Example 1: Returns an `Amazon.RuntimeAWSCredentials` instance containing temporary credentials valid for a set period of time. The credentials used to request temporary credentials are inferred from the current shell defaults. To specify other credentials, use the -ProfileName or -AccessKey/-SecretKey parameters.** ``` Get-STSSessionToken ``` **Output:** ``` AccessKeyId Expiration SecretAccessKey SessionToken ----------- ---------- --------------- ------------ EXAMPLEACCESSKEYID 2/16/2015 9:12:28 PM examplesecretaccesskey... SamPleTokeN..... ``` **Example 2: Returns an `Amazon.RuntimeAWSCredentials` instance containing temporary credentials valid for one hour. The credentials used to make the request are obtained from the specified profile.** ``` Get-STSSessionToken -DurationInSeconds 3600 -ProfileName myprofile ``` **Output:** ``` AccessKeyId Expiration SecretAccessKey SessionToken ----------- ---------- --------------- ------------ EXAMPLEACCESSKEYID 2/16/2015 9:12:28 PM examplesecretaccesskey... SamPleTokeN..... ``` **Example 3: Returns an `Amazon.RuntimeAWSCredentials` instance containing temporary credentials valid for one hour using the identification number of the MFA device associated with the account whose credentials are specified in the profile 'myprofilename' and the value provided by the device.** ``` Get-STSSessionToken -DurationInSeconds 3600 -ProfileName myprofile -SerialNumber YourMFADeviceSerialNumber -TokenCode 123456 ``` **Output:** ``` AccessKeyId Expiration SecretAccessKey SessionToken ----------- ---------- --------------- ------------ EXAMPLEACCESSKEYID 2/16/2015 9:12:28 PM examplesecretaccesskey... SamPleTokeN..... ``` + For API details, see [GetSessionToken](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*. ------ #### [ Python ] **SDK for Python (Boto3)** There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sts#code-examples). Get a session token by passing an MFA token and use it to list Amazon S3 buckets for the account. ``` def list_buckets_with_session_token_with_mfa(mfa_serial_number, mfa_totp, sts_client): """ Gets a session token with MFA credentials and uses the temporary session credentials to list Amazon S3 buckets. Requires an MFA device serial number and token. :param mfa_serial_number: The serial number of the MFA device. For a virtual MFA device, this is an Amazon Resource Name (ARN). :param mfa_totp: A time-based, one-time password issued by the MFA device. :param sts_client: A Boto3 STS instance that has permission to assume the role. """ if mfa_serial_number is not None: response = sts_client.get_session_token( SerialNumber=mfa_serial_number, TokenCode=mfa_totp ) else: response = sts_client.get_session_token() temp_credentials = response["Credentials"] s3_resource = boto3.resource( "s3", aws_access_key_id=temp_credentials["AccessKeyId"], aws_secret_access_key=temp_credentials["SecretAccessKey"], aws_session_token=temp_credentials["SessionToken"], ) print(f"Buckets for the account:") for bucket in s3_resource.buckets.all(): print(bucket.name) ``` + For API details, see [GetSessionToken](https://docs.aws.amazon.com/goto/boto3/sts-2011-06-15/GetSessionToken) in *AWS SDK for Python (Boto3) API Reference*. ------ ## Calling AssumeRole with MFA authentication The following examples show how to call `AssumeRole` and pass MFA authentication information. The temporary security credentials returned by `AssumeRole` are then used to list all Amazon S3 buckets in the account. For more information about this scenario, see [Scenario: MFA protection for cross-account delegation](id_credentials_mfa_configure-api-require.md#MFAProtectedAPI-cross-account-delegation). The following code examples show how to use `AssumeRole`. ------ #### [ .NET ] **SDK for .NET** There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv3/STS#code-examples). ``` using System; using System.Threading.Tasks; using Amazon; using Amazon.SecurityToken; using Amazon.SecurityToken.Model; namespace AssumeRoleExample { class AssumeRole { /// /// This example shows how to use the AWS Security Token /// Service (AWS STS) to assume an IAM role. /// /// NOTE: It is important that the role that will be assumed has a /// trust relationship with the account that will assume the role. /// /// Before you run the example, you need to create the role you want to /// assume and have it trust the IAM account that will assume that role. /// /// See https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html /// for help in working with roles. /// // A region property may be used if the profile or credentials loaded do not specify a region, // or to use a specific region. private static readonly RegionEndpoint REGION = RegionEndpoint.USWest2; static async Task Main() { // Create the SecurityToken client and then display the identity of the // default user. var roleArnToAssume = "arn:aws:iam::123456789012:role/testAssumeRole"; var client = new Amazon.SecurityToken.AmazonSecurityTokenServiceClient(REGION); // Get and display the information about the identity of the default user. var callerIdRequest = new GetCallerIdentityRequest(); var caller = await client.GetCallerIdentityAsync(callerIdRequest); Console.WriteLine($"Original Caller: {caller.Arn}"); // Create the request to use with the AssumeRoleAsync call. var assumeRoleReq = new AssumeRoleRequest() { DurationSeconds = 1600, RoleSessionName = "Session1", RoleArn = roleArnToAssume }; var assumeRoleRes = await client.AssumeRoleAsync(assumeRoleReq); // Now create a new client based on the credentials of the caller assuming the role. var client2 = new AmazonSecurityTokenServiceClient(credentials: assumeRoleRes.Credentials, REGION); // Get and display information about the caller that has assumed the defined role. var caller2 = await client2.GetCallerIdentityAsync(callerIdRequest); Console.WriteLine($"AssumedRole Caller: {caller2.Arn}"); } } } ``` + For API details, see [AssumeRole](https://docs.aws.amazon.com/goto/DotNetSDKV3/sts-2011-06-15/AssumeRole) in *AWS SDK for .NET API Reference*. ------ #### [ Bash ] **AWS CLI with Bash script** There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/aws-cli/bash-linux/iam#code-examples). ``` ############################################################################### # function iecho # # This function enables the script to display the specified text only if # the global variable $VERBOSE is set to true. ############################################################################### function iecho() { if [[ $VERBOSE == true ]]; then echo "$@" fi } ############################################################################### # function errecho # # This function outputs everything sent to it to STDERR (standard error output). ############################################################################### function errecho() { printf "%s\n" "$*" 1>&2 } ############################################################################### # function sts_assume_role # # This function assumes a role in the AWS account and returns the temporary # credentials. # # Parameters: # -n role_session_name -- The name of the session. # -r role_arn -- The ARN of the role to assume. # # Returns: # [access_key_id, secret_access_key, session_token] # And: # 0 - If successful. # 1 - If an error occurred. ############################################################################### function sts_assume_role() { local role_session_name role_arn response local option OPTARG # Required to use getopts command in a function. # bashsupport disable=BP5008 function usage() { echo "function sts_assume_role" echo "Assumes a role in the AWS account and returns the temporary credentials:" echo " -n role_session_name -- The name of the session." echo " -r role_arn -- The ARN of the role to assume." echo "" } while getopts n:r:h option; do case "${option}" in n) role_session_name=${OPTARG} ;; r) role_arn=${OPTARG} ;; h) usage return 0 ;; \?) echo "Invalid parameter" usage return 1 ;; esac done response=$(aws sts assume-role \ --role-session-name "$role_session_name" \ --role-arn "$role_arn" \ --output text \ --query "Credentials.[AccessKeyId, SecretAccessKey, SessionToken]") local error_code=${?} if [[ $error_code -ne 0 ]]; then aws_cli_error_log $error_code errecho "ERROR: AWS reports create-role operation failed.\n$response" return 1 fi echo "$response" return 0 } ``` + For API details, see [AssumeRole](https://docs.aws.amazon.com/goto/aws-cli/sts-2011-06-15/AssumeRole) in *AWS CLI Command Reference*. ------ #### [ C\$1\$1 ] **SDK for C\$1\$1** There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp/example_code/sts#code-examples). ``` bool AwsDoc::STS::assumeRole(const Aws::String &roleArn, const Aws::String &roleSessionName, const Aws::String &externalId, Aws::Auth::AWSCredentials &credentials, const Aws::Client::ClientConfiguration &clientConfig) { Aws::STS::STSClient sts(clientConfig); Aws::STS::Model::AssumeRoleRequest sts_req; sts_req.SetRoleArn(roleArn); sts_req.SetRoleSessionName(roleSessionName); sts_req.SetExternalId(externalId); const Aws::STS::Model::AssumeRoleOutcome outcome = sts.AssumeRole(sts_req); if (!outcome.IsSuccess()) { std::cerr << "Error assuming IAM role. " << outcome.GetError().GetMessage() << std::endl; } else { std::cout << "Credentials successfully retrieved." << std::endl; const Aws::STS::Model::AssumeRoleResult result = outcome.GetResult(); const Aws::STS::Model::Credentials &temp_credentials = result.GetCredentials(); // Store temporary credentials in return argument. // Note: The credentials object returned by assumeRole differs // from the AWSCredentials object used in most situations. credentials.SetAWSAccessKeyId(temp_credentials.GetAccessKeyId()); credentials.SetAWSSecretKey(temp_credentials.GetSecretAccessKey()); credentials.SetSessionToken(temp_credentials.GetSessionToken()); } return outcome.IsSuccess(); } ``` + For API details, see [AssumeRole](https://docs.aws.amazon.com/goto/SdkForCpp/sts-2011-06-15/AssumeRole) in *AWS SDK for C\$1\$1 API Reference*. ------ #### [ CLI ] **AWS CLI** **To assume a role** The following `assume-role` command retrieves a set of short-term credentials for the IAM role `s3-access-example`. ``` aws sts assume-role \ --role-arn arn:aws:iam::123456789012:role/xaccounts3access \ --role-session-name s3-access-example ``` Output: ``` { "AssumedRoleUser": { "AssumedRoleId": "AROA3XFRBF535PLBIFPI4:s3-access-example", "Arn": "arn:aws:sts::123456789012:assumed-role/xaccounts3access/s3-access-example" }, "Credentials": { "SecretAccessKey": "9drTJvcXLB89EXAMPLELB8923FB892xMFI", "SessionToken": "AQoXdzELDDY//////////wEaoAK1wvxJY12r2IrDFT2IvAzTCn3zHoZ7YNtpiQLF0MqZye/qwjzP2iEXAMPLEbw/m3hsj8VBTkPORGvr9jM5sgP+w9IZWZnU+LWhmg+a5fDi2oTGUYcdg9uexQ4mtCHIHfi4citgqZTgco40Yqr4lIlo4V2b2Dyauk0eYFNebHtYlFVgAUj+7Indz3LU0aTWk1WKIjHmmMCIoTkyYp/k7kUG7moeEYKSitwQIi6Gjn+nyzM+PtoA3685ixzv0R7i5rjQi0YE0lf1oeie3bDiNHncmzosRM6SFiPzSvp6h/32xQuZsjcypmwsPSDtTPYcs0+YN/8BRi2/IcrxSpnWEXAMPLEXSDFTAQAM6Dl9zR0tXoybnlrZIwMLlMi1Kcgo5OytwU=", "Expiration": "2016-03-15T00:05:07Z", "AccessKeyId": "ASIAJEXAMPLEXEG2JICEA" } } ``` The output of the command contains an access key, secret key, and session token that you can use to authenticate to AWS. For AWS CLI use, you can set up a named profile associated with a role. When you use the profile, the AWS CLI will call assume-role and manage credentials for you. For more information, see [Use an IAM role in the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html) in the *AWS CLI User Guide*. + For API details, see [AssumeRole](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/sts/assume-role.html) in *AWS CLI Command Reference*. ------ #### [ Java ] **SDK for Java 2.x** There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2/example_code/sts#code-examples). ``` import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.sts.StsClient; import software.amazon.awssdk.services.sts.model.AssumeRoleRequest; import software.amazon.awssdk.services.sts.model.StsException; import software.amazon.awssdk.services.sts.model.AssumeRoleResponse; import software.amazon.awssdk.services.sts.model.Credentials; import java.time.Instant; import java.time.ZoneId; import java.time.format.DateTimeFormatter; import java.time.format.FormatStyle; import java.util.Locale; /** * To make this code example work, create a Role that you want to assume. * Then define a Trust Relationship in the AWS Console. You can use this as an * example: * * { * "Version":"2012-10-17", * "Statement": [ * { * "Effect": "Allow", * "Principal": { * "AWS": "" * }, * "Action": "sts:AssumeRole" * } * ] * } * * For more information, see "Editing the Trust Relationship for an Existing * Role" in the AWS Directory Service guide. * * Also, set up your development environment, including your credentials. * * For information, see this documentation topic: * * https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html */ public class AssumeRole { public static void main(String[] args) { final String usage = """ Usage: \s Where: roleArn - The Amazon Resource Name (ARN) of the role to assume (for example, arn:aws:iam::000008047983:role/s3role).\s roleSessionName - An identifier for the assumed role session (for example, mysession).\s """; if (args.length != 2) { System.out.println(usage); System.exit(1); } String roleArn = args[0]; String roleSessionName = args[1]; Region region = Region.US_EAST_1; StsClient stsClient = StsClient.builder() .region(region) .build(); assumeGivenRole(stsClient, roleArn, roleSessionName); stsClient.close(); } public static void assumeGivenRole(StsClient stsClient, String roleArn, String roleSessionName) { try { AssumeRoleRequest roleRequest = AssumeRoleRequest.builder() .roleArn(roleArn) .roleSessionName(roleSessionName) .build(); AssumeRoleResponse roleResponse = stsClient.assumeRole(roleRequest); Credentials myCreds = roleResponse.credentials(); // Display the time when the temp creds expire. Instant exTime = myCreds.expiration(); String tokenInfo = myCreds.sessionToken(); // Convert the Instant to readable date. DateTimeFormatter formatter = DateTimeFormatter.ofLocalizedDateTime(FormatStyle.SHORT) .withLocale(Locale.US) .withZone(ZoneId.systemDefault()); formatter.format(exTime); System.out.println("The token " + tokenInfo + " expires on " + exTime); } catch (StsException e) { System.err.println(e.getMessage()); System.exit(1); } } } ``` + For API details, see [AssumeRole](https://docs.aws.amazon.com/goto/SdkForJavaV2/sts-2011-06-15/AssumeRole) in *AWS SDK for Java 2.x API Reference*. ------ #### [ JavaScript ] **SDK for JavaScript (v3)** There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3/example_code/sts#code-examples). Create the client. ``` import { STSClient } from "@aws-sdk/client-sts"; // Set the AWS Region. const REGION = "us-east-1"; // Create an AWS STS service client object. export const client = new STSClient({ region: REGION }); ``` Assume the IAM role. ``` import { AssumeRoleCommand } from "@aws-sdk/client-sts"; import { client } from "../libs/client.js"; export const main = async () => { try { // Returns a set of temporary security credentials that you can use to // access Amazon Web Services resources that you might not normally // have access to. const command = new AssumeRoleCommand({ // The Amazon Resource Name (ARN) of the role to assume. RoleArn: "ROLE_ARN", // An identifier for the assumed role session. RoleSessionName: "session1", // The duration, in seconds, of the role session. The value specified // can range from 900 seconds (15 minutes) up to the maximum session // duration set for the role. DurationSeconds: 900, }); const response = await client.send(command); console.log(response); } catch (err) { console.error(err); } }; ``` + For API details, see [AssumeRole](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/sts/command/AssumeRoleCommand) in *AWS SDK for JavaScript API Reference*. **SDK for JavaScript (v2)** There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascript/example_code/sts#code-examples). ``` // Load the AWS SDK for Node.js const AWS = require("aws-sdk"); // Set the region AWS.config.update({ region: "REGION" }); var roleToAssume = { RoleArn: "arn:aws:iam::123456789012:role/RoleName", RoleSessionName: "session1", DurationSeconds: 900, }; var roleCreds; // Create the STS service object var sts = new AWS.STS({ apiVersion: "2011-06-15" }); //Assume Role sts.assumeRole(roleToAssume, function (err, data) { if (err) console.log(err, err.stack); else { roleCreds = { accessKeyId: data.Credentials.AccessKeyId, secretAccessKey: data.Credentials.SecretAccessKey, sessionToken: data.Credentials.SessionToken, }; stsGetCallerIdentity(roleCreds); } }); //Get Arn of current identity function stsGetCallerIdentity(creds) { var stsParams = { credentials: creds }; // Create STS service object var sts = new AWS.STS(stsParams); sts.getCallerIdentity({}, function (err, data) { if (err) { console.log(err, err.stack); } else { console.log(data.Arn); } }); } ``` + For API details, see [AssumeRole](https://docs.aws.amazon.com/goto/AWSJavaScriptSDK/sts-2011-06-15/AssumeRole) in *AWS SDK for JavaScript API Reference*. ------ #### [ PowerShell ] **Tools for PowerShell V4** **Example 1: Returns a set of temporary credentials (access key, secret key and session token) that can be used for one hour to access AWS resources that the requesting user might not normally have access to. The returned credentials have the permissions that are allowed by the access policy of the role being assumed and the policy that was supplied (you cannot use the supplied policy to grant permissions in excess of those defined by the access policy of the role being assumed).** ``` Use-STSRole -RoleSessionName "Bob" -RoleArn "arn:aws:iam::123456789012:role/demo" -Policy "...JSON policy..." -DurationInSeconds 3600 ``` **Example 2: Returns a set of temporary credentials, valid for one hour, that have the same permissions that are defined in the access policy of the role being assumed.** ``` Use-STSRole -RoleSessionName "Bob" -RoleArn "arn:aws:iam::123456789012:role/demo" -DurationInSeconds 3600 ``` **Example 3: Returns a set of temporary credentials supplying the serial number and generated token from an MFA associated with the user credentials used to execute the cmdlet.** ``` Use-STSRole -RoleSessionName "Bob" -RoleArn "arn:aws:iam::123456789012:role/demo" -DurationInSeconds 3600 -SerialNumber "GAHT12345678" -TokenCode "123456" ``` **Example 4: Returns a set of temporary credentials that have assumed a role defined in a customer account. For each role that the third party can assume, the customer account must create a role using an identifier that must be passed in the -ExternalId parameter each time the role is assumed.** ``` Use-STSRole -RoleSessionName "Bob" -RoleArn "arn:aws:iam::123456789012:role/demo" -DurationInSeconds 3600 -ExternalId "ABC123" ``` + For API details, see [AssumeRole](https://docs.aws.amazon.com/powershell/v4/reference) in *AWS Tools for PowerShell Cmdlet Reference (V4)*. **Tools for PowerShell V5** **Example 1: Returns a set of temporary credentials (access key, secret key and session token) that can be used for one hour to access AWS resources that the requesting user might not normally have access to. The returned credentials have the permissions that are allowed by the access policy of the role being assumed and the policy that was supplied (you cannot use the supplied policy to grant permissions in excess of those defined by the access policy of the role being assumed).** ``` Use-STSRole -RoleSessionName "Bob" -RoleArn "arn:aws:iam::123456789012:role/demo" -Policy "...JSON policy..." -DurationInSeconds 3600 ``` **Example 2: Returns a set of temporary credentials, valid for one hour, that have the same permissions that are defined in the access policy of the role being assumed.** ``` Use-STSRole -RoleSessionName "Bob" -RoleArn "arn:aws:iam::123456789012:role/demo" -DurationInSeconds 3600 ``` **Example 3: Returns a set of temporary credentials supplying the serial number and generated token from an MFA associated with the user credentials used to execute the cmdlet.** ``` Use-STSRole -RoleSessionName "Bob" -RoleArn "arn:aws:iam::123456789012:role/demo" -DurationInSeconds 3600 -SerialNumber "GAHT12345678" -TokenCode "123456" ``` **Example 4: Returns a set of temporary credentials that have assumed a role defined in a customer account. For each role that the third party can assume, the customer account must create a role using an identifier that must be passed in the -ExternalId parameter each time the role is assumed.** ``` Use-STSRole -RoleSessionName "Bob" -RoleArn "arn:aws:iam::123456789012:role/demo" -DurationInSeconds 3600 -ExternalId "ABC123" ``` + For API details, see [AssumeRole](https://docs.aws.amazon.com/powershell/v5/reference) in *AWS Tools for PowerShell Cmdlet Reference (V5)*. ------ #### [ Python ] **SDK for Python (Boto3)** There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python/example_code/sts#code-examples). Assume an IAM role that requires an MFA token and use temporary credentials to list Amazon S3 buckets for the account. ``` def list_buckets_from_assumed_role_with_mfa( assume_role_arn, session_name, mfa_serial_number, mfa_totp, sts_client ): """ Assumes a role from another account and uses the temporary credentials from that role to list the Amazon S3 buckets that are owned by the other account. Requires an MFA device serial number and token. The assumed role must grant permission to list the buckets in the other account. :param assume_role_arn: The Amazon Resource Name (ARN) of the role that grants access to list the other account's buckets. :param session_name: The name of the STS session. :param mfa_serial_number: The serial number of the MFA device. For a virtual MFA device, this is an ARN. :param mfa_totp: A time-based, one-time password issued by the MFA device. :param sts_client: A Boto3 STS instance that has permission to assume the role. """ response = sts_client.assume_role( RoleArn=assume_role_arn, RoleSessionName=session_name, SerialNumber=mfa_serial_number, TokenCode=mfa_totp, ) temp_credentials = response["Credentials"] print(f"Assumed role {assume_role_arn} and got temporary credentials.") s3_resource = boto3.resource( "s3", aws_access_key_id=temp_credentials["AccessKeyId"], aws_secret_access_key=temp_credentials["SecretAccessKey"], aws_session_token=temp_credentials["SessionToken"], ) print(f"Listing buckets for the assumed role's account:") for bucket in s3_resource.buckets.all(): print(bucket.name) ``` + For API details, see [AssumeRole](https://docs.aws.amazon.com/goto/boto3/sts-2011-06-15/AssumeRole) in *AWS SDK for Python (Boto3) API Reference*. ------ #### [ Ruby ] **SDK for Ruby** There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby/example_code/iam#code-examples). ``` # Creates an AWS Security Token Service (AWS STS) client with specified credentials. # This is separated into a factory function so that it can be mocked for unit testing. # # @param key_id [String] The ID of the access key used by the STS client. # @param key_secret [String] The secret part of the access key used by the STS client. def create_sts_client(key_id, key_secret) Aws::STS::Client.new(access_key_id: key_id, secret_access_key: key_secret) end # Gets temporary credentials that can be used to assume a role. # # @param role_arn [String] The ARN of the role that is assumed when these credentials # are used. # @param sts_client [AWS::STS::Client] An AWS STS client. # @return [Aws::AssumeRoleCredentials] The credentials that can be used to assume the role. def assume_role(role_arn, sts_client) credentials = Aws::AssumeRoleCredentials.new( client: sts_client, role_arn: role_arn, role_session_name: 'create-use-assume-role-scenario' ) @logger.info("Assumed role '#{role_arn}', got temporary credentials.") credentials end ``` + For API details, see [AssumeRole](https://docs.aws.amazon.com/goto/SdkForRubyV3/sts-2011-06-15/AssumeRole) in *AWS SDK for Ruby API Reference*. ------ #### [ Rust ] **SDK for Rust** There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/sts/#code-examples). ``` async fn assume_role(config: &SdkConfig, role_name: String, session_name: Option) { let provider = aws_config::sts::AssumeRoleProvider::builder(role_name) .session_name(session_name.unwrap_or("rust_sdk_example_session".into())) .configure(config) .build() .await; let local_config = aws_config::from_env() .credentials_provider(provider) .load() .await; let client = Client::new(&local_config); let req = client.get_caller_identity(); let resp = req.send().await; match resp { Ok(e) => { println!("UserID : {}", e.user_id().unwrap_or_default()); println!("Account: {}", e.account().unwrap_or_default()); println!("Arn : {}", e.arn().unwrap_or_default()); } Err(e) => println!("{:?}", e), } } ``` + For API details, see [AssumeRole](https://docs.rs/aws-sdk-sts/latest/aws_sdk_sts/client/struct.Client.html#method.assume_role) in *AWS SDK for Rust API reference*. ------ #### [ Swift ] **SDK for Swift** There's more on GitHub. Find the complete example and learn how to set up and run in the [AWS Code Examples Repository](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/swift/example_code/iam#code-examples). ``` import AWSSTS public func assumeRole(role: IAMClientTypes.Role, sessionName: String) async throws -> STSClientTypes.Credentials { let input = AssumeRoleInput( roleArn: role.arn, roleSessionName: sessionName ) do { let output = try await stsClient.assumeRole(input: input) guard let credentials = output.credentials else { throw ServiceHandlerError.authError } return credentials } catch { print("Error assuming role: ", dump(error)) throw error } } ``` + For API details, see [AssumeRole](https://sdk.amazonaws.com/swift/api/awssts/latest/documentation/awssts/stsclient/assumerole(input:)) in *AWS SDK for Swift API reference*. ------