Jamf tutorial

manifest.json

@@ -1563,6 +1563,10 @@
               "title": "Issue X.509 user certificates via your identity provider",
               "path": "/tutorials/user-authentication.mdx"
             },
+            {
+              "title": "Jamf Pro + Smallstep MDM Setup Guide",
+              "path": "/tutorials/apple-mdm-jamf-setup-guide.mdx"
+            },
             {
               "title": "Create a CA that uses RSA keys",
               "path": "/tutorials/rsa-chain.mdx"

tutorials/apple-mdm-jamf-setup-guide.mdx

@@ -0,0 +1,203 @@
+---
+title: Deploy MDM client certificates to Apple devices with Smallstep and Jamf Pro
+html_title: Deploy MDM client certificates to Apple devices with Smallstep and Jamf Pro
+description: This tutorial focuses on deploying client certificates to your devices via Jamf Pro and your Smallstep Authority, using SCEP with dynamic challenges.
+---
+
+## Introduction
+
+This tutorial focuses on deploying client certificates to your devices via Jamf Pro and your Smallstep Authority, using SCEP with dynamic challenges.
+
+Use this workflow to set up an MDM enrollment process that looks like this:
+
+![Jamf MDM Marketecture.png](/graphics/Jamf_MDM_Marketecture.png)
+
+This tutorial is for Device or Computer Level MDM profiles, not User Level profiles.
+
+<Alert severity="info">
+  <div>
+    **Will I need a Jamf SCEP Proxy?**<br />
+    Because your Smallstep hosted CA is reachable from the public internet, you do not need a Jamf SCEP proxy.
+  </div>
+</Alert>
+
+## Before you begin
+
+You will need:
+
+- A Smallstep Certificate Manager team. Don’t have one yet? [Sign up](https://smallstep.com/signup).
+- A Jamf Pro instance. For this tutorial, use a staging or testing Jamf environment, or create a group of test devices or users.
+- A test device or VM to enroll in MDM.
+- A Jamf user for testing enrollment.
+
+<Alert severity="info">
+  <div>
+    If you’re planning to deploy Wi-Fi and EAP-TLS using a JumpCloud RADIUS server, you will need to use an RSA CA.
+    This requires creating an Advanced Authority.
+    When creating the Authority, use key type `RSA_SIGN_PKCS1_2048_SHA256` for both root & intermediate CAs.
+  </div>
+</Alert>
+
+## Step-by-step instructions
+
+In this section, we will set up an MDM profile that instructs devices to establish CA trust with your Smallstep CA, and to get a client certificate via Smallstep’s SCEP server.
+
+### Configure Smallstep for Jamf
+
+1. In the **Devices** tab, add a device collection and choose **Jamf**
+2. Fill in the details related to your Jamf instance.
+3. In the Devices tab, create a collection
+4. Choose Jamf and select your Jamf instance and a Certificate Authority to use
+5. Click **Accounts** → **Add Account** → **Wifi**
+
+Smallstep will provide the following values, which you’ll need later:
+
+- A Jamf webhook URL, username and password to be used when configuring your Jamf webhook.
+- Your root CA certificate, for configuring the `Certificate` payload
+- Your SCEP CA URL, for configuring the `SCEP` payload
+- Your intermediate CA fingerprint, for configuring the `SCEP` payload
+
+### Configure Jamf to use Smallstep
+
+There are five steps to this part of the process:
+
+1. Configure a SCEP dynamic challenge webhook
+2. Create a configuration profile for testing
+3. Add a [`Certificate` payload](https://support.apple.com/guide/deployment/certificates-payload-settings-dep91d2eb26/1/web/1.0) containing your root CA certificate
+4. Add a [`SCEP` payload](https://support.apple.com/guide/deployment/scep-payload-settings-dep495a6d79/1/web/1.0) for requesting a client certificate
+5. Complete and test your setup
+
+### 1. Configure a SCEP dynamic challenge webhook
+
+1. In the Jamf dashboard, go to `Settings` and search for `Webhooks`
+2. Click **+ New**
+3. Fill out the form as follows:
+    - Set a descriptive name, e.g. `SCEP Challenge`
+    - Select ✅ **Enabled**
+    - Use `Basic Authentication`
+    - Populate the webhook URL, username, and password with what you were given by Smallstep
+    - Select JSON as the Content Type
+    - Select `SCEPChallenge` as the webhook event
+    - **Here's an example of the completed form:**
+
+        ![jamf webhook.png](/graphics/jamf_webhook.png)
+
+4. Choose **Save** in the bottom right
+
+### 2. Create a Configuration Profile for testing
+
+<Alert severity="warning">
+  <div>
+    Use a Device or Computer Level profile. These instructions do not apply to User Level profiles.
+  </div>
+</Alert>
+
+To test your setup, you can create a computer or mobile device Configuration Profile—or both—as needed. Some of the settings below are not available on mobile.
+
+When you move from test into production, you’ll repeat the setup steps below in your production profiles.
+
+**2a. Add a `Certificate` Payload to the Configuration Profile**
+
+This payload configures the device to trust your Smallstep Root CA. The device needs CA trust in order to request a client certificate.
+
+Use the following payload properties:
+
+- Set a name, e.g. `Smallstep Root CA`
+- Select Certificate Option: `Upload`
+- Choose **Upload Certificate** and upload the PEM-formatted root CA certificate you received from Smallstep.
+
+<Alert severity="warning">
+  <div>
+    Jamf requires the file extension to be `.cer` for it to appear in the file chooser, so you may need to rename your CA certificate file. The extensions `.cer`, `.crt`, and `.pem` all generally refer to the same PEM certificate format.
+  </div>
+</Alert>
+
+- Password is not required; it’s just a certificate, after all.
+- Select ✅ **Allow all apps access**
+- ✅ **Allow export from keychain** can be enabled or disabled
+
+Choose Save in the bottom right to save the profile.
+
+**2b. Add a `SCEP` Payload to the Configuration Profile**
+
+The `SCEP` payload configures the device to get a client certificate from Smallstep, using Dynamic SCEP.
+
+In the Configuration Profile, create a `SCEP` Payload with the following properties:
+
+- Use the **SCEP URL** you received from Smallstep
+- **Name** is optional; the name you choose will appear in the macOS or iOS Profiles settings panel
+- **Redistribute Profile** can be used to request Jamf redistribute the profile a number of days before the certificate expires.
+
+    Redistributing the profile renews the SCEP client certificate. The correct value for this field depends on the client certificate’s validity period.
+
+    Because mobile devices and laptops are intermittently connected, we recommend redistribution at around 20% of the certificate lifetime.
+
+    A good starting point is to use a 45 day certificate, redistributed 30 days before it expires.
+
+- Fill in the **Subject** as you wish.
+    - When using Redistribute Profile, `$PROFILE_IDENTIFIER` must be somewhere in your subject name. Use any subject name field for this — `OU`, `O`, `L`, `ST`, etc.
+    - `CN=$COMPUTERNAME` or `CN=$UDID` can be used as dynamic value. Other possible variable names are available; see the [Jamf documentation](https://learn.jamf.com/bundle/jamf-pro-documentation-current/page/Computer_Configuration_Profiles.html).
+    - A good starting point for this value is `CN=$UDID,L=$PROFILE_IDENTIFIER`
+- Optional: Add **Subject Alternative Names (SANs)** as needed.
+- Set **Challenge Type** to Dynamic. Jamf will use the Dynamic Challenge webhook configured earlier.
+- The default notification threshold should be adjusted to be a fraction of the total certificate lifetime.
+- Set **key size** to at least 2048 bits
+- Select ✅ **Use as Digital Signature**
+- Select ✅ **Use for Key Encipherment**
+- For **Fingerprint**, use the Intermediate CA Fingerprint you received from Smallstep. This value is a hex-encoded MD5 or SHA1 hash with no delimiters.
+- Only select **Allow export from Keychain** or **Allow all apps access** if you need them.
+(This setting is only available on Computer profiles.)
+- **Here's an example of the completed form**
+
+    ![jamf scep.png](/graphics/jamf_scep.png)
+
+
+Choose Save in the bottom right to save the profile.
+
+<Alert severity="info">
+  <div>
+    We recommend adding both payloads to the same Configuration Profile, but you could use separate profiles, so long as the profile with the `Certificate` payload is applied before the profile with the `SCEP` payload.
+  </div>
+</Alert>
+
+### 3. Test your MDM Profile
+
+After configuring the SCEP payload, it’s possible to add more payloads that make use of the SCEP certificate—for example, a VPN or Network/Wi-Fi payload—but we suggest testing this basic profile before you add payloads that use the certificate.
+
+To test your Configuration Profile, attach a Scope:
+
+1. In the **Configuration Profile** settings, choose the **Scope** tab
+2. Select a device or user for testing. For the device to appear, the device should already be enrolled with a basic Jamf MDM profile.
+
+<Alert severity="info">
+  <div>
+     Resist the temptation to download the profile from the Jamf admin panel and manually installing it; it won’t work.
+  </div>
+</Alert>
+
+## Adding Wi-Fi
+
+Now that we have a basic working profile with CA trust and a client certificate, we’ll configure an EAP-TLS certificate Wi-Fi connection.
+
+For this section, you will need a RADIUS server that your users will authenticate against. Check the certificate used by your RADIUS server for its common name.
+
+1. In Jamf, create a Wi-Fi payload.
+2. Configure your SSID and other basic network settings.
+3. For Network Security, select WPA2 Enterprise or WPA3 Enterprise.
+4. In the Protocols tab, select the EAP-TLS protocol.
+5. Under the Trust tab, add a Trusted Certificate for your RADIUS server. 
+
+    If your RADIUS server certificate is managed by Smallstep, choose your Smallstep Root CA Certificate payload here.
+
+    If your RADIUS server certificate is from a different PKI, you’ll need to add a new Certificate payload containing your RADIUS server’s Root CA certificate.
+
+6. Under the Certificate Common Name, use the Common Name of your RADIUS server.
+
+### Troubleshooting
+
+- Check the expected certificates have been deployed to the right stores on macOS: user vs. device; trusted roots; personal certificates.
+    - Jamf does show some states in the dashboard and there’s a bit of logging available, but they don’t provide many details, and sometimes they’re not up-to-date.
+    - Logging can be found by navigating to the Configuration Profile and looking for the `Logs` option in the bottom right. You can then navigate to the right device. Check out the `History` → `Management History` tab for the device.
+- Use the macOS Console application to diagnose issues. SCEP related (error) logs can be found by searching for “scep” (won’t catch all related log entries, but usually does the job). It’s also possible to follow these logs in realtime.
+- The `.mobileconfig` file is a text file and sometimes it can be useful to inspect it for debugging purposes.
+- If all else fails: Have you tried turning it off and on again? This can sometimes help a device to do things again.