Onboard macOS devices with certificates using Kandji and SCEP

In this topic, you will learn how to deploy Portnox™ Cloud certificates via Kandji and SCEP to manage macOS devices (Wi-Fi only).

Kandji lets you create Wi-Fi profiles using the cloud user interface but does not let you create Ethernet profiles. If you need to create a profile with Ethernet connectivity, you need to create a custom profile manually and distribute this custom profile using Kandji. For instructions, how to do it, see the following topic: Onboard macOS devices with certificates using Kandji, SCEP, and a custom profile.

Important: This topic shows the configuration for macOS computers with macOS 12 (Monterey), but the Apple profile payloads Certificate, SCEP, and WiFi, which are used in this configuration, are compatible with the following Apple operating systems: iOS 4.0+, iPadOS 4.0+, macOS 10.7+, tvOS 9.0+, watchOS 3.2+. This means that you can use the same profiles to configure other Apple devices based on these operating systems, for example, iPhones.

Turn on the Portnox Cloud SCEP services

In this section, you will configure Portnox™ Cloud to provide SCEP services to your devices.

If you have previously turned on the Portnox Cloud SCEP services, skip to the later step in which you get the Cloud SCEP URL and password.

Portnox Cloud SCEP services let devices contact the Cloud SCEP server and get a unique certificate for the device or for the specific user of the device.

Important: This topic shows the configuration for macOS computers with macOS 12 (Monterey), but the Apple profile payloads Certificate, SCEP, and WiFi, which are used in this configuration, are compatible with the following Apple operating systems: iOS 4.0+, iPadOS 4.0+, macOS 10.7+, tvOS 9.0+, watchOS 3.2+. This means that you can use the same profiles to configure other Apple devices based on these operating systems, for example, iPhones.
  1. In the Cloud portal top menu, click on the Settings option.

  2. In the Cloud portal left-hand side menu, click on the Services > GENERAL SETTINGS > SCEP Services option.

  3. Enable integration with SCEP services.

    1. Click on the Edit link.
    2. Activate the Enable integration checkbox.
    3. Click on the Save button.
  4. Click on the  ⧉  icon next to the SCEP URL field to copy the SCEP URL, and paste it in a text file for later use.
  5. Click on the  ⧉  icon next to the Password field to copy the SCEP password, and paste it in a text file for later use.

Download the root CA certificate

In this section, you will download the root CA certificate from Portnox™ Cloud, which is needed to create a profile.

  1. In the Cloud portal top menu, click on the Settings option.

  2. In the Cloud portal left-hand side menu, click on the Services > CLEAR RADIUS SERVICE > CLEAR RADIUS instance option.

  3. Click on any of the RADIUS servers listed in the right-hand pane to show its configuration.

  4. Click on the Download root certificate link.

Result: The root CA certificate file is in the Downloads folder on the local disk.

Download the tenant CA certificate

In this section, you will download the Portnox™ Cloud tenant CA certificate from the Cloud portal.

You need the tenant CA certificate from Portnox Cloud so that your managed devices can verify the validity of individual SCEP certificates, which are signed using the tenant CA certificate.

  1. In the Cloud portal top menu, click on the Settings option.

  2. In the Cloud portal left-hand side menu, click on the Services > GENERAL SETTINGS > Trusted Root Certificates option.

  3. In the Trusted Root Certificates section, click on the Download PFX link, then save the downloaded file.

    The default name of the file is Your_tenant_name - Portnox CLEAR.pfx, for example, Portnox - Portnox CLEAR.

The downloaded tenant CA certificate is a file in the Personal Information Exchange binary format (PFS, also known as PKCS#12), which you cannot use directly. You need to convert it to the Base-64 encoded X.509 format (sometimes referred to as CER or PEM).

Convert the tenant CA certificate

In this section, you will convert the downloaded tenant CA certificate into the Base-64 encoded X.509 format.

You need this certificate in the Base-64 encoded X.509 format, which is sometimes called the PEM format. Files with this format usually have the .pem or .cer extension, but files in the DER binary format also have the .cer extension.

The following are three recommended ways to convert the PKCS#12 certificate into Base-64 encoded X.509:

  • Convert the tenant CA certificate using Windows certificate management.

    You need to download the certificate to a Windows computer or copy it to a Windows computer.

    1. In Windows, right-click on the PKCS#12 file and select Open from the context menu.

      The file will be opened in the Windows certificate manager.

    2. In the certificate manager window, open the Certificates section in the left-hand pane and then double-click on Portnox - Portnox CLEAR in the right-hand side pane.

    3. In the Certificate window, click on the Details tab and then click on the Copy to File button.

    4. In the first step of the Certificate Export Wizard wizard, click on the Next button.
    5. In the second step of the wizard, select the Base-64 encoded X.509 (.CER) option.

    6. In the third step of the wizard, select a file to save the exported tenant CA certificate, and click on the Next button.

      For example, save the file as tenantCertificate.cer.

    7. In the last step of the wizard, click on the Finish button. Then, close the Certificate window.
  • Convert the tenant CA certificate using OpenSSL.

    If you have OpenSSL installed on your macOS device, you can use it to convert certificates. OpenSSL is not installed by default and the installation requires using a third party package or compiling OpenSSL from source.

    1. Open the Terminal.
    2. Type the following command: # openssl pkcs12 -in "Portnox - Portnox CLEAR.pfx" -out tenantCertificate.cer

      If asked for a certificate password, use an empty password.

  • Convert the tenant CA certificate using a third-party online converter.
    Important: The following converters are not affiliated in any way with Portnox. They were found using web search and verified to support the required conversion. If needed, search the web for other converters.
    • RVSSL (select PFX/PKCS#12 as the input format and Standard PEM as the output format)
    • SSL Shopper (select PFX/PKCS#12 as the input format and Standard PEM as the output format)

Optional: Hand over information from the Portnox Cloud team to the Kandji team

In this section, you will learn what information was collected in previous steps from Portnox Cloud, which is needed to configure Kandji to work with Portnox Cloud.

If different people are responsible for managing Portnox Cloud and Kandji, here is the information you need to hand over:

  • The URL of the Portnox Cloud SCEP server. For example, https://scep.portnox.com/b2973887-1274-45d4-91d0-4a342a861c76.

  • The password for the SCEP server.

  • The root CA certificate file in the Base-64 encoded X.509 format. For example, rootCertificate.cer.

  • The tenant CA certificate file in the Base-64 encoded X.509 format. For example, tenantCertificate.cer.

Create a blueprint in Kandji

In this section, you will create a blueprint in Kandji that lets you add Wi-Fi and wired profiles for networks as well as other Kandji security features to your managed devices.

Note: You can skip this step if you have an existing blueprint that you want to use to organize your profiles.
  1. Open your Kandji instance in the browser and log in.
    For example, vorlon.kandji.io
  2. In the Kandji main menu, click on the BLUEPRINTS option.

    Kandji shows the Blueprints pane on the right-hand side.

  3. In the top-right corner of the Blueprints pane, click on the New Blueprint button.

    Kandji shows the Create a new Blueprint window over the right-hand pane.

    Note: You can use an existing blueprint instead. If so, skip the steps for creating a new blueprint and when asked to select a blueprint, select your existing blueprint instead.
  4. In the Create a new Blueprint window, click on the + New Blueprint button in the top-left corner of the window, enter a Blueprint name, and click on the Create Blueprint button.

    We used the name Vorlon but you can use any name you like.

Create a Wi-Fi profile in Kandji

In this section, you will create a profile that contains configuration for your managed Wi-Fi network.

Note: You must first create a blueprint or have an existing blueprint that you will use.
  1. In the Kandji main menu, click on the LIBRARY option.

    Kandji shows the Library pane on the right-hand side.

  2. In the top-right corner of the Library pane, click on the Add new button.

    Kandji shows the Add Library item pane on the right-hand side.

  3. In the Add Library item pane, in the Search box on the right-hand side, start typing wi-fi and then click on the Wi-Fi tile in the Profiles section.

  4. In the Wi-Fi section on the bottom of the right-hand side pane, click on the Add & Configure button.

    Kandji shows the Wi-Fi pane on the right-hand side.

  5. In the Add a title field on top of the Wi-Fi Profile pane, enter the name for the new Wi-Fi profile.

    We used the name Vorlon Wi-Fi but you can use any name you like.

  6. In the Blueprint field, select the blueprint you created earlier.

  7. In the Settings > General section below, in the Service Set Identifier (SSID) field, enter the SSID of the Wi-Fi network configured in Portnox Cloud.

  8. In the Settings > Authentication section below:
    1. In the Authentication type field, select the WPA2 Enterprise option.

    2. In the Accepted EAP Types field, select the TLS option.

    3. In the Identity certificate field, select the SCEP option.

    4. Under the Identity certificate field, click on the Configure SCEP Certificate button.

      Kandji shows the SCEP configuration pane on the right-hand side.

  9. In the SCEP configuration pane on the right-hand side:
    1. In the URL field, enter the SCEP URL that you copied earlier from Portnox Cloud.

    2. In the Challenge field, enter the SCEP password that you copied earlier from Portnox Cloud.

    3. In the Subject field, type CN=$EMAIL for user-based authentication.

      Note:

      The $EMAIL format is a Kandji global variable. This tag is processed by Kandji and replaced by the email of the user. The full list of Kandji global variables is available in the Kandji documentation. Portnox Cloud then uses the email from the certificate fields to create or align with an account in Cloud.

      At this time, Portnox Cloud does not support device-based authentication for Kandji. If you try to use Kandji variables related to device identifiers, Cloud will not be able to align this information with information from the authentication repository, and it will create new Cloud accounts for devices instead of aligning them with accounts from the authentication repository.

    4. Activate the Specify Subject Alternative Names (SAN) checkbox, in the SAN type field, select the NT Principal Name option, and in the value field, type $EMAIL.

      Note: By default, Portnox Cloud checks for user identity information in the SAN UPN field (NT Principal Name in macOS). You can use a different SAN field, but it is not recommended. For more information, see the following topic: Certificate identity information.
    5. In the Key usage field, select the Both signing and encryption option.

    6. Adjust values of any other fields if necessary and then click on the Done button in the bottom-right corner of the SCEP configuration pane.

  10. In the Settings > Certificate trust section:
    1. Activate the Specify trusted certificates checkbox, click on the click to upload link, and select the certificate that you converted earlier (for example, the tenantCertificate.cer file).

    2. Click on the click to upload link again, and select the root CA certificate that you downloaded earlier (for example, the rootCertificate.cer file).

    3. Activate the Specify server certificate names checkbox, and in the Server certificate name field, type clear-rad.portnox.com.

      Note: To learn more about this option, read the following topic: Trusted certificate server names.
  11. Adjust values of any other fields if necessary and then click on the Save button in the bottom-right corner of the Wi-Fi configuration pane.