Skip to content
New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

#

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Browser client cert documentation #391

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Browser client cert documentation #391

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
cb9eddc
Beginning of a browser cert guide
tashian Mar 17, 2025
58dccad
Updates
tashian Mar 17, 2025
56efaca
Add Linux
tashian Mar 17, 2025
f720d59
More updates
tashian Mar 20, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions manifest.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,6 +54,15 @@
}
]
},
{
"title": "Configure Devices for Smallstep",
"routes": [
{
"title": "Configure Browser Certificates",
"path": "/tutorials/browser-certificate-setup-guide.mdx"
}
]
},
{
"title": "Smallstep for WPA-Enterprise Wi-Fi",
"routes": [
Expand Down
237 changes: 237 additions & 0 deletions tutorials/browser-certificate-setup-guide.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,237 @@
---
title: Configure Web Browser Certificates
updated_at: March 20, 2025
html_title: Configure your web browsers to use Smallstep hardware-bound device identtiy certificates.
description: This tutorial describes how to set up web browsers to access resources using mutual TLS and Smallstep certificates.
---

## Before we begin

Certificate-based authentication in web browsers
offers excellent security characteristics, thanks to mutual TLS.
However, the user experience has traditionally been poor,
with mysterious certificate errors,
confusing certificate selector dialogs,
and differing behaviors between browsers.

Smallstep addresses these issues
by keeping certificates renewed,
offering simple remediation flows when an error occurs,
and ensuring that web browers 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.

To prepare an device to use browser client certificates from Smallstep:
1. The device should be [added to Smallstep](https://smallstep.com/docs/platform/enrollment-guide/).
2. A protected resource that uses browser certificates should be added to Smallstep. This could be a Browser resource, or the Smallstep Device IdP integration (eg. Smallstep for Okta).

## macOS

For this tutorial, we'll assume you're using Jamf Pro as your MDM.
The steps are very similar for other MDMs, however.

### Firefox

#### Client certificate auto-selection

A [configuration profile](https://support.mozilla.org/en-US/kb/customizing-firefox-macos-using-configuration-prof) can be used to set Firefox's certificate preferences
so that the Smallstep certificate is automatically selected
when a protected resource is accessed.

1. In Jamf, navigate to **Computers > Configuration Profiles**
2. Create a new Configuration Profile and find the **Application & Custom Settings** > **Upload** page.
3. For Preference Domain, specify `org.mozilla.firefox`.
4. Create a plist file called `org.mozilla.firefox.plist`, and populate it with the following:

```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>EnterprisePoliciesEnabled</key>
<true/>
<key>PayloadDisplayName</key>
<string>Firefox ESR Policies</string>
<key>PayloadEnabled</key>
<true/>
<key>PayloadIdentifier</key>
<string>org.mozilla.firefox.BCADDC78-843E-4112-936A-DAB8EEEF514C</string>
<key>PayloadType</key>
<string>org.mozilla.firefox</string>
<key>PayloadUUID</key>
<string>BCADDC78-843E-4112-936A-DAB8EEEF514C</string>
<key>PayloadVersion</key>
<integer>1</integer>
<key>Preferences</key>
<dict>
<key>security.default_personal_cert</key>
<string>Select Automatically</string>
<key>security.osclientcerts.autoload</key>
<true/>
</dict>
</dict>
</plist>
```
5. Upload the plist file to Jamf.
6. Deploy the configuration profile to your test device.

To test the certificate, visit `https://accounts.ca.[team-id].smallstep.com/-/hello-mtls`. You can find your Team ID in [Team Settings](https://smallstep.com/app/?next=/settings/team).

### Chrome

#### Authority configuration


#### Client certificate auto-selection

A [configuration profile](https://support.google.com/chrome/a/answer/9020077?hl=en) can be used to set Chrome's certificate preferences
so that the Smallstep certificate is automatically selected
when a protected resource is accessed.

1. In Jamf, navigate to **Computers > Configuration Profiles**
2. Create a new Configuration Profile and find the **Application & Custom Settings** > **Upload** page.
3. For Preference Domain, specify `com.google.Chrome`.
4. Create a plist file called `com.google.Chrome.plist`, and populate it with the following:

```
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>AutoSelectCertificateForUrls</key>
<array>
<dict>
<key>pattern</key>
<string>[Server URL]</string>
<key>filter</key>
<dict>
<key>ISSUER</key>
<dict>
<key>CN</key>
<string>Smallstep Accounts Intermediate CA</string>
</dict>
</dict>
</dict>
</array>
</dict>
</plist>
```

Replace `[Server URL]` with the server that requires certificate authentication.
This field is an [Enterprise policy URL pattern](https://chromeenterprise.google/policies/url-patterns/).

Note: According to [Understand Chrome policy management](https://support.google.com/chrome/a/answer/9037717),
Chrome will *not* merge multiple `AutoSelectCertificateForUrls` policies.
You must add all of your certificate selection preferences into a single managed configuration profile.

5. Upload the plist file to Jamf.
6. Deploy the configuration profile to a test device.
7. On the device, restart Chrome and visit the [policies tab](chrome://policy/) to verify the applied policy.

To test the certificate, visit `https://accounts.ca.[team-id].smallstep.com/-/hello-mtls`. You can find your Team ID in [Team Settings](https://smallstep.com/app/?next=/settings/team).

### Safari

#### Authority configuration

Safari will trust CA certificates in Keychain Access, as long as their trust setting for SSL is turned on.
The easiest way to deploy a trusted CA to a fleet of Apple devices is via MDM.

#### Client certificate auto-selection

Safari relies on the Keychain and system-level certificate trust settings, rather than per-app policies like Chrome and Firefox. Certificate selection in Safari is mostly automatic, but it may prompt the user if multiple matching client certificates exist. Smallstep's agent will set identity preferences as needed.

To test the certificate, visit `https://accounts.ca.[team-id].smallstep.com/-/hello-mtls`. You can find your Team ID in [Team Settings](https://smallstep.com/app/?next=/settings/team).

## Linux


### Google Chrome

#### Authority configuration

Since Chrome trusts the Linux system trust store, we need to install the root CA certificate there.

1. Copy your root CA certificate to the trusted location:

For Debian/Ubuntu:

```
sudo cp your-root-ca.crt /usr/local/share/ca-certificates/your-root-ca.crt
```

For RHEL/CentOS/Fedora:

```
sudo cp your-root-ca.crt /etc/pki/ca-trust/source/anchors/your-root-ca.crt
```

2. Update the system CA store:

Debian/Ubuntu:

```
sudo update-ca-certificates
```

RHEL/CentOS/Fedora:

```
sudo update-ca-trust
```

3. Restart your web browser

Chrome trusts CA certificates installed in the system CA store.

#### Client certificate auto-selection

We can use the [AutoSelectCertificateForUrls](https://chromeenterprise.google/policies/?policy=AutoSelectCertificateForUrls) Chrome policy to automatically select the client certificate without presenting a dialog:
1. As root, create a policy file: `/etc/opt/chrome/policies/managed/auto_select_cert.json`
2. Add the following content:

```
{
"AutoSelectCertificateForUrls": ["{\"pattern\":${url},\"filter\":{\"ISSUER\":{\"CN\":\"Smallstep Accounts Intermediate CA\"}}}"]
}
```

Replace `${url}` with the server that requires certificate authentication.
For example:

```json
{
"AutoSelectCertificateForUrls": ["{\"pattern\":\"https://example.id.smallstep.com\",\"filter\":{\"ISSUER\":{\"CN\":\"Smallstep Accounts Intermediate CA\"}}}"]
}
```

3. Restart Chrome, and visit the [policies tab](chrome://policy/) to verify the applied policy.

Finally, let's verify that the user has a client certificate from the Smallstep agent.
1. Run `certutil -d sql:$HOME/.pki/nssdb -L`. You should see `Smallstep Accounts Intermediate CA` in the list.
2. Restart Chrome, and verify that the client certificate is in <a href="chrome://settings/certificates">Chrome's Certificate Manager</a>
Don't see it? Check that the Smallstep agent is installed correctly.

To test the certificate, visit `https://accounts.ca.[team-id].smallstep.com/-/hello-mtls`. You can find your Team ID in [Team Settings](https://smallstep.com/app/?next=/settings/team).

### Firefox

#### Authority configuration

Firefox has its own trust store for CAs.

To install the root CA certificate, run:

```
step certificate install root_ca.crt --firefox
```

To confirm root CA trust, restart Firefox and visit <a href="about:certificate">about:certificate</a>. Navigate to the Authorities tab. `Smallstep Accounts Intermediate CA` should be listed there.

#### Client certificate auto-selection

Use the <a href="about:certificate">about:certificate</a> URL to see all of the client certificates installed in Firefox's certificate database.

To test the certificate, visit `https://accounts.ca.[team-id].smallstep.com/-/hello-mtls`. You can find your Team ID in [Team Settings](https://smallstep.com/app/?next=/settings/team).