Home Knowledge Base Documentation Dynamic ACME DA Kandji Configuration Guide

Dynamic ACME DA Kandji Configuration Guide

Introduction

SecureW2’s ACME service can cryptographically prove a device is a genuine Apple Product, and confirm its Serial Number using Apple Managed Device Attestation (MDA). MDA is what allows JoinNow Connector to validate a device’s identity and cross-reference it with your MDM to ensure only trusted devices can enroll for certificates.

Traditional SCEP implementations only require a pre-shared key for certificate issuance. With ACME, organizations can ensure that only trusted, managed devices obtain and maintain certificates that are used to access critical resources. This guide describes the steps to integrate Kandji MDM with JoinNow’s Cloud Connector to allow devices such as macOS, iOS, iPadOS, and tvOS to enroll for digital certificates via an ACME (Automated Certificate Management Environment) Client Certificate Enrollment token.

Prerequisites

The following are the prerequisites to set-up ACME based enrollment:

  1. Active Kandji 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 Kandji

Configuring JoinNow Management Portal

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

Creating an Intermediate CA for Kandji SCEP Gateway Integration

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

To create a new intermediate CA:

  1. Log in to the JoinNow Management Portal.
  2. Navigate to Dynamic 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 (private key locked and non-exportable).
  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 for the Intermediate CA in terms of the number of years.
  12. In the Notifications section:
    1. From the Expiry Notification Frequency (in days) drop-down list, select the frequency interval for which a certificate expiration notification should be sent to users.
    2. Select the Notify user on successful Enrollment checkbox to notify users after a successful enrollment.
    3. If the RFC has a valid email address, the user will receive the certificate-issued or expired notification; otherwise, they will not receive the notification.
  13. In the Revocation section:
    1. In the Revoke Certificate if unused for field, select the number of days after which an unused certificate can be revoked.
      • Since last usage – Select this checkbox to revoke the certificate after a specified number of days if it remains unused.
      • Since certificate issuance – Select this checkbox to revoke the certificate after a specified number of days after it is issued.
    2. From the Reason Code drop-down list, select any one of the following reasons for which the certificate is revoked.
        • Certificate Hold
        • AA Compromise
        • Privilege Withdrawn
        • Unspecified

  14. Click Save. This generates the new intermediate CA.

Creating a Certificate Template for Kandji

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 how the information must be encoded in the attribute 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 for easier identification of different values being passed. To create a Kandji certificate template:

  1. Navigate to Dynamic PKI > Certificate Authorities.
  2. Click Add Certificate Template.
  3. In the Basic section, enter the name of the certificate template in the Name field.
  4. In the Subject field, enter CN=${/csr/subject/commonname}. This field can be configured to source values from Kandji MDM.
  5. In the Display Description field, enter a suitable description for the certificate template.
  6. In the Validity Period field, type the validity period of the certificate (based on the requirement).
  7. To override the Validity Period attribute, select the Override Validity Period checkbox and choose the end date from the date picker to set a hard-coded date as the expiry date of a certificate.
  8. From the Signature Algorithm drop-down list, select SHA-256 as 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}
    4. In the URI field, enter ${/device/userDescription}
  10. In the Extended Key Usage section, from the Use Certificate For list, select Client Authentication.
  11. Click Save.

Creating an ACME Device Management Platform

To generate an ACME Device Management Platform​:

  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 Kandji.
  7. Click Save. A .mobileconfig file is downloaded.

Creating a Generic HTTP Signal Source

With JoinNow, you can create a Generic HTTP-based Signal Source. This is necessary to configure a device lookup with Kandji during ACME certificate enrollment.

  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. In the Description field, enter a suitable description for the Signal Source.
  5. From the Type drop-down list, select Generic HTTP.
  6. Click Save. The page refreshes, and the Configuration, API, Attribute Mapping, and Groups.
  7. Click the Configuration tab.
  8. From the Authentication Method drop-down list, select Bearer Token.
  9. In the Bearer Token field, enter the token value obtained from Kandji.
  10. Click the API tab.
  11. In the URI field, enter the organization’s API URL (obtained in step 3 of the Enrolling Devices to Kandji MDM section).
  12. In the Response Validation section, click Add.
    1. In the Response Path field, enter data[0].serial_number
    2. From the Condition drop-down list, select Exists.
    3. In the Expected result field, enter a valid device serial number.
    4. Click Validate to verify that the configuration is correct.
  13. Click Update.

Creating a Key Attestation Platform

A Key Attestation Provider in JoinNow helps set up device attestation services for iOS devices. To create a Key Attestation Provider:

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

Policy Management in JoinNow

Policy management helps admins define and create various policies that associate rules with identity providers. These rules are configured for user authentication via network profiles.

Creating a Security Signal Source

The Security Signal Source can be mapped along with the Generic HTTP Signal Source created earlier for device lookup.

  1. Go to Policy Management > Security Signal Sources.
  2. Click Add Security Signal Source.
  3. In the Basic section, enter a name and description in the respective fields.
  4. Lookup Purpose – Purpose of Account Lookup
    1. Certificate Issuance – To lookup user/device account during Enrollment.
    2. RADIUS Authentication – To lookup user/device account during RADIUS Authentication.
  5. Click Save.
  6. The page refreshes, and the Conditions and Settings tabs are displayed.
  7. Click the Settings tab.
  8. From the Identity Provider Lookup drop-down list, select the Generic HTTP Signal Source created earlier.
  9. From the Identity drop-down list, select the options based on your business requirements.
    • Custom – The Org Admin can select this option to add custom lookup attributes for both Enrollment and RADIUS authentication, in addition to the listed options, during device lookup.
    • CSR – The Org Admin can select any CSR attribute as the lookup attribute for Enrollment during device lookup.
    • Certificate – The Org Admin can select any certificate attribute as the lookup attribute for RADIUS authentication during device lookup.
  10. Select the Revoke On Failure checkbox to automatically revoke a certificate if an account lookup fails, if necessary.
  11. Click the Validate Configuration button to check if the lookup is valid.
  12. On the Validate Configuration pop-up window, in the Enter a valid identity field, enter the identity (device) to validate the lookup, and then click Validate.
  13. Click Update.

Creating a Policy Workflow

To configure a Policy Workflow:

  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.
  6. The page refreshes, and the Conditions tab is displayed. 
  7. Click the Conditions tab.
  8. From the Core Provider drop-down list, select the identity provider you created earlier in the section Creating a Generic HTTP Signal Source.

  9. In the Attributes/Groups section, for the Attribute field, retain ANY.
  10. Click Update.

Creating a Device Role

Device Role Policy helps in mapping the attestation provider in JoinNow for device attestation.

  1. Go to Policy Management > Device Role.
  2. Click Add Device Role Policy.
  3. In the Basic tab, enter a name in the Name field.
  4. For Description, enter a description.
  5. Click Save.

  6. The page refreshes, and the Conditions tab opens.
  7. Click on the Conditions tab.
  8. From the Identity drop-down list, select the Key Attestation platform created in Creating a Key Attestation Platform.
  9. Click Update.

Creating an Enrollment Policy

  1. Go 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.
  6. The page refreshes, and the Conditions and Settings tabs are displayed.
  7. Click the Conditions tab.
  8. From the Role list, select the Role policy you created in Creating a Policy Workflow.
  9. From the Device Role drop-down list, select the Device Role policy created in Creating a Device Role.
  10. Click the Settings tab.
  11. From the Use Certificate Authority drop-down list, select the Intermediate CA created in  Creating an Intermediate CA for Kandji SCEP Gateway Integration.
  12. From the Use Certificate Template drop-down list, choose the certificate template you created in the section Creating a Certificate Template for Kandji​.
  13. Click Update.

Configuring Kandji

Configuring Kandji for certificate enrollment via ACME requires:

Creating a New Blueprint

  1. In the Kandji portal, on the left pane, click BLUEPRINTS.
  2. At the top-right corner, click New Blueprint. Select New Classic Blueprint.
  3. On the displayed window, click +New Blueprint.
  4. Enter the Blueprint name and Blueprint description in the corresponding fields.
  5. Click Create Blueprint.

Creating a Kandji Library

  1. To map the Blueprint to the profile, in the left pane, click LIBRARY and then click Add new.
  2. On the displayed page, click Custom profile and then click the Add & Configure button.
  3. Near the gear symbol, enter a name for the profile.
  4. In the Assignment section, from the Blueprint drop-down list, select the Blueprint you created in the section Creating a New Blueprint.
  5. From the Install on drop-down list, select the devices for enrollment.
  6. In the Settings section, in the Profile section, upload/drag and drop the .mobileconfig file obtained from the Management Portal.
  7. Click Save.

Enrolling Devices to Kandji MDM

  1. To add the devices to the MDM, in the left pane, click ADD DEVICES. In the Add Devices section, from the Blueprint drop-down list, select the Blueprint and click Download.
  2. In the Enrollment Portal section, copy the Enrollment Portal Link, which will be sent to users to self-enroll their devices.
  3. Copy the Enrollment code, which is used during the enrollment process, to map the Blueprint used for device enrollment.


    The user should access the URL and fill in the Enrollment Code specific to the required blueprint to enroll devices in Kandji.
  4. On the left pane, click DEVICES, and the devices added to the Blueprint are displayed on the page.
  5. Click the added device.
  6. On the displayed page, in the top-right corner, click the Ellipses icon.
  7. Click Edit Blueprint Assignment.
  8. On the displayed window, from the Assign device to the Blueprint drop-down list, select the Blueprint you added.
  9. 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.

JoinNow Admins can check for successful certificate enrollment under Data and Monitoring > General Events. A Certificate Issued event should be displayed when device certificate enrollment is successful.

More Kandji Explainers