smallstep_full_white

Deploy MDM client certificates to Apple devices with Smallstep and Jamf Pro

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

This tutorial is for Device or Computer Level MDM profiles, not User Level profiles.

Before you begin

You will need:

  • A Smallstep Certificate Manager team. Don’t have one yet? Sign up.
  • 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.

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 containing your root CA certificate
  4. Add a SCEP payload 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

  4. Choose Save in the bottom right

2. Create a Configuration Profile for testing

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.
  • 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.
    • 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

Choose Save in the bottom right to save the profile.

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.

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.