Skip to main content
Version: 3.5.2

Agent Authentication

Two available strategies can be used to authenticate Agents against a Server.

StrategyFeatures
API keyRequires explicit initial setup on Server for each Agent
Auto-EnrollmentServer is configured once with a shared secret, which is re-used by Agents
note

Both of these authentication strategies can be used in tandem on the Server. However, each Agent can only use one of these strategies.

API Key Authentication​

Known as the default strategy, API key authentication is useful when further control is needed over Agent authentication. It's especially useful for Agents running on untrusted (or less-trusted) systems. With this strategy, Agents must be configured and authorized on the Server before they are allowed to connect to the Server.

Adding a new Agent involves the following two steps, as well as specific configuration:

Server Configuration

  1. Create a new Agent with a name. As an option, customize the Agent ID.

  2. Create a new API key on the Server, or re-use an existing API key.

Agent Configuration

Under the Agent startup settings:

  1. Configure the Agent ID (HOTROD_AGENT_ID) and API key (HOTROD_AGENT_API_KEY) as per the Server configuration above.
note

The Agent name is optional when using API key authentication.

Auto-Enrollment Authentication​

Auto-Enrollment uses a shared secret, configured once on the Server and then re-used among Agents. Unlike the API key strategy, adding new Agents does not require initial Server configuration. Because of the shared secret, it's recommended to only use this strategy for Agents running on trusted or self-managed systems.

The Auto-Enrollment strategy is disabled by default on the Server. Enable it as follows:

Server

  1. Configure a shared secret in the Server startup settings (HOTROD_AUTO_ENROLLMENT_KEY).

Agent

  1. Configure an Agent with a name (HOTROD_AGENT_NAME) and the Server shared secret (HOTROD_AUTO_ENROLLMENT_KEY).

  2. Do not give the Agent an ID or API key (HOTROD_AGENT_ID).

The Server will automatically create Agent entries for any connecting Agents using the Server Auto-Enrollment secret.

SecuRity

Use a randomly generated value of at least 32 characters for the shared secret, for example: c3s3R0s1T5QAQr7lz1KsT00pKh3adnma.

danger

If the Auto-Enrollment secret is known, anyone with network access to the Server can add new Agents, without having access to the Server itself.