Access Control Policy

Overview

This document defines the access control mechanisms, policies, and procedures for HeliosDB-Lite, ensuring appropriate protection of data and system resources.

Authentication Methods

1. Password Authentication (SCRAM-SHA-256)

PostgreSQL-compatible password authentication with salted challenge-response.

-- Create user with password
CREATE USER analyst WITH PASSWORD 'secure_password_123';

-- Authentication happens automatically via PostgreSQL protocol

Security Features:

Password hashed with Argon2id (standard) or PBKDF2 (FIPS)
SCRAM-SHA-256 challenge-response over wire
Protection against replay attacks
Automatic account lockout after failed attempts

2. JWT Authentication

Token-based authentication for API and service access.

-- Enable JWT authentication
SET heliosdb.jwt_secret = 'your-secret-key';

-- Or use asymmetric keys
SET heliosdb.jwt_public_key = '/path/to/public.pem';

Configuration:

[auth.jwt]
enabled = true
algorithm = "RS256"  # or ES256, HS256
public_key = "/etc/heliosdb/jwt-public.pem"
issuer = "https://auth.example.com"
audience = "heliosdb-lite"
expiration_tolerance = 60  # seconds

3. Mutual TLS (mTLS)

Certificate-based authentication for server-to-server communication.

[tls]
enabled = true
cert = "/etc/heliosdb/server.crt"
key = "/etc/heliosdb/server.key"

[tls.client_auth]
enabled = true
ca_cert = "/etc/heliosdb/client-ca.crt"
required = true

Certificate Requirements:

RSA 2048-bit or ECDSA P-256 minimum
Valid certificate chain
Subject Alternative Names for hostname verification

Authorization Framework

Role-Based Access Control (RBAC)

-- Create roles
CREATE ROLE read_only;
CREATE ROLE data_analyst;
CREATE ROLE admin;

-- Grant privileges
GRANT SELECT ON ALL TABLES IN SCHEMA public TO read_only;
GRANT SELECT, INSERT, UPDATE ON sales TO data_analyst;
GRANT ALL PRIVILEGES ON DATABASE mydb TO admin;

-- Assign roles to users
GRANT read_only TO analyst_user;
GRANT data_analyst TO senior_analyst;

Built-in Roles

Role	Description	Permissions
`pg_read_all_data`	Read access to all data	SELECT on all tables
`pg_write_all_data`	Write access to all data	INSERT, UPDATE, DELETE on all tables
`pg_database_owner`	Database administration	CREATE, DROP, ALTER objects
`pg_execute_server_program`	Execute server programs	EXECUTE functions

Row-Level Security (RLS)

Fine-grained data access control at the row level.

-- Enable RLS on table
ALTER TABLE orders ENABLE ROW LEVEL SECURITY;

-- Policy: Users see only their own orders
CREATE POLICY user_orders ON orders
    FOR ALL
    USING (user_id = current_user_id());

-- Policy: Managers see all orders in their region
CREATE POLICY manager_orders ON orders
    FOR SELECT
    USING (
        region IN (
            SELECT managed_region
            FROM managers
            WHERE manager_id = current_user_id()
        )
    );

-- Policy: Admins see everything
CREATE POLICY admin_orders ON orders
    FOR ALL
    USING (current_user_has_role('admin'));

Column-Level Permissions

-- Grant specific column access
GRANT SELECT (name, email) ON customers TO support_team;
GRANT SELECT (name, email, credit_limit) ON customers TO sales_team;

-- Revoke sensitive column access
REVOKE SELECT (ssn, credit_card) ON customers FROM ALL;
GRANT SELECT (ssn, credit_card) ON customers TO compliance_team;

Multi-Tenancy Access Control

Tenant Isolation

-- Create tenant schema
CREATE SCHEMA tenant_acme;

-- Set default tenant for session
SET heliosdb.tenant_id = 'acme';

-- Automatic RLS for tenant isolation
CREATE POLICY tenant_isolation ON orders
    FOR ALL
    USING (tenant_id = current_setting('heliosdb.tenant_id'));

Cross-Tenant Access (Superuser Only)

-- Superuser can bypass tenant isolation
SET ROLE superuser;
SET heliosdb.bypass_rls = true;
SELECT * FROM orders;  -- All tenants visible

Access Control Lists (ACLs)

Object-Level Permissions

-- View current permissions
SELECT * FROM pg_class WHERE relname = 'orders';
SELECT * FROM information_schema.table_privileges WHERE table_name = 'orders';

-- Grant with grant option
GRANT SELECT ON orders TO analyst WITH GRANT OPTION;

-- Revoke cascade
REVOKE ALL PRIVILEGES ON orders FROM analyst CASCADE;

Schema-Level Permissions

-- Grant schema usage
GRANT USAGE ON SCHEMA analytics TO analysts;
GRANT CREATE ON SCHEMA analytics TO senior_analysts;

-- Default privileges for new objects
ALTER DEFAULT PRIVILEGES IN SCHEMA analytics
    GRANT SELECT ON TABLES TO analysts;

Session Management

Session Security

[session]
# Maximum session duration
max_age = "24h"

# Idle timeout
idle_timeout = "30m"

# Maximum concurrent sessions per user
max_concurrent = 5

# Force re-authentication for sensitive operations
require_reauth_for = ["DROP", "TRUNCATE", "ALTER SYSTEM"]

Session Monitoring

-- View active sessions
SELECT * FROM pg_stat_activity;

-- Terminate specific session
SELECT pg_terminate_backend(pid);

-- Terminate all sessions for user
SELECT pg_terminate_backend(pid)
FROM pg_stat_activity
WHERE usename = 'suspect_user';

Audit Trail

Access Logging

All access control decisions are logged:

{
  "timestamp": "2026-01-24T12:00:00Z",
  "event": "authorization",
  "user": "analyst",
  "action": "SELECT",
  "object": "public.orders",
  "result": "allowed",
  "rls_policies": ["user_orders"],
  "rows_affected": 150,
  "client_ip": "192.168.1.100"
}

Compliance Reports

-- Generate access report
SELECT
    user_name,
    object_name,
    privilege_type,
    granted_at
FROM heliosdb_access_log
WHERE granted_at > NOW() - INTERVAL '90 days'
ORDER BY granted_at DESC;

Service Accounts

Creating Service Accounts

-- Create service account with limited lifetime
CREATE USER svc_etl_pipeline WITH PASSWORD 'generated_password'
    VALID UNTIL '2026-12-31';

-- Grant minimum required permissions
GRANT INSERT ON staging.raw_data TO svc_etl_pipeline;
GRANT SELECT ON staging.config TO svc_etl_pipeline;

-- Restrict connection source
ALTER USER svc_etl_pipeline SET heliosdb.allowed_ips = '10.0.0.0/8';

Service Account Rotation

# Rotate service account credentials
heliosdb-cli rotate-credentials --user svc_etl_pipeline --notify etl-team@example.com

Emergency Access

Break-Glass Procedure

For emergency access bypassing normal controls:

Request: Submit emergency access request with justification
Approve: Security team approval required
Grant: Temporary elevated access (max 4 hours)
Audit: All actions logged with break-glass flag
Revoke: Automatic access revocation after time limit
Review: Post-incident review required

-- Emergency access grant (security team only)
SELECT heliosdb_emergency_access(
    user_name := 'oncall_engineer',
    reason := 'Production incident #12345',
    duration := INTERVAL '2 hours',
    approver := 'security_lead'
);

Best Practices

Principle of Least Privilege

Start with no permissions
Grant only what is needed
Use roles, not direct user grants
Review permissions regularly
Revoke unused permissions

Access Review Checklist

All users have appropriate role assignments
No users have unnecessary admin privileges
Service accounts have minimum required access
RLS policies correctly isolate data
Audit logs show no unauthorized access attempts
Emergency access procedures are documented and tested