Agent Authentication
This reference describes the two available strategies for authenticating agents against a Hotrod server.
| Strategy | Features |
|---|---|
| API Key | Requires explicit initial setup on Hotrod server for each agent |
| Auto-enrollment | Hotrod server is configured once with a shared secret, which is re-used by agents |
Both authentication strategies can be used together on Hotrod server. Each agent can only use one of these strategies.
API Key Authentication
API key authentication is the default strategy, and is useful when more control is needed over agent authentication. It's especially useful for agents that must run on untrusted or less-trusted systems. With this strategy, Agents must be configured and authorized on Hotrod Server before they are allowed to connect to the Server.
Adding a new agent involves 2 steps on Hotrod Server, and specific configuration on the agent.
Server configuration
- Create a new agent with a name. Optionally, customize the agent ID.
- Create a new API key on the server, or re-use an existing API key.
Agent configuration
In the agent startup settings:
- Configure the agent ID (
HOTROD_AGENT_ID) and API key (HOTROD_AGENT_API_KEY) as per the server configuration above.
The agent name is optional when using API key authentication.
Auto-enrollment Authentication
Auto-enrollment uses a shared secret which is configured once on Hotrod server, and then re-used between 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 Hotrod Server. To enable it, follow these steps:
Hotrod Server
- Configure a shared secret in the server's startup settings (
HOTROD_AUTO_ENROLLMENT_KEY)
Hotrod Agent
- Configure an agent with a name (
HOTROD_AGENT_NAME) and the server's shared secret (HOTROD_AUTO_ENROLLMENT_KEY) - Do not give the agent an ID or API key (
HOTROD_AGENT_ID)
Hotrod server will automatically create agent entries for any connecting agents using the server's auto-enrollment secret.
For the shared secret, it's recommended to use a randomly generated value of at least 20 characters. For example: c3s3R0s1T5QAQr7lz1KsT00pKh3adnma.
If the auto-enrollment secret is known, anyone with network access to the Hotrod server can add new agents, without having access to the server itself.