How to troubleshoot typical device onboarding issues

In this topic, you will learn how to address the most common issues when onboarding devices onto a network managed by Portnox™ Cloud.

Check common causes of connection failures

In this section, you will learn how to use alerts and configuration checks to identify and resolve common causes of authentication and onboarding failures.

If you cannot connect your device to the network managed by Portnox Cloud, go to the Cloud portal, select Alerts in the top menu, and look at the most recent alerts. To make it easier to find relevant alerts, you can filter them by account name, NAS device, or other parameters. These alerts will inform you about the causes of authentication failures or will confirm successful authentication.

Here are some typical reasons for connection failures:

  • Check if your group settings allow authentication with the selected method (credentials, certificates, etc.) for the network you’re trying to connect to. See the topic: Create a group.

  • Check if the account you are using is a member of the group that you have configured for the network you’re trying to connect to. See the topic: Manage members of a group.

  • Check if the number of devices per account, which is configured in group settings, has not been exceeded. For more information on setting this limit, see the topic: Edit and configure a group.

  • Check if the network in your group is set up to configure the correct authentication type. For example, if the user uses credentials and belongs to a Microsoft directory (Entra ID or AD), the group must be set up for MSCHAPv2 authentication. If the user uses credentials and belongs to a non-Microsoft directory like Google Workspace, the group must be set up for PAP authentication. If the user uses a certificate, the group must be set up for TLS authentication.

  • If you want to log in using credentials, your instance is integrated with Microsoft Entra ID, and your Entra ID access policy enforces multi-factor authentication (MFA), you need to set up a MFA bypass by following the steps in this topic: Bypass multi-factor authentication in Entra ID.

  • If you want to log in using credentials and your instance is integrated with Google Workspace, you must use an app password, not your regular password.

  • If certificate-based authentication does not work but credential-based authentication works, check if the packets are being fragmented by firewalls/routers between the NAS and the RADIUS server.

  • If you’re onboarding an Android or iOS device to a Wi-Fi network, make sure to turn off operating system features such as Use Private Address or Private Wi-Fi Address on iOS or Use randomized MAC on Android. Depending on the UEM and its configuration, and the access point and its configuration, MAC randomization may prevent network access.

  • If you’re trying to access the network without AgentP, but your account was previously activated with AgentP, check if the following setting is on: Settings > Services > GENERAL SETTINGS > Agentless access > Enable agentless access for all automatically-created accounts.

  • If you manage user groups via LDAP/AD and map LDAP groups to Cloud groups, make sure that if some LDAP groups map to the Unassigned group and at least one LDAP group maps to a dedicated Cloud group, you set the Unassigned group as the default. Otherwise, a user who belongs to multiple LDAP groups may be incorrectly assigned to Unassigned, preventing them from authenticating, even after a LDAP Broker sync.

  • If your AgentP reports an error, see the following topic: How to collect AgentP logs for support

Known onboarding issues

In this section, you will learn about specific known issues that can cause authentication or onboarding to behave unexpectedly.

Windows domain-joined devices authenticate automatically using computer credentials instead of prompting the user

On Windows domain-joined devices, when a network profile is deployed via Group Policy or UEM/MDM, the device may automatically attempt to use its domain credentials (computer account) via PEAP/MSCHAPv2 to log in to the network, often before the user is prompted for their credentials. This behavior is considered the default in centrally managed environments.

These automatic login attempts using computer credentials may trigger alerts in Portnox Cloud, which can be confusing if your organization expects user-based authentication.

If you observe this behavior, navigate to Settings > Services > GENERAL SETTINGS > Access control mode > Edit, activate the Ignore computer credentials authentications checkbox, and click on the Save button.

Note:
Enabling this option prevents any credential-based authentication using computer credentials.
Note:
If the network profile is created manually on the device, automatic use of computer credentials is not a default behaviour – Windows will prompt the user for credentials unless the option Automatically use my Windows logon name and password (and domain if any) is explicitly enabled in the profile settings.
MAC-address-based onboarding fails with device already exists in organization for a device that previously onboarded successfully

A device may successfully authenticate via MAB but receive a MAC Onboarding failed because device already exists in organization alert, even though the same device onboarded successfully in the past using the same MAC address and the same authentication flow.

This is expected behavior, not an error. Authentication and onboarding are two separate steps:

  • Authentication verifies whether the device is allowed to connect to the network, and does not necessarily require an account to already exist. This can succeed independently of onboarding, and does not by itself create or modify any account.

  • Onboarding is the one-time process of creating an account for a previously-unknown device and assigning it to a group. Once a MAC address has been onboarded and associated with an account – a MAC-based account created automatically, or a device-type account it was later moved to through device recognition – Portnox Cloud does not onboard that MAC address again.

This restriction exists to prevent a device from repeatedly moving between accounts. For example, if automatic re-onboarding were allowed, the following cycle could occur:

  1. The device authenticates via MAB and is onboarded into an automatically created MAC-based account in the group configured for MAC-address-based onboarding.

  2. Device recognition identifies the device type and moves it to an existing device-type account, which may belong to a different group with different policies.

  3. On the device’s next connection, if onboarding were allowed to run again, it would repeat the same sequence: a new MAC-based account, followed by another move to the device-type account.

To prevent this, once a device is associated with an account through device recognition or otherwise, it stays with that account, and later MAC-address-based onboarding attempts for the same MAC address are rejected. The device continues to authenticate and access the network normally under its existing account; only the redundant onboarding step is blocked.

Note:
If you need to move a device to a different account or group, do this manually. Do not expect a repeated MAB authentication to recreate or reassign the device’s onboarding account.

This issue is most commonly seen when MAC-address-based onboarding is left enabled permanently or for an extended period, rather than being used as intended for temporary, mass onboarding of new IoT/MAB devices during a migration or initial deployment. The longer the feature stays active, the more devices accumulate onboarding history and become candidates for this failure once device recognition moves them to a different account. For guidance on enabling and disabling this feature correctly, see How to onboard IoT devices using MAC-address-based onboarding.