vault-link/docs/config/authentication.md

Authentication Configuration

VaultLink uses token-based authentication with per-user vault access control. This guide covers all authentication and authorization options.

Overview

Authentication in VaultLink:

• Token-based: Users authenticate with secure tokens
• Configured in YAML: All users defined in config.yml
• Vault-level access: Control which vaults each user can access
• No password hashing: Tokens are treated as secrets

Basic Configuration

users:
    user_configs:
        - name: alice
          token: alice-secure-token-here
          vault_access:
              type: allow_access_to_all

User Configuration Fields

name

Type: String Required: Yes

Human-readable identifier for the user. Used in logs and auditing.

- name: alice

Notes:

• Must be unique across all users
• Used for identification only, not authentication
• Appears in server logs
• Can be any string (e.g., email, username)

token

Type: String Required: Yes

Authentication token for the user. Must be kept secret.

- token: 1a2b3c4d5e6f7g8h9i0j...

Best practices:

• Generate with: openssl rand -hex 32
• Minimum length: 32 characters
• Use different token per user
• Never commit to version control
• Rotate periodically

Example token generation:

# Generate a secure token
openssl rand -hex 32
# Output: a7f3c9d1e8b2f4a6c3d9e1f7b8a4c2d6e9f1a3b7c5d8e2f4a6b9c3d1e8f7a4b2

vault_access

Type: Object Required: Yes

Defines which vaults the user can access.

Three modes:

1. allow_access_to_all: Access to all vaults
2. allow_list: Access to specific vaults only
3. deny_list: Access to all vaults except specific ones

Access Control Modes

Allow Access to All

Grant access to every vault:

users:
    user_configs:
        - name: admin
          token: admin-token
          vault_access:
              type: allow_access_to_all

Use cases:

• Administrator accounts
• Personal single-user deployments
• Development/testing

Allow List

Grant access only to specific vaults:

users:
    user_configs:
        - name: alice
          token: alice-token
          vault_access:
              type: allow_list
              allowed:
                  - personal
                  - shared-team
                  - project-alpha

Use cases:

• Multi-user deployments
• Restricted access scenarios
• Separation of concerns

Notes:

• User can only access listed vaults
• Attempting to access other vaults returns authentication error
• Empty list = no access to any vault

Deny List

Grant access to all vaults except specific ones:

users:
    user_configs:
        - name: bob
          token: bob-token
          vault_access:
              type: deny_list
              denied:
                  - restricted
                  - admin-only

Use cases:

• Users with broad access except sensitive vaults
• Simplify configuration when most vaults are accessible

Notes:

• User can access any vault not in the deny list
• Attempting to access denied vaults returns authentication error

Multi-User Scenarios

Personal Use (Single User)

users:
    user_configs:
        - name: me
          token: my-super-secret-token
          vault_access:
              type: allow_access_to_all

Small Team (Shared Vaults)

users:
    user_configs:
        - name: alice
          token: alice-token
          vault_access:
              type: allow_list
              allowed:
                  - personal-alice
                  - team-shared
        - name: bob
          token: bob-token
          vault_access:
              type: allow_list
              allowed:
                  - personal-bob
                  - team-shared
        - name: charlie
          token: charlie-token
          vault_access:
              type: allow_list
              allowed:
                  - personal-charlie
                  - team-shared

Organization (Mixed Access)

users:
    user_configs:
        - name: admin
          token: admin-token
          vault_access:
              type: allow_access_to_all

        - name: developer
          token: dev-token
          vault_access:
              type: allow_list
              allowed:
                  - engineering-docs
                  - api-specs
                  - shared

        - name: designer
          token: design-token
          vault_access:
              type: allow_list
              allowed:
                  - design-docs
                  - brand-assets
                  - shared

        - name: readonly
          token: readonly-token
          vault_access:
              type: allow_list
              allowed:
                  - public-wiki

Authentication Flow

Connection

1. Client connects via WebSocket
2. Client sends authentication message:

   {
     "type": "auth",
     "token": "user-token",
     "vault": "vault-name"
   }
   

3. Server validates:
   • Token exists in config
   • User has access to requested vault
4. Server responds:
   • Success: Connection established
   • Failure: Connection closed with error

Validation

Server checks:

1. Token match: Token exists in user_configs
2. Vault access: User has permission for vault
3. Connection limits: Not exceeding max_clients_per_vault

Errors

Invalid token:

Authentication failed: Invalid token

No vault access:

Authentication failed: User does not have access to vault 'restricted'

Connection limit:

Connection rejected: Maximum clients reached for vault

Security Best Practices

Token Generation

Generate strong tokens:

# 64 character hex token (256 bits)
openssl rand -hex 32

# Base64 encoded (256 bits)
openssl rand -base64 32

# UUID v4
uuidgen

Token Storage

In config file:

users:
    user_configs:
        - name: alice
          token: !ENV ALICE_TOKEN # Read from environment variable

Load from environment:

export ALICE_TOKEN="$(openssl rand -hex 32)"
./sync_server config.yml

Token Rotation

Periodically change tokens:

1. Generate new token
2. Update config.yml
3. Restart server
4. Update clients with new token

Token Revocation

To revoke access:

1. Remove user from config.yml
2. Restart server
3. User's connections will be rejected

For immediate revocation:

• Remove user from config
• Restart server
• Existing connections are terminated

Access Patterns

Read-Only Users

VaultLink doesn't distinguish read-only vs read-write. Implement via client:

# Server: Grant access
users:
  user_configs:
  - name: readonly
    token: readonly-token
    vault_access:
      type: allow_list
      allowed:
        - public

# Client: Use CLI in read-only mode (mount vault read-only)
docker run -v /vault:/vault:ro ...

Temporary Access

Grant temporary access:

1. Add user to config
2. Set reminder to remove later
3. Remove user when no longer needed
4. Restart server

For automation:

# Add user with expiry comment
echo "  - name: temp-user  # EXPIRES: 2024-12-31" >> config.yml
echo "    token: temp-token" >> config.yml

Shared Tokens (Not Recommended)

Multiple users sharing a token:

• All appear as same user in logs
• Can't revoke individual access
• Security risk if one person leaves

Instead: Create separate users with same vault access.

Monitoring

Server Logs

Authentication events are logged:

2024-01-01 12:00:00 INFO User 'alice' authenticated for vault 'personal'
2024-01-01 12:00:05 WARN Authentication failed: Invalid token from 192.168.1.100
2024-01-01 12:00:10 WARN User 'bob' denied access to vault 'restricted'

Audit Trail

Monitor authentication:

# View authentication logs
grep "authenticated" logs/*.log

# View failed authentications
grep "Authentication failed" logs/*.log

# View access denials
grep "denied access" logs/*.log

Advanced Scenarios

Multiple Servers

Same user across multiple server instances:

# Server 1 config.yml
users:
  user_configs:
  - name: alice
    token: alice-global-token
    vault_access:
      type: allow_list
      allowed:
        - vault-1
        - vault-2

# Server 2 config.yml
users:
  user_configs:
  - name: alice
    token: alice-global-token  # Same token
    vault_access:
      type: allow_list
      allowed:
        - vault-3
        - vault-4

Service Accounts

Tokens for automated systems:

users:
    user_configs:
        - name: backup-service
          token: backup-service-token
          vault_access:
              type: allow_access_to_all

        - name: ci-pipeline
          token: ci-token
          vault_access:
              type: allow_list
              allowed:
                  - documentation

        - name: monitoring
          token: monitoring-token
          vault_access:
              type: allow_list
              allowed:
                  - metrics

Dynamic Vault Access

VaultLink doesn't support runtime user management. To change access:

1. Update config.yml
2. Restart server
3. Users reconnect automatically

For frequent changes, consider:

• Over-provision access (deny list)
• Use external authentication proxy
• Script config updates + reload

Troubleshooting

Can't connect

Check token:

# Verify token in config matches client
grep "token:" config.yml

Check vault name:

# Ensure vault is in allowed list
grep -A 5 "name: alice" config.yml

Check server logs:

tail -f logs/*.log | grep -i auth

Access denied

Verify vault access:

# Check user's vault_access configuration
users:
    user_configs:
        - name: alice
          vault_access:
              type: allow_list
              allowed:
                  - vault-name # Must match exactly

Case sensitivity:

• Vault names are case-sensitive
• Vault ≠ vault
• Ensure exact match in config and client

Token not working

Check for typos:

• Extra spaces
• Hidden characters
• Wrong quotes in YAML

Regenerate token:

# Generate new token
openssl rand -hex 32

# Update config
# Restart server
# Update client

Next Steps

• Server configuration reference →
• Advanced configuration →
• Deploy the server →