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

```bash
# 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:

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

### Step 2: Migrate Secrets

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

For dry run (test without actually migrating):

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

### Step 3: Verify Migration

```bash
# 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

```bash
# 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

```bash
# 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

```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

```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](./PHOENIX_VAULT_CLUSTER_DEPLOYMENT.md)
- [Master Secrets Inventory](./MASTER_SECRETS_INVENTORY.md)
- [Secrets Quick Reference](./SECRETS_QUICK_REFERENCE.md)
- [Vault Operations Guide](./VAULT_OPERATIONS_GUIDE.md)

---

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