From 4fd4ec5233c866de47bba6aad7595ddac7cdb6f0 Mon Sep 17 00:00:00 2001 From: James Walters Date: Mon, 20 Jul 2026 12:16:20 -0500 Subject: [PATCH] [Access] Add FIDO2 as MFA type for Infrastructure SSH Applications --- ...26-07-20-fido2-keys-infrastructure-ssh.mdx | 14 ++++ .../access-settings/independent-mfa.mdx | 80 ++++++++++++++----- .../non-http/infrastructure-apps.mdx | 14 ++-- .../policies/mfa-requirements.mdx | 30 ++++--- .../ssh/ssh-infrastructure-access.mdx | 30 +++++-- 5 files changed, 124 insertions(+), 44 deletions(-) create mode 100644 src/content/changelog/cloudflare-one/2026-07-20-fido2-keys-infrastructure-ssh.mdx diff --git a/src/content/changelog/cloudflare-one/2026-07-20-fido2-keys-infrastructure-ssh.mdx b/src/content/changelog/cloudflare-one/2026-07-20-fido2-keys-infrastructure-ssh.mdx new file mode 100644 index 00000000000..17e9161497c --- /dev/null +++ b/src/content/changelog/cloudflare-one/2026-07-20-fido2-keys-infrastructure-ssh.mdx @@ -0,0 +1,14 @@ +--- +title: FIDO2 Key support for infrastructure SSH applications +description: Access supports FIDO2 Keys for independent MFA on infrastructure SSH applications. +date: 2026-07-20 +products: + - cloudflare-one + - access +--- + +[Access for Infrastructure](/cloudflare-one/access-controls/applications/non-http/infrastructure-apps/) SSH applications support independent multi-factor authentication (MFA) with FIDO2 Keys. You can allow `ssh_fido2_key`, `piv_key`, or both in application-level and policy-level MFA settings. + +Users enroll FIDO2 Keys through the App Launcher and connect with the generated SSH identity. FIDO2 Keys for SSH are separate from browser-based WebAuthn **Security keys** and Personal Identity Verification (PIV) keys. + +For setup instructions, refer to [Enroll a FIDO2 Key for infrastructure apps](/cloudflare-one/access-controls/access-settings/independent-mfa/#enroll-a-fido2-key-for-infrastructure-apps) and [Configure MFA for infrastructure applications](/cloudflare-one/access-controls/policies/mfa-requirements/#infrastructure-applications). 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 1a01d8257ca..6a20d7ac427 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 @@ -18,12 +18,13 @@ Because you can [configure MFA at the application and policy level](/cloudflare- ## Supported MFA methods -| MFA method | Description | -| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Authenticator application | Time-based one-time passwords (TOTP) generated by apps such as Google Authenticator, Microsoft Authenticator, or Authy. Access supports one TOTP authenticator per user at a time. | -| Security key | Hardware security keys that support the [WebAuthn](https://www.w3.org/TR/webauthn-2/) standard. Users can enroll multiple security keys. | -| Biometrics | Built-in device authenticators that use [WebAuthn](https://www.w3.org/TR/webauthn-2/), including Apple Touch ID, Apple Face ID, and Windows Hello. Users can enroll multiple biometrics. | +| MFA method | Description | +| ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Authenticator application | Time-based one-time passwords (TOTP) generated by apps such as Google Authenticator, Microsoft Authenticator, or Authy. Access supports one TOTP authenticator per user at a time. | +| Security key | Hardware security keys that support the [WebAuthn](https://www.w3.org/TR/webauthn-2/) standard. Users can enroll multiple security keys. | +| Biometrics | Built-in device authenticators that use [WebAuthn](https://www.w3.org/TR/webauthn-2/), including Apple Touch ID, Apple Face ID, and Windows Hello. Users can enroll multiple biometrics. | | Personal Identity Verification (PIV) key (infrastructure apps only) | YubiKey PIV keys used for public key authentication during SSH connections. Requires YubiKey firmware 4.3 or later. This method is only available for [infrastructure applications](/cloudflare-one/access-controls/applications/non-http/infrastructure-apps/). Users can enroll multiple PIV keys. | +| FIDO2 Key (infrastructure apps only) | FIDO2 hardware keys used for public key authentication during SSH connections. This method is separate from PIV keys and the browser-based WebAuthn **Security key** method. | ## Turn on independent MFA @@ -73,6 +74,7 @@ Before you can [enforce independent MFA on applications and policies](/cloudflar - `biometrics` — Biometrics (Touch ID, Face ID, Windows Hello). - `security_key` — Security keys (hardware keys that support WebAuthn). - `piv_key` — PIV keys (YubiKeys). + - `ssh_fido2_key` — FIDO2 keys for SSH connections to infrastructure applications. Set `session_duration` to a duration string (for example, `30m`, `1h`, `24h`). To require MFA on every access, use `0m`. @@ -89,25 +91,29 @@ If you plan to use PIV keys for [MFA for infrastructure applications](/cloudflar 2. Under **Allow multi-factor authentication (MFA)**, turn on the "Personal Identity Verification (PIV) key" authenticator. 3. Configure the following settings: - | Setting | Description | Options | - | ----------------- | ---------------------------------------------- | --------------------------------------------------------------- | - | **Key type** | The SSH key algorithm | ECDSA, Ed25519, RSA | - | **Key size** | The key length in bits | ECDSA: 256, 384, 521. RSA: 2048, 3072, 4096 | - | **PIN policy** | When the user must enter their PIV PIN | `never`, `once` (once per session), `always` (every use) | - | **Touch policy** | When the user must touch the hardware key | `never`, `always` (every use), `cached` (cached for 15 seconds) | - | **Require FIPS** | Require the PIV key to be on a FIPS-validated device | `true`, `false` | + | Setting | Description | Options | + | ---------------- | ---------------------------------------------------- | --------------------------------------------------------------- | + | **Key type** | The SSH key algorithm | ECDSA, Ed25519, RSA | + | **Key size** | The key length in bits | ECDSA: 256, 384, 521. RSA: 2048, 3072, 4096 | + | **PIN policy** | When the user must enter their PIV PIN | `never`, `once` (once per session), `always` (every use) | + | **Touch policy** | When the user must touch the hardware key | `never`, `always` (every use), `cached` (cached for 15 seconds) | + | **Require FIPS** | Require the PIV key to be on a FIPS-validated device | `true`, `false` | 4. Select **Save**. :::note - + + ::: ## 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. +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 an authenticator model. Use `required_aaguids` to restrict AAGUID-bearing MFA devices to approved authenticator models. -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. +Access enforces the restriction during device enrollment and when a FIDO2 SSH key connects. PIV keys are not subject to AAGUID restrictions. When `required_aaguids` is unset, Access does not enforce AAGUID restrictions. :::caution Some authenticators do not send an AAGUID during WebAuthn registration, such as 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/). @@ -171,7 +177,7 @@ You can look up AAGUIDs for common authenticators in the [FIDO Alliance Metadata 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). +After you save, only matching Security keys and FIDO2 SSH keys can enroll. Matching FIDO2 SSH keys are also required when connecting. To remove the restriction, unset the AAGUID list. @@ -200,7 +206,7 @@ After you save, only authenticators whose AAGUIDs appear in the list can be enro code={{ mark: ["required_aaguids"] }} /> - To remove the restriction, set `required_aaguids` to `null`. + To remove the restriction, omit or unset `required_aaguids`. @@ -215,8 +221,8 @@ If your identity provider already prompts users for MFA, you can configure Acces ### Supported AMR values -| AMR value | Matches Access authenticator type | Description | -| --------- | --------------------------------- | -------------------------------------- | +| 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 | @@ -376,8 +382,44 @@ To enroll an authenticator: PIV key enrollment requires additional client-side setup and is only used for [MFA with infrastructure applications](/cloudflare-one/access-controls/policies/mfa-requirements/#infrastructure-applications). For full instructions, refer to [Enroll a PIV key for infrastructure apps](#enroll-a-piv-key-for-infrastructure-apps). +
+ FIDO2 Key enrollment creates an SSH key for infrastructure applications. This method differs from browser-based WebAuthn **Security key** enrollment and PIV key enrollment. For instructions, refer to [Enroll a FIDO2 Key for infrastructure apps](#enroll-a-fido2-key-for-infrastructure-apps). +
+ You can now use these authenticators to log in to your organization's applications. +### Enroll a FIDO2 key for infrastructure apps + +The App Launcher generates the enrollment command for your account. Do not construct the enrollment command manually. + +1. Go to your organization's App Launcher at `.cloudflareaccess.com`. +2. Log in with your identity provider or a one-time PIN (OTP). +3. Go to **Account** > **MFA devices** > **Add an MFA device** > **FIDO2 Key**. +4. Copy the enrollment command shown in the App Launcher. +5. Run the command in a local terminal on the device you use for SSH. +6. Follow the prompts, then copy the JSON output. +7. Return to the App Launcher and paste the JSON into the enrollment field. +8. Complete the enrollment. + +#### Configure your SSH client for a FIDO2 key + +The command creates the identity at `~/.ssh/id_ed25519_sk_cf`. + +Add the following configuration to your `~/.ssh/config` file: + +```txt +Host * + IdentityFile ~/.ssh/id_ed25519_sk_cf +``` + +Alternatively, supply the identity when you connect: + +```sh +ssh -i ~/.ssh/id_ed25519_sk_cf @ +``` + +For more information on how OpenSSH uses FIDO2 hardware keys, refer to Yubico's [Securing SSH with FIDO2](https://developers.yubico.com/SSH/Securing_SSH_with_FIDO2.html). + ### Enroll a PIV key for infrastructure apps PIV key enrollment is separate from the general authenticator enrollment above and requires additional client-side setup. diff --git a/src/content/docs/cloudflare-one/access-controls/applications/non-http/infrastructure-apps.mdx b/src/content/docs/cloudflare-one/access-controls/applications/non-http/infrastructure-apps.mdx index d988ac99b61..925be0e6cf1 100644 --- a/src/content/docs/cloudflare-one/access-controls/applications/non-http/infrastructure-apps.mdx +++ b/src/content/docs/cloudflare-one/access-controls/applications/non-http/infrastructure-apps.mdx @@ -7,8 +7,8 @@ title: Add an infrastructure application sidebar: order: 2 tags: -- SSH -- Authentication + - SSH + - Authentication --- import { Badge, Details, Tabs, TabItem, Render } from "~/components"; @@ -16,8 +16,8 @@ import { Badge, Details, Tabs, TabItem, Render } from "~/components";
| [Client modes](/cloudflare-one/team-and-resources/devices/cloudflare-one-client/configure/modes/) | [Zero Trust plans](https://www.cloudflare.com/teams-pricing/) | -| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------- | -|
  • Traffic and DNS mode
  • Traffic only mode
| All plans | +| ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | +|
  • Traffic and DNS mode
  • Traffic only mode
| All plans | | System | Availability | | -------- | ------------ | @@ -63,7 +63,9 @@ Access for Infrastructure currently supports [SSH](/cloudflare-one/networks/conn ## 4. (Optional) Require independent MFA -You can require users to authenticate with a [YubiKey PIV key](/cloudflare-one/access-controls/access-settings/independent-mfa/#enroll-a-piv-key-for-infrastructure-apps) before connecting with SSH to targets. You can configure MFA at the application level or at the policy level, allowing you to enforce stricter requirements for sensitive usernames. +You can require independent MFA before users connect with SSH. The application configuration selects the supported infrastructure authenticators: PIV key (`piv_key`), FIDO2 Key (`ssh_fido2_key`), or both. + +Application-level settings define the default authenticators and session duration. A policy can define custom settings for specific users or usernames. For setup instructions, refer to [Enforce MFA for infrastructure applications](/cloudflare-one/access-controls/policies/mfa-requirements/#infrastructure-applications). @@ -73,6 +75,8 @@ Certain protocols require configuring the server to trust connections through Ac - [SSH](/cloudflare-one/networks/connectors/cloudflare-tunnel/use-cases/ssh/ssh-infrastructure-access/#7-configure-ssh-server) +For SSH, this includes trusting the Cloudflare SSH CA and, if your server restricts certificate principals, [authorizing the SSH usernames](/cloudflare-one/networks/connectors/cloudflare-tunnel/use-cases/ssh/ssh-infrastructure-access/#authorize-the-certificate-principal) you configured on the target. + ## 6. Connect as a user Users connect to the target's IP address using their preferred client software. The user must be logged into the Cloudflare One Client on their device, but no other system configuration is required. You can optionally configure a [private DNS resolver](/cloudflare-one/traffic-policies/resolver-policies/) to allow connections to the target's private hostname. 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 0edc747b59c..ff8fc2f0a58 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 @@ -19,7 +19,7 @@ Cloudflare Access supports two methods of enforcing multi-factor authentication - **[Identity provider-based MFA](#identity-provider-based-mfa)** — Require specific MFA methods reported by your identity provider (IdP). - **[Independent MFA](#independent-mfa)** — Prompt users for a second factor directly in Access, without relying on a third-party identity provider. -For SSH connections to [infrastructure applications](/cloudflare-one/access-controls/applications/non-http/infrastructure-apps/), Access also supports [independent MFA with PIV keys](#infrastructure-applications). +For SSH connections to [infrastructure applications](/cloudflare-one/access-controls/applications/non-http/infrastructure-apps/), Access also supports [independent MFA with PIV and FIDO2 keys](#infrastructure-applications). ## Identity provider-based MFA @@ -78,7 +78,7 @@ You can configure MFA requirements at three levels: | [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. +MFA settings use this precedence: **Policy** > **Application** > **Organization**. ### Prerequisites @@ -195,16 +195,20 @@ In this example: ## Infrastructure applications -Infrastructure applications that use SSH support independent MFA with [YubiKey PIV keys](/cloudflare-one/access-controls/access-settings/independent-mfa/#enroll-a-piv-key-for-infrastructure-apps). When MFA is required, users must complete public key authentication with their enrolled PIV key before the connection is established. Users must [enroll their PIV key](/cloudflare-one/access-controls/access-settings/independent-mfa/#enroll-a-piv-key-for-infrastructure-apps) through the App Launcher before they can connect. +Infrastructure applications that use SSH support two infrastructure-only MFA methods. `piv_key` uses an enrolled Personal Identity Verification (PIV) key. `ssh_fido2_key` uses an enrolled FIDO2 SSH key. Neither method applies to other Access application types or browser WebAuthn authentication. You can configure MFA for infrastructure apps at the application level or at the policy level. ### Configure MFA for an infrastructure application -Infrastructure applications use a PIV key authenticator (`piv_key`) that is specific to SSH connections. This authenticator type is not available for other Access application types. +Select PIV key, FIDO2 Key, or both when configuring custom MFA. The corresponding API arrays are `["piv_key"]`, `["ssh_fido2_key"]`, and `["piv_key", "ssh_fido2_key"]`. :::note - + + :::
@@ -233,16 +237,16 @@ https://api.cloudflare.com/client/v4/accounts/{account_id}/access/apps/{app_id} "mfa_config": { "mfa_disabled": false, "session_duration": "12h", - "allowed_authenticators": ["piv_key"] + "allowed_authenticators": ["piv_key", "ssh_fido2_key"] } }' ``` -| Field | Type | Description | -| ------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| `mfa_disabled` | Boolean | If `true`, MFA is not required for this application, even if global settings enforce MFA. | -| `session_duration` | String | Duration before the user must re-authenticate with MFA (for example, `30m`, `1h`, `24h`). Set to `0m` to require MFA on every SSH connection. | -| `allowed_authenticators` | Array | List of allowed authenticator types. For infrastructure applications, `piv_key` is the only available modality. | +| Field | Type | Description | +| ------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------- | +| `mfa_disabled` | Boolean | If `true`, MFA is not required for this application, even if global settings enforce MFA. | +| `session_duration` | String | Duration before the user must re-authenticate with MFA (for example, `30m`, `1h`, `24h`). Set to `0m` to require MFA on every SSH connection. | +| `allowed_authenticators` | Array | Use `["piv_key"]`, `["ssh_fido2_key"]`, or `["piv_key", "ssh_fido2_key"]`. |
@@ -285,7 +289,7 @@ https://api.cloudflare.com/client/v4/accounts/{account_id}/access/policies/{poli "mfa_config": { "mfa_disabled": false, "session_duration": "1h", - "allowed_authenticators": ["piv_key"] + "allowed_authenticators": ["piv_key", "ssh_fido2_key"] }, "connection_rules": { "ssh": { @@ -300,7 +304,7 @@ https://api.cloudflare.com/client/v4/accounts/{account_id}/access/policies/{poli ### MFA session duration for SSH -The MFA session duration determines how long after performing MFA a user can open new SSH connections without being prompted again. After the session expires, the user must re-authenticate with their PIV key on their next SSH connection. Existing SSH sessions are not affected by session expiration. Set the session duration to `0` to require MFA on every SSH connection. +The MFA session duration determines how long users can open new SSH connections without another MFA prompt. Set the duration to `0m` to require MFA for every new connection. Expiration does not terminate an active connection. MFA sessions are bound to the user's device. If a user switches to a different device, they must re-authenticate regardless of the remaining session duration. diff --git a/src/content/docs/cloudflare-one/networks/connectors/cloudflare-tunnel/use-cases/ssh/ssh-infrastructure-access.mdx b/src/content/docs/cloudflare-one/networks/connectors/cloudflare-tunnel/use-cases/ssh/ssh-infrastructure-access.mdx index 2b273d82931..a2924e869d4 100644 --- a/src/content/docs/cloudflare-one/networks/connectors/cloudflare-tunnel/use-cases/ssh/ssh-infrastructure-access.mdx +++ b/src/content/docs/cloudflare-one/networks/connectors/cloudflare-tunnel/use-cases/ssh/ssh-infrastructure-access.mdx @@ -11,7 +11,7 @@ sidebar: label: SSH with Access for Infrastructure --- -import { Tabs, TabItem, Badge, Render, APIRequest, DashButton } from "~/components"; +import { Tabs, TabItem, Render, APIRequest, DashButton } from "~/components"; [Access for Infrastructure](/cloudflare-one/access-controls/applications/non-http/infrastructure-apps/) provides granular control over how users can connect to your SSH servers. Like the [self-managed SSH keys](/cloudflare-one/networks/connectors/cloudflare-tunnel/use-cases/ssh/ssh-device-client/) method, it uses the Cloudflare One Client on user devices and Cloudflare Tunnel on the server to create a secure, private connection through Cloudflare's network. Access for Infrastructure adds application-level policies with per-target and per-username controls, as well as SSH command logging. @@ -109,20 +109,20 @@ chmod 600 /etc/ssh/ca.pub ## 8. (Optional) Require independent MFA for SSH -You can require users to authenticate with a [YubiKey PIV key](/cloudflare-one/access-controls/access-settings/independent-mfa/#enroll-a-piv-key-for-infrastructure-apps) before connecting to your SSH servers. When MFA is required, users must complete public key authentication with their enrolled PIV key before the connection is established. +You can require users to authenticate with a PIV key or FIDO2 Key before connecting to SSH servers. When configuring custom MFA, select **PIV key**, **FIDO2 Key**, or both. To configure independent MFA for SSH, refer to [Enforce MFA for infrastructure applications](/cloudflare-one/access-controls/policies/mfa-requirements/#infrastructure-applications). -Before users can connect with MFA enabled, they must: +Before users can connect with MFA turned on, they must enroll and configure their selected key: -1. [Enroll a PIV key](/cloudflare-one/access-controls/access-settings/independent-mfa/#enroll-a-piv-key-for-infrastructure-apps) through the App Launcher. -2. [Configure their SSH client](/cloudflare-one/access-controls/access-settings/independent-mfa/#configure-your-ssh-client) to use the enrolled PIV key. +- For PIV keys, [enroll the key](/cloudflare-one/access-controls/access-settings/independent-mfa/#enroll-a-piv-key-for-infrastructure-apps) and [configure the SSH client](/cloudflare-one/access-controls/access-settings/independent-mfa/#configure-your-ssh-client). +- For FIDO2 Keys, [enroll the key](/cloudflare-one/access-controls/access-settings/independent-mfa/#enroll-a-fido2-key-for-infrastructure-apps) and [configure the SSH client](/cloudflare-one/access-controls/access-settings/independent-mfa/#configure-your-ssh-client-for-a-fido2-key). -When the user runs `ssh @`, the SSH proxy checks if MFA is required for the matching policy. If required, the user must touch their YubiKey and enter their PIN (depending on the key's PIN policy). The proxy then completes the connection. +When the user runs `ssh @`, the SSH proxy checks if MFA is required for the matching policy. If required, the user completes authentication using their enrolled PIV or FIDO2 Key. The proxy then completes the connection. ## 9. Connect as a user -Users can use any SSH client to connect to the target, as long as they are logged into the Cloudflare One Client on their device. If the target is located within a particular virtual network, ensure that the Cloudflare One Client is [connected to that virtual network](/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/cloudflared/tunnel-virtual-networks/#connect-to-a-virtual-network) before initiating the connection. Users do not need to modify any SSH configs on their device. For example, to SSH from a terminal: +Users can use any SSH client while logged in to the Cloudflare One Client. If the target uses a virtual network, [connect to that virtual network](/cloudflare-one/networks/connectors/cloudflare-tunnel/private-net/cloudflared/tunnel-virtual-networks/#connect-to-a-virtual-network) first. ```sh ssh @ @@ -462,6 +462,22 @@ Subsystem sftp /usr/lib/openssh/sftp-server
+#### Confirm the account authorizes the certificate principal + +If your `sshd` logs show that the certificate was accepted as CA-signed but the connection still fails, the account may not authorize the certificate's principal. `sshd` reports this as: + +```txt +Certificate invalid: name is not a listed principal +``` + +Check the effective configuration for the account you are connecting as, because these directives are often set within a `Match` block: + +```sh +sudo sshd -T -C user= | grep -i principals +``` + +If `authorizedprincipalsfile` or `authorizedprincipalscommand` is set to any value other than `none`, confirm that the SSH username appears in that file or in the command's output. If it is missing, [authorize the principal](#authorize-the-certificate-principal), validate your configuration with `sudo sshd -t`, then [reload](#reload-your-ssh-server) your SSH server. + #### Replace and test with example configuration The next steps will walk you through a troubleshooting regimen. You will temporarily replace your existing `sshd_config` file with the provided example to rule out configuration issues. Before proceeding, carefully [review and compare both files](#review-your-sshd_config-file-for-misconfigurations) to identify any conflicting directives.