Skip to content

Commit a90f1d0

Browse files
tashiantashian
authored
Merge pull request #362 from smallstep/carl/con-187
Update user-facing documentation to remove Device Collection concepts
2 parents 6c36bb2 + d0f8c2e commit a90f1d0

File tree

7 files changed

+308
-136
lines changed

7 files changed

+308
-136
lines changed

‎tutorials/intune-mdm-setup-guide.mdx‎

Lines changed: 9 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ In this tutorial, you will configure Smallstep and Microsoft Intune to establish
1212
You will:
1313

1414
- Connect Microsoft Entra ID to Smallstep via an Entra ID App Registration.
15-
- Create and configure an Intune Device Collection in Smallstep
15+
- Configure an Intune Integration in Smallstep
1616
- Configure Intune to use Smallstep as a CA
1717

1818
Once you've completed this tutorial, your Intune certificate enrollment process will look like this:
@@ -79,24 +79,20 @@ You’ve completed the App Registration setup.
7979
## 3. Configure Smallstep
8080

8181
In your Smallstep dashboard,
82-
visit the **Devices** tab,
83-
create a **+ New Collection**,
84-
choose **Intune Windows Devices**,
85-
and choose **Submit**.
82+
visit the **Integrations** tab,
83+
and choose **Intune**.
8684

87-
Configure the Collection with the values you gathered above:
85+
Configure the integration with the values you gathered above:
8886

89-
- The tenant **Primary domain**
9087
- The App Registration **Application (client) ID**
9188
- The App Registration **Secret Value**
89+
- The **Intune Tenant Name** (this is the tenant's primary domain)
9290

93-
Once the Collection is created, you'll need to make a new Account.
94-
Choose **+ Add Account**.
95-
Choose either Wi-Fi or VPN, depending on what you need, and select Create.
91+
Once the integration is added, go to the Protect tab.
92+
Choose either Wi-Fi or VPN, depending on what you need, and add a Wi-Fi or VPN resource.
9693
This tutorial assumes you are configuring EAP-TLS Wi-Fi network access.
97-
98-
Once you've created the Account, open the Account details.
99-
You cna keep this tab open as you configure Intune.
94+
Once you've created the Wi-Fi resource, open the Wi-Fi resource details page.
95+
You can keep this tab open as you configure Intune.
10096

10197
To prepare for the next section:
10298
- Download your Root CA Certificate

‎tutorials/vpn-client-setup-guide.mdx‎

Lines changed: 261 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
---
2+
title: Configure Your VPN Client For Certificate-Based VPN With Smallstep
3+
updated_at: June 3, 2024
4+
html_title: How to configure common VPN servers to use Smallstep for client and server certificate authentication.
5+
description: This tutorial describes how to configure VPN servers for a high-security, certificate-based VPN with Smallstep.
6+
---
7+
8+
Smallstep supports any Remote Access VPN that offers X.509 client certificate authentication.
9+
This includes IKEv2 VPN (using EAP-TLS), OpenVPN, and F5 SSL VPN.
10+
11+
Site-to-site VPNs are not officially supported, but Smallstep can issue certificates for those.
12+
13+
14+
The following VPN clients are covered in this document:
15+
- [IKEv2 EAP-TLS VPN](#ikev2-eap-tls)
16+
- [F5 SSL VPN](#f5-ssl-vpn)
17+
- [OpenVPN](#openvpn)
18+
- [Cisco Meraki AnyConnect](#cisco-meraki-anyconnect)
19+
20+
## IKEv2 EAP-TLS
21+
22+
IKEv2 with EAP-TLS is a common standards-based VPN authentication method
23+
for end-user certificate-based authentication.
24+
25+
VPN configurations can be created manually or using Mobile Device Management (MDM).
26+
27+
General instructions for VPN configuration:
28+
For macOS, see [Set up a VPN Connection on Mac](https://support.apple.com/guide/mac-help/set-up-a-vpn-connection-on-mac-mchlp2963/14.0/mac/14.0)
29+
For Apple devices using MDM, see [VPN settings overview for Apple devices](https://support.apple.com/guide/deployment/vpn-settings-overview-dep2d2adb35d/web).
30+
For Windows, see [Connect to a VPN in Windows](https://support.microsoft.com/en-us/windows/connect-to-a-vpn-in-windows-3d29aeb1-f497-f6b7-7633-115722c1009c)
31+
32+
33+
## F5 Edge and F5 Access Clients
34+
35+
Intended audience: Enterprise IT administrators
36+
Estimated time commitment: 1 hour
37+
38+
### Introduction
39+
40+
In this tutorial, we will configure an F5 SSL VPN on [F5 BIG-IP® APM](https://www.f5.com/products/big-ip-services/access-policy-manager) to use Smallstep certificate-based authentication with mutual TLS.
41+
42+
Client certificate management is not documented here. Client certificates could be issued to the F5 Access or Edge Client by the Smallstep app or by an MDM.
43+
44+
You will need a BIG-IP® instance with Local Traffic (LTM) and Access Policy (APM) resources provisioned.
45+
46+
This tutorial was tested on BIG-IP® VE v17.1.1 Build 0.2.6.
47+
48+
### Overview of the setup
49+
50+
For a complete setup, you will add the following to your F5 BIG-IP® configuration:
51+
52+
- An Access Profile with an Access Policy that performs certificate authentication and assigns resources to clients that successfully authenticate.
53+
54+
The Access Profile also contains configuration for the VPN itself, including IP lease pools and DNS settings.
55+
56+
- A Virtual Server which will serve your VPN traffic. This is where you’ll configure the mutual TLS handshake for your VPN server. The Virtual Server will accept client certificates from Smallstep, and use a server certificate from Smallstep.
57+
58+
### Access Profile
59+
60+
The Access Profile defines the certificate authentication flow and VPN settings for F5 BIG-IP®.
61+
62+
**This is just an example policy. After importing, please review and modify it as needed**. You may want a fallback authentication method, for instance, in case certificate authentication fails. Or you may want a different set of resource assignments after successful certificate authentication.
63+
64+
1. Download this profile: [smallstep-vpn-profile.conf.tar.gz](https://files.smallstep.com/smallstep-vpn-profile.conf.tar.gz)
65+
2. Go to Access → Profiles / Policies and choose Import…
66+
- Profile name: `smallstep`
67+
- Config File Upload: Upload smallstep-vpn-profile.conf.tar.gz
68+
69+
3. Choose “Import”
70+
71+
Here’s what the Access Policy will look like once imported:
72+
73+
![Imported BIG IP Access Policy](/graphics/imported-access-policy.png)
74+
75+
After import, you’ll need to customize your Access Profile to align with your VPN needs. Users commonly customize things like:
76+
77+
- IP Lease Pool address ranges
78+
- Compression settings (in the Network Access List)
79+
- DNS servers and domain suffix (in the Network Access List)
80+
81+
### Configuring TLS
82+
83+
Next, you’ll configure the TLS handshake for your VPN. You’ll add the following:
84+
85+
- CAs and Certificates for your Virtual Server
86+
- F5 Menu: System → Certificate Management → Traffic Certificate Management → SSL Certificate List
87+
- A Client SSL Profile
88+
- F5 Menu: Local Traffic → Profiles → SSL → Client
89+
- Virtual Server Configurations for ports 80 and 443
90+
- F5 Menu: Local Traffic → Virtual Servers
91+
92+
### Certificates and Certificate Authorities
93+
94+
Now let’s configure CAs and Certificates on the BIG IP.
95+
96+
First, you’ll add a root of trust that will verify client certificates:
97+
98+
1. Go to System → Certificate Management → Traffic Certificate Management → SSL Certificate List
99+
2. Choose “Import…” and on the next screen, choose:
100+
- Import Type: Certificate
101+
- Certificate Name: `smallstep-accounts-root-intermediate`
102+
- Certificate Source: Browse for the Intermediate and Root Cert Bundle from your Smallstep Accounts CA
103+
- Choose Import
104+
3. You should now see a new Certificate Bundle in the list.
105+
106+
Next, you’ll configure a server certificate and private key for your virtual server’s Client SSL profile. This certificate must be issued by a root CA that will be trusted by your VPN clients when they connect.
107+
108+
<aside>
109+
These instructions will help you create and import a certificate and key manually. A fully automated certificate management workflow is beyond the scope of this document. In a production environment, it is recommended to automate BIG IP server certificate management using Ansible, Terraform, or another IaC tool. BIG IP’s REST API can be leveraged for certificate automation. See [this F5 DevCentral post](https://community.f5.com/discussions/technicalforum/lets-encrypt-with-cloudflare-dns-and-f5-rest-api/292929) for details.
110+
</aside>
111+
112+
1. Create the server certificate and private key. You can do this in the Smallstep UI, or locally by running `step ca certificate`. For example:
113+
114+
```bash
115+
$ step ca certificate vpn.example.com server.crt server.key \
116+
--not-after 8160h \
117+
--san vpn.example.com \
118+
--san 14.13.12.10
119+
```
120+
121+
2. Combine the certificate + intermediate CA certificate and the private key into a PKCS 12 archive. You can generate a PKCS 12 archive with `step`. For example, if `server.crt` contains your server certificate and intermediate CA PEM blocks, and `server.key` contains your server private key, run:
122+
123+
```bash
124+
$ step certificate p12 server.p12 server.crt server.key
125+
```
126+
127+
You’ll be asked to provide a password to encrypt the file.
128+
129+
3. Next, in F5 BIG IP, go to System → Certificate Management → Traffic Certificate Management → SSL Certificate List
130+
4. Choose “Import…” and on the next screen, choose:
131+
- Import Type: PKCS 12 (IIS)
132+
- Certificate and Key Name: `smallstep-vpn-server`
133+
- Certificate and Key Source, browse for your `server.p12` PKCS 12 archive
134+
- Enter the password you used to encrypt the PKCS 12 archive
135+
5. Choose Import
136+
137+
You should now see the EC Certificate & Key you uploaded, in the SSL Certificate List.
138+
139+
### Virtual Servers
140+
141+
Now you’ll associate your Access Policy to a Virtual Server
142+
143+
You’ll need two Virtual Server configurations:
144+
145+
- For port 80, to redirect to port 443 using the built-in redirect iRule
146+
- For port 443, with attached profiles
147+
148+
To get started, create a Client SSL profile:
149+
150+
1. Go to Local Traffic → Profiles → SSL → Client
151+
2. Create a new Client SSL Profile
152+
3. Use the following values:
153+
- Name: `smallstep-clientssl`
154+
- Certificate Key Chain: Add the `smallstep-vpn-server` server certificate and private key you imported earlier
155+
- Client Certificate: Request
156+
- Trusted Certificate Authorities: Choose the `smallstep-accounts-root-intermediate` CA Bundle that you imported earlier. Your client certificates must be issued by this CA.
157+
- Advertised Certificate Authorities: Same value as Trusted Certificate Authorities
158+
4. Save the Profile
159+
160+
Next, create a Connectivity Profile:
161+
162+
1. Go to Local Traffic → Profiles → Services → Connectivity
163+
2. Choose “Add…”
164+
- Name: `smallstep-connectivity`
165+
- Parent profile: `/Common/connectivity`
166+
3. Ok
167+
168+
Next, create the Virtual Server for port 80
169+
170+
1. Go to Local Traffic → Virtual Servers
171+
2. Choose “Create…”
172+
3. Use the following properties:
173+
- Name: `smallstep-vpn-redirect`
174+
- Provide your source address mask, eg. `0.0.0.0/0`
175+
- Provide your destination address/mask. This may be the internal IP addresses of your F5 BIG IP.
176+
- Service port: 80 / HTTP
177+
- HTTP Profile (Client): http
178+
- Add iRule **`_sys_https_redirect`**
179+
180+
Finally, create a Virtual Server for port 443:
181+
182+
1. Go to Local Traffic → Virtual Servers
183+
2. Choose “Create…”
184+
3. Use the following properties:
185+
- Name: `smallstep-vpn`
186+
- Provide your source and destination addresses/masks
187+
- Service port: 443 / HTTPS
188+
- HTTP Profile (Client): http
189+
- SSL Profile (Client): Add the Client SSL Profile you created above
190+
- Access Profile: Select the Access Profile you imported above
191+
- Connectivity Profile: Select the Connectivity Profile you created above
192+
193+
Your VPN configuration is now ready for testing.
194+
195+
Further reading:
196+
197+
- [F5: Configuring an HTTP virtual server to redirect to HTTPS using an iRule](https://my.f5.com/manage/s/article/K10090418)
198+
- [F5’s Dev/Central](https://community.f5.com/) Community support
199+
200+
---
201+
202+
### Creating an Access Profile manually
203+
204+
If you want to create an Access Profile manually instead of importing one, do the following:
205+
206+
### Add a Network Access List
207+
208+
1. Go to Access → Connectivity / VPN → Network Access (VPN) → Network Access Lists
209+
2. Choose “Create…”
210+
- Name: `smallstep-na-res`
211+
- Description: `Smallstep VPN Access`
212+
- Customize the Customization Settings as desired
213+
3. Choose “Finished”
214+
215+
### Add an IPv4/IPv6 Lease Pool
216+
217+
Add at least one lease IPv4 or IPv6 lease pool:
218+
219+
1. Go to Access → Connectivity / VPN → Network Access (VPN) → IPv4 Lease Pools
220+
2. Choose “Create…”
221+
- Name: `smallstep-lp`
222+
- Start IP: `192.168.133.2`, for example
223+
- End IP: `192.168.133.254`, for example
224+
225+
### Add an Access Profile
226+
227+
1. Go to Access → Profiles / Policies and create an Access Profile
228+
- Name: `smallstep-vpn`
229+
- Profile Type: All
230+
- Languages: Add a language
231+
- Choose “Finish”
232+
2. Open the access policy you just created. In the Access Policy tab, open the visual policy editor
233+
3. Import the following Access Policy:
234+
235+
If you want to create this policy manually, do the following:
236+
237+
- Authentication → On-Demand Cert Auth: Dynamically initiate an SSL re-handshake and validate the received client certificate
238+
- Choose Auth Mode: “Require”
239+
- Leave all other settings as default
240+
- On the “Successful” branch after “On-Demand Cert Auth”, add Authentication → Client Cert Inspection: Check the result of client certificate authentication by the Local Traffic Client SSL profile
241+
- Leave all settings as default
242+
- On the “Successful” branch after “Client Cert Inspection”, add Assignment → Advanced Resource Assign:
243+
- Use the Simple Expression “Client Cert is valid”
244+
- Add a new Resource Assignment entry
245+
- Assign your Network Access Profile
246+
- Save
247+
248+
The Advanced Resource Assign properties should look like this:
249+
250+
![Advanced Resource Assign properties](/graphics/advanced-resource-assign.png)
251+
252+
- Finally, change the fallback Ending from Advanced Resource Assign to **Allow**
253+
254+
## Juniper SSL-VPN
255+
256+
See [Create a Remote Access VPN—Juniper Secure Connect](https://www.juniper.net/documentation/us/en/software/jweb-srx21.3/jweb-srx/topics/task/j-web-security-ipsec-remote-access-vpn-juniper-secure-connect-creating.html)
257+
258+
## Cisco Meraki AnyConnect
259+
260+
- [Server docs at meraki.net](https://learning.meraki.net/#/online-courses/3def4293-8b71-406f-ae12-ab0c1028261b)
261+
- [Client docs at meraki.net](https://documentation.meraki.com/MX/Client_VPN/AnyConnect_on_the_MX_Appliance/Client_deployment)

‎tutorials/vpn-setup-guide-azure-vng.mdx‎

Lines changed: 10 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,8 @@ You can use an [Azure Point-to-Site VPN](https://learn.microsoft.com/en-us/azure
1414

1515
In this tutorial, we'll set up client certificate authenticatin with Smallstep, using an IPSec IKEv2 VPN.
1616

17+
You will need the [`step` CLI](https://smallstep.com/docs/step-cli/installation/) tool.
18+
1719
## Step-by-step instructions
1820

1921
1. Start by deploying a Virtual Network Gateway. Follow the steps in [Create the VPN Gateway](https://learn.microsoft.com/en-us/azure/vpn-gateway/vpn-gateway-howto-point-to-site-resource-manager-portal#creategw) section of Microsoft's tutorial. Deploy the gateway, but do not generate any certificates yet.
@@ -41,25 +43,21 @@ In this tutorial, we'll set up client certificate authenticatin with Smallstep,
4143

4244
This file is in DER (binary) certificate format.
4345
Before you upload it to Smallstep, convert it to PEM format.
44-
Run:
46+
In the CLI, run:
4547

4648
```
4749
step certificate format VpnServerRoot.cer_0 > VpnServerRoot.pem
4850
```
4951

50-
3. In [Smallstep](https://smallstep.com/app), create a Mobile Device Collection and add your device to it.
51-
(If you're using the Smallstep app, a New Devices collection will be created for you when you sign in.)
52-
53-
4. Now, under the Accounts tab of your Device Collection, create a VPN Account:
54-
55-
* Connection type: **IKEv2 with IPSec**
52+
3. In Smallstep's Protect tab, create a [VPN resource](https://smallstep.com/app/?next=/protect/vpn):
53+
* VPN Server: Azure Virtual Network
5654
* Remote address: Use the server name or remote IP of your Azure VPN
5755
* Remote ID: Use the Remote ID you located earier.
58-
* Server Certificate Roots: Choose "Upload external root" and upload the `VpnServerRoot.pem` file you created earlier.
59-
60-
5. Choose "Save account"
61-
6. Download your Smallstep Root Certificate from the Authority Settings page.
62-
7. In Azure, follow the instructions in [Upload root certificate public key information](https://learn.microsoft.com/en-us/azure/vpn-gateway/vpn-gateway-howto-point-to-site-resource-manager-portal#uploadfile) to add the Smallstep Root Certifcate to the Root certificates section of your VPN's Point-to-site Configuration.
56+
4. Choose "Next"
57+
5. Under Certificate authorities, choose "Upload external root" and upload the `VpnServerRoot.pem` file you created earlier.
58+
6. Finish creating the resource.
59+
7. On the VPN resource page, download your Smallstep Root Certificate for your Accounts CA. This is the CA that will authenticate your devices.
60+
8. In Azure, follow the instructions in [Upload root certificate public key information](https://learn.microsoft.com/en-us/azure/vpn-gateway/vpn-gateway-howto-point-to-site-resource-manager-portal#uploadfile) to add the Smallstep Root Certifcate to the Root certificates section of your VPN's Point-to-site Configuration.
6361

6462
You're now ready to verify your VPN connection.
6563

0 commit comments

Comments
 (0)