Worker Authentication

Worker authentication has two layers:

1. Bootstrap authentication (how a worker first proves identity to the server).
2. Runtime authorization (how external workers are continuously authorized to execute jobs).

For bootstrap authentication, two strategies are available:

Strategy	Features
API key	Pre-create each worker and provide a per-worker API key
Auto-Enrollment	Bootstrap with a shared secret; server issues and the worker caches an API key

Note

The server can support both bootstrap strategies at once, but each worker should use one strategy during initial bootstrap.

API key authentication

API key bootstrap is best when you need explicit, per-worker control. It is especially useful for workers on less-trusted networks.

External workers require a licensed deployment. Community Edition supports only the built-in worker.

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

Server Configuration

1. Create a new Worker with a name. As an option, customize the Worker ID.
2. Create a new API key on the Server, or re-use an existing API key.

Worker Configuration

Under the Worker startup settings:

3. Configure the Worker ID (LYFTDATA_WORKER_ID) and API key (LYFTDATA_WORKER_API_KEY) as per the Server configuration above.

Note

The Worker name is optional when using API key authentication.

Auto-enrollment authentication

Auto-enrollment uses a server-side shared secret to bootstrap new workers quickly. The server then issues an API key, and the worker caches that credential for subsequent restarts.

Unlike the API key strategy, you do not need to pre-create each worker or issue per-worker keys manually. Because this uses a shared secret, use it only on trusted networks.

Auto-enrollment is disabled by default.

Server (licensed deployments)

1. Sign in as an admin and enable auto-enrollment in Settings → Security.
2. Set an enrollment secret (random 32+ characters) and save. The secret is write-only.

Worker

3. Configure a worker with a name (LYFTDATA_WORKER_NAME) and the shared secret (LYFTDATA_AUTO_ENROLLMENT_KEY).
4. In most cases leave pre-issued worker identity settings unset (LYFTDATA_WORKER_ID, LYFTDATA_WORKER_API_KEY). If you need deterministic IDs, you can provide LYFTDATA_WORKER_ID during enrollment.

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

After the first successful enrollment, remove LYFTDATA_AUTO_ENROLLMENT_KEY from the worker service configuration. The worker will continue using cached credentials.

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 Workers, without having access to the Server itself.

See also: Worker Auto Enrollment for provisioning and rotation runbooks.

Runtime authorization (external workers)

After bootstrap, external workers are authorized at runtime using signed, time-bounded auth leases issued by the server and refreshed periodically.

• Built-in workers do not use auth leases.
• External workers that cannot obtain/refresh valid authorization stop running jobs.
• Community Edition does not authorize external workers.