Security - Embucket

Embucket implements Snowflake’s authentication mechanisms and provides multiple options for securing your deployment. This guide covers authentication methods, token management, and production security recommendations.

Authentication Overview

Embucket supports two primary authentication methods:

Demo Credentials

Username/password authentication for development and testing environments.

JWT Tokens

JSON Web Token-based authentication for secure production deployments.

Demo User/Password Authentication

Default Credentials

For local development, Embucket provides demo credentials:

Username: embucket
Password: embucket

Default demo credentials should never be used in production environments.

Configuration

Demo credentials are configured at startup:

docker run --name embucket --rm -p 3000:3000 \
  -e AUTH_DEMO_USER=myuser \
  -e AUTH_DEMO_PASSWORD=mypassword \
  embucket/embucket

When a client connects, they authenticate via the Snowflake login endpoint:

curl -X POST http://localhost:3000/session/v1/login-request \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "LOGIN_NAME": "embucket",
      "PASSWORD": "embucket",
      "ACCOUNT_NAME": "acc",
      "CLIENT_APP_ID": "SnowSQL",
      "CLIENT_APP_VERSION": "1.0"
    }
  }'

Response:

{
  "success": true,
  "message": "successfully executed",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

The returned JWT token is used for subsequent requests.

JWT Token Configuration

JWT Secret Setup

The JWT secret is used to sign and verify authentication tokens. Set it using environment variables or command-line flags:

export JWT_SECRET="your-secret-key-here"
./embucketd

Never commit JWT secrets to version control. Use environment variables or secret management systems.

Generating Secure Secrets

Generate a cryptographically secure JWT secret:

# Generate random 32-byte secret (base64 encoded)
openssl rand -base64 32

# Example output:
K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=

Use this generated value as your JWT_SECRET:

export JWT_SECRET="K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols="

JWT Token Properties

Expiration

3 days

Tokens expire after 3 days (259,200 seconds) by default.

Algorithm

HS256

Tokens are signed using HMAC-SHA256.

Claims

object

Includes session_id, username, account, database, schema, and host.

Token Anatomy

A decoded JWT token contains:

{
  "sub": "embucket",
  "exp": 1735948800,
  "iat": 1735689600,
  "aud": "localhost",
  "session": {
    "session_id": "01HZK3X...",
    "metadata": {
      "user_name": "embucket",
      "account_name": "acc",
      "database": "analytics",
      "schema": "public",
      "warehouse": "em.wh",
      "client_app_id": "SnowSQL",
      "client_app_version": "1.2.3"
    }
  }
}

Session Management

Session Creation

Sessions are created upon successful login:

Client sends credentials to /session/v1/login-request
Embucket validates credentials against configured demo user/password
A new session is created with a unique session_id
A JWT token is generated and returned

Session Lifecycle

Sessions remain active as long as:

The JWT token hasn’t expired (3 days)
The session hasn’t been explicitly deleted
The Embucket instance is running

Session Termination

Delete a session explicitly:

curl -X POST http://localhost:3000/session?delete=true \
  -H "Authorization: Bearer <your-jwt-token>"

Sessions are stored in-memory and are lost when Embucket restarts.

Query Context

Each query execution carries session context:

Database: Active database for the query
Schema: Active schema for the query
Warehouse: Virtual warehouse identifier
User: Authenticated username
Request ID: Unique identifier for query tracking

Authorization

Currently, Embucket uses a simplified authorization model:

Authenticated users have full access to all databases and schemas

No role-based access control (RBAC) - coming in future releases

All operations are permitted once authenticated

Role and permission management is planned for future releases. Track progress on the Embucket GitHub repository.

Network Security

TLS/HTTPS

For production deployments, use TLS encryption:

Reverse Proxy (Recommended)
Load Balancer
API Gateway

Deploy Embucket behind a reverse proxy like Nginx or Traefik:

server {
    listen 443 ssl;
    server_name embucket.example.com;
    
    ssl_certificate /etc/ssl/certs/embucket.crt;
    ssl_certificate_key /etc/ssl/private/embucket.key;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Network Isolation

Restrict network access to Embucket:

Firewall Rules

Limit incoming connections to specific IP ranges or VPCs.

Private Networks

Deploy Embucket in private subnets without public IP addresses.

VPN/Bastion Access

Require VPN or bastion host access to reach Embucket.

Lambda Security

For AWS Lambda deployments:

# Deploy with function URL authentication
cargo lambda deploy \
  --binary-name bootstrap \
  embucket-lambda \
  --enable-function-url \
  --iam-role arn:aws:iam::123456789012:role/embucket-lambda-role

Configure IAM authentication for the Lambda function URL:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:user/allowed-user"
      },
      "Action": "lambda:InvokeFunctionUrl",
      "Resource": "arn:aws:lambda:us-east-2:123456789012:function:embucket-lambda"
    }
  ]
}

Production Security Best Practices

Rotate Secrets

Regularly rotate JWT secrets and demo credentials. Update all client configurations after rotation.

Use Strong Passwords

Set complex demo passwords with high entropy: uppercase, lowercase, numbers, and symbols.

Enable TLS

Always use HTTPS/TLS in production. Never transmit credentials over unencrypted connections.

Monitor Access

Log authentication attempts and query activity for security auditing.

Limit Exposure

Deploy in private networks with restricted access. Use VPNs or bastion hosts.

Update Regularly

Keep Embucket updated to the latest version for security patches.

Security Checklist

Change Default Credentials

export AUTH_DEMO_USER=production_user
export AUTH_DEMO_PASSWORD=$(openssl rand -base64 24)

Set Strong JWT Secret

export JWT_SECRET=$(openssl rand -base64 32)

Enable TLS

Deploy behind a reverse proxy with valid TLS certificate.

Configure Firewall

Restrict access to known IP addresses or VPC ranges.

Enable Logging

Capture authentication and query logs for audit trails.

Test Security

Verify unauthorized access is blocked and credentials are required.

Security Limitations

Be aware of current security limitations:

No RBAC: All authenticated users have full access
No multi-tenancy: Single authentication domain per instance
In-memory sessions: Sessions lost on restart
No SSO: SAML, OAuth not yet supported
No audit logging: Query auditing must be implemented externally

These features are on the roadmap. See the GitHub issues for status updates.

Environment-Specific Security

Development

# Development: Relaxed security is acceptable
export AUTH_DEMO_USER=dev
export AUTH_DEMO_PASSWORD=dev
export JWT_SECRET=dev-secret-not-for-production

# No TLS required for localhost
./embucketd --host 127.0.0.1 --port 3000

Staging

# Staging: Production-like security
export AUTH_DEMO_USER=staging_user
export AUTH_DEMO_PASSWORD=$(cat /run/secrets/staging_password)
export JWT_SECRET=$(cat /run/secrets/jwt_secret)

# Use TLS via reverse proxy
# Restrict to internal network only
./embucketd --host 0.0.0.0 --port 3000

Production

# Production: Maximum security
export AUTH_DEMO_USER=$(cat /run/secrets/production_user)
export AUTH_DEMO_PASSWORD=$(cat /run/secrets/production_password)
export JWT_SECRET=$(cat /run/secrets/jwt_secret)

# Deploy behind TLS-terminating load balancer
# Use private subnets
# Enable audit logging
# Monitor for security events
./embucketd --host 0.0.0.0 --port 3000

Troubleshooting

Authentication fails with correct credentials

Solution:

Verify credentials match server configuration:

echo $AUTH_DEMO_USER
echo $AUTH_DEMO_PASSWORD

Check JWT secret is set:
```
echo $JWT_SECRET
```
Ensure client is sending correct Content-Type header
Review server logs for authentication errors

JWT token expired errors

Solution:

Tokens expire after 3 days - re-authenticate to get a new token
Check system clock synchronization on client and server
Use the Snowflake CLI which handles token refresh automatically

Invalid JWT signature

Solution:

Verify JWT_SECRET matches on server and during token generation
Don’t change JWT_SECRET while sessions are active
Restart Embucket and re-authenticate after changing secrets

Connection works locally but fails remotely

Solution:

Ensure firewall rules allow inbound connections
Verify TLS certificate is valid and trusted
Check if reverse proxy is properly forwarding requests

Test with curl to isolate client vs server issues:

curl -k -X POST https://embucket.example.com/session/v1/login-request

Next Steps

Deployment Guide

Secure deployment patterns for production

Configuration

Advanced configuration options

Monitoring

Log authentication events and monitor security

API Reference

Programmatic authentication via REST API

Get Started

Core Concepts

Deployment

Catalogs & Storage

Usage Guides

Operations

Documentation Index

​Authentication Overview

Demo Credentials

JWT Tokens

​Demo User/Password Authentication

​Default Credentials

​Configuration

​Login Process

​JWT Token Configuration

​JWT Secret Setup

​Generating Secure Secrets

​JWT Token Properties

​Token Anatomy

​Session Management

​Session Creation

​Session Lifecycle

​Session Termination

​Query Context

​Authorization

​Network Security

​TLS/HTTPS

​Network Isolation

​Lambda Security

​Production Security Best Practices

Rotate Secrets

Use Strong Passwords

Enable TLS

Monitor Access

Limit Exposure

Update Regularly

​Security Checklist

​Security Limitations

​Environment-Specific Security

​Development

​Staging

​Production

​Troubleshooting

​Next Steps

Deployment Guide

Configuration

Monitoring

API Reference

Authentication Overview

Demo User/Password Authentication

Default Credentials

Configuration

Login Process

JWT Token Configuration

JWT Secret Setup

Generating Secure Secrets

JWT Token Properties

Token Anatomy

Session Management

Session Creation

Session Lifecycle

Session Termination

Query Context

Authorization

Network Security

TLS/HTTPS

Network Isolation

Lambda Security

Production Security Best Practices

Security Checklist

Security Limitations

Environment-Specific Security

Development

Staging

Production

Troubleshooting

Next Steps