Skip to content

Add ChromeOS device identity certificates tutorial - #545

Open
llewis1234 wants to merge 16 commits into
smallstep:mainfrom
llewis1234:docs/chromeos-device-identity-certificates
Open

Add ChromeOS device identity certificates tutorial#545
llewis1234 wants to merge 16 commits into
smallstep:mainfrom
llewis1234:docs/chromeos-device-identity-certificates

Conversation

@llewis1234

@llewis1234 llewis1234 commented Aug 1, 2026

Copy link
Copy Markdown

Summary

  • New tutorial covering issuing mTLS-capable device identity certificates to ChromeOS devices (Devices/Accounts authority, ACME Device Attestation, trust distribution, forced re-enrollment, verification, troubleshooting)
  • Extends the Google Workspace integration guide with the Chrome Verified Access API setup, verifiedaccess OAuth scope, Verified Access Mode config, and ChromeOS extension deployment steps that the new tutorial depends on
  • Cross-links from the agent troubleshooting doc and adds the new tutorial to the nav manifest

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
  • Visual preview via the docs renderer (not yet done — recommend before merge)

🤖 Generated with Claude Code

@llewis1234
llewis1234 requested a review from a team as a code owner August 1, 2026 07:27
@CLAassistant

CLAassistant commented Aug 1, 2026 •
edited
Loading

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@llewis1234 llewis1234 mentioned this pull request Aug 1, 2026
Draft
3 tasks
@llewis1234

llewis1234 commented Aug 1, 2026

Copy link
Copy Markdown
Author

Follow-up ready and waiting: #546 (ChromeOS Wi-Fi enrollment via ACME Device Attestation) is stacked on this branch and opened as a draft. It's blocked on this PR merging — once this lands, #546's diff will collapse to just its own changes and it'll be ready for review.

@llewis1234
llewis1234 force-pushed the docs/chromeos-device-identity-certificates branch from 85b3fd9 to ed0795a Compare August 1, 2026 07:37
hslatman
hslatman reviewed Aug 2, 2026
View reviewed changes
Comment thread tutorials/chromeos-device-identity-certificates.mdx Outdated
Comment thread tutorials/chromeos-device-identity-certificates.mdx Outdated
Comment thread tutorials/chromeos-device-identity-certificates.mdx Outdated
Comment thread tutorials/chromeos-device-identity-certificates.mdx Outdated
Comment thread tutorials/chromeos-device-identity-certificates.mdx
Comment thread tutorials/chromeos-device-identity-certificates.mdx Outdated
Comment thread tutorials/chromeos-device-identity-certificates.mdx
Comment thread tutorials/chromeos-device-identity-certificates.mdx Outdated
Comment thread tutorials/connect-google-workspace-to-smallstep.mdx Outdated
hslatman and others added 15 commits August 2, 2026 16:07
@hslatman @llewis1234
Add Google Workspace WIF integration docs
09b6e94
@hslatman @llewis1234
Use sts.googleapis.com as audience in Google Workspace WIF
28081f9 
Also specify the numeric GCP project ID to be used.
@hslatman @llewis1234
Ignore https://container.googleapis.com` in link checker
0fbecca
@hslatman @llewis1234
Add Verified Access API to prerequisites
4586a4a
@hslatman @llewis1234
Fix JSON markup
a61822d
@hslatman @llewis1234
Ignore ../verifiedaccess.googleapis.com in URL checker
3fbdd05
@hslatman @llewis1234
Update k8s_sa attribute
68fa44a
@llewis1234
Add ChromeOS device identity certificates tutorial
28296ea 
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.
@llewis1234
Cross-link ChromeOS troubleshooting to setup and cert-identity docs
2e60373
@llewis1234
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
Address review feedback on device identity certificate behavior
8d96c02 
- 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.
@llewis1234
Stop naming the attestation certificate as a user-facing concept
e5fbfda 
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).
@llewis1234
Reframe Step 1 as confirming, not self-service choosing
ef3a33a 
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).
@llewis1234
Clarify when forcing a fresh enrollment is actually needed
31618a7 
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).
@llewis1234
Fix unescaped <team-slug> placeholder breaking MDX compilation
bcad58b 
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.
@llewis1234
llewis1234 force-pushed the docs/chromeos-device-identity-certificates branch from ed0795a to bcad58b Compare August 2, 2026 21:55
@llewis1234
Finish the incomplete Installation URL sentence
e9f5348 
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.
@llewis1234

llewis1234 commented Aug 5, 2026

Copy link
Copy Markdown
Author

All inline feedback addressed:

  • Attestation certificate removed as a user-facing concept (L8/L27) — it's now just "the certificate," no comparison table
  • Step 1 reframed from "choose an authority" to "confirm your issuing authority," since this is normally set up together with a Smallstep contact rather than self-service (L39)
  • Corrected the trust-distribution failure description — the extension does retry in the background, it just doesn't surface that to the admin (L48)
  • Downgraded the curl verification tip to info severity, clarified it runs from your own machine, not the Chromebook (L43)
  • Clarified devices_ca_directory_url is only needed for the Accounts authority or a non-default Devices setup — not required by default (L72)
  • Fixed a related bug this surfaced: the default-authority path was pointing readers to skip to the wrong step (Step 4 instead of Step 5)
  • Clarified Step 4 (force re-enrollment) only applies when Step 3's policy actually changed on an already-enrolled device — never on first-time setup, which answers the "specific use case" question (L65)
  • Corrected the dashboard-gap explanation — it's a known gap in the ChromeOS extension today, unrelated to ACME vs. SCEP (L91)
  • Rebased onto herman/chromeos-wif per our Slack conversation (L2)

Ready for review whenever you get a chance.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@hslatman hslatman hslatman left review comments
@tashian tashian tashian approved these changes

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@llewis1234 @CLAassistant @tashian @hslatman