Home Knowledge Base SecureW2 Documentation Iru ACME-Based Certificate Issuance with JoinNow

Iru ACME-Based Certificate Issuance with JoinNow

Introduction

SecureW2 ACME service can enroll Apple devices with certificates. It can cryptographically prove that a device is a genuine Apple product and confirm its serial number using Apple Managed Device Attestation (MDA). MDA enables JoinNow CloudConnector to validate a device’s identity and cross-reference it with your MDM to ensure only trusted devices can enroll for certificates.

This guide describes how to integrate Iru MDM with the JoinNow Cloud Connector to enable devices running macOS, iOS, iPadOS, and tvOS to enroll for digital certificates via ACME.

Prerequisites

  1. Active Iru subscription
  2. Active JoinNow CloudConnector subscription along with the Enterprise Enrollment and Attestation (EEA) add-on
  3. iOS or macOS devices (that support the ACME protocol) actively managed in Iru

Configuring JoinNow Management Portal

To configure ACME-based enrollment with the JoinNow Management Portal, the following high-level steps are required:

  1. Create an Intermediate CA
  2. Create an Iru Certificate Template
  3. Create an ACME API Token
  4. Create a Generic HTTP Signal Source
  5. Create Policies

Creating an Intermediate CA for Iru

As a best practice, it is recommended to have a new intermediate CA for ACME Gateway-based integrations with Iru.

To create a new intermediate CA:

  1. Log in to the JoinNow Management Portal.
  2. Navigate to PKI > Certificate Authorities.
  3. Click Add Certificate Authority.
  4. In the Basic section, from the Generate CA For drop-down list, select the Device and User Authentication option to authenticate devices and users.
  5. From the Type drop-down list, select Intermediate CA.
  6. From the Certificate Authority drop-down list, select the default Root CA that comes with your organization.
  7. From the Generate via drop-down list, select Internal system.
  8. For the Common Name field, enter a name.  It is recommended to use a name that includes ‘ACME’.
  9. From the Key Size drop-down list, select 2048 for the CA certificate key pair.
  10. From the Signature Algorithm drop-down list, select the signature algorithm for the certificate signing request. The option available is SHA-256.
  11. In the Validity Period (in years) field, enter the validity period of the CA certificate.
  12. Click Save.

The new intermediate CA is generated.

Creating a Certificate Template for Iru

A certificate template determines how information is encoded in the certificate to be issued by the Certificate Authority. The template consists of a list of certificate attributes and the encoding required for their values. This information is provided by the Admin in the JoinNow Management Portal.

It is recommended to create a separate template for each MDM platform to make it easier to identify the different values being passed. 

To create an Iru certificate template, perform the following steps:

  1. Navigate to Dynamic PKI > Certificate Authorities.
  2. Scroll down to the Certificate Templates.
  3. Click Add Certificate Template.
  4. Under the Basic section, in the Name field, enter the name of the certificate template.
  5. In the Subject field, enter CN=${/csr/subject/commonname} to source attributes from Iru.
  6. In the Display Description field, enter a suitable description for the certificate template.
  7. In the Validity Period field, type the validity period of the certificate (based on the requirement).
  8. From the Signature Algorithm drop-down list, select the signature algorithm for the certificate signing request.
  9. In the SAN section:
    1. In the Other Name field, enter ${/csr/san/othername}
    2. In the RFC822 field, enter ${/csr/san/rfc822name}
    3. In the DNS field, enter ${/csr/san/dnsname}
  10. In the Extended Key Usage section, from the Use Certificate For list, select Client Authentication.
  11. Click Save.

Creating a Device Management Platform

In this section, we create a Device Management Platform, which generates a .mobileconfig file containing the configuration required for ACME certificate enrollment. This file is uploaded to Iru as a custom profile, where it configures managed devices to obtain certificates through the SecureW2 ACME service.

  1. Navigate to Integration Hub > Device Management Platforms.
  2. Click Add.
  3. In the Basic section, enter the name of the device management platform in the Name field.
  4. In the Description field, enter a suitable description for the device management platform.
  5. From the Type drop-down list, select ACME Client Certificate Enrollment Token.
  6. From the Vendor drop-down list, select Iru (Kandji).
  7. Click Save. A .mobileconfig file containing the ACME enrollment configuration is downloaded.

Creating a Signal Source

In this section, create a Generic HTTP Signal Source, which is used to perform a device lookup with Iru during ACME certificate enrollment.

To create a generic HTTP signal source, perform the following steps:

  1. Navigate to Integration Hub > Core Platforms.
  2. Click Add.
  3. In the Basic section, enter the name of the signal source in the Name field.
  4. From the Type drop-down list, select Generic HTTP under the Signal Source category.
  5. Click Save. The page refreshes, and the Configuration, API, Attribute Mapping, and Groups are displayed.
  6. Click the Configuration tab.
    1. From the Authentication Method drop-down list, select Bearer Token.
    2. In the Bearer Token field, enter the token value obtained in the Creating a Token in Iru section.
  7. Click the API tab.
    1. In the URI field, enter your tenant’s API host URL (copied from Iru), and append the following path: /api/v1/devices/${identity}/details. So the URI value will be https://productteam-securew2.api.kandji.io/api/v1/devices/${identity}/details
    2. In the Validation section, click Add, then add the attributes required for device validation based on your business requirements. For example:

      Response Path

      Condition

      Expected Result

      kandji_agent.agent_installed

      Equals

      True

      automated_device_enrollment

      Equals

      True

    3. Click Validate. The Validate pop-up window appears.
    4. In the Validate pop-up window, enter the device ID and click Validate. The message Connection verified successfully is displayed, confirming that the configuration is reachable and can identify and parse the specified return attributes. This configuration is used each time device validation is triggered during enrollment or authentication.
  8. Click Update.

Creating a Key Attestation Provider

In this section, you configure device attestation for iOS devices. To create a key attestation provider, perform the following steps:

  1. Navigate to Integration Hub > Key Attestation Platforms.
  2. Click Add.
  3. In the Name field, enter a name for your key attestation provider.
  4. In the Display Description field, enter a description (Optional).
  5. From the Type drop-down list, select Apple.
  6. Click Save.

Policy Management

This section outlines the policies required in the JoinNow Management Portal to enable ACME-based certificate enrollment.

  1. Security Signal Source
  2. Policy Workflow
  3. Device Role Policy
  4. Enrollment Policy

Creating a Security Signal Source

A Security Signal Source acts as a filter that determines whether a device exists before deciding whether to invoke an Enrollment policy.

Here, you specify which field in the certificate contains the device’s identifying attribute, and instruct SecureW2 to use the Generic HTTP Signal Source configured earlier to look up whether the device exists.

To create a security signal source, perform the following steps:

  1. Navigate to Policy Management >  Security Signal Sources.
  2. Click Add Security Signal Source.
  3. In the Lookup Purpose field, select Certificate Issuance to look up the device account during enrollment.
  4. Click Save. The page refreshes, and the Conditions and Settings tabs are displayed.
  5. Click the Settings tab.
    1. From the Provider drop-down list, select the signal source created earlier in the Creating a Signal Source section.
    2. From the Lookup Type drop-down list, select Device to perform a device-based lookup.
    3. From the Identity drop-down list, select the attribute where the device ID is encoded. The displayed attributes depend on the Lookup Type selected earlier.
  6. Select the Revoke On Failure checkbox to automatically revoke a certificate if an account lookup fails.
  7. Click Validate Configuration.
  8. On the Validate Configuration dialog, enter the device ID and click Validate.
  9. On the Security Signal Details dialog box, the “Account validation successful” message is displayed, and the Attributes section displays the device attributes being looked up.
  10. Click Update.

Creating a Policy Workflow

A Policy Workflow segments devices based on predefined criteria and associated attributes, with each segment identified as a distinct Policy Workflow.

To create a policy workflow, perform the following steps:

  1. Navigate to Policy Management > Policy Workflows.
  2. Click Add Policy Workflow.
  3. In the Basic section, enter the name of the policy workflow in the Name field.
  4. In the Display Description field, enter a suitable description for the policy workflow.
  5. Click Save. The page refreshes, and the Conditions tab is displayed. 
  6. Select the Conditions tab.
    1. From the Core Provider drop-down list, select the signal source you created earlier in the Creating a Signal Source section.
  7. Click Update.

Creating a Device Role Policy

A Device Role Policy maps the Key Attestation Provider for device attestation. To create a device role policy, perform the following steps:

  1. Navigate to Policy Management > Device Role.
  2. Click Add Device Role Policy.
  3. In the Basic tab, enter a name for the device role policy in the Name field.
  4. In the Description field, enter a description for the device role policy.
  5. Click Save. The page refreshes, and the Conditions tab opens.
  6. Select the Conditions tab.
  7. From the Identity drop-down list, select the key attestation provider created earlier in the Creating a Key Attestation Provider section.
  8. Click Update.

Creating an Enrollment Policy

An Enrollment Policy defines the certificate template and Certificate Authority used for each Policy Workflow. It leverages the segmentation established in the Policy Workflow to ensure the appropriate certificate template is issued for each workflow.

To create an enrollment policy, perform the following steps:

  1. Navigate to Policy Management > Enrollment.
  2. Click Add Enrollment Policy.
  3. In the Basic section, in the Name field, enter a name for the enrollment policy.
  4. In the Description field, enter a description for the enrollment policy.
  5. Click Save. The page refreshes, and the Conditions tab is displayed.
  6. Click the Conditions tab.
    1. In the Policy Workflow list, select the policy workflow created earlier in the Creating a Policy Workflow section.
    2. In the Device Role list, select the device role policy created earlier in the Creating a Device Role Policy section.
  7. Click the Settings tab.
    1. From the Use Certificate Authority drop-down list, select the intermediate CA created earlier in the Creating an Intermediate CA for Iru section.
    2. From the Use Certificate Template drop-down list, choose the certificate template created earlier in the Creating a Certificate Template for Iru section.
  8. Click Update.

Configuring Iru

Configuring Iru for certificate enrollment via ACME requires the following high-level steps:

  1. Creating an API Token
  2. Creating a New Blueprint
  3. Adding a Custom Profile to the Iru Library
  4. Adding Devices to Iru MDM
  5. Assigning a Device to the Blueprint

Creating an API Token in Iru

In this section, create a scoped API token in Iru, which allows SecureW2 to query device attributes during ACME certificate enrollment.

To create a new token, perform the following steps:

  1. Log in to the Iru portal.
  2. In the bottom-left corner, click your profile icon, then select Access.
  3. On the Access page, select the API tokens tab.
  4. Copy the API URL for your organization. This URL is used later when configuring the Generic HTTP Signal Source.
  5. Click Add token.
  6. In the Name field, enter a name for the API token.
  7. In the Description field, enter a description (optional).
  8. Click Create.
  9. Copy the token and save it in a text editor. You’ll use this token when configuring the Generic HTTP Signal Source.
  10. Click Next. The Manage API Permissions pop-up window opens.
  11. On the Manage API Permissions pop-up window, click Configure.
  12. On the token’s details page, click Configure Permissions.
  13. Select the Permissions tab.
  14. In the Devices section, expand Device Information and select the following permissions:

    Permission

    Endpoint

    Description

    Device details

    /api/v1/devices/{device_id}/details

    Get the full details for a specific device

    Device list

    /api/v1/devices

    Get a list of all devices

    Device Status

    /api/v1/devices/{device_id}/status

    Get Library Items and Parameters for device

  15. Click Save, then Close.

Creating a New Blueprint

In this section, create a new Blueprint. This step is optional — if a Blueprint already exists for your organization, you can use it instead. To create a new one, start from scratch or choose from a pre-filled template.

To create a new Blueprint, perform the following steps:

  1. On the left pane, navigate to Blueprints.
  2. In the top-right corner, click + Add Blueprint.
  3. On the Create Blueprint pop-up window, click Start from scratch.
  4. On the Create Blueprint pop-up window, enter a name in the Blueprint name field, and a description in the Description field (optional).
  5. Click Create Blueprint.

Adding a Custom Profile to the Iru Library

This section adds the .mobileconfig file obtained from the JoinNow Management Portal as a Custom Profile in the Iru Library and maps it to the Blueprint created earlier for device deployment.

To add a custom profile to the Iru Library, perform the following steps:

  1. On the left pane, click LIBRARY, and then click + Add Library Item.
  2. On the Add Library Item page, in the search bar, search for Custom Profile.
  3. Select Custom Profile, and click Add and Configure.
  4. On the displayed page, in the Add a title field, enter a name for the Custom Profile.
  5. From the Install on drop-down list, select the devices for enrollment.
  6. In the Assignment section, click + Assign and select the Blueprint created earlier in the Creating a New Blueprint section.
  7. In the Settings section, under Profile, upload the .mobileconfig file obtained from the JoinNow Management Portal (refer to the Creating a Device Management Platform section).
  8. Click Save, then Close.

Adding Devices to Iru MDM

This section generates the Enrollment Portal link and Enrollment code, which users use to self-enroll their devices in Iru.

To add devices to Iru MDM, perform the following steps:

  1. On the left pane, click Enrollment.
  2. Click the Manual Enrollment tab.
  3. Under Choose an enrollment method, select Enrollment portal with code.
  4. Copy the Enrollment Portal link.
  5. Under Select Blueprint to enroll the device into, search for the Blueprint created earlier, and copy its Enrollment code.
  6. Share the Enrollment Portal link and Enrollment code with users.

The user accesses the Enrollment Portal link and enters the Enrollment Code to enroll their device in the corresponding Blueprint.

Assigning a Device to the Blueprint

This section maps an enrolled device to the Blueprint, so the ACME certificate profile is pushed to the device.

To assign a device to the Blueprint, perform the following steps:

  1. On the left pane, click Devices. The devices added to the Blueprint are displayed on the page.
  2. Click the added device.
  3. On the displayed page, click Edit device details.
  4. Click Edit Blueprint.
  5. On the Assign Blueprint pop-up window, from the Assign device to the Blueprint drop-down list, select the Blueprint created earlier in the Creating a New Blueprint section.
  6. Click Change. The profile is automatically pushed to the device, and a success message is displayed.

Certificate Issuance

After completing the steps above, the profile is pushed to the device, followed by certificate enrollment. 

Admins can verify successful certificate enrollment under Data and Monitoring > Enhanced Events, where a Certificate Issued event is displayed once the device certificate is successfully issued.

More Iru Explainers
Reseller or MSP? Join our Partner Program