Jeff Mitchell
163ce184b8
This adds a new mechanism for worker authentication that uses the third-party arbitration of the original KMS flow by leveraging recently-added capabilities in nodeenrollment to support a registration wrapper. This allows for workers to be registered to the system with just a name and a matching wrapper, while at the same time allowing these workers to be used for private Vault access and multi-hop as they contain per-worker encryption keys and support rotation. Nodes using this mode will generate and rotate credentials in-memory (using another recently added nodeenrollment capability) so will have a new set of keys on every startup. This has the side effect of ensuring that there is never a conflict or re-use of these credentials. Note that the normal test worker flow was using the now-deprecated KMS method; there is still a test that uses this (explicitly) but all other tests using test workers that did not specify a specific PKI flow now actually use this mechanism. This means there is fairly decent test coverage in a general sense, plus the specific tests updated/added for this feature. This also adds a new KMS type that can be used to have distinct KMSes for upstream authentication vs. accepting from downstream.
80 lines
2.9 KiB
Plaintext
80 lines
2.9 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: PKI Worker Configuration
|
|
description: |-
|
|
PKI worker-specific parameters.
|
|
---
|
|
|
|
|
|
# PKI worker configuration
|
|
PKI Workers authenticate to Boundary using an activation token. They require an
|
|
accessible directory defined by `auth_storage_path` for credential storage and
|
|
rotation.
|
|
|
|
Example (not safe for production!):
|
|
|
|
```hcl
|
|
worker {
|
|
auth_storage_path="/boundary/demo-worker-1"
|
|
initial_upstreams = ["10.0.0.1"]
|
|
}
|
|
```
|
|
|
|
## Authorization methods
|
|
There are two mechanisms that can be used to register a worker to the cluster.
|
|
|
|
### Controller-led authorization flow
|
|
In this flow, the operator fetches an activation token from the controller's
|
|
`workers:create:controller-led` action (on the CLI, this is via `boundary
|
|
workers create controller-led`). That activation token is given to the worker
|
|
via the `controller_generated_activation_token` parameter. This can be done
|
|
either directly or via an env var or file by using `env://` or `file://` syntax:
|
|
|
|
```hcl
|
|
worker {
|
|
auth_storage_path="/boundary/demo-worker-1"
|
|
initial_upstreams = ["10.0.0.1"]
|
|
controller_generated_activation_token = "neslat_........."
|
|
# controller_generated_activation_token = "env://ACT_TOKEN"
|
|
# controller_generated_activation_token = "file:///tmp/worker_act_token"
|
|
}
|
|
```
|
|
|
|
Once the worker starts, it reads this token and uses it to authorize to the
|
|
cluster. Note that this token is one-time-use; it is safe to keep it here even
|
|
after the worker has successfully authorized and authenticated, as it will be
|
|
unusable at that point.
|
|
|
|
Note: If this value is not present at worker startup time and the worker is not
|
|
authorized, it will print and write out suitable information for the worker-led
|
|
flow, described below. So long as the worker-led flow has not been used to
|
|
authorize the worker, if the controller-generated activation token is provided
|
|
and the worker restarted, it will make use of it.
|
|
|
|
### Worker-led authorization flow
|
|
In this flow, the worker prints out an authorization request token to two
|
|
places: the startup information printed to stdout, and a file called
|
|
`auth_request_token` in the base of the configured `auth_storage_path`. This
|
|
token can be submitted to a controller at the `workers:create:worker-led` path;
|
|
on the CLI this would be via `boundary workers create worker-led
|
|
-worker-generated-auth-token`. No values are needed in the configuration file.
|
|
|
|
## KMS configuration
|
|
PKI Workers' credentials can be encrypted by including an optional KMS stanza
|
|
with the purpose `worker-auth-storage`.
|
|
|
|
Example (not safe for production!):
|
|
```hcl
|
|
kms "aead" {
|
|
purpose = "worker-auth-storage"
|
|
aead_type = "aes-gcm"
|
|
key = "X+IJMVT6OnsrIR6G/9OTcJSX+lM9FSPN"
|
|
key_id = "worker-auth-storage"
|
|
}
|
|
```
|
|
|
|
~> **Note:** `name` and `description` fields are not valid config fields for PKI
|
|
workers. These fields are only valid for [KMS Workers][]. `name` and
|
|
`description` can only be set for PKI workers through the API.
|
|
|