Examine security agent authentication methods

5 minutes

The Microsoft Defender for IoT service provides a reference architecture for security agents. Security agents are able to log, process, aggregate, and deliver security data through IoT Hub.

Security agents are designed to work in a resource-constrained IoT environment. Security agents are also highly customizable in terms of the value they provide when compared to the resources they consume.

Security agents support the following features:

They collect raw security events from the underlying Operating System (Linux, Windows).
They aggregate raw security events to create messages that are delivered through IoT Hub.
They authenticate with either an existing device identity or a dedicated module identity.
They configure remotely through the use of the azureiotsecurity module twin.

A security module is required for each device onboarded to Microsoft Defender for IoT in the IoT Hub. To authenticate the device, Microsoft Defender for IoT can use one of two methods:

SecurityModule option.
Device option.

Authentication methods

You can use the following information to help you choose between the two methods for authentication:

SecurityModule authentication mode.

The agent is authenticated using the security module identity independently of the device identity. Use this authentication type if you would like the security agent to use a dedicated authentication method through security module (symmetric key only).

Device authentication mode.

In this method, the security agent first authenticates with the device identity. After the initial authentication, the Microsoft Defender for IoT agent performs a REST call to the IoT Hub using the REST API with the authentication data of the device. The Microsoft Defender for IoT agent then requests the security module authentication method and data from the IoT Hub. In the final step, the Microsoft Defender for IoT agent performs an authentication against the Microsoft Defender for IoT module.

Use this authentication type if you would like the security agent to reuse an existing device authentication method (self-signed certificate or symmetric key).

Authentication methods known limitations

SecurityModule authentication mode only supports symmetric key authentication.

CA-Signed certificate is not supported by Device authentication mode.

Security agent installation parameters

When you are deploying a security agent, authentication details must be provided as arguments. These arguments are documented in the following table.

Linux Parameter Name

Windows Parameter Name

Shorthand Parameter

Description

Options

authentication-identity

AuthenticationIdentity

aui

Authentication identity.

SecurityModule or Device

authentication-method

AuthenticationMethod

aum

Authentication method.

SymmetricKey or SelfSignedCertificate

file-path

FilePath

Absolute full path for the file containing the certificate or the symmetric key.

host-name

HostName

FQDN of the IoT Hub.

Example: ContosoIotHub.azure-devices.net

device-id

DeviceId

Device ID.

Example: MyDevice1

certificate-location-kind

CertificateLocationKind

Certificate storage location.

LocalFile or Store

When you deploy a security agent with an installation script, a configuration file is automatically created.

Change authentication method after deployment

To change authentication methods after deployment, manual editing of the configuration file is required.

C#-based security agent

Edit Authentication.config with the following parameters:

<Authentication>
  <add key="deviceId" value=""/>
  <add key="gatewayHostname" value=""/>
  <add key="filePath" value=""/>
  <add key="type" value=""/>
  <add key="identity" value=""/>
  <add key="certificateLocationKind" value="" />
</Authentication>

C-based security agent

Edit LocalConfiguration.json with the following parameters:

"Authentication" : {
"Identity" : "",
"AuthenticationMethod" : "",
"FilePath" : "",
"DeviceId" : "",
"HostName" : ""
}

Continue