Onboard devices with AgentP using Iru

In this topic, you will learn how to deploy Portnox™ AgentP on managed macOS and Windows devices by using Iru.

Note:

Iru was previously called Kandji.

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.

Open your Iru instance in the browser and log in.
For example, vorlon.iru.com
In the Iru left-hand menu, click on the Endpoint > Blueprints option.

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

Iru shows the Create Blueprint window.
In the Create Blueprint window, click on the Start from scratch tile.
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.
In the top-right corner, click on the Save button.

Iru shows the Assignment Map tab of the new blueprint.

Deploy AgentP on macOS devices

In this section, you will deploy Portnox™ AgentP on managed macOS devices using an Iru Mac Custom App library item.

There are two options to deploy AgentP on managed macOS devices using Iru:

Onboard devices using SCEP certificates and use AgentP for risk assessment only (recommended)
Deploy AgentP and have the users onboard manually

If you choose the first option, begin by completing the steps in the following topic: Onboard devices with certificates using Iru and SCEP. Then, continue with steps in the current section.

Note:

Do not install AgentP on managed macOS devices before you complete the certificate-based onboarding. If you already installed AgentP, make sure to uninstall it and delete all related configuration and profiles.

Get issuer information from Portnox Cloud

In this task, you will copy the issuer name from the Portnox™ Cloud portal, so you can use it later when creating a configuration script for AgentP.

In the Cloud portal top menu, click on the Settings option.
In the Cloud portal left-hand side menu, click on the Services > GENERAL SETTINGS > Trusted Root Certificates option.
In the Trusted Root Certificates section, copy the value of the Issued to field in this section to a text file.

macOS: Create a Mac Custom App library item for AgentP

In this section, you will download the Portnox™ AgentP installation package for macOS and add it to an Iru library item that installs it on managed macOS devices.

Open the Download Portnox AgentP page in your browser.
Click on the tile that represents the macOS system to download the AgentP installer.
Open your Iru instance in the browser and log in.
For example, vorlon.iru.com
In the Iru left-hand menu, click on the Endpoint > Library option.

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

Iru shows the Add Library Item screen.
In the search box, type custom app, and then click on the Mac Custom App tile in the General section.
In the bottom-right corner, click on the Add and configure button.

Iru shows the configuration screen for the new library item.
In the Add a title field at the top of the screen, enter the name for the new library item.
Next to the Assignment Maps field, click on the Assign button, and select your blueprint.
In the Installation section, make sure that the Install once per device option is selected.

Note:
The Audit and enforce option requires a custom audit script, which this topic doesn’t cover.
In the Install Details section, make sure that the Installer Package option is selected.
Click on the Add Preinstall Script button.

Iru shows the Preinstall Script field.

Enter the script code in the Preinstall Script field.

Adjust your script to your environment and requirements (see: AgentP configuration/installation options).

mkdir -p /var/agentp
json='{"HideUI":true}'
echo $json > /var/agentp/uipreferences.cfg
json='{"Mode":"certificate","Certificate":"issuer:issued_to","AutoSwitch":true,"UseCertificateSerialNumberAsDeviceId":true,"Domain":"your_domain","profileInstallationNeeded":false}'
echo $json > /var/agentp/unattended.cfg
chmod a+rw /var/agentp
chmod a+rw /var/agentp/uipreferences.cfg
chmod a+rw /var/agentp/unattended.cfg

As issued_to, paste the value that you copied earlier from the Portnox Cloud portal.

For example:

json='{"Mode":"certificate","Certificate":"issuer:Vorlon - Portnox CLEAR","AutoSwitch":true,"UseCertificateSerialNumbeurAsDeviceId":true,"Domain":"your_domain","profileInstallationNeeded":false}'

As your_domain, use the domain serviced by Portnox Cloud (the domain configured in your authentication repository integration).

For example:

json='{"Mode":"certificate","Certificate":"issuer:Vorlon - Portnox CLEAR","AutoSwitch":true,"UseCertificateSerialNumberAsDeviceId":true,"Domain":"vorlon.com","profileInstallationNeeded":false}'

If you did not onboard macOS devices using SCEP certificates and you want AgentP to download the profile and have the user of the device confirm profile installation, set profileInstallationNeeded to true.
For example:
```
json='{"Mode":"certificate","Certificate":"issuer:Vorlon - Portnox CLEAR","AutoSwitch":true,"UseCertificateSerialNumberAsDeviceId":true,"Domain":"vorlon.com","profileInstallationNeeded":true}'
```

Click on the Drag file here or choose file tile, and select the AgentP installation package file that you downloaded earlier (PortnoxAgentP.pkg).
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.

Deploy AgentP on Windows devices

In this section, you will deploy Portnox™ AgentP on managed Windows devices using an Iru Windows Custom App library item.

Prepare the AgentP installation files

In this section, you will download the Portnox™ AgentP MSI package for Windows and prepare the files and values that Iru needs.

Open the Download Portnox AgentP page in your browser.
Scroll down to the Windows files section and click on the tile that matches the architecture of your managed Windows devices to download the AgentP MSI package.

Note down the version number from the file name. You will need it later.

For example, in the file name PortnoxAgentP64_1.1.360.msi, the version number is 1.1.360.
Open Windows PowerShell and run the following script to read the product code from the MSI package. In the first line, replace the path with the path to the downloaded MSI file.
Note:
Iru uses the product code to detect whether AgentP is installed. If you don’t want Iru to detect the installation, or if you want to use a different detection method, such as files or registry values, skip this step. This guide doesn’t cover other detection methods.
```
$path = "C:\path\to\PortnoxAgentP.msi"
$installer = New-Object -ComObject WindowsInstaller.Installer
$db = $installer.GetType().InvokeMember("OpenDatabase", "InvokeMethod", $null, $installer, @($path, 0))
$view = $db.GetType().InvokeMember("OpenView", "InvokeMethod", $null, $db, ("SELECT Value FROM Property WHERE Property='ProductCode'"))
$view.GetType().InvokeMember("Execute", "InvokeMethod", $null, $view, $null)
$record = $view.GetType().InvokeMember("Fetch", "InvokeMethod", $null, $view, $null)
$record.GetType().InvokeMember("StringData", "GetProperty", $null, $record, 1)
$view.GetType().InvokeMember("Close", "InvokeMethod", $null, $view, $null)
```
PowerShell shows the product code. Copy it, including the curly brackets, and paste it in a text file for later use.
For example: {5AA5FEB1-A27A-4774-A53D-AA01F914B338}
Run the following script to extract the AgentP icon from the MSI package. In the first line, replace the path with the path to the downloaded MSI file.
Note:
Iru requires an app icon, and you can’t save the library item without one. If you prefer, you can use your own PNG file instead, for example, with your company logo. In that case, skip this step.
```
$msi = "C:\path\to\PortnoxAgentP.msi"
$out = "$env:USERPROFILE\Downloads\AgentP_extracted"
Start-Process msiexec.exe -ArgumentList "/a `"$msi`" /qb TARGETDIR=`"$out`"" -Wait
Add-Type -AssemblyName System.Drawing
$exe = Get-ChildItem $out -Recurse -Filter "*.exe" | Select-Object -First 1
$exe.FullName
$icon = [System.Drawing.Icon]::ExtractAssociatedIcon($exe.FullName)
$icon.ToBitmap().Save("$env:USERPROFILE\Downloads\agentp_icon.png", [System.Drawing.Imaging.ImageFormat]::Png)
```
The script unpacks the MSI package without installing it and saves the icon as agentp_icon.png in your Downloads folder.
In File Explorer, right-click on the downloaded MSI file and select Compress to... > ZIP File.

Note:
Iru accepts only .zip files, so you can’t upload the MSI file directly.

Windows creates a .zip file with the same name in the same folder.

Create a Windows Custom App library item for AgentP

In this section, you will create an Iru library item that installs Portnox™ AgentP on managed Windows devices.

Open your Iru instance in the browser and log in.
For example, vorlon.iru.com
In the Iru left-hand menu, click on the Endpoint > Library option.

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

Iru shows the Add Library Item screen.
In the search box, type custom app, and then click on the Windows Custom App tile in the General section.
In the bottom-right corner, click on the Add and configure button.

Iru shows the configuration screen for the new library item.
In the Add a title field at the top of the screen, enter the name for the new library item.
Next to the Assignment Maps field, click on the Assign button, and select your blueprint.
In the Installation options section, select the Install and continuously enforce option.

Note:
With this option, Iru checks (at each daily check-in) whether AgentP is installed, and installs it again if it’s missing. If you select the Install once per device option instead, Iru installs AgentP once and doesn’t reinstall it, for example, if the user uninstalls it. Choose the option that matches your requirements and skip related next steps if you do not select enforcement.
In the Enforcement timeframe section, in the Enforcement deadline field, select the Immediately option.

Note:
If the security policies of your organization let users delay the installation, you can select the By enforcement deadline option instead.
In the Application details section:
1. In the Publisher field, enter Portnox.
2. In the Name field, enter AgentP.
3. In the Version field, enter the version number from the file name of the MSI package that you downloaded earlier.
4. In the App icon section, click on the Drag file here or choose file tile, and select the agentp_icon.png file that you extracted earlier or your own PNG file.
5. In the Upload app section, click on the Drag file here or choose file tile, and select the .zip file that you created earlier.
Configure the detection logic:
1. In the Detection logic rules field, select the MSI option.
  
  Note:
  If MSI detection doesn’t meet your requirements, you can select the File, Folder, or Registry option instead. In that case, you must design the detection logic yourself. This guide doesn’t cover it.
2. In the MSI product code field, paste the product code that you copied earlier, including the curly brackets.
  
  Important:
  The product code may change between AgentP versions. Each time you upload a new MSI package to this library item, run the product code script again and update this field if the value is different.
3. In the Check MSI product version section, select the No option.
  
  Note:
  You can also select the Yes option, then select the is greater than or equal to option in the Version field, and enter the version number. We don’t recommend it. AgentP updates itself automatically.
In the Architecture field, select the architecture that matches the MSI package that you downloaded.

For example, select x64 for PortnoxAgentP64_1.1.360.msi.
In the Install command line parameters field, enter msiexec /i msi_file_name /qn UI_LAUNCH=1, where msi_file_name is the name of the MSI file inside the .zip file.

Note:
The /qn option makes AgentP onboard automatically with the Windows user account, so users don’t have to onboard manually. The UI_LAUNCH=1 option hides the onboarding window during this process. Automatic onboarding works only on computers joined to Microsoft Entra ID or Active Directory. On other computers, users must onboard manually. For the full list of AgentP installation options, see the following topic: AgentP configuration/installation options.

For example: msiexec /i PortnoxAgentP64_1.1.360.msi /qn UI_LAUNCH=1
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.