Onboard Windows devices with AgentP in unattended or kiosk mode

In this topic, you will learn how to run Portnox™ AgentP in unattended mode or kiosk mode.

Note:

To learn about different AgentP operating and installation modes, see the following topic: AgentP working and installation modes.

Install AgentP on Windows in unattended mode

In this section, you will learn how to install AgentP in unattended mode. User interaction is only necessary if AgentP cannot be onboarded automatically.

Important:

Standard AgentP unattended enrollment is only possible if the Windows device is a member of Active Directory or Entra ID, and Portnox Cloud is integrated with Active Directory or Entra ID.

Note:

To install AgentP in unattended mode, you need administrator privileges on the Windows device.

If you run AgentP in unattended mode, AgentP checks if the device is a member of Active Directory or Entra ID, and then sends AD/Entra ID identification data to Portnox Cloud (for example, the tenant ID, device ID, domain, user name, computer name). If the identification data matches the data in Cloud, AgentP can onboard in Portnox Cloud automatically using this data with no need of user interaction.

If AgentP is not installed:
1. Download the AgentP installation file from the download page.
```
curl -o agentp.msi "https://clear.portnox.com/enduser/DownloadAgentPForOsAndPackageType?osType=2&packageType=Windows_x64"
```
  Replace Windows_x64 with Windows_x86 if you have a 32-bit architecture.
2. Run the installation from the command prompt with the /qn parameter that activates unattended mode.
```
msiexec /i agentp.msi /qn
```
3. Optional: If you do not want the user to see the AgentP interface during this process, modify the above command:
```
msiexec /i agentp.msi /qn UI_LAUNCH=1
```
If AgentP is already installed in interactive mode:
1. Prepare a Windows registry file with REG_SZ (String) values that make AgentP run in unattended enrollment mode. Create a .reg file with the following content:
```
Windows Registry Editor Version 5.00
                                        
[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Portnox AgentP]
"Mode"="umode"
```
2. Optional: If you want to hide the tray icon of AgentP, use the following .reg file instead:
```
Windows Registry Editor Version 5.00
                                        
[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Portnox AgentP]
"Mode"="umode"
"TrayIcon"="hide"
```
3. Import the .reg file that you just created.
```
regedit.exe /s your_reg_file.reg
```
4. Restart the AgentP service.
```
net stop PortnoxAgentP
```
```
net start PortnoxAgentP
```
  Important:
  If AgentP is already enrolled manually, before you switch to unattended mode, you must manually unenroll it by clicking on the Deactivate button in the AgentP user interface. Otherwise, AgentP will remain enrolled with the manually onboarded user and will not automatically switch to the current Active Directory or Entra ID user.
Optional: After completion of one of the above steps, check the AgentP logs to confirm that AgentP is running in unattended mode.

The log file will contain an entry: Running in unattended mode.

To learn how to access AgentP logs, see the following topic: How to collect AgentP logs for support.

When the onboarding window appears, one of two things can happen:

If AgentP finds that the device/user are already onboarded, the onboarding window disappears after 5 to 20 seconds (after enrollment is complete), and AgentP is automatically enrolled.
Otherwise, you must follow the steps in the onboarding window to enroll the current user manually. Until then, AgentP will not be enrolled.

Note:

If AgentP cannot recognize the user/device as onboarded, it will show the onboarding window after it’s installed, even if you follow all the steps above. To make sure that no onboarding window is shown, ensure that your endpoint management software first onboards the user/device, and only then run AgentP installation. If the user/device is onboarded (can connect to the company network), and the onboarding window still appears, examine the AgentP logs for an underlying cause.

Install AgentP on Windows in kiosk mode or switch to kiosk mode

Kiosk mode means that AgentP is enrolled using the computer account, not the user account. If you already have AgentP installed in user-based mode, you can change its configuration so that it runs in kiosk mode.

Important:

This mode works only with authentication repositories that support computer accounts: Microsoft Entra ID and Active Directory. This mode cannot be used with Okta Workforce Identity or Google Workspace.

If AgentP is not installed:
1. Run the installation from the command prompt with parameters for unattended mode.
```
msiexec /i agentp.msi /qn ETYPE=computer_account
```
If AgentP is already installed:
1. Configure the Windows registry settings for AgentP to work in kiosk mode. Create a .reg file with the following REG_SZ (String) values.
```
Windows Registry Editor Version 5.00
                                    
[HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Portnox AgentP]
"Mode"="umode"
"Etype"="computer_account"
```
2. Import the .reg file that you just created.
```
regedit.exe /s your_reg_file.reg
```
3. Restart the AgentP service.
```
net stop PortnoxAgentP
```
```
net start PortnoxAgentP
```
  Important:
  If AgentP is already enrolled manually, before you switch to kiosk mode, you must manually unenroll it by clicking on the Deactivate button in the AgentP user interface. Otherwise, AgentP will remain enrolled with the manually onboarded user and will not automatically switch to the computer account in Active Directory or Entra ID.

Install AgentP on Windows in unattended mode based on SCEP certificates

In this section, you will learn how to install AgentP in unattended mode if your Windows is not enrolled in Entra ID or Active Directory. However, this process requires UEM software.

The only way to achieve unattended AgentP user enrollment on a Windows computer not enrolled in Entra ID or Active Directory is by first installing a SCEP certificate on the computer. Then, install AgentP with a specific flag (registry key), which makes it enroll based on the data in the SCEP certificate. This allows you to install AgentP in unattended mode even with other authentication repositories like Okta and Google Workspace. However, the only way to get a SCEP certificate is by using UEM software.

Install SCEP certificates on clients.
Create a suitable configuration profile in your UEM software that makes the clients request SCEP certificates from the Portnox Cloud SCEP server.
Distribute configuration values for AgentP on clients.
If your UEM software allows you to enter command-line arguments, you can distribute configuration values using command-line arguments. Alternatively, you can distribute registry key values.
- If your UEM software allows you to enter command-line arguments, enter the following argument string in the relevant field in the UEM software (for example, the Command-line arguments field in Intune):
  - ENROLLMENTIDENTITY=certificate ENROLLMENTCERTIFICATE="issuer:your_organization - Portnox CLEAR" DOMAIN=optional_domain
    
    Where your_organization - Portnox CLEAR is the CN value in the Subject of your tenant CA certificate (Example: issuer:Vorlon - Portnox CLEAR).
    
    Note:
    The DOMAIN parameter is only needed if the SCEP certificate does not specify the domain already by having the user’s email already in the Subject or SAN fields.
- If your UEM software does not allow you to enter command-line arguments, the most common way to distribute registry key values is through PowerShell scripts (see: this external example). Consult your UEM documentation to learn how to distribute Windows registry key values.
  
  You need to distribute the following REG_SZ (String) values of the [HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Portnox AgentP] key:
  - - string value: EnrollmentIdentity
    - data: certificate
  - - string value: EnrollmentCertificate
    - data: issuer:your_organization - Portnox CLEAR, which is the CN value in the Subject of your tenant CA certificate (Example: issuer:Vorlon - Portnox CLEAR).
  - - (Optional) string value: Domain
    - data: your_domain
      
      Note:
      Only needed if the SCEP certificate does not specify the domain already by having the user’s email already in the Subject or SAN fields.
Note:
To check the Subject of your tenant CA certificate, open the certificate on Windows, go to the Details tab, scroll down and click on the Subject entry, and note down the value after CN = in the text box below.
Alternatively, you can find this value in Portnox Cloud: open the Settings menu, click on the Services > GENERAL SETTINGS > Trusted Root Certificates option, and in the right-hand side pane, in the table in this section, note down the value next to the Issued to label.
Distribute AgentP to clients.
Once the client Windows machines have the SCEP certificate installed and the required registry key values, you can now distribute AgentP. AgentP will detect the registry key values, use them to select the correct certificate installed on the computer, and then use this certificate for unattended enrollment.

Install AgentP on macOS in unattended mode based on SCEP certificates

In this section, you will learn how to install AgentP in unattended mode on macOS. However, this process requires UEM software.

The only way to achieve unattended AgentP user enrollment on macOS is by first installing a SCEP certificate on the computer. Then, install AgentP with a specific configuration file, which makes it enroll based on the data in the SCEP certificate. However, the only way to get a SCEP certificate is by using UEM software.

Important:

The SCEP certificate must have the user’s UPN or email address in the Subject or in the SAN UPN field. There are no limitations for the support of authentication repositories, all repositories that are supported by Portnox Cloud are supported in this unattended mode.

Install SCEP certificates on clients.
Create a suitable configuration profile in your UEM software that makes the clients request SCEP certificates from the Portnox Cloud SCEP server.
Install a configuration script on clients.
You need to distribute the following configuration script, which creates the unattended.cfg and uipreferences.cfg files in the /var/agentp directory before the installation of AgentP:
```
mkdir -p /var/agentp
json='{"HideUI":true}'
echo $json > /var/agentp/uipreferences.cfg
                           
json='{"Mode":"certificate","Certificate":"issuer:issued_to","AutoSwitch":true,"UseCertificateSerialNumberAsDeviceId":true,"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
```
Note:
For explanation of configuration options in this script, see the following topic: AgentP configuration/installation options.
Important:
If the SCEP certificate does not have the user’s email in the Subject or in the SAN UPN, add the Domain attribute by modifying the fifth line of the above code as follows:
```
json='{"Mode":"certificate","Certificate":"issuer:issued_to","AutoSwitch":true,"UseCertificateSerialNumberAsDeviceId":true,"Domain":"your_domain","profileInstallationNeeded":false}'
```
1. As issued_to, paste the CN value of your tenant CA certificate: your_organization - Portnox CLEAR.
  You can get this value by opening the certificate and checking the Subject field, or in Portnox Cloud: open the Settings menu, click on the Services > GENERAL SETTINGS > Trusted Root Certificates option, and in the right-hand side pane, in the table in this section, note down the value next to the Issued to label.
  For example:
```
json='{"Mode":"certificate","Certificate":"issuer:Vorlon - Portnox CLEAR","AutoSwitch":true,"UseCertificateSerialNumberAsDeviceId":true,"Domain":"your_domain","profileInstallationNeeded":false}'
```
2. 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}'
```
Distribute AgentP to clients.
Once the client machines have the SCEP certificate and the configuration file, you can now distribute AgentP. AgentP will parse the configuration file, use the values from that file to select the correct SCEP certificate installed on the computer, and then use this certificate for unattended enrollment.

Examples: