Skip to content

Commit 52d1d09

Browse files
tashiantashian
authored
Merge pull request #391 from smallstep/carl/browser-mtls
Browser client cert documentation
2 parents 6533072 + bf944c2 commit 52d1d09

File tree

3 files changed

+244
-8
lines changed

3 files changed

+244
-8
lines changed

‎manifest.json

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,10 +30,6 @@
3030
{
3131
"title": "Smallstep API",
3232
"path": "/platform/smallstep-api.mdx"
33-
},
34-
{
35-
"title": "Smallstep App",
36-
"path": "/platform/smallstep-app.mdx"
3733
}
3834
]
3935
},
@@ -54,6 +50,19 @@
5450
}
5551
]
5652
},
53+
{
54+
"title": "Configure Devices for Smallstep",
55+
"routes": [
56+
{
57+
"title": "Install the Smallstep App",
58+
"path": "/platform/smallstep-app.mdx"
59+
},
60+
{
61+
"title": "Configure Browser Certificates",
62+
"path": "/tutorials/browser-certificate-setup-guide.mdx"
63+
}
64+
]
65+
},
5766
{
5867
"title": "Smallstep for WPA-Enterprise Wi-Fi",
5968
"routes": [

‎platform/smallstep-app.mdx

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,19 @@
11
---
2+
updated_at: April 08, 2025
23
title: The Smallstep App
34
html_title: The Smallstep App
45
description: This document specifies app download links, system requirements, runtime requirements, file permissions, and telemetry data collected for the Smallstep desktop app.
56
---
6-
Smallstep ensures that access to financial data, code repositories, PII, and other sensitive resources is only possible from trusted, company-managed devices.
7+
Smallstep ensures that access to financial data, code repositories, PII, and other sensitive resources is only possible from trusted devices.
78

8-
The Smallstep desktop app is central to that process. It offers a uniform experience for device identity across macOS, Windows, and Linux, and is the foundation for Smallstep's high-assurance device identity attestation workflow, automating the issuance of certificates to devices and configuring the components that depend on these certificates. P.S: The Smallstep app operates differently for Linux. For Linux specific instructions, see [Smallstep Agent for Linux](https://smallstep.com/docs/platform/smallstep-agent).
9+
The Smallstep desktop app offers a uniform experience for device identity across macOS, Windows, and Linux, and is foundational to Smallstep's high-assurance device attestation workflow, automating the enrollment and delivery of client certificates, and configuring the components that depend on them.
910

10-
Here's all the necessary info you need to install and use the Smallstep app effectively and consciously.
11+
The Smallstep app operates differently for Linux. For Linux specific instructions, see [Smallstep Agent for Linux](./smallstep-agent.mdx).
1112

1213
## Download
1314

1415
<Alert severity="info">
15-
The Smallstep App includes the <a href="smallstep-agent.mdx">Smallstep Agent</a>,
16+
The Smallstep App includes the <a href="/docs/platform/smallstep-agent">Smallstep Agent</a>,
1617
which runs in the background.
1718
</Alert>
1819

‎tutorials/browser-certificate-setup-guide.mdx

Lines changed: 226 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,226 @@
1+
---
2+
title: Configure Web Browser Certificates
3+
updated_at: April 09, 2025
4+
html_title: Configure your web browsers to use Smallstep hardware-bound device identtiy certificates.
5+
description: This tutorial describes how to set up web browsers to access resources using mutual TLS and Smallstep certificates.
6+
---
7+
8+
## Before we begin
9+
10+
Certificate-based authentication in web browsers
11+
offers excellent security characteristics, thanks to mutual TLS.
12+
However, the user experience has traditionally been poor,
13+
with mysterious TLS errors,
14+
confusing certificate selection dialogs,
15+
and differing behaviors between browsers.
16+
17+
Smallstep addresses these issues
18+
by keeping certificates renewed,
19+
offering simple remediation flows when an error occurs,
20+
and ensuring that web browers are configured to find client certificates automatically,
21+
so the user can have a seamless experience.
22+
23+
Smallstep browser certificates are available for macOS, Windows, and Linux devices.
24+
25+
## Before you begin
26+
27+
Before you begin, make sure:
28+
29+
1. Your devices are [enrolled into your Smallstep inventory](https://smallstep.com/docs/platform/enrollment-guide/).
30+
2. Someone from [our support team](https://support.smallstep.com/kb-tickets/new) has helped you get set up. Client certificates can be used in several ways. Confirm that your Smallstep team is configured for the resource that you are using client certificates to protect.
31+
32+
You will need a list of URLs that will require a client certificate on your devices.
33+
34+
These URLs will vary by use case.
35+
36+
## macOS
37+
38+
For this tutorial, we'll assume you're using Jamf Pro as your MDM.
39+
The steps are very similar for other MDMs, however.
40+
41+
### Firefox
42+
43+
#### Client certificate auto-selection
44+
45+
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
46+
so that the Smallstep certificate is automatically selected
47+
when a protected resource is accessed.
48+
49+
1. In Jamf, navigate to **Computers > Configuration Profiles**
50+
2. Create a new Configuration Profile and find the **Application & Custom Settings** > **Upload** page.
51+
3. For Preference Domain, specify `org.mozilla.firefox`.
52+
4. Create a plist file called `org.mozilla.firefox.plist`, and populate it with the following:
53+
54+
```
55+
<?xml version="1.0" encoding="UTF-8"?>
56+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
57+
<plist version="1.0">
58+
<dict>
59+
<key>EnterprisePoliciesEnabled</key>
60+
<true/>
61+
<key>PayloadDisplayName</key>
62+
<string>Firefox ESR Policies</string>
63+
<key>PayloadEnabled</key>
64+
<true/>
65+
<key>PayloadIdentifier</key>
66+
<string>org.mozilla.firefox.BCADDC78-843E-4112-936A-DAB8EEEF514C</string>
67+
<key>PayloadType</key>
68+
<string>org.mozilla.firefox</string>
69+
<key>PayloadUUID</key>
70+
<string>BCADDC78-843E-4112-936A-DAB8EEEF514C</string>
71+
<key>PayloadVersion</key>
72+
<integer>1</integer>
73+
<key>Preferences</key>
74+
<dict>
75+
<key>security.default_personal_cert</key>
76+
<string>Select Automatically</string>
77+
<key>security.osclientcerts.autoload</key>
78+
<true/>
79+
</dict>
80+
</dict>
81+
</plist>
82+
```
83+
5. Upload the plist file to Jamf.
84+
6. Deploy the configuration profile to your test device.
85+
86+
To test the certificate, restart the browser and visit one your target URLs.
87+
88+
### Chrome
89+
90+
#### Client certificate auto-selection
91+
92+
A [configuration profile](https://support.google.com/chrome/a/answer/9020077?hl=en) can be used to set Chrome's certificate preferences
93+
so that the Smallstep certificate is automatically selected
94+
when a protected resource is accessed.
95+
96+
1. In Jamf, navigate to **Computers > Configuration Profiles**
97+
2. Create a new Configuration Profile and find the **Application & Custom Settings** > **Upload** page.
98+
3. For Preference Domain, specify `com.google.Chrome`.
99+
4. Create a plist file called `com.google.Chrome.plist`, and populate it with the following:
100+
101+
```
102+
<?xml version="1.0" encoding="UTF-8"?>
103+
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
104+
<plist version="1.0">
105+
<dict>
106+
<key>AutoSelectCertificateForUrls</key>
107+
<array>
108+
<dict>
109+
<key>pattern</key>
110+
<string>[Server URL]</string>
111+
<key>filter</key>
112+
<dict>
113+
<key>ISSUER</key>
114+
<dict>
115+
<key>CN</key>
116+
<string>Smallstep [Team Slug] Accounts Intermediate CA</string>
117+
</dict>
118+
</dict>
119+
</dict>
120+
</array>
121+
</dict>
122+
</plist>
123+
```
124+
125+
Replace `[Server URL]` with the server that requires certificate authentication.
126+
Replace `[Team Slug]` with your Smallstep team slug.
127+
This field is an [Enterprise policy URL pattern](https://chromeenterprise.google/policies/url-patterns/).
128+
129+
Note: According to [Understand Chrome policy management](https://support.google.com/chrome/a/answer/9037717),
130+
Chrome will *not* merge multiple `AutoSelectCertificateForUrls` policies.
131+
You must add all of your certificate selection preferences into a single managed configuration profile.
132+
133+
5. Upload the plist file to Jamf.
134+
6. Deploy the configuration profile to a test device.
135+
7. On the device, restart Chrome and visit the [policies tab](chrome://policy/) to verify the applied policy.
136+
137+
To test the certificate, restart the browser and visit one your target URLs.
138+
139+
### Safari
140+
141+
#### Client certificate auto-selection
142+
143+
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.
144+
145+
To test the certificate, restart the browser and visit one your target URLs.
146+
147+
## Windows
148+
149+
### Microsoft Edge and Google Chrome
150+
151+
#### Client certificate auto-selection
152+
153+
1. Confirm that a client certificate has been issued, run `certmgr` from PowerShell.
154+
Look inside Certificates - Current User → Personal → Certificates.
155+
You should see a certificate issued by a Smallstep Accounts Intermediate CA.
156+
157+
2. Confirm your client certificate is visible in your browser. If not, restart the browser.
158+
159+
- In Chrome, check <a href="chrome://settings/certificates">chrome://settings/certificates</a>.
160+
- In Edge, check <a href="edge://settings/privacy/securitySubPage">edge://settings/privacy/securitySubPage</a> and choose "Manage certificates".
161+
162+
For Chrome and Edge, we can use the [`AutoSelectCertificateForUrls`](https://chromeenterprise.google/policies/?policy=AutoSelectCertificateForUrls) policy to prevent the certificate selection dialog from appearing.
163+
164+
1. Open the Registry Editor (`regedit`)
165+
2. Navigate to to the key for your browser.
166+
167+
- For Chrome, visit `HKEY_LOCAL_MACHINE\Software\Policies\Google\Chrome`
168+
- For Edge, visit `HKEY_CURRENT_USER\SOFTWARE\Policies\Microsoft\Edge`
169+
- If the key you're looking for doesn't exist, you may need to create the `Google` and `Google/Chrome` keys or the `Edge` key.
170+
171+
3. In the registry path for your browser, create a new String Value named `AutoSelectCertificateForUrls`
172+
4. Set the value to `["{\"pattern\":\"$URL\",\"filter\":{\"ISSUER\":{\"CN\":\"Smallstep $TEAM Accounts Intermediate CA\"}}}"]`, substituting `$URL` for the URL you want to use with the Smallstep client certificate, and `$TEAM` for your Smallstep team slug.
173+
5. Restart the browser.
174+
6. Confirm the policy change.
175+
176+
- In Chrome, check <a href="chrome://policy">chrome://policy</a>.
177+
- In Edge, check <a href="edge://policy">edge://policy</a>.
178+
179+
To test the certificate, restart the browser and visit one your target URLs.
180+
You should not see any certificate selection dialogs.
181+
182+
## Linux
183+
184+
### Google Chrome
185+
186+
#### Client certificate auto-selection
187+
188+
We can use the [AutoSelectCertificateForUrls](https://chromeenterprise.google/policies/?policy=AutoSelectCertificateForUrls) Chrome policy to automatically select the client certificate without presenting a dialog:
189+
1. As root, create a policy file: `/etc/opt/chrome/policies/managed/auto_select_cert.json`
190+
2. Add the following content:
191+
192+
```
193+
{
194+
"AutoSelectCertificateForUrls": ["{\"pattern\":\"$URL\",\"filter\":{\"ISSUER\":{\"CN\":\"Smallstep $TEAM Accounts Intermediate CA\"}}}"]
195+
}
196+
```
197+
198+
Replace `$URL` with the server that requires certificate authentication.
199+
Replace `$TEAM` with your Smallstep team slug.
200+
For example:
201+
202+
```json
203+
{
204+
"AutoSelectCertificateForUrls": ["{\"pattern\":\"https://example.id.smallstep.com\",\"filter\":{\"ISSUER\":{\"CN\":\"Smallstep example Accounts Intermediate CA\"}}}"]
205+
}
206+
```
207+
208+
3. Restart Chrome, and visit the [policies tab](chrome://policy) to verify the applied policy.
209+
210+
Finally, let's verify that the user has a client certificate from the Smallstep agent.
211+
212+
Restart Chrome, and verify that the client certificate is in <a href="chrome://settings/certificates">Chrome's Certificate Manager</a>
213+
Don't see it? Check that the Smallstep agent is installed correctly.
214+
215+
To test the certificate, restart the browser and visit one your target URLs.
216+
You should not see any certificate selection dialogs.
217+
218+
### Firefox
219+
220+
#### Client certificate auto-selection
221+
222+
Use the <a href="about:certificate">about:certificate</a> URL to see all of the client certificates installed in Firefox's certificate database.
223+
224+
To test the certificate, restart the browser and visit one your target URLs.
225+
You should not see any certificate selection dialogs.
226+

0 commit comments

Comments
 (0)