How to configure 802.1x on Neat Devices

Last updated August 14, 2023

As of the Neat firmware version 20230504.xxxx, 802.1x is no longer a Beta feature.

Introduction – What is 802.1x?

802.1x is a standard network authentication protocol that enables port-based access control based on the user’s identity and its authentication by the organisation’s internal authenticator. This offers security within the network to protect organisations from unmanaged devices that find themselves in the workplace.

Requirements and Limitations:

Required Components for Configuration:

Neat devices must be on a local area network (LAN) (wired or wireless) and reachable by IP address for configuration, before moving devices to a wired 802.1x network environment.
802.1x capable switch and network
- Wired: EAP-TLS only
- Wireless: WEP, WPA, WPA2, EAP-TLS, EAP-PEAP
Certificate Components for EAP-TLS :
- Certificate Signing Request (CSR)
- Certificate Authority (CA) to sign CSR
  - Certificate Chains are supported
Python 3 environment for customer-side script
- Familiarity with Python and PIP is preferable
- Install PIP – If you have Python version 3.4 or later, PIP is included by default
- For the Latest version of neat-dot1x-cli please see the Release or run
  neat-dot1x-cli -V on your Command terminal.

Current Limitations (at time of writing):

Only EAP-TLS support for wired

Please note: The following steps assume that you have preconfigured 802.1x on your network including owning a certificate authority

Important Note: The following process will need to be performed for each Neat device separately (e.g certificates will need to be requested, signed and uploaded separately for the Neat Bar and Neat Pad).

Step 1 – Setting up the devices

Accessing the device’s Web API can be done during the initial Out-of-Box (OOB) set-up, during the first installation/after a factory reset, or if they are already set up and running Zoom/Teams, by enabling Remote Access instead.

Connect the devices to a LAN via ethernet or wifi that is NOT an 802.1x network. Please note that captive portals are not supported.
- For an OOB configuration, confirm that the device is receiving an IP address by pressing the reset button on the back of the device. Please note: The device does not have to reach the internet – it only requires being reachable from a laptop/computer on the same network. The Web-API during OOB only applies up to choosing the platform to run (Teams/Zoom).
- For devices already running Zoom/Teams room configuration, under Neat’s System settings navigate to System -> Remote access and enable. Please set a password, which is required for Steps 3 and 4. For more information on how to enable Remote access see the following article here.

Step 2 – Verifying Neat device connectivity

From a laptop or computer on the same LAN, confirm that the Neat device is reachable:
- Ping the IP address of the unit or
- Ping via hostname (“Serial Number.local”) or FQDN

Tip: If the device is in OOB press and release the reset button on the back of the Neat device to see both the Serial number and the IP address.
If the Neat device is already running Zooms/Teams go to System Settings > System > Network > Information > IP address

Step 3 – Creating a Certificate Signing Request (CSR)

Run the following command on your terminal/command prompt to PIP install the 802.1x client package:
```
pip install neat_dot1x_client --upgrade --extra-index-url https://gitlab.com/api/v4/projects/41183007/packages/pypi/simple
```
- Please note: Some networks will require a proxy to install the package and avoid SSL errors. Please use the--proxy http://<usr_name>:<password>@<proxyserver_name>:<port#> command accordingly.
  - Those with a transparent proxy, like Zscaler, may need to use the --trusted-host gitlab.com command.
- Optional step: Verify version matches the latest as stated above by running:
  neat-dot1x-cli -V
Once the PIP package is installed, the command-line client, now called neat-dot1x-cli, should be available for use. In order to generate the certificate signing request (CSR), the following parameters are required to access the device’s Web-API:
- IP address or Hostname
- Username
  - a) Device in OOB => Username: oob
  - b) Device running Teams/Zoom => Username: admin (Refer to Step 1)
- Password
  - a) Device in OOB => Password: Serial Number
  - b) Device running Teams/Zoom => Password: Refer to Step 1
- Optional arguments are supported in a JSON file format.
  - { "C": "NO", "ST": "Oslo", "L": "Oslo", "O": "Neat", "OU": "RD", "CN": "802.1X device", "EMAIL": "neat@neat.no" }
- Please note; The "key": "value" pairs seen in the examples above are optional and their order is arbitrary. If a "commonName" is not provided, by default the device will use the Serial number instead.
- If no key/value pairs are provided, the device will default to the following:
```
'{"country":"NO","organizationName":"Neatframe Ltd","organizationalUnit":"neat.no"}'
```
  Important: Please note that Neat currently doesn’t support Subject Alternative Name (SAN) in the JSON file and therefore the CSR file that will be created will not have SAN field but only the Common Name.
Once you have decided on the arguments stated in point 2, run the following command substituting the arguments unique to the device and network:
```
neat-dot1x-cli HOST_OR_IP USERNAME PASSWORD csr CSR_FILE.pem --subject-file Subject_JSON_File
```
Please note: It could take up to 30 seconds for the device to generate the CSR
Optional step: To verify if the certificate signing request has been successfully created run: cat CSR_FILE.PEM and check if it opens a PEM-formatted text file which you will then need to be signed by your certificate authority (CA)

Step 4 – Signing the Certificate

802.1x offers unprecedented visibility and secure, identity-based access control at the network edge. With EAP/TLS protocol each enterprise controls how they sign the certificate and typically own an internal Certificate Authority (CA) for this purpose.

Take the CSR created in Step 3 and sign the certificate using your own internal CA

Important Note: The certificate file will need to be in PEM format.

Tip: To reduce the frequency of updating the Certificate of each device we recommend setting up an extended expiry date. The certificate is saved as an encrypted file, stored in the device’s memory, and can only be wiped with a Factory reset.

Step 5 – Uploading the Certificate

Once the CSR has been signed by the CA it can then be installed onto the device.

For a wired 802.1x network:

At this stage, there are two new arguments required, ‘identity’ and ‘device certificate file path’ as well as the initial arguments defined in Step 3.
- Identity is passed alongside the signed certificate when the device presents itself to the radius server. Please configure this in accordance with your network environment.
- The certificate File Path will be uniquely defined by each user and needs to contain the device certificate in PEM format.
- If a certificate chain is used it will need to be a list of PEM-formatted certificates (all in the same file). For each following certificate in the chain, it must directly certify the one preceding it as is the standard protocol.
Optional: The third optional argument is the Root server certificate. Please note that this is not a required argument and, unless specified by the user, the device will attempt to communicate with any radius server.
Once you have decided on the arguments, listed in points 1 & 2, run these in your command-line client, neat-dot1x-cli. Please see the example command below where “SERVER_CA_CERT_FILE.pem” is an optional argument:
```
neat-dot1x-cli HOST_OR_IP USERNAME PASSWORD init IDENTITY DEVICE_CERT_FILE.pem SERVER_CA_CERT_FILE.pem
```

For a wireless 802.1x network:

At this stage, there are 3 new arguments required, ‘Wifi configuration JSON file path’, ‘Device certificate file path’ and ‘CA certificate file path’. This is alongside the initial mandatory arguments defined in Step 3.
- The Wifi Configuration JSON file will need to include the SSID, isHidden, Wifi security type, and finally, credentials. Note: WPA2 Enterprise has been substituted by “wifi security”: “EAP”
  See below an example JSON file for an EAP-TLS 802.1x network:

{
  "ssid": "Neat",
  "isHidden": false,
  "wifiSecurity": "EAP",
  "credentials": {
    "method": "TLS",
    "phase2Method": "NONE",
    "identity": "Neat-wifi",
    "anonymousIdentity": "",
    "password": ""
  }
}

Device Certificate File Path This will be uniquely defined by each user and needs to be in PEM format. This will be inserted into the command line by replacing [DEVICE_CERT_PATH] with its unique file path.
- If a certificate chain is used it will need to be a list of PEM-formatted certificates (all in the same file). For each following certificate in the chain, it must directly certify the one preceding it as is the standard protocol.

CA certificate File Path will need to be inserted into the command line by replacing [CA_CERT_PATH] with its file path.

2. Once you have decided on the arguments, listed in point 1, run these in your command-line client, neat-dot1x-cli. Please see the example command below:

neat-dot1x-cli HOST_OR_IP USERNAME PASSWORD init_wifi WIFI_CONFIG_JSON_PATH [DEVICE_CERT_PATH] [CA_CERT_PATH]

Step 6 – (Wired) Moving devices to an 802.1x network

Finally, move the device to a wired 802.1x network and the device will begin to answer the challenges of the 802.1x authenticator. As soon as the identity of the device is known, all traffic from that endpoint is allowed and your device will now be connected to your network!

Additional Information:

The Python tool syntax:

Tool version: neat-dot1x-cli -V
Help: neat-dot1x-cli -h
Positional arguments help for CSR parameters: neat-dot1x-cli X Y Z csr -h
Positional arguments help for Uploading cert (wired): neat-dot1x-cli X Y Z init -h
Positional arguments help for Uploading cert (wireless): neat-dot1x-cli X Y Z init_wifi -h