diff --git a/tutorials/browser-certificate-setup-guide.mdx b/tutorials/browser-certificate-setup-guide.mdx index 032a0c29..3631c316 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)](./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..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 @@ -365,6 +374,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 +803,60 @@ 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 the Chrome Verified Access API. + +#### Before you begin + +This guide covers deploying the Smallstep ChromeOS extension and issuing a device identity certificate on your endpoints. + +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). + +Second, you will need your RADIUS server details, including: +- The CA certificate that issued your RADIUS server certificate. + +#### Configure RADIUS server trust + +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 + +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 use `Smallstep () Accounts Intermediate CA` if you chose that authority. + +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 + +On the Chromebook, the configured network should appear and connect automatically with no password prompt. + +If it doesn't connect: + +- **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. + # Verify and troubleshoot To verify the end-to-end setup, join the network with a test device and confirm it authenticates.