API Security and Least-Privilege ACLs
Module 3 · IT Tier Security — Vault, Pipelines, and ACLs

API Security and Least-Privilege ACLs

Secure the IT tier's API surface with Vault-managed API keys, OAuth 2.0 scopes, and strict ACLs — completing the IT Enterprise Zone security posture aligned to ISA/IEC 62443 FR 1 and FR 2.

The API Attack Surface

The IT Enterprise Zone exposes APIs for legitimate business reasons: the historian replica provides a read API for dashboards, the build pipeline has a trigger API for deployments, and the Vault server exposes its own management API. Each API is an entry point that must be secured with the same rigor as a network firewall.

The most common API security failures in IT/OT environments:

  1. Overprivileged API keys — a single key with admin scope used for both monitoring reads and configuration writes
  2. No key rotation — keys issued years ago, some for former employees’ integrations, never revoked
  3. Exposed keys in logs — API keys passed as URL parameters (e.g., ?api_key=abc123) appear in web server access logs, monitoring tools, and browser histories
  4. No rate limiting — a compromised key can exfiltrate historian data at network speed with no throttle

API Key Management via Vault

The Vault KV secrets engine manages API keys the same way it manages other credentials: with TTLs, audit logging, and least-privilege policies.

For API keys that cannot be dynamically generated (external vendor APIs with fixed key schemes), use Vault as an encrypted store with access control:

# Store an external API key (e.g., for a cloud industrial IoT platform)
vault kv put secret/apis/cloud-iot-platform \
  api_key="<key-value>" \
  scope="read:telemetry" \
  owner="historian-sync-service" \
  rotated="2026-06-01" \
  next_rotation="2026-09-01"

# Policy: only historian-sync may read this key
cat > /etc/vault.d/policies/cloud-iot-read.hcl <<'EOF'
path "secret/data/apis/cloud-iot-platform" {
  capabilities = ["read"]
}
EOF
vault policy write cloud-iot-read /etc/vault.d/policies/cloud-iot-read.hcl

OAuth 2.0 Scopes for Internal APIs

For IT-internal APIs (historian replica, pipeline triggers), use OAuth 2.0 with scope-based access control. Vault can act as an OIDC provider, issuing tokens with granular scopes:

# Enable the OIDC auth method
vault auth enable oidc

# Configure Vault as an OIDC provider
vault write auth/oidc/config \
  oidc_discovery_url="https://vault.it.internal:8200/v1/identity/oidc/provider/it-ot" \
  bound_issuer="https://vault.it.internal:8200/v1/identity/oidc/provider/it-ot"

API scopes follow the principle of least privilege:

ScopeWhat It PermitsAssigned To
historian:readRead process data from replicaDashboards, reporting tools
historian:syncWrite to historian replicaHistorian sync service only
pipeline:triggerTrigger a deploymentRelease manager role only
vault:pki:issueIssue certificatesPipeline runners only
vault:adminManage Vault configurationVault admin (named individual)

No token should combine historian:sync and pipeline:trigger — these are distinct operations for distinct roles, and combining them creates a credential that an attacker can use to both exfiltrate data and deploy malicious software.


Hardened API Gateway Configuration

Place an API gateway (nginx, Kong, or Envoy) in front of the historian replica. The gateway enforces:

Authentication: validate the Bearer token against Vault’s OIDC endpoint before proxying any request.

Scope enforcement: reject requests where the token scope doesn’t match the requested operation.

Rate limiting: cap requests per authenticated identity to prevent exfiltration at scale.

Input validation: reject requests with unexpected query parameters or body size.

Example nginx configuration for the historian replica API:

# /etc/nginx/sites-available/historian-api.conf
server {
    listen 443 ssl;
    server_name historian-api.it.internal;

    ssl_certificate     /etc/nginx/certs/historian-api.crt;
    ssl_certificate_key /etc/nginx/certs/historian-api.key;

    # Enforce TLS 1.3 minimum (FR 4 data confidentiality)
    ssl_protocols TLSv1.3;
    ssl_ciphers 'TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256';

    # Rate limit per IP (prevent credential stuffing and exfiltration)
    limit_req_zone $binary_remote_addr zone=historian_api:10m rate=30r/m;
    limit_req zone=historian_api burst=10 nodelay;

    location /api/v1/telemetry {
        # Require Bearer token — proxy to auth validator
        auth_request /auth-validate;
        auth_request_set $auth_scope $upstream_http_x_auth_scope;

        # Enforce scope for this endpoint
        if ($auth_scope !~* "historian:read") {
            return 403 "Insufficient scope";
        }

        # Strip auth header before proxying to backend
        proxy_set_header Authorization "";
        proxy_pass http://historian-backend:8089;

        # Never expose API keys in access logs
        access_log /var/log/nginx/historian-access.log combined;
    }

    location = /auth-validate {
        internal;
        proxy_pass https://vault.it.internal:8200/v1/identity/oidc/provider/it-ot/userinfo;
        proxy_set_header Authorization $http_authorization;
    }
}

Vault ACL Design: Complete Reference

By the end of Module 3, the Vault ACL structure covers all IT Enterprise Zone components:

secret/
  apis/                    → readable by specific service policies only
    cloud-iot-platform     → [cloud-iot-read policy]
  it-ot/
    wireguard/
      psk                  → [wg-gateway policy]
      authorized-peers     → [wg-gateway policy (list), vault-admin (write)]

database/
  creds/
    historian-sync         → [historian-sync policy (read)]

pki_code_signing/
  issue/
    pipeline-runner        → [pipeline-runner policy (create)]
  cert/
    ca                     → [pipeline-verifier policy (read)]

auth/
  approle/role/            → [vault-admin policy]
  oidc/config              → [vault-admin policy]
💻 Code Lab: Audit All Vault Policies for Overprivilege

Run this script periodically (at least quarterly) to identify policies that grant * or sudo capabilities — these are almost always over-privileged:

#!/usr/bin/env bash
# audit-vault-policies.sh

echo "=== Vault Policy Overprivilege Audit $(date) ==="
echo ""

vault policies list | while read policy; do
  # Skip default and root
  [[ "$policy" == "default" || "$policy" == "root" ]] && continue

  echo "--- Policy: $policy ---"
  vault policy read "$policy" | grep -E "capabilities.*\*|sudo|root" && \
    echo "  WARNING: Overprivileged capabilities detected in $policy" || \
    echo "  OK: No wildcard capabilities"
  echo ""
done

Any policy with capabilities = ["*"] or sudo should be reviewed and scoped down. The root policy cannot be edited — ensure no service authenticates with root-equivalent privileges.


Aligning to ISA/IEC 62443 FR 1 and FR 2

The controls deployed in Module 3 map directly to the standard:

ControlISA/IEC 62443 Requirement
Vault AppRole authenticationFR 1 SR 1.1 — Identification and authentication
Short-lived API tokens (15 min)FR 1 SR 1.1 RE 2 — Multifactor (possession: token + identity)
Scope-based API accessFR 2 SR 2.1 — Least-privilege authorization
API gateway rate limitingFR 7 SR 7.1 — Denial-of-service protection
Vault audit logFR 6 SR 6.1 — Audit log generation
Policy review cadenceFR 2 SR 2.1 RE 1 — Periodic access review

Document each control against its FR/SR reference in your site’s security assessment. This documentation is the evidence an ISA/IEC 62443 auditor will review.


⚠️ Common Pitfall: API Keys in URLs Are Always Logged

Never design an API that accepts credentials in the URL path or query string (e.g., GET /telemetry?token=abc123). URL parameters appear in:

  • Web server access logs
  • Browser history and bookmarks
  • Referrer headers when linking to other sites
  • Proxy and load balancer logs
  • Network monitoring tools

Always pass API keys and Bearer tokens in the Authorization HTTP header. If you inherit an API that uses URL-based keys, wrap it behind a proxy that translates header-based auth into the legacy format — and plan to deprecate the legacy pattern on a documented timeline.


🧠 Knowledge Check

A dashboard service needs to read telemetry from the historian API and write anomaly alerts to a ticketing system. Should these two operations use the same API credential? Why or why not?

Reveal Answer & Explanation

No — they should use separate credentials with separate scopes.

Using a single credential for both operations violates the principle of least privilege and creates a blast radius problem:

  • If the credential is compromised, the attacker can both read all historian telemetry and write to the ticketing system (potentially injecting false alerts or suppressing real ones).
  • If the historian API is compromised, the blast extends to the ticketing system.

Instead, issue two credentials:

  1. A historian:read-scoped token for reading telemetry
  2. A ticketing:write-scoped token for writing alerts

If the dashboard process must hold both, it holds two short-lived tokens with separate renewal cycles. The two tokens are stored separately (e.g., different Vault AppRoles, different environment variable namespaces) so that a memory leak or log exposure of one doesn’t expose the other.

This decomposition also makes the audit trail clearer: historian reads appear in one credential’s log, and ticketing writes in another.


What’s Next

The IT Enterprise Zone is secured: secrets in Vault, build artifacts signed, API keys scoped and managed.

In Module 4, we move to the OT network and deploy Zeek and Suricata for deep packet inspection of industrial protocols — detecting the anomalous traffic that precedes a physical attack.