proxmox/docs/04-configuration/ADMIN_VAULT_SETUP.md

Admin Vault Setup - Sankofa Admin Portal

Last Updated: 2026-01-31
Document Version: 1.0
Status: Active Documentation

---

Date: 2026-01-19
Status: ✅ READY FOR DEPLOYMENT

---

Executive Summary

This document describes the setup and migration of all discovered secrets to the private admin vault for the Sankofa Admin Portal. The admin vault provides secure, centralized storage for all administrative secrets used across the Phoenix infrastructure.

---

Overview

What is the Admin Vault?

The Admin Vault is a private, isolated namespace within the Phoenix Vault cluster dedicated to storing administrative secrets for the Sankofa Admin Portal. It provides:

• Elevated Permissions: Super admin access for administrative operations
• Audit Logging: All access logged for security compliance
• Organized Structure: Secrets organized by category (blockchain, cloudflare, database, etc.)
• Enhanced Security: Extended TTL and enhanced encryption
• Automatic Backups: Included in daily cluster backups

Admin Vault Path Structure

secret/data/admin/sankofa-admin/
├── blockchain/
│   ├── private-keys/
│   ├── addresses/
│   └── contracts/
├── cloudflare/
│   ├── api-tokens/
│   ├── api-keys/
│   ├── tunnel-tokens/
│   └── origin-ca-key
├── database/
│   └── dbis-core/
├── npm/
│   ├── passwords/
│   └── email
├── unifi/
│   ├── api-key
│   └── password
└── infrastructure/

---

Setup Instructions

Step 1: Provision Admin Vault

# Set Vault credentials
export VAULT_TOKEN=hvs.PMJcL6HkZnz0unUYZAdfttZY
export VAULT_ADDR=http://192.168.11.200:8200

# Provision admin vault
cd /home/intlc/projects/proxmox
./scripts/provision-admin-vault.sh

Or using the TypeScript script directly:

cd dbis_core
npx tsx scripts/provision-admin-vault.ts \
  --org "Sankofa Admin" \
  --name "sankofa-admin" \
  --level "super_admin"

Step 2: Migrate Secrets

# Migrate all secrets from inventory
./scripts/migrate-secrets-to-admin-vault.sh

For dry run (test without actually migrating):

DRY_RUN=true ./scripts/migrate-secrets-to-admin-vault.sh

Step 3: Verify Migration

# List secrets in admin vault
vault list secret/data/admin/sankofa-admin

# Read a specific secret
vault read secret/data/admin/sankofa-admin/blockchain/private-keys/deployer

---

Secrets Migration

Migrated Secrets

All secrets from MASTER_SECRETS_INVENTORY.md are migrated to the admin vault:

1. Blockchain/Web3 Secrets

• Private Keys: Deployer, 237-combo
• Addresses: Deployer address
• Contracts: LINK token, CCIP router, Token factory, Token registry

2. Cloudflare Secrets

• API Tokens: Main token, script tokens
• API Keys: Proxmox, loc-az-hci
• Tunnel Tokens: Main tunnel, shared tunnel
• Origin CA Key: Full certificate key
• Account Info: Account ID, email

3. NPM (Nginx Proxy Manager) Secrets

• Passwords: Hashed and plain text
• Email: Admin email

4. Database Credentials

• DBIS Core: Database URL (from .env)

5. UniFi/Omada Secrets

• API Key: UniFi API key
• Password: UniFi password

---

Admin Vault Access

AppRole Credentials

After provisioning, you'll receive:

• Role ID: Unique AppRole identifier
• Secret ID: Unique AppRole secret (display once)
• API Endpoint: http://192.168.11.200:8200

Authentication

# Authenticate with AppRole
export VAULT_ADDR=http://192.168.11.200:8200
export VAULT_ROLE_ID=<role-id>
export VAULT_SECRET_ID=<secret-id>

vault write auth/approle/login \
  role_id=$VAULT_ROLE_ID \
  secret_id=$VAULT_SECRET_ID

Access Secrets

# Read a secret
vault read secret/data/admin/sankofa-admin/blockchain/private-keys/deployer

# List secrets in a category
vault list secret/data/admin/sankofa-admin/blockchain

# Write a new secret
vault write secret/data/admin/sankofa-admin/infrastructure/new-secret \
  value="secret-value" \
  description="Description"

---

Integration with Applications

Node.js/TypeScript

import Vault from 'node-vault';

const vault = Vault({
  endpoint: process.env.VAULT_ADDR || 'http://192.168.11.200:8200',
});

// Authenticate
await vault.approleLogin({
  role_id: process.env.VAULT_ROLE_ID,
  secret_id: process.env.VAULT_SECRET_ID,
});

// Read secret
const secret = await vault.read('secret/data/admin/sankofa-admin/blockchain/private-keys/deployer');
const privateKey = secret.data.data.value;

Python

import hvac

client = hvac.Client(url='http://192.168.11.200:8200')

# Authenticate
response = client.auth.approle.login(
    role_id=os.environ['VAULT_ROLE_ID'],
    secret_id=os.environ['VAULT_SECRET_ID']
)
client.token = response['auth']['client_token']

# Read secret
secret = client.secrets.kv.v2.read_secret_version(
    path='admin/sankofa-admin/blockchain/private-keys/deployer'
)
private_key = secret['data']['data']['value']

---

Security Considerations

Access Control

• Super Admin Level: Full access to admin vault
• Extended TTL: 8-hour tokens, 7-day secret IDs
• Audit Logging: All access logged
• Policy Isolation: Separate policies from user vaults

Best Practices

1. Store Credentials Securely:

   • Role ID and Secret ID should be stored in secure vault
   • Never commit credentials to version control
   • Rotate Secret IDs regularly

2. Monitor Access:

   • Review audit logs regularly
   • Set up alerts for unusual access patterns
   • Track all secret reads/writes

3. Backup Strategy:

   • Admin vault included in daily cluster backups
   • Test restore procedures regularly
   • Maintain off-site backups

4. Secret Rotation:

   • Rotate secrets regularly
   • Update secrets in admin vault immediately
   • Remove old secrets after rotation

---

Troubleshooting

Provisioning Fails

Issue: Admin vault provisioning fails

Solutions:

1. Check Vault cluster is accessible
2. Verify root token has permissions
3. Ensure cluster is unsealed
4. Check logs for specific errors

Migration Fails

Issue: Secret migration fails

Solutions:

1. Verify admin vault exists
2. Check authentication credentials
3. Ensure vault path is correct
4. Review error messages for specific issues

Access Denied

Issue: Cannot access admin vault secrets

Solutions:

1. Verify AppRole credentials are correct
2. Check token hasn't expired
3. Verify policy allows access
4. Ensure vault path matches exactly

---

Related Documentation

• Phoenix Vault Cluster Deployment
• Master Secrets Inventory
• Secrets Quick Reference
• Vault Operations Guide

---

Status: ✅ READY FOR DEPLOYMENT
Last Updated: 2026-01-19