Authentication & Authorization

BoilStream provides two distinct authentication systems tailored to different use cases: enterprise JWT-based authentication for programmatic access and web-based OAuth authentication for PostgreSQL connections.

Two Authentication Systems

BoilStream has two independent authentication systems that can be enabled separately:

System	Interface	Method	Configuration	Use Case
FlightRPC JWT Auth	DuckDB Airport, Arrow Flight	JWT tokens from enterprise SSO	auth section	Data ingestion, programmatic API access
PostgreSQL Web Auth	PostgreSQL protocol, BI tools	OAuth web UI + email/password	auth_server + oauth_providers	SQL queries, BI tools, interactive exploration

Which Authentication System Do You Need?

• For data ingestion from DuckDB or applications: Use FlightRPC JWT Authentication (this page)
• For SQL queries from BI tools (Power BI, Tableau) or psql: Use PostgreSQL Web Authentication
• For both use cases: Enable both systems independently

FlightRPC JWT Authentication

BoilStream's FlightRPC authentication provides enterprise-grade JWT-based security for data streaming operations. The system supports multiple identity providers and implements a flexible 3-level authorization hierarchy.

Overview

BoilStream's FlightRPC security model consists of two main components:

• Authentication: Verifying user identity using JWT tokens from trusted providers
• Authorization: Controlling access to resources based on user groups, scopes, and identity

Supported Identity Providers

BoilStream supports the following enterprise SSO providers:

Provider	Status	Multi-tenant	Custom Claims
AWS Cognito	✅ Production Ready	No	Limited
Azure AD (Entra ID)	✅ Production Ready	✅ Yes	Yes
Google Cloud Platform	✅ Production Ready	✅ Workspace	✅ Configurable
Auth0	✅ Production Ready	✅ Yes	✅ Configurable
Okta	✅ Production Ready	✅ Yes	✅ Configurable

3-Level Authorization Hierarchy

BoilStream implements a prioritized authorization system with three levels:

Level 1: Groups/Roles (Highest Priority)

• Primary authorization mechanism
• Provider-specific group mappings
• Admin, read-only, and write groups

Level 2: Scopes/Permissions (API-level)

• OAuth 2.0 style scopes for API access
• Fine-grained operation control
• Can require specific scopes for read/write/admin operations

Level 3: User Identity (User-specific)

• Individual user access rules
• Topic-specific permissions
• Lowest priority, used for edge cases

Security Features

JWT Token Validation

• Signature Verification: RSA/ECDSA signature validation using JWKS
• Claims Validation: Issuer, audience, expiration, and custom claims
• JWKS Caching: Automatic key rotation support with TTL-based caching

Access Control

• Resource-based Authorization: Control access to topics, admin functions, metrics
• Action-based Permissions: Separate read, write, publish, subscribe, admin actions
• Topic-level Security: Fine-grained per-topic access control

Production Security

• TLS Encryption: All FlightRPC communications encrypted in transit
• Database Encryption: OAuth and users databases are always encrypted at rest
• PGP Email Encryption: Optional PGP encryption for deleted account emails (GDPR Article 17 compliance with legal claim preservation)
• Audit Logging: Comprehensive authentication and authorization logging
• Graceful Degradation: System works with authentication disabled for development

When to Use Authentication

Enable Authentication When:

• ✅ Running in production environments
• ✅ Multi-tenant deployments
• ✅ Compliance requirements (SOC2, GDPR, etc.)
• ✅ Sensitive data processing
• ✅ External client access

Skip Authentication When:

• ⚠️ Development and testing environments
• ⚠️ Internal, trusted network deployments
• ⚠️ Single-user scenarios
• ⚠️ Performance testing (reduces overhead)

Security Consideration

Always enable authentication in production environments. Running without authentication exposes all data and administrative functions to any network client.

Database Encryption (PostgreSQL Web Auth)

PostgreSQL authentication databases are always encrypted when the authentication server is enabled. This ensures user credentials and session data are protected at rest.

For complete encryption key management details, see the PostgreSQL Web Authentication guide.

FlightRPC vs PostgreSQL Authentication

• FlightRPC JWT Auth: No database encryption (stateless JWT validation)
• PostgreSQL Web Auth: Encrypted databases for user profiles and sessions

Quick Key Management Reference

Method	Configuration	Key Storage	Use Case
Auto-generate	encryption_key_path: "key.file"	Saved to file	Development
Manual entry	No encryption_key_path	Not saved	High security
File-based	encryption_key_path: "key.file"	Loaded from file	Production
Piped input	Any config	Never saved	CI/CD, K8s secrets

WARNING

If you lose the encryption key, the PostgreSQL user databases cannot be decrypted. Store keys securely!

See PostgreSQL Web Authentication - Initial Setup for detailed encryption key setup instructions.

Configuration Overview

Authentication is configured entirely through environment variables, making it ideal for containerized deployments:

# Enable authentication with multiple providers
AUTH_PROVIDERS="cognito,azure-ad,gcp"

# Configure authorization rules
ADMIN_GROUPS="boilstream-admins,data-engineers"
READ_ONLY_GROUPS="analysts,viewers"
WRITE_GROUPS="producers,data-writers"

Quick Start

FlightRPC JWT Authentication

For complete FlightRPC authentication setup, see our provider-specific guides:

• AWS Cognito Setup - Enterprise user pools
• Azure AD Setup - Microsoft 365 integration
• Google Cloud Setup - Workspace and Cloud Identity
• Auth0 Setup - Universal identity platform
• Okta Setup - Enterprise identity and access management

PostgreSQL Web Authentication

For PostgreSQL access with OAuth or email/password:

• PostgreSQL Web Authentication Guide - Complete setup for BI tools and SQL clients

Next Steps

For FlightRPC JWT Authentication:

1. Choose Your Provider: Select the identity provider that matches your organization
2. Configure Environment Variables: Set up authentication credentials and rules
3. Test Authentication: Verify JWT tokens are properly validated
4. Deploy with Security: Enable TLS and proper network security

For PostgreSQL Web Authentication:

1. Enable auth_server: Configure auth_server and oauth_providers in config.yaml
2. Setup Encryption Key: Provide encryption key on first startup
3. Configure OAuth Providers: Setup GitHub, Google, or SAML integration
4. Access Web UI: Navigate to https://your-domain/auth to login

Ready to secure your BoilStream deployment?

• FlightRPC: Start with the Environment Variables guide
• PostgreSQL: Start with the PostgreSQL Web Authentication guide