Onboard devices with certificates using Iru and SCEP

In this topic, you will learn how to deploy Portnox™ Cloud certificates via Iru and SCEP to manage macOS, iOS, iPadOS, and Windows devices.

Note:
Iru was previously called Kandji.
Note:
This topic shows how to create one Wi-Fi library item for macOS, iOS, iPadOS, and Windows devices, and one Ethernet library item for macOS devices. Windows devices also need a separate library item with the tenant CA certificate. If you don’t manage one of these operating systems, don’t select it in the Install on field of a library item. Iru then hides the settings for that operating system.

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.

  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 > CLOUD RADIUS SERVICE > Cloud 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.

Copy the tenant CA thumbprint and download the tenant CA certificate

In this section, you will copy the thumbprint of the Portnox™ Cloud tenant CA certificate. If you manage Windows devices with Iru, you will also download the tenant CA certificate file.

  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, select the value of the Thumbprint next to the certificate that you currently use (if more than one), copy it using your operating system’s copy function, and paste it in a text file for later use.

  4. If you manage Windows devices with Iru, click on the Download CER link in the Trusted Root Certificates section, then save the downloaded file.

    Only Windows devices need this file. If you manage only macOS, iOS, or iPadOS devices, skip this step.

    Note:
    The default name of the file is Your_tenant_name - Portnox CLEAR.cer, for example, Vorlon - Portnox CLEAR.cer. You can rename the downloaded file to tenantCertificate.cer. This is the name used in the next part of this guide.

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

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

If different people are responsible for managing Portnox Cloud and Iru, 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 tenant CA thumbprint.

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

  • Windows only: the tenant CA certificate file in the X.509 format. For example, tenantCertificate.cer.

Create a blueprint in Iru

In this section, you will create a blueprint (assignment map) in Iru. You will assign all library items from this topic to this blueprint.

Note:
If you already have a blueprint that you use for your devices, you can use it instead. Skip this section and select your existing blueprint when asked. You can also create the blueprint later and assign existing library items to it.
Important:
Make sure that each device is assigned to the blueprint and has an assigned user. The user’s email address must match the one in your Portnox Cloud authentication repository. Iru puts this email address in the certificate, and Portnox Cloud uses it to match the certificate with the user in the authentication repository. Device enrollment in Iru is not covered in this topic.
  1. Open your Iru instance in the browser and log in.
    For example, vorlon.iru.com
  2. In the Iru left-hand menu, click on the Endpoint > Blueprints option.

    Iru shows the Blueprints screen.

  3. In the top-right corner of the Blueprints screen, click on the Add Blueprint button.

    Iru shows the Create Blueprint window.

  4. In the Create Blueprint window, click on the Start from scratch tile.

  5. In the Blueprint name field, enter the name for the new blueprint, and click on the Create Blueprint button.

    Iru shows the assignment map of the new blueprint in edit mode.

  6. In the top-right corner, click on the Save button.

    Iru shows the Assignment Map tab of the new blueprint.

Windows only: Create a Certificate library item for the tenant CA certificate

In this section, you will create a library item that installs the Portnox™ Cloud tenant CA certificate on Windows devices.

Important:
Only Windows devices need this library item. If you don’t manage Windows devices with Iru, skip this section. Windows uses the fingerprint from the Wi-Fi library item to find a client certificate issued by the tenant CA. To match the certificate, Windows must build the chain from the SCEP certificate to the tenant CA certificate in its certificate store. macOS, iOS, and iPadOS devices don’t need this certificate because their Wi-Fi and Ethernet profiles point directly to the certificate that the SCEP settings in the same profile request.
  1. In the Iru left-hand menu, click on the Endpoint > Library option.

    Iru shows the Library screen.

  2. In the top-right corner of the Library screen, click on the Add Library Item button.

    Iru shows the Add Library Item screen.

  3. In the search box, type certificate, and then click on the Certificate tile in the Profiles section.

  4. In the bottom-right corner, click on the Add and configure button.

    Iru shows the configuration screen for the new library item.

  5. In the Add a title field at the top of the screen, enter the name for the new library item.

  6. In the Install on field, click on the  ×  icon next to the Apple option, so that only the Windows option remains.

  7. Next to the Assignment Maps field, click on the Assign button, and select your blueprint.

  8. In the Certificate type field, select the PKCS #1-formatted certificate option.

  9. In the Certificate section, click on the Drag file here or choose file tile to upload the tenant CA certificate file that you downloaded earlier (for example, tenantCertificate.cer).

  10. In the Windows only settings section, in the Certificate Store field, make sure that the Trusted Root Certification Authorities option is selected.

  11. In the bottom-right corner, click on the Save button.

Create a Wi-Fi library item in Iru

In this section, you will create one library item that configures your managed Wi-Fi network on macOS, iOS, iPadOS, and Windows devices.

  1. In the Iru left-hand menu, click on the Endpoint > Library option.

    Iru shows the Library screen.

  2. In the top-right corner of the Library screen, click on the Add Library Item button.

    Iru shows the Add Library Item screen.

  3. In the search box, type wi-fi, and then click on the Wi-Fi tile in the Profiles section.

  4. In the bottom-right corner, click on the Add and configure button.

    Iru shows the configuration screen for the new library item.

  5. In the Add a title field at the top of the screen, enter the name for the new library item.

  6. In the Install on field, select the Apple option, the Windows option, or both, depending on the devices that you manage.

  7. Next to the Assignment Maps field, click on the Assign button, and select your blueprint.

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

  9. Activate the Disable MAC address randomization checkbox.

    Important:
    If you do not turn off MAC address randomization, and the supplicant certificates are not issued by Portnox SCEP, and the certificate’s SAN field does not include a Jamf or Intune device ID, Portnox Cloud assigns a new license to the device each time it connects with a different MAC address. This can significantly increase your licensing costs. Even if you use Portnox SCEP and this issue does not apply, we still recommend turning MAC address randomization off for safety. For more information, see the following topic: MAC address randomization – why it causes problems and how to turn it off.
  10. In the Authentication section:
    1. In the Authentication type field, select the WPA2 Enterprise option.

      Note:
      If you manage only Apple devices, you can select the WPA3 Enterprise option instead. The rest of the setup is nearly the same. For Windows devices, Iru supports only WPA2 Enterprise.
    2. In the Apple only settings section, in the Accepted EAP Types field, select the TLS option.

    3. In the Windows only settings section, in the Accepted EAP Types field, select the TLS option.

    4. In the Windows only settings section, in the Credential source field, select the Certificate Store option and activate the Simple certificate selection checkbox.

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

      Iru shows the Configure SCEP pane on the right-hand side.

  11. In the Configure SCEP pane:
    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.

      Warning:
      Iru shows the Challenge field in plain text. Anyone who can open this library item in Iru can see the SCEP password. Make sure that only trusted administrators have access to it.
    3. In the Fingerprint field, paste the tenant CA thumbprint that you copied earlier from Portnox Cloud.

      Windows devices need this value to select the SCEP certificate during authentication.

      Important:
      At the time of writing, Iru Wi-Fi library items with SCEP don’t install on iOS and iPadOS devices because of a bug in Iru related to the Fingerprint field. This happens even if you leave this field empty. Iru is working on a fix, which may already be available. Test the library item on an iOS or iPadOS device before you deploy it. If it doesn’t install, the only workaround is to build a custom profile for iOS/iPadOS from scratch, for example, using iMazing Profile Editor. Don’t delete or change any Wi-Fi profiles that currently work on iOS or iPadOS devices. Any change may stop them from working.
    4. In the Subject field, type CN=$EMAIL for user certificates, or CN=$DEVICE_NAME for device certificates.

      $EMAIL and $DEVICE_NAME are Iru global variables. Iru replaces them with the email address of the user assigned to the device and with the device name. For the full list of variables, see the following topic: Global Variables.

      Iru adds the $PROFILE_UUID variable to the CN automatically. Iru needs this variable to renew certificates automatically. You don’t see this variable in the Subject field, but the issued certificate contains it.

      If you use device certificates, Portnox Cloud can’t match the devices with accounts in your authentication repository. It creates Portnox accounts for the devices instead and names each account using the value of the Subject field. You must then assign these accounts to the correct groups in Portnox Cloud manually. You can also use CN=$SERIAL_NUMBER, but a human-readable device name makes the accounts easier to find in Portnox Cloud.

    5. For user certificates, activate the Subject Alternative Names (SAN) checkbox. Then, in the SAN type field, select the NT Principal Name option, and in the value field, type $EMAIL.

      For device certificates, leave this checkbox cleared.

      Important:
      By default, Portnox Cloud matches users with an external authentication repository using the SAN UPN field (NT Principal Name in macOS), not the Subject. If you use an external authentication repository and skip this setting, Portnox Cloud can’t match the users. To understand how Portnox Cloud matches the identity in the certificates with the authentication repository, see the following section: Certificate identity information.
    6. In the Key usage field, select the Both signing and encryption option.

    7. Activate the Automatic profile redistribution checkbox and set the number of days that suits your environment.

      Important:
      Portnox Cloud can’t monitor or track the validity of SCEP certificates that it issues. It only provides the service that lets a device request a supplicant certificate when the UEM/MDM starts the process. The UEM/MDM is fully responsible for certificate renewal and expiration warnings. In Iru, you manage this using the Certificate expiration notification and Automatic profile redistribution fields. If you don’t enable them, certificates don’t renew, and devices lose access after the certificates expire.
    8. In the Mac only settings section, activate the Certificate expiration notification checkbox and set the number of days.

      We recommend that you use the same number of days as in the Automatic profile redistribution field.

    9. Keep the default values of all other fields, or adjust them to the needs of your environment. Then, click on the Done button in the bottom-right corner of the Configure SCEP pane.

  12. In the Certificate trust section:
    1. Activate the Specify trusted certificates checkbox, click on the Drag file here or choose file tile, and select the root CA certificate that you downloaded earlier (for example, the rootCertificate.cer file).

    2. Activate the Specify server certificate names checkbox, click on the Add button, and in the Server certificate name field, type clear-rad.portnox.com.

      Note:
      To learn more about this option, see the following section: Trusted certificate server names.
  13. Keep the default values of all other fields, or adjust them to the needs of your environment. Then, click on the Save button in the bottom-right corner of the screen.

Create an Ethernet library item in Iru

In this section, you will create a library item that configures your managed Ethernet network.

Note:
At the time of writing, Iru supports Ethernet library items only for macOS devices. That’s why this section covers only macOS. Iru may add support for Windows devices in the future.
Note:
Iru doesn’t let you create a separate SCEP configuration and link it to several library items. You must add the same SCEP and certificate trust settings to the library item for each network type. If you change these settings later, change them in both the Wi-Fi and the Ethernet library items.
  1. In the Iru left-hand menu, click on the Endpoint > Library option.

    Iru shows the Library screen.

  2. In the top-right corner of the Library screen, click on the Add Library Item button.

    Iru shows the Add Library Item screen.

  3. In the search box, type Ethernet, and then click on the Ethernet tile in the Profiles section.

  4. In the bottom-right corner, click on the Add and configure button.

    Iru shows the configuration screen for the new library item.

  5. In the Add a title field at the top of the screen, enter the name for the new library item.

  6. In the Assignment section, next to the Blueprint field, click on the Assign button, and select your blueprint.

  7. In the Authentication section:
    1. In the Accepted EAP Types field, select the TLS option.

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

      Iru shows the Configure SCEP pane on the right-hand side.

  8. In the Configure SCEP pane:
    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.

      Warning:
      Iru shows the Challenge field in plain text. Anyone who can open this library item in Iru can see the SCEP password. Make sure that only trusted administrators have access to it.
    3. In the Fingerprint field, paste the tenant CA thumbprint that you copied earlier from Portnox Cloud.

    4. In the Subject field, type CN=$EMAIL for user certificates, or CN=$DEVICE_NAME for device certificates.

      $EMAIL and $DEVICE_NAME are Iru global variables. Iru replaces them with the email address of the user assigned to the device and with the device name. For the full list of variables, see the following topic: Global Variables.

      Iru adds the $PROFILE_UUID variable to the CN automatically. Iru needs this variable to renew certificates automatically. You don’t see this variable in the Subject field, but the issued certificate contains it.

      If you use device certificates, Portnox Cloud can’t match the devices with accounts in your authentication repository. It creates Portnox accounts for the devices instead and names each account using the value of the Subject field. You must then assign these accounts to the correct groups in Portnox Cloud manually. You can also use CN=$SERIAL_NUMBER, but a human-readable device name makes the accounts easier to find in Portnox Cloud.

    5. For user certificates, activate the Specify Subject Alternative Names (SAN) checkbox. Then, in the SAN type field, select the NT Principal Name option, and in the value field, type $EMAIL.

      For device certificates, leave this checkbox cleared.

      Important:
      By default, Portnox Cloud matches users with an external authentication repository using the SAN UPN field (NT Principal Name in macOS), not the Subject. If you use an external authentication repository and skip this setting, Portnox Cloud can’t match the users. To understand how Portnox Cloud matches the identity in the certificates with the authentication repository, see the following section: Certificate identity information.
    6. In the Key usage field, select the Both signing and encryption option.

    7. Activate the Certificate expiration notification checkbox and set the value according to your environment needs.

    8. Activate the Automatic profile redistribution checkbox and set the number of days that suits your environment.

      Note:
      We recommend that you use the same number of days as in the Certificate expiration notification field.
      Important:
      Portnox Cloud can’t monitor or track the validity of SCEP certificates that it issues. It only provides the service that lets a device request a supplicant certificate when the UEM/MDM starts the process. The UEM/MDM is fully responsible for certificate renewal and expiration warnings. In Iru, you manage this using the Certificate expiration notification and Automatic profile redistribution fields. If you don’t enable them, certificates don’t renew, and devices lose access after the certificates expire.
    9. Keep the default values of all other fields, or adjust them to the needs of your environment. Then, click on the Done button in the bottom-right corner of the Configure SCEP pane.

  9. In the Certificate trust section:
    1. Activate the Specify trusted certificates checkbox, click on the Drag file here or click to upload tile, and select the root CA certificate that you downloaded earlier (for example, the rootCertificate.cer file).

    2. Activate the Specify server certificate names checkbox, click on the Add certificate name link, and in the Server certificate name field, type clear-rad.portnox.com.

      Note:
      To learn more about this option, see the following section: Trusted certificate server names.
  10. Keep the default values of all other fields, or adjust them to the needs of your environment. Then, click on the Save button in the bottom-right corner of the screen.