Add ChromeOS Wi-Fi enrollment via ACME Device Attestation by llewis1234 · Pull Request #546 · smallstep/docs

llewis1234 · 2026-08-01T07:29:21Z

Summary

Adds a "ChromeOS with Google Workspace (ACME Device Attestation)" section to the wireless networks guide, covering RADIUS server config, the EAP-TLS Wi-Fi network setup in Google Admin, setting the issuer pattern, and verification/troubleshooting
Replaces the old inline Wi-Fi certificate auto-selection steps in the browser certificate setup guide with a pointer to the new section, since the two now depend on the same underlying device identity certificate

Blocked on #545 — this branch is stacked on top of it, so the diff below currently includes #545's changes too. Once #545 merges, this diff will automatically collapse down to just this PR's own changes and it'll be ready for review. Opening now as a draft so it's visible and trackable rather than sitting only in my fork.

Test plan

vale run against changed files (noise-filtered against house style — no unaddressed findings)
markdown-link-check run against changed files — all internal/external links resolve once Add ChromeOS device identity certificates tutorial #545 is merged
Visual preview via the docs renderer (not yet done — recommend before merge)

🤖 Generated with Claude Code

CLAassistant · 2026-08-01T07:29:28Z

All committers have signed the CLA.

hslatman · 2026-08-02T09:25:11Z

+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.


— not through an MDM profile push, and not through Smallstep's Wi-Fi or credential resources described above. can be removed.

hslatman · 2026-08-02T10:14:58Z

+
+<Alert severity="info" mb={4}>
+<div>
+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.


Eventually we'll want these resources to still be created, so that the ChromeOS agent can get a full configuration, with more use cases automatically handled. We'll have to ensure that we have docs on root distribution for all use cases configured for ChromeOS.

Oh, interesting. I understand why a credential might be valuable for this, but is the extension also going to be capable of taking over Wi-Fi or VPN config settings?

hslatman · 2026-08-02T10:18:24Z

+
+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.


Or no cert issued at all, which can have a few causes.

hslatman · 2026-08-02T10:19:04Z

+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.


I believe just the root is sufficient. The ChromeOS EAP-TLS handshake includes the client intermediate.

Also specify the numeric GCP project ID to be used.

Rebased onto herman/chromeos-wif — drops the Verified Access Mode and extension deployment steps that PR previously added, since that PR now covers the same ground as part of its Workload Identity Federation rewrite of the Google Workspace connection flow.

By default the extension only gets a short-lived attestation certificate, not a usable device identity certificate — point readers to the next step.

- The trust-distribution failure isn't a dead end: the extension retries in the background, it's just that nothing surfaces the retry or the failure to an admin. - Downgrade the curl verification tip to info severity, and clarify it runs from the admin's own machine, not the Chromebook. - devices_ca_directory_url isn't required for the default Devices authority — only needed for Accounts or a non-default Devices setup. - The dashboard not showing the device identity cert is a known gap in the ChromeOS extension, not related to ACME vs. SCEP (ChromeOS doesn't use SCEP at all). Per Herman's review comments on smallstep#545.

It's an implementation detail readers don't need: the ACME Device Attestation exchange issues it automatically, and it's never usable for mTLS or exposed in Certificate Manager. Keep the one practically useful fact (a freshly enrolled device isn't immediately mTLS-ready) without explaining why. Per Herman's review comments on smallstep#545 (L8, L27).

The authority is normally set up together with a Smallstep contact during onboarding, not picked independently from an open menu — this was overstating the current self-service reality. Per Herman's review comment on smallstep#545 (L39).

Fix a bug: the default-authority path was pointing readers to skip to Step 4 (force re-enrollment), when there's nothing to force if no policy changed — it should skip straight to Step 5 (verify). Step 4 itself only applies when Step 3's policy change happens on a device that's already enrolled with a valid certificate (e.g. switching authorities later) — never on first-time setup. Per Herman's review comment on smallstep#545 (L77).

A bare <team-slug> in prose (outside code formatting) is parsed as an unclosed JSX tag, which fails MDX compilation for the whole page. Wrap it in backticks like every other placeholder in this doc. This is pre-existing content from smallstep#528 (herman/chromeos-wif), not introduced here — flagged separately on that PR.

- 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 smallstep#546.

tashian · 2026-08-03T17:37:02Z

+14. Scroll down in the side panel details, and ensure the installation URL is set to ...
+15. Set the **Update URL** to **Installation URL (see above)**


We're missing a URL here.
For step 15, is the UI for Update URL a dropdown with an "Installation URL (see above)" option?
I believe Herman's notion page has the installation URL, it's probably a https://packages.smallstep.com or https://release.smallstep.com URL.

tashian · 2026-08-03T17:40:25Z

+5. Click **Continue**
+6. Select **OpenID Connect (OIDC)** as the provider
+7. Set a name, e.g. "Smallstep Google Workspace Sync"
+8. Set the issuer URL to **https://container.googleapis.com/v1/projects/prod-us-central1-e5bd/locations/us-central1/clusters/primary**


Is there any way to get a cleaner issuer URL?
(I think the answer is no, because it's a Google token and a Google URL...)

@hslatman Just a half-formed thought here: would it be worth the effort or even valuable at all to have a separate GCP project that acts as issuer for this? Maybe something branded, and that can be differentiated from the prod tenant.

tashian · 2026-08-03T17:49:35Z

+
+#### 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).


I don't think you can run freeradius on a Chromebook?

Step 14 trailed off with no actual value. Confirmed via live testing in Google Admin: the Installation URL field is a plain textbox that already mirrors the custom URL set in step 7, and the Update URL dropdown in step 15 genuinely does offer "Installation URL (see above)" as a literal option, so step 15 needed no change. Per Carl's review comment on smallstep#545.

- 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 smallstep#546.

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 smallstep#546.

llewis1234 mentioned this pull request Aug 1, 2026

Add ChromeOS device identity certificates tutorial #545

Open

3 tasks

llewis1234 force-pushed the docs/chromeos-wifi-enrollment branch from d79ea11 to 0b3c143 Compare August 1, 2026 07:37

hslatman reviewed Aug 2, 2026

View reviewed changes

hslatman and others added 15 commits August 2, 2026 16:07

Add Google Workspace WIF integration docs

09b6e94

Use sts.googleapis.com as audience in Google Workspace WIF

28081f9

Also specify the numeric GCP project ID to be used.

Ignore https://container.googleapis.com` in link checker

0fbecca

Add Verified Access API to prerequisites

4586a4a

Fix JSON markup

a61822d

Ignore ../verifiedaccess.googleapis.com in URL checker

3fbdd05

Update k8s_sa attribute

68fa44a

Cross-link ChromeOS troubleshooting to setup and cert-identity docs

2e60373

Link to the device identity certificates tutorial from Confirmation

32c1996

By default the extension only gets a short-lived attestation certificate, not a usable device identity certificate — point readers to the next step.

llewis1234 force-pushed the docs/chromeos-wifi-enrollment branch from 0b3c143 to 3c51717 Compare August 2, 2026 21:55

tashian requested changes Aug 3, 2026

View reviewed changes

llewis1234 and others added 6 commits August 3, 2026 15:57

Add ChromeOS Wi-Fi enrollment via ACME Device Attestation

07914be

Use consistent same-directory link style for wireless-networks reference

95f79a5

Some suggested updates

e10033c

llewis1234 force-pushed the docs/chromeos-wifi-enrollment branch from 1493482 to e10033c Compare August 3, 2026 21:04

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add ChromeOS Wi-Fi enrollment via ACME Device Attestation - #546

Add ChromeOS Wi-Fi enrollment via ACME Device Attestation#546
llewis1234 wants to merge 21 commits into
smallstep:mainfrom
llewis1234:docs/chromeos-wifi-enrollment

llewis1234 commented Aug 1, 2026

Uh oh!

CLAassistant commented Aug 1, 2026 •

edited

Loading

Uh oh!

hslatman Aug 2, 2026

Uh oh!

hslatman Aug 2, 2026

Uh oh!

tashian Aug 3, 2026

Uh oh!

hslatman Aug 2, 2026

Uh oh!

hslatman Aug 2, 2026

Uh oh!

tashian Aug 3, 2026

Uh oh!

tashian Aug 3, 2026

Uh oh!

tashian Aug 3, 2026

Uh oh!

tashian Aug 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

		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.


		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.

		14. Scroll down in the side panel details, and ensure the installation URL is set to ...
		15. Set the Update URL to Installation URL (see above)


		#### 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).

Uh oh!

Conversation

llewis1234 commented Aug 1, 2026

Summary

Test plan

Uh oh!

CLAassistant commented Aug 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

CLAassistant commented Aug 1, 2026 •

edited

Loading