From d8ab2548ba1563a20c9bf46e5c7d980d195c1999 Mon Sep 17 00:00:00 2001 From: Kenneth Johnson Date: Thu, 23 Apr 2026 17:33:15 -0500 Subject: [PATCH 1/7] [Access] Document AAGUID restrictions and AMR matching for independent MFA --- .../access-settings/independent-mfa.mdx | 207 +++++++++++++++--- .../policies/mfa-requirements.mdx | 22 +- .../reusable-components/lists.mdx | 1 + 3 files changed, 194 insertions(+), 36 deletions(-) diff --git a/src/content/docs/cloudflare-one/access-controls/access-settings/independent-mfa.mdx b/src/content/docs/cloudflare-one/access-controls/access-settings/independent-mfa.mdx index 6d639a8bc8d..a8547ed575f 100644 --- a/src/content/docs/cloudflare-one/access-controls/access-settings/independent-mfa.mdx +++ b/src/content/docs/cloudflare-one/access-controls/access-settings/independent-mfa.mdx @@ -75,6 +75,159 @@ Before you can [enforce independent MFA on applications and policies](/cloudflar After you turn on independent MFA, users can [enroll authenticators](#enroll-authenticators) through the [App Launcher](/cloudflare-one/access-controls/access-settings/app-launcher/). +## Restrict authenticators by AAGUID + +An [AAGUID](https://fidoalliance.org/specs/fido-v2.0-id-20180227/fido-registry-v2.0-id-20180227.html#authenticator-attestation-guid) (Authenticator Attestation GUID) is a 128-bit identifier that indicates the make and model of a [WebAuthn](https://www.w3.org/TR/webauthn-2/) authenticator. By restricting enrollment to a specific set of AAGUIDs, you can require that users only enroll approved hardware, such as FIPS-validated security keys or company-issued devices. + +AAGUID restrictions apply at enrollment time only. Access verifies the AAGUID when a user registers an authenticator, not when they authenticate. As a result, AAGUID restrictions are configured at the organization level. + +:::caution +Some authenticators do not send an AAGUID during WebAuthn registration, including: + +- Apple devices using iCloud Keychain passkeys. +- YubiKey 4 and earlier models using U2F (CTAP1). + +Users cannot enroll these authenticators when AAGUID restrictions are turned on. Before turning on AAGUID restrictions, confirm that your required authenticators are in the [FIDO Alliance Metadata Service](https://fidoalliance.org/metadata/). +::: + +### Create an AAGUID list + +AAGUIDs are managed using [Lists](/cloudflare-one/reusable-components/lists/). Create a list of type **AAGUID**, then reference the list in your organization's MFA configuration. + + + +1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Resources** > **Lists**. +2. Select **Create new list**. +3. Enter a **List name** (for example, `Approved security keys`) and an optional description. +4. Set **List type** to **AAGUID**. +5. Add one or more AAGUIDs. For each entry: + - **Value** — The AAGUID of the authenticator, in 32-character hexadecimal format without dashes (for example, `8c39ee867f9a4a959ba3f6b097e5c2ee`). + - **Description** — An optional label such as the authenticator's name and model. +6. Select **Save**. + + + +Send a `POST` request to create the list: + + + +The response contains an `id` (UUID) for the list. Use this ID when you assign the list to your organization's MFA configuration. + + + +:::tip +You can look up AAGUIDs for common authenticators in the [FIDO Alliance Metadata Service](https://fidoalliance.org/metadata/). Most vendors also publish AAGUIDs for their hardware on their support sites. +::: + +### Assign an AAGUID list to your organization + + + +1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Access settings**. +2. Under **Allow multi-factor authentication (MFA)**, go to **Required AAGUIDs**. +3. Select an existing [AAGUID list](#create-an-aaguid-list). +4. Select **Save**. + +After you save, only authenticators whose AAGUIDs appear in the list can be enrolled. Users with previously enrolled authenticators outside the list can continue to use them until an administrator deletes the device. + + + +Send a `PATCH` request to assign the list. Set `mfa_config.required_aaguids` to the ID of your AAGUID list. + + + +To remove the restriction, set `required_aaguids` to `null`. + + + +:::note +Required AAGUIDs and [AMR matching](#amr-matching) cannot both be turned on at the organization level. If required AAGUIDs is set, Access skips AMR matching even when the identity provider returns a matching AMR value. +::: + +## AMR matching + +Authentication Method Reference (AMR) matching tells Access to skip the independent MFA prompt when the user has already completed an equivalent MFA with their identity provider. This avoids prompting the user twice for MFA — once at the IdP and again at Access — while still ensuring that MFA occurred. + +Access uses the `amr` claim returned by the IdP, as defined in [RFC 8176](https://datatracker.ietf.org/doc/html/rfc8176). If the IdP returns an AMR value that matches an [allowed authenticator type](#supported-mfa-methods) for the application or policy, Access accepts the IdP's MFA and does not issue its own prompt. + +### Supported AMR values + +| AMR value | Matches Access authenticator type | Description | +| --------- | --------------------------------- | -------------------------------------- | +| `hwk` | Security key | Proof-of-possession of a hardware key. | +| `swk` | Security key | Proof-of-possession of a software key. | +| `otp` | Authenticator application | One-time password. | +| `face` | Biometrics | Facial recognition. | +| `fpt` | Biometrics | Fingerprint. | +| `iris` | Biometrics | Iris scan. | +| `retina` | Biometrics | Retina scan. | +| `vbm` | Biometrics | Voice biometric. | + +Access ignores AMR values that do not map to a supported authenticator type (for example, `pwd`, `sms`, `tel`, `geo`, `kba`, `sc`, `pin`, `user`, `mca`, `rba`, `wia`). + +### Turn on AMR matching + + + +1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Access settings**. +2. Under **Allow multi-factor authentication (MFA)**, turn on **Trust identity provider MFA (AMR matching)**. +3. Set an **AMR session duration**. This determines how long a successful IdP MFA remains valid for AMR matching. Format: `5m`, `1h`, `24h`. Minimum: `5m`. Maximum: `720h`. +4. Select **Save**. + + + +Send a `PATCH` request to your organization: + + + + + +### When AMR matching is skipped + +Access does not apply AMR matching in the following cases: + +- [Required AAGUIDs](#restrict-authenticators-by-aaguid) is set at the organization level. AAGUID information is not present in the IdP's AMR claim, so Access cannot verify that the IdP's MFA came from an approved device. +- The IdP does not return an `amr` claim. +- The IdP returns only AMR values that do not map to an [allowed authenticator type](#supported-mfa-methods) for the application or policy. +- The user's last IdP MFA is older than the configured AMR session duration. + +In these cases, Access prompts the user to complete independent MFA. + +:::note +Identity providers differ in how they populate the `amr` claim. Some providers, including Okta, may return provider-specific values such as `pop` that are not part of RFC 8176. Test the behavior with your IdP before relying on AMR matching for production applications. +::: + ## Turn off independent MFA :::caution @@ -124,42 +277,42 @@ If a user already has at least one authenticator enrolled, Access requires them To enroll an authenticator: -1. Go to your organization's App Launcher at `.cloudflareaccess.com`. -2. Log in with your identity provider or with a one-time PIN (OTP). -3. Go to **Account** > **MFA devices** > **Add an MFA device**. - :::note - Administrators can also share a direct enrollment link to help onboard users: `.cloudflareaccess.com/AddMfaDevice` - ::: -4. If you already have an MFA device enrolled, complete the MFA verification prompt. -5. Select the authenticator type you want to enroll and follow the on-screen instructions. +1. Go to your organization's App Launcher at `.cloudflareaccess.com`. +2. Log in with your identity provider or with a one-time PIN (OTP). +3. Go to **Account** > **MFA devices** > **Add an MFA device**. + :::note + Administrators can also share a direct enrollment link to help onboard users: `.cloudflareaccess.com/AddMfaDevice` + ::: +4. If you already have an MFA device enrolled, complete the MFA verification prompt. +5. Select the authenticator type you want to enroll and follow the on-screen instructions. -
+
- 1. Select **Authenticator application**. - 2. Scan the QR code with your authenticator app (for example, Google Authenticator, Microsoft Authenticator, or Authy). Alternatively, you can manually enter the setup key into your authenticator app. Use SHA1 as the hash function and set the time-step size to 30 seconds. - 3. Enter the 6-digit time-based one-time password (TOTP) generated by your authenticator app to verify enrollment. + 1. Select **Authenticator application**. + 2. Scan the QR code with your authenticator app (for example, Google Authenticator, Microsoft Authenticator, or Authy). Alternatively, you can manually enter the setup key into your authenticator app. Use SHA1 as the hash function and set the time-step size to 30 seconds. + 3. Enter the 6-digit time-based one-time password (TOTP) generated by your authenticator app to verify enrollment. - :::note - You can only have one TOTP authenticator enrolled at a time. If you use multiple devices, scan the same QR code on each device during enrollment. To replace an existing TOTP authenticator, delete it first and then enroll a new one. - ::: + :::note + You can only have one TOTP authenticator enrolled at a time. If you use multiple devices, scan the same QR code on each device during enrollment. To replace an existing TOTP authenticator, delete it first and then enroll a new one. + ::: -
+
-
- 1. Select **Security key**. - 2. When your browser prompts you, insert your security key and follow the on-screen instructions. - 3. After your browser confirms the registration, the security key is enrolled. +
+ 1. Select **Security key**. + 2. When your browser prompts you, insert your security key and follow the on-screen instructions. + 3. After your browser confirms the registration, the security key is enrolled. - You can enroll multiple security keys for backup purposes. + You can enroll multiple security keys for backup purposes. -
+
-
- 1. Select **Biometrics** > **Register biometrics**. - 2. You will be prompted to enroll with an authenticator type that is available on your device (for example, **Add macOS Touch ID** or **Add Windows Hello**). - 3. After your browser confirms the registration, the platform authenticator is enrolled. +
+ 1. Select **Biometrics** > **Register biometrics**. + 2. You will be prompted to enroll with an authenticator type that is available on your device (for example, **Add macOS Touch ID** or **Add Windows Hello**). + 3. After your browser confirms the registration, the platform authenticator is enrolled. -
+
You can now use these authenticators to log in to your organization's applications. diff --git a/src/content/docs/cloudflare-one/access-controls/policies/mfa-requirements.mdx b/src/content/docs/cloudflare-one/access-controls/policies/mfa-requirements.mdx index 1a19e98c4a4..00a59f2a2c5 100644 --- a/src/content/docs/cloudflare-one/access-controls/policies/mfa-requirements.mdx +++ b/src/content/docs/cloudflare-one/access-controls/policies/mfa-requirements.mdx @@ -70,11 +70,11 @@ Independent MFA prompts users for a second factor directly in Access. This allow You can configure MFA requirements at three levels: -| Level | Description | -| ---------------- | -------------------------------------------------------------- | -| [Organization](/cloudflare-one/access-controls/access-settings/independent-mfa/) | Enforce MFA by default for all applications in your account. | -| [Application](#configure-independent-mfa-for-an-application) | Require or turn off MFA for a specific application. | -| [Policy](#configure-independent-mfa-for-a-policy) | Require or turn off MFA for users who match a specific policy. | +| Level | Description | +| -------------------------------------------------------------------------------- | -------------------------------------------------------------- | +| [Organization](/cloudflare-one/access-controls/access-settings/independent-mfa/) | Enforce MFA by default for all applications in your account. | +| [Application](#configure-independent-mfa-for-an-application) | Require or turn off MFA for a specific application. | +| [Policy](#configure-independent-mfa-for-a-policy) | Require or turn off MFA for users who match a specific policy. | Settings at lower levels (policy) override settings at higher levels (organization), giving you granular control over MFA enforcement. @@ -82,15 +82,19 @@ Settings at lower levels (policy) override settings at higher levels (organizati Before you configure independent MFA on applications or policies, you must [turn on independent MFA](/cloudflare-one/access-controls/access-settings/independent-mfa/) at the organization level. +:::tip +At the organization level, you can also [restrict which authenticators can be enrolled using AAGUIDs](/cloudflare-one/access-controls/access-settings/independent-mfa/#restrict-authenticators-by-aaguid) and [skip independent MFA when the identity provider already performed MFA](/cloudflare-one/access-controls/access-settings/independent-mfa/#amr-matching). +::: + ### Configure independent MFA for an application Each application has three MFA options: -| Option | Behavior | -| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Option | Behavior | +| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Respect global enforcement setting** | Uses the [organization-level](/cloudflare-one/access-controls/access-settings/independent-mfa/) MFA configuration. If MFA is required globally, users must complete MFA. If MFA is not required globally, users are not prompted. This is the default. | -| **Custom MFA settings** | Overrides the organization setting with application-specific allowed authenticators and session duration. | -| **Disable MFA** | Users are not prompted for independent MFA when accessing this application, even if MFA is required globally. | +| **Custom MFA settings** | Overrides the organization setting with application-specific allowed authenticators and session duration. | +| **Disable MFA** | Users are not prompted for independent MFA when accessing this application, even if MFA is required globally. | To configure MFA for an application: diff --git a/src/content/docs/cloudflare-one/reusable-components/lists.mdx b/src/content/docs/cloudflare-one/reusable-components/lists.mdx index 391aea21725..32c6f3146e1 100644 --- a/src/content/docs/cloudflare-one/reusable-components/lists.mdx +++ b/src/content/docs/cloudflare-one/reusable-components/lists.mdx @@ -28,6 +28,7 @@ Lists can contain a single type of data each. Supported data types include: - User email addresses - IP addresses - Device ID numbers +- AAGUIDs (used by [Access independent MFA](/cloudflare-one/access-controls/access-settings/independent-mfa/#restrict-authenticators-by-aaguid) to restrict the WebAuthn authenticators users can enroll) From bb1f9cf32dcb446f08c599faaa576d9b917c84ee Mon Sep 17 00:00:00 2001 From: Kenneth Johnson Date: Thu, 23 Apr 2026 17:38:29 -0500 Subject: [PATCH 2/7] [Access] Add changelog for AAGUID restrictions and AMR matching --- .../2026-04-23-independent-mfa-aaguid-amr.mdx | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 src/content/changelog/access/2026-04-23-independent-mfa-aaguid-amr.mdx diff --git a/src/content/changelog/access/2026-04-23-independent-mfa-aaguid-amr.mdx b/src/content/changelog/access/2026-04-23-independent-mfa-aaguid-amr.mdx new file mode 100644 index 00000000000..9f3fe9769c1 --- /dev/null +++ b/src/content/changelog/access/2026-04-23-independent-mfa-aaguid-amr.mdx @@ -0,0 +1,14 @@ +--- +title: AAGUID restrictions and AMR matching for Access independent MFA +description: Restrict which WebAuthn authenticators users can enroll and skip redundant MFA prompts when the identity provider already performed MFA. +date: 2026-04-23 +products: + - access +--- + +[Independent MFA](/cloudflare-one/access-controls/access-settings/independent-mfa/) in Cloudflare Access now supports two additional organization-level controls: + +- **[Restrict authenticators by AAGUID](/cloudflare-one/access-controls/access-settings/independent-mfa/#restrict-authenticators-by-aaguid)** — Limit enrollment to a specific set of WebAuthn authenticators using their [AAGUID](https://fidoalliance.org/specs/fido-v2.0-id-20180227/fido-registry-v2.0-id-20180227.html#authenticator-attestation-guid). This is useful for organizations that require FIPS-validated security keys or company-issued hardware. AAGUIDs are managed through a new [List](/cloudflare-one/reusable-components/lists/) type. +- **[AMR matching](/cloudflare-one/access-controls/access-settings/independent-mfa/#amr-matching)** — Skip the independent MFA prompt when the identity provider has already performed an equivalent MFA. Access reads the `amr` claim defined in [RFC 8176](https://datatracker.ietf.org/doc/html/rfc8176) and matches supported values such as `hwk`, `otp`, and `fpt` to the authenticator types allowed on the application or policy. This prevents users from having to complete MFA twice when their identity provider already enforces it. + +To get started, refer to [Independent MFA](/cloudflare-one/access-controls/access-settings/independent-mfa/). From aee1dad2d666273ac5342dbeacf9c8b860d1685a Mon Sep 17 00:00:00 2001 From: Kenneth Johnson Date: Fri, 24 Apr 2026 15:47:26 -0500 Subject: [PATCH 3/7] [Access] Address review feedback on AAGUID and AMR matching docs --- .../access/2026-04-23-independent-mfa-aaguid-amr.mdx | 2 +- .../access-settings/independent-mfa.mdx | 12 +++++++++--- 2 files changed, 10 insertions(+), 4 deletions(-) diff --git a/src/content/changelog/access/2026-04-23-independent-mfa-aaguid-amr.mdx b/src/content/changelog/access/2026-04-23-independent-mfa-aaguid-amr.mdx index 9f3fe9769c1..0c78a4f4ae7 100644 --- a/src/content/changelog/access/2026-04-23-independent-mfa-aaguid-amr.mdx +++ b/src/content/changelog/access/2026-04-23-independent-mfa-aaguid-amr.mdx @@ -1,6 +1,6 @@ --- title: AAGUID restrictions and AMR matching for Access independent MFA -description: Restrict which WebAuthn authenticators users can enroll and skip redundant MFA prompts when the identity provider already performed MFA. +description: Restrict which WebAuthn authenticators users can enroll and allow users to skip redundant MFA prompts when they have already performed MFA using their IdP. date: 2026-04-23 products: - access diff --git a/src/content/docs/cloudflare-one/access-controls/access-settings/independent-mfa.mdx b/src/content/docs/cloudflare-one/access-controls/access-settings/independent-mfa.mdx index a8547ed575f..6086e1865e6 100644 --- a/src/content/docs/cloudflare-one/access-controls/access-settings/independent-mfa.mdx +++ b/src/content/docs/cloudflare-one/access-controls/access-settings/independent-mfa.mdx @@ -142,7 +142,7 @@ You can look up AAGUIDs for common authenticators in the [FIDO Alliance Metadata 3. Select an existing [AAGUID list](#create-an-aaguid-list). 4. Select **Save**. -After you save, only authenticators whose AAGUIDs appear in the list can be enrolled. Users with previously enrolled authenticators outside the list can continue to use them until an administrator deletes the device. +After you save, only authenticators whose AAGUIDs appear in the list can be enrolled. Users with previously enrolled authenticators outside the list can continue to use them until they are [deleted by an administrator](#delete-a-user-authenticator). @@ -153,11 +153,17 @@ Send a `PATCH` request to assign the list. Set `mfa_config.required_aaguids` to method="PATCH" json={{ mfa_config: { + allowed_authenticators: ["security_key", "totp", "biometrics"], + session_duration: "24h", required_aaguids: "05ddacda-5131-41ab-9eeb-6763f8dce3be", }, }} /> +:::note +The `PATCH` request must include all existing `mfa_config` fields (such as `allowed_authenticators` and `session_duration`) in addition to `required_aaguids`. Omitting existing fields will overwrite your current MFA configuration. +::: + To remove the restriction, set `required_aaguids` to `null`. @@ -220,9 +226,9 @@ Access does not apply AMR matching in the following cases: - [Required AAGUIDs](#restrict-authenticators-by-aaguid) is set at the organization level. AAGUID information is not present in the IdP's AMR claim, so Access cannot verify that the IdP's MFA came from an approved device. - The IdP does not return an `amr` claim. - The IdP returns only AMR values that do not map to an [allowed authenticator type](#supported-mfa-methods) for the application or policy. -- The user's last IdP MFA is older than the configured AMR session duration. +- The user's AMR matching session has expired because they last performed MFA via their IdP longer ago than the configured AMR session duration. -In these cases, Access prompts the user to complete independent MFA. +In these cases, Access falls back to checking for existing MFA sessions. If there are no valid MFA sessions, Access prompts the user to complete independent MFA. :::note Identity providers differ in how they populate the `amr` claim. Some providers, including Okta, may return provider-specific values such as `pop` that are not part of RFC 8176. Test the behavior with your IdP before relying on AMR matching for production applications. From 62ac2d8ceb7042cfd2e8ce5d9ea43d7c7a74dbc7 Mon Sep 17 00:00:00 2001 From: ranbel <101146722+ranbel@users.noreply.github.com> Date: Mon, 27 Apr 2026 18:25:10 -0400 Subject: [PATCH 4/7] Update independent-mfa.mdx fix API examples and UI labels --- .../access-settings/independent-mfa.mdx | 172 +++++++++++------- 1 file changed, 105 insertions(+), 67 deletions(-) diff --git a/src/content/docs/cloudflare-one/access-controls/access-settings/independent-mfa.mdx b/src/content/docs/cloudflare-one/access-controls/access-settings/independent-mfa.mdx index 6086e1865e6..bca15c9e050 100644 --- a/src/content/docs/cloudflare-one/access-controls/access-settings/independent-mfa.mdx +++ b/src/content/docs/cloudflare-one/access-controls/access-settings/independent-mfa.mdx @@ -28,7 +28,8 @@ Because you can [configure MFA at the application and policy level](/cloudflare- Before you can [enforce independent MFA on applications and policies](/cloudflare-one/access-controls/policies/mfa-requirements/#independent-mfa), you must turn on independent MFA at the organization level. - + + 1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Access settings**. 2. Under **Allow multi-factor authentication (MFA)**, select the [MFA methods](#supported-mfa-methods) you want to allow in your organization. @@ -39,7 +40,8 @@ Before you can [enforce independent MFA on applications and policies](/cloudflar ::: 5. Select **Save**. - + + 1. Get your existing Zero Trust organization configuration: @@ -71,7 +73,8 @@ Before you can [enforce independent MFA on applications and policies](/cloudflar Set `session_duration` to a duration string (for example, `30m`, `1h`, `24h`). To require MFA on every access, use `0m`. - + + After you turn on independent MFA, users can [enroll authenticators](#enroll-authenticators) through the [App Launcher](/cloudflare-one/access-controls/access-settings/app-launcher/). @@ -90,27 +93,31 @@ Some authenticators do not send an AAGUID during WebAuthn registration, includin Users cannot enroll these authenticators when AAGUID restrictions are turned on. Before turning on AAGUID restrictions, confirm that your required authenticators are in the [FIDO Alliance Metadata Service](https://fidoalliance.org/metadata/). ::: -### Create an AAGUID list +### 1. Create an AAGUID list AAGUIDs are managed using [Lists](/cloudflare-one/reusable-components/lists/). Create a list of type **AAGUID**, then reference the list in your organization's MFA configuration. - + + 1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Resources** > **Lists**. 2. Select **Create new list**. 3. Enter a **List name** (for example, `Approved security keys`) and an optional description. -4. Set **List type** to **AAGUID**. -5. Add one or more AAGUIDs. For each entry: - - **Value** — The AAGUID of the authenticator, in 32-character hexadecimal format without dashes (for example, `8c39ee867f9a4a959ba3f6b097e5c2ee`). - - **Description** — An optional label such as the authenticator's name and model. +4. Set **List type** to **MFA AAGUIDs**. +5. Add one or more AAGUID entries: + - To add predefined AAGUIDs, select authenticators from the **Known authenticators** list. + - To add a custom AAGUID, fill out the following fields: + - **MFA AAGUIDs** — The AAGUID of the authenticator, in 32-character hexadecimal format without dashes (for example, `8c39ee867f9a4a959ba3f6b097e5c2ee`). + - **Description** — An optional label such as the authenticator's name and model. 6. Select **Save**. - + + Send a `POST` request to create the list: + + :::tip You can look up AAGUIDs for common authenticators in the [FIDO Alliance Metadata Service](https://fidoalliance.org/metadata/). Most vendors also publish AAGUIDs for their hardware on their support sites. ::: -### Assign an AAGUID list to your organization +### 2. Assign an AAGUID list to your organization - + + 1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Access settings**. -2. Under **Allow multi-factor authentication (MFA)**, go to **Required AAGUIDs**. -3. Select an existing [AAGUID list](#create-an-aaguid-list). +2. Under **Allow multi-factor authentication (MFA)**, go to **Limit MFA to specific authentication methods**. +3. Select an existing [AAGUID list](#1-create-an-aaguid-list). 4. Select **Save**. After you save, only authenticators whose AAGUIDs appear in the list can be enrolled. Users with previously enrolled authenticators outside the list can continue to use them until they are [deleted by an administrator](#delete-a-user-authenticator). - + + -Send a `PATCH` request to assign the list. Set `mfa_config.required_aaguids` to the ID of your AAGUID list. +1. Get your existing Zero Trust organization configuration: - + -:::note -The `PATCH` request must include all existing `mfa_config` fields (such as `allowed_authenticators` and `session_duration`) in addition to `required_aaguids`. Omitting existing fields will overwrite your current MFA configuration. -::: +2. Send a `PUT` request to assign the list. To avoid overwriting your existing configuration, the `PUT` request body should contain all fields returned by the previous `GET` request. Set `mfa_config.required_aaguids` to the ID of your AAGUID list. + + -To remove the restriction, set `required_aaguids` to `null`. + To remove the restriction, set `required_aaguids` to `null`. - + + :::note -Required AAGUIDs and [AMR matching](#amr-matching) cannot both be turned on at the organization level. If required AAGUIDs is set, Access skips AMR matching even when the identity provider returns a matching AMR value. +AAGUID requirements and [AMR matching](#amr-matching) cannot both be turned on at the organization level. If AAGUID requirements are turned on, Access skips AMR matching even when the identity provider returns a matching AMR value. ::: ## AMR matching @@ -182,51 +199,66 @@ Access uses the `amr` claim returned by the IdP, as defined in [RFC 8176](https: | AMR value | Matches Access authenticator type | Description | | --------- | --------------------------------- | -------------------------------------- | -| `hwk` | Security key | Proof-of-possession of a hardware key. | -| `swk` | Security key | Proof-of-possession of a software key. | -| `otp` | Authenticator application | One-time password. | -| `face` | Biometrics | Facial recognition. | -| `fpt` | Biometrics | Fingerprint. | -| `iris` | Biometrics | Iris scan. | -| `retina` | Biometrics | Retina scan. | -| `vbm` | Biometrics | Voice biometric. | +| `hwk` | Security key | Proof-of-possession of a hardware key | +| `swk` | Security key | Proof-of-possession of a software key | +| `otp` | Authenticator application | One-time password | +| `face` | Biometrics | Facial recognition | +| `fpt` | Biometrics | Fingerprint | +| `iris` | Biometrics | Iris scan | +| `retina` | Biometrics | Retina scan | +| `vbm` | Biometrics | Voice biometric | Access ignores AMR values that do not map to a supported authenticator type (for example, `pwd`, `sms`, `tel`, `geo`, `kba`, `sc`, `pin`, `user`, `mca`, `rba`, `wia`). ### Turn on AMR matching - + + 1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Access settings**. -2. Under **Allow multi-factor authentication (MFA)**, turn on **Trust identity provider MFA (AMR matching)**. -3. Set an **AMR session duration**. This determines how long a successful IdP MFA remains valid for AMR matching. Format: `5m`, `1h`, `24h`. Minimum: `5m`. Maximum: `720h`. +2. Under **Allow multi-factor authentication (MFA)**, turn on **Use identity provider MFA**. +3. Under **Authentication Method Reference (AMR) matching duration**, set how long a successful IdP MFA remains valid. During this period, users can log in to Access without an additional MFA prompt. You can set a custom duration (default 24 hours) or check for a [valid AMR value](#supported-amr-values) on every login. 4. Select **Save**. - + + -Send a `PATCH` request to your organization: +1. Get your existing Zero Trust organization configuration: - + + +2. Send a `PUT` request to update your organization's AMR matching settings. To avoid overwriting your existing configuration, the `PUT` request body should contain all fields returned by the previous `GET` request. + + - + + ### When AMR matching is skipped Access does not apply AMR matching in the following cases: -- [Required AAGUIDs](#restrict-authenticators-by-aaguid) is set at the organization level. AAGUID information is not present in the IdP's AMR claim, so Access cannot verify that the IdP's MFA came from an approved device. +- [AAGUID requirements](#restrict-authenticators-by-aaguid) are turned on at the organization level. AAGUID information is not present in the IdP's AMR claim, so Access cannot verify that the IdP's MFA came from an approved device. - The IdP does not return an `amr` claim. - The IdP returns only AMR values that do not map to an [allowed authenticator type](#supported-mfa-methods) for the application or policy. -- The user's AMR matching session has expired because they last performed MFA via their IdP longer ago than the configured AMR session duration. +- The user's AMR matching session has expired because they last performed MFA via their IdP longer ago than the configured AMR matching duration. In these cases, Access falls back to checking for existing MFA sessions. If there are no valid MFA sessions, Access prompts the user to complete independent MFA. @@ -242,7 +274,8 @@ Turning off independent MFA removes MFA protection on all Access applications. B To turn off independent MFA for the organization: - + + 1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Access settings**. 2. Under **Allow multi-factor authentication (MFA)**, turn off **Apply global MFA settings by default**. @@ -250,7 +283,8 @@ To turn off independent MFA for the organization: If you get an error updating MFA settings, ensure that you have removed custom MFA settings from all applications and policies. - + + 1. Get your existing Zero Trust organization configuration: @@ -273,7 +307,8 @@ If you get an error updating MFA settings, ensure that you have removed custom M }} /> - + + ## Enroll authenticators @@ -361,7 +396,8 @@ To view a user's enrolled authenticators: If a user is locked out or you need to revoke an authenticator for security reasons, you can delete it from the dashboard or API. - + + 1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Team & Resources** > **Users**. 2. Select the user whose authenticator you want to delete. @@ -369,7 +405,8 @@ If a user is locked out or you need to revoke an authenticator for security reas The user will need to enroll a new authenticator the next time they access an application that requires MFA. - + + Send a `DELETE` request to remove a specific authenticator: @@ -383,7 +420,8 @@ Parameters: - `user_id` — The UUID of the user. You can find this in the user details under **Team & Resources** > **Users**. - `authenticator_id` — The unique identifier for the authenticator. - + + ### Lockout recovery From 195ba394cbf420dd8a1cbe9a264bfa79cc36d995 Mon Sep 17 00:00:00 2001 From: kennyj42 <73258453+kennyj42@users.noreply.github.com> Date: Tue, 28 Apr 2026 09:27:30 -0500 Subject: [PATCH 5/7] Enhance MFA settings with identity provider option Updated the MFA settings instructions to include the option for using identity provider MFA, which prevents double prompting for MFA. Adjusted the section title to reflect the new feature. --- .../access-controls/access-settings/independent-mfa.mdx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/content/docs/cloudflare-one/access-controls/access-settings/independent-mfa.mdx b/src/content/docs/cloudflare-one/access-controls/access-settings/independent-mfa.mdx index bca15c9e050..a7ac01e1828 100644 --- a/src/content/docs/cloudflare-one/access-controls/access-settings/independent-mfa.mdx +++ b/src/content/docs/cloudflare-one/access-controls/access-settings/independent-mfa.mdx @@ -34,11 +34,12 @@ Before you can [enforce independent MFA on applications and policies](/cloudflar 1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Access settings**. 2. Under **Allow multi-factor authentication (MFA)**, select the [MFA methods](#supported-mfa-methods) you want to allow in your organization. 3. Set an **Authentication duration**. This determines how long a user can log in to Access without being prompted for MFA again. If the user does not have an active MFA session for the required authenticator method, they must complete MFA in addition to IdP authentication. -4. (Optional) To apply your MFA methods and authentication duration to all Access applications, select **Apply global MFA settings by default**. You can [override the global MFA settings](/cloudflare-one/access-controls/policies/mfa-requirements/#configure-independent-mfa-for-an-application) for individual applications and policies. +4. (Optional) To avoid double prompting a user for MFA, you can enable **Use identity provider MFA**. This will check the AMR value passed from the identity provider at the time of authentication, if that AMR value passes an allowed MFA method, the user will not be prompted for MFA for the duration configured. +5. (Optional) To apply your MFA methods and authentication duration to all Access applications, select **Apply global MFA settings by default**. You can [override the global MFA settings](/cloudflare-one/access-controls/policies/mfa-requirements/#configure-independent-mfa-for-an-application) for individual applications and policies. :::note The [App Launcher](/cloudflare-one/access-controls/access-settings/app-launcher/) is exempt from the global MFA requirement. Users must be able to access the App Launcher without MFA to enroll their authenticators. ::: -5. Select **Save**. +6. Select **Save**. @@ -189,7 +190,7 @@ After you save, only authenticators whose AAGUIDs appear in the list can be enro AAGUID requirements and [AMR matching](#amr-matching) cannot both be turned on at the organization level. If AAGUID requirements are turned on, Access skips AMR matching even when the identity provider returns a matching AMR value. ::: -## AMR matching +## Use Identity provider MFA Authentication Method Reference (AMR) matching tells Access to skip the independent MFA prompt when the user has already completed an equivalent MFA with their identity provider. This avoids prompting the user twice for MFA — once at the IdP and again at Access — while still ensuring that MFA occurred. From e062e41468a420a343ea9e2b2112dbb5fb244e4b Mon Sep 17 00:00:00 2001 From: ranbel <101146722+ranbel@users.noreply.github.com> Date: Tue, 28 Apr 2026 10:41:18 -0400 Subject: [PATCH 6/7] update links and intro to align with new section header --- .../access-settings/independent-mfa.mdx | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/src/content/docs/cloudflare-one/access-controls/access-settings/independent-mfa.mdx b/src/content/docs/cloudflare-one/access-controls/access-settings/independent-mfa.mdx index a7ac01e1828..dbe753f0167 100644 --- a/src/content/docs/cloudflare-one/access-controls/access-settings/independent-mfa.mdx +++ b/src/content/docs/cloudflare-one/access-controls/access-settings/independent-mfa.mdx @@ -34,7 +34,7 @@ Before you can [enforce independent MFA on applications and policies](/cloudflar 1. In the [Cloudflare dashboard](https://dash.cloudflare.com/), go to **Zero Trust** > **Access controls** > **Access settings**. 2. Under **Allow multi-factor authentication (MFA)**, select the [MFA methods](#supported-mfa-methods) you want to allow in your organization. 3. Set an **Authentication duration**. This determines how long a user can log in to Access without being prompted for MFA again. If the user does not have an active MFA session for the required authenticator method, they must complete MFA in addition to IdP authentication. -4. (Optional) To avoid double prompting a user for MFA, you can enable **Use identity provider MFA**. This will check the AMR value passed from the identity provider at the time of authentication, if that AMR value passes an allowed MFA method, the user will not be prompted for MFA for the duration configured. +4. (Optional) To avoid double prompting a user for MFA, you can enable [**Use identity provider MFA**](#use-identity-provider-mfa). This will check the AMR value passed from the identity provider at the time of authentication, if that AMR value passes an allowed MFA method, the user will not be prompted for MFA for the duration configured. 5. (Optional) To apply your MFA methods and authentication duration to all Access applications, select **Apply global MFA settings by default**. You can [override the global MFA settings](/cloudflare-one/access-controls/policies/mfa-requirements/#configure-independent-mfa-for-an-application) for individual applications and policies. :::note The [App Launcher](/cloudflare-one/access-controls/access-settings/app-launcher/) is exempt from the global MFA requirement. Users must be able to access the App Launcher without MFA to enroll their authenticators. @@ -187,14 +187,12 @@ After you save, only authenticators whose AAGUIDs appear in the list can be enro :::note -AAGUID requirements and [AMR matching](#amr-matching) cannot both be turned on at the organization level. If AAGUID requirements are turned on, Access skips AMR matching even when the identity provider returns a matching AMR value. +AAGUID requirements and [AMR matching](#use-identity-provider-mfa) cannot both be turned on at the organization level. If AAGUID requirements are turned on, Access skips AMR matching even when the identity provider returns a matching AMR value. ::: -## Use Identity provider MFA +## Use identity provider MFA -Authentication Method Reference (AMR) matching tells Access to skip the independent MFA prompt when the user has already completed an equivalent MFA with their identity provider. This avoids prompting the user twice for MFA — once at the IdP and again at Access — while still ensuring that MFA occurred. - -Access uses the `amr` claim returned by the IdP, as defined in [RFC 8176](https://datatracker.ietf.org/doc/html/rfc8176). If the IdP returns an AMR value that matches an [allowed authenticator type](#supported-mfa-methods) for the application or policy, Access accepts the IdP's MFA and does not issue its own prompt. +If your identity provider already prompts users for MFA, you can configure Access to accept that MFA instead of prompting again. Access checks the Authentication Method Reference (AMR) claim returned by the IdP, as defined in [RFC 8176](https://datatracker.ietf.org/doc/html/rfc8176). If the AMR value matches an [allowed authenticator type](#supported-mfa-methods) for the application or policy, Access skips the independent MFA prompt. ### Supported AMR values From 617daf90b365a28aa2df4f4854caf9b76ceb6a7d Mon Sep 17 00:00:00 2001 From: ranbel <101146722+ranbel@users.noreply.github.com> Date: Tue, 28 Apr 2026 11:07:24 -0400 Subject: [PATCH 7/7] fix anchor links Co-authored-by: ranbel <101146722+ranbel@users.noreply.github.com> --- .../changelog/access/2026-04-23-independent-mfa-aaguid-amr.mdx | 2 +- .../access-controls/policies/mfa-requirements.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/changelog/access/2026-04-23-independent-mfa-aaguid-amr.mdx b/src/content/changelog/access/2026-04-23-independent-mfa-aaguid-amr.mdx index 0c78a4f4ae7..844a05947b2 100644 --- a/src/content/changelog/access/2026-04-23-independent-mfa-aaguid-amr.mdx +++ b/src/content/changelog/access/2026-04-23-independent-mfa-aaguid-amr.mdx @@ -9,6 +9,6 @@ products: [Independent MFA](/cloudflare-one/access-controls/access-settings/independent-mfa/) in Cloudflare Access now supports two additional organization-level controls: - **[Restrict authenticators by AAGUID](/cloudflare-one/access-controls/access-settings/independent-mfa/#restrict-authenticators-by-aaguid)** — Limit enrollment to a specific set of WebAuthn authenticators using their [AAGUID](https://fidoalliance.org/specs/fido-v2.0-id-20180227/fido-registry-v2.0-id-20180227.html#authenticator-attestation-guid). This is useful for organizations that require FIPS-validated security keys or company-issued hardware. AAGUIDs are managed through a new [List](/cloudflare-one/reusable-components/lists/) type. -- **[AMR matching](/cloudflare-one/access-controls/access-settings/independent-mfa/#amr-matching)** — Skip the independent MFA prompt when the identity provider has already performed an equivalent MFA. Access reads the `amr` claim defined in [RFC 8176](https://datatracker.ietf.org/doc/html/rfc8176) and matches supported values such as `hwk`, `otp`, and `fpt` to the authenticator types allowed on the application or policy. This prevents users from having to complete MFA twice when their identity provider already enforces it. +- **[AMR matching](/cloudflare-one/access-controls/access-settings/independent-mfa/#use-identity-provider-mfa)** — Skip the independent MFA prompt when the identity provider has already performed an equivalent MFA. Access reads the `amr` claim defined in [RFC 8176](https://datatracker.ietf.org/doc/html/rfc8176) and matches supported values such as `hwk`, `otp`, and `fpt` to the authenticator types allowed on the application or policy. This prevents users from having to complete MFA twice when their identity provider already enforces it. To get started, refer to [Independent MFA](/cloudflare-one/access-controls/access-settings/independent-mfa/). diff --git a/src/content/docs/cloudflare-one/access-controls/policies/mfa-requirements.mdx b/src/content/docs/cloudflare-one/access-controls/policies/mfa-requirements.mdx index 00a59f2a2c5..66966ba9371 100644 --- a/src/content/docs/cloudflare-one/access-controls/policies/mfa-requirements.mdx +++ b/src/content/docs/cloudflare-one/access-controls/policies/mfa-requirements.mdx @@ -83,7 +83,7 @@ Settings at lower levels (policy) override settings at higher levels (organizati Before you configure independent MFA on applications or policies, you must [turn on independent MFA](/cloudflare-one/access-controls/access-settings/independent-mfa/) at the organization level. :::tip -At the organization level, you can also [restrict which authenticators can be enrolled using AAGUIDs](/cloudflare-one/access-controls/access-settings/independent-mfa/#restrict-authenticators-by-aaguid) and [skip independent MFA when the identity provider already performed MFA](/cloudflare-one/access-controls/access-settings/independent-mfa/#amr-matching). +At the organization level, you can also [restrict which authenticators can be enrolled using AAGUIDs](/cloudflare-one/access-controls/access-settings/independent-mfa/#restrict-authenticators-by-aaguid) and [skip independent MFA when the identity provider already performed MFA](/cloudflare-one/access-controls/access-settings/independent-mfa/#use-identity-provider-mfa. ::: ### Configure independent MFA for an application