Authentication

Noid uses token-based authentication to secure access to the server.

Quick Start

Setup Authentication

Configure your client to connect to a Noid server:

noid auth setup --url http://your-server:7654 --token <your-api-token>

This command:

  • Saves credentials to ~/.noid/config.toml
  • Verifies connectivity to the server
  • Tests authentication

Note: The default server port is 7654, not 8080.

Configuration Methods

1. Command Line

noid auth setup --url http://my-server:7654 --token abc123def456...

2. Environment Variables

export NOID_SERVER=http://my-server:7654
export NOID_TOKEN=your-64-char-token-here

# Commands now use these credentials automatically
noid list

3. Configuration File

Manually edit ~/.noid/config.toml:

server = "http://my-server:7654"
token = "your-64-character-hexadecimal-token"

Protect the configuration file:

chmod 600 ~/.noid/config.toml

API Tokens

Noid uses 64-character hexadecimal tokens for authentication.

Token Format

Example: a1b2c3d4e5f6...
Length: 64 characters
Charset: Hexadecimal (0-9, a-f)

Token Security

  • Tokens use SHA-256 hashing
  • Constant-time verification prevents timing attacks
  • Tokens grant full access to manage VMs
  • Store tokens securely - treat like passwords

Server-Side User Management

On the server, administrators manage users and tokens.

Creating Users

noid-server user create <username>

This generates a new user with a 64-character hexadecimal API token.

Rotating Tokens

If a token is compromised, rotate it:

noid-server user rotate-token <username>

This invalidates the old token and generates a new one.

Removing Users

noid-server user delete <username>

This removes the user and all their VMs.

Multi-Tenant Isolation

The Noid server provides complete isolation between users:

Database Level:

  • Each user's VMs are stored separately
  • Users can only query their own VMs

Filesystem Level:

  • Data organized under ~/.noid/users/<user-id>/
  • Complete directory isolation per user
  • Separate VM storage and checkpoints

Example structure:

~/.noid/
└── users/
    ├── alice-id/
    │   ├── vms/
    │   ├── checkpoints/
    │   └── logs/
    └── bob-id/
        ├── vms/
        ├── checkpoints/
        └── logs/

Security Features

Rate Limiting

The server implements rate limiting on failed authentication attempts to prevent brute force attacks.

Token Storage

  • Tokens are hashed with SHA-256 before storage
  • Original tokens are never stored in plaintext
  • Constant-time comparison prevents timing attacks

HTTPS/TLS

For production deployments, use HTTPS to encrypt token transmission:

noid auth setup --url https://my-server:7654 --token <token>

Use a reverse proxy (nginx, Caddy) to handle TLS termination.

Troubleshooting

Authentication Failed

Check token:

# Verify token in config
cat ~/.noid/config.toml

# Re-setup with correct token
noid auth setup --url http://my-server:7654 --token <correct-token>

Connection Refused

Verify server URL and port:

# Test server connectivity
curl http://my-server:7654/health

# Check port (should be 7654)
noid auth setup --url http://my-server:7654 --token <token>

Token Expired or Invalid

Tokens in Noid don't expire by default, but if authentication fails:

# Request new token from server administrator
# Then reconfigure
noid auth setup --url http://my-server:7654 --token <new-token>

Configuration Not Found

If the client can't find configuration:

# Check config file exists
ls -la ~/.noid/config.toml

# Recreate configuration
noid auth setup --url http://my-server:7654 --token <token>

Best Practices

  1. Secure Token Storage

    • Set file permissions: chmod 600 ~/.noid/config.toml
    • Never commit tokens to version control
    • Use environment variables in CI/CD

  2. Use HTTPS

    • Encrypt token transmission
    • Prevent man-in-the-middle attacks
    • Use TLS termination proxy

  3. Token Rotation

    • Rotate tokens if compromised
    • Rotate periodically for high-security environments
    • Generate new tokens for each environment (dev, staging, prod)

  4. Minimal Permissions

    • Each user gets their own token
    • Don't share tokens between users
    • Use separate tokens for different applications

  5. Monitor Access

    • Check server logs for authentication attempts
    • Monitor for unusual activity
    • Investigate failed authentication attempts

Configuration Examples

Local Development

# ~/.noid/config.toml
server = "http://localhost:7654"
token = "dev-token-for-local-testing"

Remote Server

# ~/.noid/config.toml
server = "https://noid.example.com:7654"
token = "production-64-character-hex-token"

CI/CD Environment

# .gitlab-ci.yml or similar
export NOID_SERVER=https://ci-server:7654
export NOID_TOKEN=$NOID_CI_TOKEN  # From CI variables

noid create ci-vm-$CI_JOB_ID
noid exec ci-vm-$CI_JOB_ID -- ./run-tests.sh
noid destroy ci-vm-$CI_JOB_ID

API Authentication

When using the HTTP API directly (not the CLI), include the token in the Authorization header:

curl -H "Authorization: Bearer your-64-char-token" \
     http://my-server:7654/v1/vms

All authenticated endpoints are under /v1/.

Next Steps