Skip to content

Vault Integration Overview

Vault is the central secrets management system for CWIQ. All credentials, tokens, and API keys are stored in Vault — never in GitLab CI/CD variables or configuration files.

Vault URL: https://vault.shared.cwiq.io

All CWIQ secrets are stored in the KV version 2 (KV v2) secrets engine, mounted at the path secret/. Every application, CI/CD pipeline job, and service authenticates to Vault independently and receives only the secrets it needs — not a shared token.

Authentication Methods

Three authentication methods are used across CWIQ, each suited to a different caller type.

Auth Method Used By Mechanism
JWT CI/CD pipeline jobs GitLab issues a JWT token per job; exchanged for a short-lived Vault token
AppRole Docker containers and application services Role ID + Secret ID pair; Vault Agent handles renewal automatically
OIDC / Token Human users (Vault UI, CLI) Browser-based SSO login via Authentik, or a personal API token

How Secrets Flow

flowchart LR
    subgraph CI["CI/CD Pipeline"]
        GL[GitLab CI Job] -->|JWT token| VA[Vault /auth/jwt/login]
        VA -->|short-lived VAULT_TOKEN| SEC[Read secrets via curl]
        SEC -->|env vars| JOB[Job script]
    end

    subgraph APP["Application Runtime"]
        AGENT[Vault Agent sidecar] -->|AppRole Role ID + Secret ID| VB[Vault AppRole auth]
        VB -->|renewable token| TMPL[Render .env template]
        TMPL -->|write to tmpfs| VOL[/vault/secrets/.env]
        CONTAINER[Application container] -->|source .env at startup| VOL
    end

    subgraph HUMAN["Human Access"]
        DEV[Developer] -->|OIDC SSO| VUI[Vault UI / CLI]
        VUI -->|read/write secrets| KV[KV v2: secret/]
    end

Secrets Engine Layout

All secrets use the KV v2 engine at secret/. The path convention is:

secret/{scope}/{env}/{app}/{concern}

Top-level scopes:

Scope Contains
secret/cwiq/ Platform application secrets (per environment and service)
secret/nexus/ Nexus service account credentials
secret/sonarqube/ SonarQube admin and CI service account
secret/defectdojo/ DefectDojo admin and CI service account
secret/orchestrator/ Platform-level service secrets (E2E test user)
secret/reportportal/ ReportPortal service account

See Secret Path Conventions for the full reference table.

Key Principles

Secrets never touch GitLab. No Vault tokens, credentials, or API keys are stored as GitLab CI/CD variables. Pipeline jobs authenticate to Vault using a JWT token issued by GitLab and fetch secrets at job start.

Least-privilege policies. Each Vault role grants access only to the specific paths that caller needs. A CI job using the nexus-ci role can read Nexus credentials and scan tool tokens, but cannot read database passwords or application config secrets.

Secrets are never written to disk. Application containers receive secrets through a tmpfs volume (RAM only). The Vault Agent sidecar renders secrets into /vault/secrets/ which is a tmpfs mount — it is never persisted to the container filesystem or any host volume.

Credentials in GitLab variables are a security anti-pattern.

GitLab CI/CD variables are visible to any maintainer of the project and are logged in job traces if not masked correctly. Vault JWT auth eliminates this risk entirely — a CI job gets a short-lived token that is only valid for the duration of that job.

Vault Policies

Vault policies control which paths each role can access. The nexus-ci policy covers CI/CD jobs across all platform services:

# nexus-ci policy (read-only, CI pipeline scope)
path "secret/data/nexus/*" {
  capabilities = ["read"]
}
path "secret/data/sonarqube/svc-orchestrator" {
  capabilities = ["read"]
}
path "secret/data/defectdojo/svc-orchestrator" {
  capabilities = ["read"]
}
path "secret/data/orchestrator/e2e-test-user" {
  capabilities = ["read"]
}
path "secret/data/reportportal/svc-orchestrator" {
  capabilities = ["read"]
}

Application-specific policies follow the same pattern but scope to secret/data/cwiq/{env}/{app}/*.