From b0072cf510a9b08cfc8982cccb4cf3ecef6bbd5c Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Wed, 20 May 2026 15:20:03 -0700 Subject: [PATCH 1/2] Document automatic certificate selection in Chrome on ChromeOS Closes CON-263 Co-Authored-By: Claude Opus 4.7 (1M context) --- tutorials/browser-certificate-setup-guide.mdx | 69 ++++++++++++++++++- 1 file changed, 68 insertions(+), 1 deletion(-) diff --git a/tutorials/browser-certificate-setup-guide.mdx b/tutorials/browser-certificate-setup-guide.mdx index 368e0a4f..4d9914d6 100644 --- a/tutorials/browser-certificate-setup-guide.mdx +++ b/tutorials/browser-certificate-setup-guide.mdx @@ -20,7 +20,7 @@ offering simple remediation flows when an error occurs, and ensuring that web browsers are configured to find client certificates automatically, so the user can have a seamless experience. -Smallstep browser certificates are available for macOS, Windows, and Linux devices. +Smallstep browser certificates are available for macOS, Windows, Linux, and ChromeOS devices. ## Before you begin @@ -216,3 +216,70 @@ Use the about:certificate URL to see all of the To test the certificate, restart the browser and visit one your target URLs. You should not see any certificate selection dialogs. +## ChromeOS + +On managed Chromebooks, Smallstep certificates are made available to Chrome +by the [Smallstep extension for ChromeOS](https://chromewebstore.google.com/detail/smallstep-agent-for-chrom/khlfhcjblheppjmebghnnfgklpkofbob). +Once the extension is deployed and a client certificate has been issued, +you can configure Chrome to select the certificate automatically. + +Chrome policies are deployed to managed Chromebooks through the +[Google Workspace Admin Console](https://admin.google.com), +so there is no per-device configuration step. + +### Google Chrome + +#### Client certificate auto-selection + +To automatically select the Smallstep client certificate when a user visits a protected URL, +use the [`AutoSelectCertificateForUrls`](https://chromeenterprise.google/policies/?policy=AutoSelectCertificateForUrls) policy. + +1. In the Google Workspace Admin Console, visit **Devices → Chrome → Settings → Users & browsers**. +2. Choose the organizational unit you want to apply the policy to. +3. Find the **Client certificates** section and locate **Auto-select client certificate for these sites**. +4. Add an entry for each protected URL, in the following format: + + ```json + {"pattern":"[Server URL pattern]","filter":{"ISSUER":{"CN":"Smallstep [Team Slug] Accounts Intermediate CA"}}} + ``` + + Replace `[Server URL pattern]` with the server that requires certificate authentication. + This field is a [Chrome Enterprise policy URL pattern](https://chromeenterprise.google/policies/url-patterns/). + + - Example: `[.*]xample.com` matches `xample.com` and `hello.xample.com` for any scheme, port, and path. It will not match `example.com`. + - For more examples, see [the Chrome Enterprise docs](https://chromeenterprise.google/policies/url-patterns/). + + Replace `[Team Slug]` with your Smallstep team slug. + +5. Save the policy. + +The policy is applied to managed devices the next time they sync with Google Workspace. + +To verify the policy is in effect, open Chrome on a managed Chromebook and visit [chrome://policy](chrome://policy). +Then visit one of your target URLs. +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, +not through `AutoSelectCertificateForUrls`. + +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] Accounts 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. + From 9175ccfb41531c89258ad15b7b04a2e45d440068 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Wed, 20 May 2026 15:25:30 -0700 Subject: [PATCH 2/2] Updates --- tutorials/browser-certificate-setup-guide.mdx | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/tutorials/browser-certificate-setup-guide.mdx b/tutorials/browser-certificate-setup-guide.mdx index 4d9914d6..a59876bf 100644 --- a/tutorials/browser-certificate-setup-guide.mdx +++ b/tutorials/browser-certificate-setup-guide.mdx @@ -219,7 +219,7 @@ You should not see any certificate selection dialogs. ## ChromeOS On managed Chromebooks, Smallstep certificates are made available to Chrome -by the [Smallstep extension for ChromeOS](https://chromewebstore.google.com/detail/smallstep-agent-for-chrom/khlfhcjblheppjmebghnnfgklpkofbob). +by the Smallstep extension for ChromeOS. Once the extension is deployed and a client certificate has been issued, you can configure Chrome to select the certificate automatically. @@ -227,9 +227,7 @@ Chrome policies are deployed to managed Chromebooks through the [Google Workspace Admin Console](https://admin.google.com), so there is no per-device configuration step. -### Google Chrome - -#### Client certificate auto-selection +### Google Chrome client certificate auto-selection 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,11 +257,10 @@ To verify the policy is in effect, open Chrome on a managed Chromebook and visit Then visit one of your target URLs. You should not see any certificate selection dialogs. -#### Wi-Fi client certificate auto-selection (802.1X) +### 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, -not through `AutoSelectCertificateForUrls`. +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.