Administration configuration

Paths in the tables are relative to the section heading. Check parsing, unknown keys, and cross-field rules with gdsgate doctor --config <PATH> --json. See the admin configuration templates.

[admin]

Used by: the operator workstation (the gdsgate CLI run by an administrator).

The mTLS identity the CLI uses for these commands: authority tokens create, five CA rotations (rotate-ca, rotate-onward-ca, rotate-host-tls-ca, rotate-spiffe-ca, rotate-jwt-ca), registry and catalog actions (revoke-node, delete-node, forget-user, revoke-workload, import-node, list-nodes, list-offered, list-workloads, list-resources, set-resource, remove-resource), and the audit list. Create the identity once with gdsgate authority identities bootstrap --role admin and set identity_dir to the directory it writes.

Policy pull, push, edit, approve-edit, pending-edits and the recordings viewer use an identity token through the gateway. The emergency socket is separate.

Key	Type	Default	Purpose
endpoint	string	unset	Authority's mTLS gRPC endpoint, for example https://auth.example.com:50051. Must be https://; any other scheme is refused. gdsgate doctor reports it as config.admin.endpoint_scheme.
identity_dir	string	unset	Directory with cert.pem, key.pem and ca.pem from bootstrap. Bootstrap creates a missing directory and makes each file owner-only (mode 0600 on Linux, an owner-only access list on Windows). It does not protect the directory; do that yourself.
transport	enum	direct	direct: endpoint is Authority. fronted: endpoint is a gateway or router that routes by TLS server name; the CLI asks for auth.gdsgate.internal. See below.

[admin]
endpoint     = "https://auth.example.com:50051"
identity_dir = "/etc/gdsgate/admin"

Administering through the gateway

With transport = "fronted" the CLI sends the TLS server name auth.gdsgate.internal; with direct it sends gdsgate.internal. The gateway puts such connections in the administrative lane. The certificate and its authentication are the same.

[admin]
endpoint     = "https://gate.example.com:50061"
identity_dir = "/etc/gdsgate/admin"
transport    = "fronted"

GDSGATE_ADMIN_TRANSPORT overrides the value; an unrecognized value is ignored.

The name auth.gdsgate.internal verifies only after Authority's certificate has been reissued with it, at enrollment or renewal (not at CA rotation). Until then fronted fails with a verification error naming auth.gdsgate.internal. The wait is at most one transport identity lifetime (a day by default); gdsgate doctor on the Authority host shows when the identity expires. gdsgate.internal and direct connections keep working.

On a relayed connection the address in administrative audit rows and in context.src_ip is the gateway's. A rule such as context.src_ip.isInRange(ip("10.0.0.0/8")) on an administrative action then matches the gateway's address. Use a direct connection where such rules apply.

The gateway must have [proxy].public_join enabled; otherwise the connection fails.

[policy.editor]

Used by: Authority.

Policy-edit quorum and break-glass recovery. Optional. Unset: one editPolicy permit is enough to push a new active version.

Key	Type	Default	Purpose
min_approvers	usize	1	Distinct approvers needed before a proposed policy version becomes active. With 2 or more, authority policy push queues a proposal and reviewers vote with authority policy proposals approve <version>.
break_glass_policy_file	string	unset	Cedar policy file on the Authority host, read at each start after the stored policy is loaded. If it differs from the active version, it becomes the new active version without the editPolicy check, with proposer break-glass:<hostname>, and the log says break-glass policy restore. An identical file changes nothing. A missing file does not stop the start; gdsgate doctor reports it as a failed check. The file must contain the break-glass rule, or the start stops. Use it to recover from a policy that locks out policy editing ([policy].path only seeds an empty store). See Admin guide → Lock-out and recovery.

[policy.editor]
min_approvers           = 2
break_glass_policy_file = "/etc/gdsgate/break-glass.cedar"

[approvals]

Used by: Authority.

Just-in-time access thresholds. The number of distinct approvers for gdsgate requests create is the first level that is set:

1. The resource's catalog row (min_approvers stored on it).
2. [[discovery.resources]].min_approvers.
3. [approvals].per_environment.
4. [approvals].min_approvers.

The minimum is 1.

All HA instances read the same catalog row. Levels 2 to 4 come from the configuration file of the instance that answers; keep it the same on every instance. Authority writes [[discovery.resources]].min_approvers into the row at start-up. A value set through Authority's catalog API is replaced at the next start if the resource is also declared in [[discovery.resources]].

Key	Type	Default	Purpose
min_approvers	usize	1	Global default.
per_environment	table of string to usize	{}	Per-environment override, keyed by environment name (prod, staging, dev).

[approvals]
min_approvers = 1

[approvals.per_environment]
prod    = 2
staging = 1
dev     = 1