diff --git a/tutorials/browser-certificate-setup-guide.mdx b/tutorials/browser-certificate-setup-guide.mdx index 368e0a4f..a59876bf 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,67 @@ 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. +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. + +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. +