Day 0 Machine Identity Configuration

This guide is the Day 0 reference for enabling machine identity (SPIFFE JWT-SVID issuance) at the site level. It covers the secrets, site config, and DPU agent settings that must be in place before any tenant can configure per-org identity (a Day 1 activity).

Machine identity lets tenant workloads on provisioned instances obtain short-lived JWT tokens that assert a SPIFFE ID. NICo signs those tokens when a DPU calls the Core gRPC API or when a workload reads the instance metadata service (IMDS). Per-org issuer, audiences, and TTL are configured later — see Machine Identity (Day 1).

The design and API details live in the SPIFFE JWT-SVID SDD. This page focuses on what an operator configures once during initial site bring-up.

Prerequisites

Before starting:

• A running NICo deployment with healthy nico-api (Core) and nico-rest-api (REST).
• Site config (siteConfig in helm-prereqs/values/ncx-core.yaml or equivalent) is already wired for your site — see Quick Start Guide, Step 3.

This page assumes you have completed Day 0 IP and Network Configuration or equivalent network bring-up.

What Day 0 Enables

Day 0 configuration turns on the site-wide machinery:

Per-org settings (issuer, audiences, TTL, token delegation) are not Day 0 — they are created with PUT …/tenant-identity/config after Day 0 is complete.

1. Generate Master Encryption Keys

Per-org JWT signing private keys are encrypted at rest with a site master encryption key (KEK). Generate one or more 256-bit keys and store them in site credentials.

$
openssl rand -base64 32

Record each key under a stable id (for example kv1, kv2). The id must match current_encryption_key_id in site config.

File-backed credentials

When using a local credential snapshot (development or file-based deployments), add a machine_identity block:

1
{
2
  "machine_identity": {
3
    "encryption_keys": {
4
      "kv1": "<base64-encoded-32-byte-key>"
5
    }
6
  }
7
}

Vault-backed credentials

In Vault deployments, store each key at a path that resolves to machine_identity/encryption_keys/<key-id> in the credential loader (for example …/machine_identity/encryption_keys/kv1). Follow the same secret-management process you use for other NICo site credentials.

Important: Keep all key ids that appear in stored ciphertext until you complete a KEK re-wrap. Decrypt always uses the key_id embedded in each encrypted blob, not the site’s current key id alone. See Master Encryption Key Rotation (KEK).

2. Configure Site [machine_identity]

Add or update the [machine_identity] section in the NICo API site config. In Helm deployments this is typically helm/charts/nico-api/files/carbide-api-config.toml (rendered into the nico-api ConfigMap) or the siteConfig overlay you maintain for your environment.

1
[machine_identity]
2
enabled = true
3
current_encryption_key_id = "kv1"   # must match a key in site secrets
4
algorithm = "ES256"                 # only ES256 is supported today
5
6
# Optional bounds enforced on per-org tokenTtlSeconds (defaults are documented in the SDD)
7
# token_ttl_min_sec = 60
8
# token_ttl_max_sec = 86400
9
10
# Optional: max signing_key_overlap_seconds on per-org JWT signing-key rotation
11
# signing_key_overlap_max_sec = 604800
12
13
# Optional: egress proxy for token delegation (RFC 8693) — see Day 1 guide
14
# token_endpoint_http_proxy = "https://nico-egress-proxy.example.com"
15
16
# Optional hostname allowlists (empty = no extra restriction beyond API validation)
17
# trust_domain_allowlist = ["*.example.com"]
18
# token_endpoint_domain_allowlist = ["sts.example.com", "*.tenant.example.com"]

Field reference (Day 0)

Startup behavior

After editing site config or secrets, restart nico-api (site config for [machine_identity] is not hot-reloaded).

3. Configure DPU Agent [machine-identity] (Optional)

IMDS identity requests are served by the DPU agent (and standalone FMDS when used). Limits and an optional HTTP sign-proxy are configured on the agent, not in the API site config.

Defaults apply when the section is omitted:

Example override in the agent config file (see crates/agent/example_agent_config.toml):

1
[machine-identity]
2
requests-per-second = 3
3
burst = 8
4
wait-timeout-secs = 2
5
sign-timeout-secs = 5
6
# sign-proxy-url = "https://sign-proxy.example.com/prefix"
7
# sign-proxy-tls-root-ca = "/etc/forge/sign_proxy_root.pem"

When sign-proxy-url is set, the agent forwards signing to an HTTP proxy instead of calling Forge gRPC directly. Use this only when your architecture requires an out-of-band signing path.

Restart or redeploy DPU agents after changing this section.

4. Apply and Verify Site-Level Enablement

4.1 Confirm API startup

After rollout, verify nico-api pods are running and logs show no machine-identity config errors:

$
kubectl logs -n <nico-namespace> deploy/nico-api --tail=100

If [machine_identity] is enabled but secrets or required fields are wrong, the pod will crash-loop until fixed.

4.2 Confirm global gate (expected before Day 1)

Before any org has identity config, per-org REST calls correctly return 503 Service Unavailable (machine identity not enabled at site level is indistinguishable from “enabled globally but not configured for org” until you complete Day 1):

$
curl -s -o /dev/null -w '%{http_code}\n' \
>
  -H "Authorization: Bearer $TOKEN" \
>
  "https://<nico-rest>/v2/org/<org>/nico/site/<site-id>/tenant-identity/config"

Once Day 0 is complete and enabled = true, this endpoint returns 404 (no config yet) or 200 (after Day 1), not 503.

After Day 1 config and a READY instance, run the Machine Identity Verification runbook for gRPC and IMDS smoke tests.

Troubleshooting

Day 0 verification uses API startup checks (§4.1) and the REST global gate (§4.2). Signing-path errors (SignMachineIdentity, IMDS) surface only after Day 1 and are covered in Machine Identity Verification.

Next Steps

• Machine Identity (Day 1) — per-org issuer, audiences, token delegation, JWKS/OIDC verification
• Machine Identity Verification — end-to-end checks after Day 1
• JWT Signing Key Rotation — per-org signing key rotation
• Master Encryption Key Rotation (KEK) — rotate site master keys safely
• Tenant Management — allocate instances before workloads need tokens
• SPIFFE JWT-SVID SDD — full design reference