Secrets Management

This guide covers best practices for managing sensitive configuration values like API keys, database credentials, and authentication secrets.

Overview

Secrets that require protection:

Secret	Component	Purpose
LICENSE_MONITOR_API_KEY	Both	API authentication
AUTH_OKTA_SECRET	Dashboard	OAuth client secret
AUTH_SECRET	Dashboard	JWT signing key
AUTH_OKTA_ID	Dashboard	OAuth client ID
Database credentials	Dashboard	Convex connection

Secret Sources

Priority Order

Secrets are loaded in this priority (highest to lowest):

1. Secrets manager (HashiCorp Vault, AWS Secrets Manager)
2. Environment variables
3. Configuration files
4. Default values (never use for secrets)

Environment Variables

Linux/macOS

# Set secrets in shell profile
export LICENSE_MONITOR_API_KEY="your-api-key"
export AUTH_SECRET="your-jwt-secret"
export AUTH_OKTA_SECRET="your-okta-secret"

# Or use a secrets file
cat > /etc/license-monitor/secrets.env << 'EOF'
LICENSE_MONITOR_API_KEY=your-api-key
AUTH_SECRET=your-jwt-secret
AUTH_OKTA_SECRET=your-okta-secret
EOF

chmod 600 /etc/license-monitor/secrets.env

Windows

# Set machine-level environment variables
[Environment]::SetEnvironmentVariable(
    "LICENSE_MONITOR_API_KEY",
    "your-api-key",
    [EnvironmentVariableTarget]::Machine
)

# Or use Windows Credential Manager
cmdkey /generic:LicenseMonitorApiKey /user:service /pass:your-api-key

Systemd Integration

/etc/systemd/system/license-monitor.service

[Service]
EnvironmentFile=/etc/license-monitor/secrets.env

Secure the secrets file:

sudo chown root:license-monitor /etc/license-monitor/secrets.env
sudo chmod 640 /etc/license-monitor/secrets.env

Docker Secrets

Docker Compose

docker-compose.yml

version: '3.8'

services:
  license-monitor:
    image: license-monitor:latest
    secrets:
      - license_monitor_api_key
    environment:
      - LICENSE_MONITOR_API_KEY_FILE=/run/secrets/license_monitor_api_key

  license-server-detail:
    image: license-server-detail:latest
    secrets:
      - auth_secret
      - okta_secret
    environment:
      - AUTH_SECRET_FILE=/run/secrets/auth_secret
      - AUTH_OKTA_SECRET_FILE=/run/secrets/okta_secret

secrets:
  license_monitor_api_key:
    file: ./secrets/license_monitor_api_key.txt
  auth_secret:
    file: ./secrets/auth_secret.txt
  okta_secret:
    file: ./secrets/okta_secret.txt

Docker Swarm

# Create secrets
echo "your-api-key" | docker secret create license_monitor_api_key -
echo "your-jwt-secret" | docker secret create auth_secret -

# Use in service
docker service create \
    --name license-monitor \
    --secret license_monitor_api_key \
    license-monitor:latest

HashiCorp Vault

Setup

# Enable KV secrets engine
vault secrets enable -path=license-monitor kv-v2

# Store secrets
vault kv put license-monitor/api-keys \
    license_monitor_api_key="your-api-key" \
    auth_secret="your-jwt-secret"

# Create policy
vault policy write license-monitor - << 'EOF'
path "license-monitor/data/api-keys" {
  capabilities = ["read"]
}
EOF

# Create AppRole for application
vault auth enable approle
vault write auth/approle/role/license-monitor \
    policies="license-monitor" \
    secret_id_ttl=0 \
    token_ttl=1h \
    token_max_ttl=24h

Application Integration

# Get role ID and secret ID
ROLE_ID=$(vault read -field=role_id auth/approle/role/license-monitor/role-id)
SECRET_ID=$(vault write -field=secret_id -f auth/approle/role/license-monitor/secret-id)

# Login and get token
VAULT_TOKEN=$(vault write -field=token auth/approle/login \
    role_id=$ROLE_ID \
    secret_id=$SECRET_ID)

# Read secrets
export LICENSE_MONITOR_API_KEY=$(vault kv get -field=license_monitor_api_key license-monitor/api-keys)

Vault Agent

vault-agent.hcl

auto_auth {
  method "approle" {
    config = {
      role_id_file_path = "/etc/vault/role_id"
      secret_id_file_path = "/etc/vault/secret_id"
    }
  }

  sink "file" {
    config = {
      path = "/etc/vault/token"
    }
  }
}

template {
  source = "/etc/license-monitor/secrets.env.tpl"
  destination = "/etc/license-monitor/secrets.env"
  perms = 0640
}

AWS Secrets Manager

Store Secrets

# Create secret
aws secretsmanager create-secret \
    --name license-monitor/api-keys \
    --secret-string '{
        "LICENSE_MONITOR_API_KEY": "your-api-key",
        "AUTH_SECRET": "your-jwt-secret",
        "AUTH_OKTA_SECRET": "your-okta-secret"
    }'

Retrieve Secrets

AWS CLI

# Get secret value
aws secretsmanager get-secret-value \
    --secret-id license-monitor/api-keys \
    --query SecretString \
    --output text | jq -r '.LICENSE_MONITOR_API_KEY'

Node.js

const { SecretsManagerClient, GetSecretValueCommand } = require('@aws-sdk/client-secrets-manager');

const client = new SecretsManagerClient({ region: 'us-east-1' });

async function getSecrets() {
  const command = new GetSecretValueCommand({
    SecretId: 'license-monitor/api-keys',
  });

  const response = await client.send(command);
  return JSON.parse(response.SecretString);
}

IAM Policy

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue"
            ],
            "Resource": [
                "arn:aws:secretsmanager:us-east-1:123456789:secret:license-monitor/*"
            ]
        }
    ]
}

Secret Rotation

Rotation Strategy

1. Generate new secret
2. Update secrets manager
3. Deploy to applications (rolling update)
4. Verify functionality
5. Remove old secret

Automated Rotation Script

rotate-api-key.sh

#!/bin/bash
# Generate new key
NEW_KEY=$(openssl rand -hex 32)

# Update Vault
vault kv patch license-monitor/api-keys \
    license_monitor_api_key="$NEW_KEY"

# Restart services to pick up new secret
systemctl restart license-monitor
systemctl restart license-server-detail

# Verify health
sleep 10
curl -f http://localhost:8080/api/health || exit 1
curl -f http://localhost:3000/api/health || exit 1

echo "Rotation complete"

Rotation Schedule

Secret	Rotation Frequency	Notes
API Keys	90 days	Automated rotation
OAuth Secrets	Annually	Coordinate with IdP
JWT Secrets	90 days	Plan for session invalidation
SSL Certificates	Before expiry	Use cert-manager or similar

CI/CD Integration

GitHub Actions

.github/workflows/deploy.yml

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to production
        env:
          LICENSE_MONITOR_API_KEY: ${{ secrets.LICENSE_MONITOR_API_KEY }}
          AUTH_SECRET: ${{ secrets.AUTH_SECRET }}
          AUTH_OKTA_SECRET: ${{ secrets.AUTH_OKTA_SECRET }}
        run: |
          # Deploy with secrets
          ./deploy.sh

GitLab CI

.gitlab-ci.yml

deploy:
  stage: deploy
  script:
    - ./deploy.sh
  variables:
    LICENSE_MONITOR_API_KEY: $LICENSE_MONITOR_API_KEY
    AUTH_SECRET: $AUTH_SECRET
  only:
    - main

Best Practices

Do

• Use a secrets manager in production
• Rotate secrets regularly
• Use least-privilege access
• Audit secret access
• Encrypt secrets at rest
• Use separate secrets per environment

Do Not

• Commit secrets to version control
• Log secrets (even accidentally)
• Share secrets via email or chat
• Use default or example secrets
• Store secrets in plain text
• Reuse secrets across environments

Auditing

# Monitor secret access (Vault example)
vault audit enable file file_path=/var/log/vault/audit.log

# Review access logs
grep "license-monitor" /var/log/vault/audit.log | jq '.request.path'

Caution

Regularly audit who has access to secrets and revoke unnecessary permissions. Implement alerting for unusual access patterns.

Next Steps

• API Authentication - Using API keys
• Production Setup - Production deployment
• Security Overview - Complete security guide