From 07914be31d51dd7ba2a4cd6ef4b5ddc3b2c3fd86 Mon Sep 17 00:00:00 2001 From: Lucas Date: Sun, 2 Aug 2026 16:09:15 -0500 Subject: [PATCH 1/5] Add ChromeOS Wi-Fi enrollment via ACME Device Attestation --- tutorials/browser-certificate-setup-guide.mdx | 26 ++------ tutorials/protect-wireless-networks.mdx | 61 +++++++++++++++++++ 2 files changed, 67 insertions(+), 20 deletions(-) diff --git a/tutorials/browser-certificate-setup-guide.mdx b/tutorials/browser-certificate-setup-guide.mdx index 032a0c29..c75a2da1 100644 --- a/tutorials/browser-certificate-setup-guide.mdx +++ b/tutorials/browser-certificate-setup-guide.mdx @@ -229,6 +229,9 @@ so there is no per-device configuration step. ### Google Chrome client certificate auto-selection +Prerequisite: complete [Configure ChromeOS Device Identity Certificates](./chromeos-device-identity-certificates.mdx) +first so a client certificate has actually been issued to select. + To automatically select the Smallstep client certificate when a user visits a protected URL, use the [`AutoSelectCertificateForUrls`](https://chromeenterprise.google/policies/?policy=AutoSelectCertificateForUrls) policy. @@ -259,24 +262,7 @@ You should not see any certificate selection dialogs. ### Wi-Fi client certificate auto-selection (802.1X) -For Wi-Fi networks that authenticate with EAP-TLS, -client certificate selection is configured per-network in the Google Workspace Admin Console. - -1. In the Google Workspace Admin Console, visit **Devices → Networks → Wi-Fi**. -2. Edit or create the Wi-Fi network used for 802.1X authentication. -3. Set the **EAP type** to **EAP-TLS**. -4. Set the **Issuer pattern** to the full common name of your Smallstep intermediate issuing CA: - - ``` - Smallstep ([Team Slug]) Devices Intermediate CA - ``` - - Replace `[Team Slug]` with your Smallstep team slug. - -5. Save the network configuration. - -When a Chromebook connects to the network, -it will automatically select the Smallstep client certificate -issued by the matching intermediate CA, -without prompting the user. +Wi-Fi client certificate selection for ChromeOS is now covered in +[ChromeOS with Google Workspace (ACME Device Attestation)](../tutorials/protect-wireless-networks.mdx#chromeos-with-google-workspace-acme-device-attestation), +alongside the RADIUS and access point setup it depends on. diff --git a/tutorials/protect-wireless-networks.mdx b/tutorials/protect-wireless-networks.mdx index d84768f1..b5ea30b3 100644 --- a/tutorials/protect-wireless-networks.mdx +++ b/tutorials/protect-wireless-networks.mdx @@ -365,6 +365,7 @@ The subsections below cover the common combinations: - [Windows with Intune (SCEP)](#windows-with-intune-scep) - [Windows with Intune (agent credential + OMA-URI profile)](#windows-with-intune-agent-credential--oma-uri-profile) - [Windows with Workspace ONE UEM](#windows-with-workspace-one-uem) +- [ChromeOS with Google Workspace (ACME Device Attestation)](#chromeos-with-google-workspace-acme-device-attestation) ### macOS and iOS with Jamf Pro (SCEP) @@ -793,6 +794,66 @@ Workspace ONE UEM can deploy the same WLAN profile XML shown above: 5. Enter the WLAN profile XML in the `Wlan Xml` field 6. Click **Next**, set the assignments as desired, and click **Save and Publish** +### ChromeOS with Google Workspace (ACME Device Attestation) + +ChromeOS devices get their Wi-Fi credential through the **Smallstep extension for ChromeOS**, +using ACME Device Attestation against Google's Chrome Verified Access API — not through an MDM profile push, +and not through Smallstep's Wi-Fi or credential resources described above. + + +
+Skip Step 1 (credential) and the Wi-Fi resource created at the top of Step 3 for ChromeOS. Neither applies here: the client certificate comes from Certificate Manager directly, and the Wi-Fi network profile is delivered by Google Admin rather than by Smallstep. +
+ + +First, complete [Connect Google Workspace to Smallstep](./connect-google-workspace-to-smallstep.mdx) and [Configure ChromeOS Device Identity Certificates](./chromeos-device-identity-certificates.mdx) — the second guide covers deploying the extension and issuing an mTLS-capable device identity certificate, which is a prerequisite for everything below. + +#### Configure your RADIUS server + +Choose one of the three options from [Step 2: Configure the enforcement point](#step-2-configure-the-enforcement-point) above — Smallstep Managed RADIUS, Smallstep Enterprise RADIUS, or your own RADIUS server. ChromeOS has no platform-specific requirement here; whichever option you choose, you'll need the resulting `serverCA` (or your own RADIUS server's CA) for the Google Admin Wi-Fi policy below. + +Make sure the RADIUS server's client-facing trust store includes the **root and intermediate** of whichever authority you chose in [Configure ChromeOS Device Identity Certificates](./chromeos-device-identity-certificates.mdx) — that's the chain it needs to verify ChromeOS clients. + +#### Configure the EAP-TLS Wi-Fi network in Google Admin + +1. In the Admin Console, go to **Devices → Networks → Wi-Fi** and select your target Organizational Unit. +2. Click **Add Wi-Fi network** and configure: + + | Field | Value | + |---|---| + | Name | Your Wi-Fi network SSID | + | Security type | WPA/WPA2 Enterprise | + | EAP method | EAP-TLS | + | EAP Identity | `${DEVICE_ASSET_ID}` or `${USER_EMAIL}`, depending on which authority you chose | + | Issuer pattern → Common name | See below | + | CA certificate | Your RADIUS server's CA (`serverCA` from above) — upload it first under **Devices → Networks → Certificates** | + +#### Set the issuer pattern + +The issuer pattern tells ChromeOS which client certificate to present. It must match the exact common name of the intermediate CA you configured in [Configure ChromeOS Device Identity Certificates](./chromeos-device-identity-certificates.mdx): + +``` +Smallstep () Devices Intermediate CA +``` + +(or `Accounts Intermediate CA` if you chose that authority instead.) Leave **Locality**, **Organization**, and **Organizational unit** empty, and leave **Subject pattern** empty entirely — Smallstep's device certificates don't set those fields, and any value there will prevent a match. + + +
+Don't guess this value — read it directly off an issued certificate at chrome://certificate-manager/clientcerts/platformclientcerts → open the certificate → Details → Issuer. A mismatched issuer pattern produces "Error configuring network" on the device with zero RADIUS traffic generated — the device fails before it ever associates, which looks identical to an access-point or RADIUS problem but isn't one. +
+ + +#### Verify + +On the Chromebook, the configured network should appear and connect automatically with no password prompt. If you're running your own RADIUS server, a foreground `freeradius -X` (or equivalent verbose mode) session will show the full handshake, including a two-certificate chain (device leaf + issuing intermediate). + +If it doesn't connect: + +- **No RADIUS traffic at all** — the device never associated. This is always a client-side certificate selection failure; recheck the issuer pattern above, not the network or access point. +- **`unknown CA` / `unable to get local issuer certificate`** — the RADIUS server's trust store is missing the issuing authority's root or intermediate. +- **The certificate being presented has the wrong issuer** — confirm [Configure ChromeOS Device Identity Certificates](./chromeos-device-identity-certificates.mdx) was completed and the device was rebooted after re-enrollment; a device can continue presenting a stale certificate until it restarts. + # Verify and troubleshoot To verify the end-to-end setup, join the network with a test device and confirm it authenticates. From 95f79a558c1edd067b9af1bfe05414461c8f05b2 Mon Sep 17 00:00:00 2001 From: Lucas Date: Sun, 2 Aug 2026 16:09:22 -0500 Subject: [PATCH 2/5] Use consistent same-directory link style for wireless-networks reference --- tutorials/browser-certificate-setup-guide.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/browser-certificate-setup-guide.mdx b/tutorials/browser-certificate-setup-guide.mdx index c75a2da1..3631c316 100644 --- a/tutorials/browser-certificate-setup-guide.mdx +++ b/tutorials/browser-certificate-setup-guide.mdx @@ -263,6 +263,6 @@ You should not see any certificate selection dialogs. ### Wi-Fi client certificate auto-selection (802.1X) Wi-Fi client certificate selection for ChromeOS is now covered in -[ChromeOS with Google Workspace (ACME Device Attestation)](../tutorials/protect-wireless-networks.mdx#chromeos-with-google-workspace-acme-device-attestation), +[ChromeOS with Google Workspace (ACME Device Attestation)](./protect-wireless-networks.mdx#chromeos-with-google-workspace-acme-device-attestation), alongside the RADIUS and access point setup it depends on. From ae854966a12b76b88ded39f7d12192eb608c4c5a Mon Sep 17 00:00:00 2001 From: Lucas Date: Sun, 2 Aug 2026 16:13:20 -0500 Subject: [PATCH 3/5] Address review feedback on ChromeOS Wi-Fi setup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Trim the redundant "not through MDM/Smallstep resources" clause. - Trust store only needs the authority's root — ChromeOS's EAP-TLS handshake already includes the client intermediate. - "No RADIUS traffic" isn't always a certificate-selection failure; it can also mean no device identity certificate was issued at all. Per Herman's review comments on #546. --- tutorials/protect-wireless-networks.mdx | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/tutorials/protect-wireless-networks.mdx b/tutorials/protect-wireless-networks.mdx index b5ea30b3..ef2d222e 100644 --- a/tutorials/protect-wireless-networks.mdx +++ b/tutorials/protect-wireless-networks.mdx @@ -797,8 +797,7 @@ Workspace ONE UEM can deploy the same WLAN profile XML shown above: ### ChromeOS with Google Workspace (ACME Device Attestation) ChromeOS devices get their Wi-Fi credential through the **Smallstep extension for ChromeOS**, -using ACME Device Attestation against Google's Chrome Verified Access API — not through an MDM profile push, -and not through Smallstep's Wi-Fi or credential resources described above. +using ACME Device Attestation against Google's Chrome Verified Access API.
@@ -812,7 +811,7 @@ First, complete [Connect Google Workspace to Smallstep](./connect-google-workspa Choose one of the three options from [Step 2: Configure the enforcement point](#step-2-configure-the-enforcement-point) above — Smallstep Managed RADIUS, Smallstep Enterprise RADIUS, or your own RADIUS server. ChromeOS has no platform-specific requirement here; whichever option you choose, you'll need the resulting `serverCA` (or your own RADIUS server's CA) for the Google Admin Wi-Fi policy below. -Make sure the RADIUS server's client-facing trust store includes the **root and intermediate** of whichever authority you chose in [Configure ChromeOS Device Identity Certificates](./chromeos-device-identity-certificates.mdx) — that's the chain it needs to verify ChromeOS clients. +Make sure the RADIUS server's client-facing trust store includes the **root** of whichever authority you chose in [Configure ChromeOS Device Identity Certificates](./chromeos-device-identity-certificates.mdx) — ChromeOS's EAP-TLS handshake already includes the client intermediate, so the root alone is sufficient. #### Configure the EAP-TLS Wi-Fi network in Google Admin @@ -850,7 +849,7 @@ On the Chromebook, the configured network should appear and connect automaticall If it doesn't connect: -- **No RADIUS traffic at all** — the device never associated. This is always a client-side certificate selection failure; recheck the issuer pattern above, not the network or access point. +- **No RADIUS traffic at all** — the device never associated. This is a client-side problem, not the network or access point: either a certificate selection failure (recheck the issuer pattern above) or no device identity certificate was issued at all — confirm [Configure ChromeOS Device Identity Certificates](./chromeos-device-identity-certificates.mdx) actually completed successfully. - **`unknown CA` / `unable to get local issuer certificate`** — the RADIUS server's trust store is missing the issuing authority's root or intermediate. - **The certificate being presented has the wrong issuer** — confirm [Configure ChromeOS Device Identity Certificates](./chromeos-device-identity-certificates.mdx) was completed and the device was rebooted after re-enrollment; a device can continue presenting a stale certificate until it restarts. From 288178240c81bc394702fd1f6006165d3a458593 Mon Sep 17 00:00:00 2001 From: Lucas Date: Mon, 3 Aug 2026 15:50:09 -0500 Subject: [PATCH 4/5] Remove the freeradius -X troubleshooting tip MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Homelab-specific advice from testing this setup — not realistic guidance for enterprise customers, who won't be running their own FreeRADIUS server. Also addresses the ambiguity Carl flagged about whether this implied running freeradius on the Chromebook itself. Per Carl's review comment on #546. --- tutorials/protect-wireless-networks.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tutorials/protect-wireless-networks.mdx b/tutorials/protect-wireless-networks.mdx index ef2d222e..05697327 100644 --- a/tutorials/protect-wireless-networks.mdx +++ b/tutorials/protect-wireless-networks.mdx @@ -845,7 +845,7 @@ Don't guess this value — read it directly off an issued certificate at c #### Verify -On the Chromebook, the configured network should appear and connect automatically with no password prompt. If you're running your own RADIUS server, a foreground `freeradius -X` (or equivalent verbose mode) session will show the full handshake, including a two-certificate chain (device leaf + issuing intermediate). +On the Chromebook, the configured network should appear and connect automatically with no password prompt. If it doesn't connect: From e10033cd2346edaeb738ff28ffce12c413563b63 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Mon, 3 Aug 2026 10:51:04 -0700 Subject: [PATCH 5/5] Some suggested updates --- tutorials/protect-wireless-networks.mdx | 40 ++++++++++++++----------- 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/tutorials/protect-wireless-networks.mdx b/tutorials/protect-wireless-networks.mdx index 05697327..2a4a3c99 100644 --- a/tutorials/protect-wireless-networks.mdx +++ b/tutorials/protect-wireless-networks.mdx @@ -80,8 +80,9 @@ the configuration Smallstep uses to issue a Wi-Fi client certificate to each of
If all of your clients will be MDM-managed (using SCEP or ACME Device Attestation to get certificates), - you can skip to Step 2. - A credential resource is only needed for agent-managed clients. + please skip to Step 2. + A credential resource is only needed for macOS, Windows, or Linux clients managed by the Smallstep agent. + ChromeOS clients should skip this step, too.
@@ -315,6 +316,14 @@ so that clients trust your server during the EAP-TLS handshake. Now that certificates are being issued and the RADIUS server is running, create the **Wi-Fi resource** that describes the network to your clients. + +
+ **Deploying to ChromeOS?**
+ Wi-Fi settings for ChromeOS clients are managed inside Google Workspace. + Skip this section and continue at [ChromeOS with Google Workspace (ACME Device Attestation)](#chromeos-with-google-workspace-acme-device-attestation). +
+ + Use the [Create Wi-Fi](https://gateway.smallstep.com/v2025-01-01/operations/PostWifi) endpoint: ```bash @@ -797,21 +806,20 @@ Workspace ONE UEM can deploy the same WLAN profile XML shown above: ### ChromeOS with Google Workspace (ACME Device Attestation) ChromeOS devices get their Wi-Fi credential through the **Smallstep extension for ChromeOS**, -using ACME Device Attestation against Google's Chrome Verified Access API. +using ACME Device Attestation against the Chrome Verified Access API. - -
-Skip Step 1 (credential) and the Wi-Fi resource created at the top of Step 3 for ChromeOS. Neither applies here: the client certificate comes from Certificate Manager directly, and the Wi-Fi network profile is delivered by Google Admin rather than by Smallstep. -
- +#### Before you begin + +This guide covers deploying the Smallstep ChromeOS extension and issuing a device identity certificate on your endpoints. -First, complete [Connect Google Workspace to Smallstep](./connect-google-workspace-to-smallstep.mdx) and [Configure ChromeOS Device Identity Certificates](./chromeos-device-identity-certificates.mdx) — the second guide covers deploying the extension and issuing an mTLS-capable device identity certificate, which is a prerequisite for everything below. +First, complete the steps in [Connect Google Workspace to Smallstep](./connect-google-workspace-to-smallstep.mdx) and [Configure ChromeOS Device Identity Certificates](./chromeos-device-identity-certificates.mdx). -#### Configure your RADIUS server +Second, you will need your RADIUS server details, including: +- The CA certificate that issued your RADIUS server certificate. -Choose one of the three options from [Step 2: Configure the enforcement point](#step-2-configure-the-enforcement-point) above — Smallstep Managed RADIUS, Smallstep Enterprise RADIUS, or your own RADIUS server. ChromeOS has no platform-specific requirement here; whichever option you choose, you'll need the resulting `serverCA` (or your own RADIUS server's CA) for the Google Admin Wi-Fi policy below. +#### Configure RADIUS server trust -Make sure the RADIUS server's client-facing trust store includes the **root** of whichever authority you chose in [Configure ChromeOS Device Identity Certificates](./chromeos-device-identity-certificates.mdx) — ChromeOS's EAP-TLS handshake already includes the client intermediate, so the root alone is sufficient. +If you're using an external RADIUS server, make sure your RADIUS server's client certificate trust configuration includes the **root** of whichever authority you chose in [Configure ChromeOS Device Identity Certificates](./chromeos-device-identity-certificates.mdx). ChromeOS's EAP-TLS handshake includes the client intermediate, so the root alone is sufficient. #### Configure the EAP-TLS Wi-Fi network in Google Admin @@ -835,13 +843,9 @@ The issuer pattern tells ChromeOS which client certificate to present. It must m Smallstep () Devices Intermediate CA ``` -(or `Accounts Intermediate CA` if you chose that authority instead.) Leave **Locality**, **Organization**, and **Organizational unit** empty, and leave **Subject pattern** empty entirely — Smallstep's device certificates don't set those fields, and any value there will prevent a match. +Or use `Smallstep () Accounts Intermediate CA` if you chose that authority. - -
-Don't guess this value — read it directly off an issued certificate at chrome://certificate-manager/clientcerts/platformclientcerts → open the certificate → Details → Issuer. A mismatched issuer pattern produces "Error configuring network" on the device with zero RADIUS traffic generated — the device fails before it ever associates, which looks identical to an access-point or RADIUS problem but isn't one. -
- +Replace `` with your Smallstep team label . Leave **Locality**, **Organization**, and **Organizational unit** empty, and leave **Subject pattern** empty entirely. Smallstep's device certificates don't set those fields, and any value there will prevent a match. #### Verify