Environment Variables

BoilStream authentication and authorization is configured entirely through environment variables. This approach ensures secure, container-friendly deployments without configuration files.

Core Authentication Variables

Provider Selection

Variable	Description	Default	Example
AUTH_PROVIDERS	Comma-separated list of enabled providers	(none)	"cognito,azure-ad,gcp"

Supported Provider Names:

• cognito - AWS Cognito User Pools
• azure-ad, azure, entra-id - Azure Active Directory
• gcp, google, google-cloud - Google Cloud Platform

Provider Aliases

You can use provider aliases for convenience. azure and entra-id both enable Azure AD support.

AWS Cognito Configuration

Variable	Required	Description	Example
COGNITO_USER_POOL_ID	✅ Yes	Cognito User Pool ID	us-east-1_ABC123DEF
COGNITO_REGION	No	AWS region	us-east-1
COGNITO_AUDIENCE	No	Expected audience/client ID	4n8j9k2l1m3n4o5p6q7r

Example Cognito Configuration

export AUTH_PROVIDERS="cognito"
export COGNITO_USER_POOL_ID="us-east-1_ABC123DEF"
export COGNITO_REGION="us-east-1"
export COGNITO_AUDIENCE="4n8j9k2l1m3n4o5p6q7r"

Azure Active Directory Configuration

Variable	Required	Description	Example
AZURE_TENANT_ID	✅ Yes	Azure AD tenant ID or common	12345678-1234-1234-1234-123456789abc
AZURE_CLIENT_ID	✅ Yes	Application/client ID	87654321-4321-4321-4321-210987654321
AZURE_ALLOW_MULTI_TENANT	No	Allow multi-tenant tokens	true

Example Azure AD Configuration

export AUTH_PROVIDERS="azure-ad"
export AZURE_TENANT_ID="12345678-1234-1234-1234-123456789abc"
export AZURE_CLIENT_ID="87654321-4321-4321-4321-210987654321"
export AZURE_ALLOW_MULTI_TENANT="false"

Multi-tenant Support

For multi-tenant scenarios (supporting users from multiple Azure AD tenants):

export AZURE_TENANT_ID="common"
export AZURE_ALLOW_MULTI_TENANT="true"

Google Cloud Platform Configuration

Variable	Required	Description	Example
GCP_CLIENT_ID	Conditional	OAuth 2.0 client ID for Google identity tokens	123456789-abc.apps.googleusercontent.com
GCP_PROJECT_ID	Conditional	GCP project ID for STS tokens	my-project-123
GCP_REQUIRE_WORKSPACE_DOMAIN	No	Required workspace domain	company.com
GCP_ALLOW_STS_TOKENS	No	Allow STS tokens	true
GCP_GROUPS_CLAIM	No	Custom claim for groups	groups
GCP_ROLES_CLAIM	No	Custom claim for roles	roles

GCP Requirements

You must provide either GCP_CLIENT_ID or GCP_PROJECT_ID. Provide both for maximum compatibility.

Example GCP Configuration

export AUTH_PROVIDERS="gcp"
export GCP_CLIENT_ID="123456789-abc.apps.googleusercontent.com"
export GCP_PROJECT_ID="my-project-123"
export GCP_REQUIRE_WORKSPACE_DOMAIN="company.com"
export GCP_ALLOW_STS_TOKENS="true"

Authorization Configuration

Group-based Authorization

Variable	Description	Example
ADMIN_GROUPS	Admin groups (highest privileges)	"boilstream-admins,data-engineers"
READ_ONLY_GROUPS	Read-only access groups	"analysts,viewers,read-only"
WRITE_GROUPS	Write access groups	"producers,data-writers,publishers"

Scope-based Authorization

Variable	Description	Example
REQUIRED_READ_SCOPES	Required scopes for read operations	"boilstream:read,data:read"
REQUIRED_WRITE_SCOPES	Required scopes for write operations	"boilstream:write,data:write"
REQUIRED_ADMIN_SCOPES	Required scopes for admin operations	"boilstream:admin,admin:*"

Authorization Control

Variable	Description	Default	Example
AUTHORIZATION_ENABLED	Explicitly enable authorization	auto	true

Auto-Enable Authorization

Authorization is automatically enabled when any authorization rules are configured. Set AUTHORIZATION_ENABLED=true to force enable even without rules.

Complete Configuration Examples

Single Provider Setup (AWS Cognito)

# Authentication
export AUTH_PROVIDERS="cognito"
export COGNITO_USER_POOL_ID="us-east-1_ABC123DEF"
export COGNITO_REGION="us-east-1"

# Authorization  
export ADMIN_GROUPS="data-engineers"
export WRITE_GROUPS="producers,etl-jobs"
export READ_ONLY_GROUPS="analysts,viewers"

Multi-Provider Setup

# Enable all three providers
export AUTH_PROVIDERS="cognito,azure-ad,gcp"

# AWS Cognito
export COGNITO_USER_POOL_ID="us-east-1_ABC123DEF"
export COGNITO_REGION="us-east-1"

# Azure AD
export AZURE_TENANT_ID="common" 
export AZURE_CLIENT_ID="87654321-4321-4321-4321-210987654321"
export AZURE_ALLOW_MULTI_TENANT="true"

# Google Cloud Platform
export GCP_CLIENT_ID="123456789-abc.apps.googleusercontent.com"
export GCP_PROJECT_ID="my-project-123"
export GCP_REQUIRE_WORKSPACE_DOMAIN="company.com"

# Authorization (applies to all providers)
export ADMIN_GROUPS="boilstream-admins,data-platform-admins"
export WRITE_GROUPS="data-producers,etl-services"
export READ_ONLY_GROUPS="data-analysts,business-users"
export REQUIRED_ADMIN_SCOPES="boilstream:admin"

Development/Testing Configuration

# Disable authentication entirely for development
# (Comment out or don't set AUTH_PROVIDERS)
# export AUTH_PROVIDERS=""

# Or enable with minimal restrictions
export AUTH_PROVIDERS="cognito"
export COGNITO_USER_POOL_ID="us-east-1_TEST123"
export COGNITO_REGION="us-east-1"
# No authorization groups = allow all authenticated users

Environment Variable Priority

When multiple authorization methods are configured, BoilStream follows this priority:

1. Groups/Roles (highest priority)
2. Scopes/Permissions
3. User-specific rules (lowest priority)

Within each level, users need to match ANY of the configured groups/scopes (OR logic).

Security Best Practices

✅ Production Recommendations

# Always use specific tenant IDs in production
export AZURE_TENANT_ID="your-specific-tenant-id"  # Not "common"

# Require workspace domains for GCP
export GCP_REQUIRE_WORKSPACE_DOMAIN="yourcompany.com"

# Use specific, restrictive groups
export ADMIN_GROUPS="boilstream-production-admins"
export WRITE_GROUPS="boilstream-production-writers"

⚠️ Security Warnings

• Never use AZURE_TENANT_ID="common" in production without careful consideration
• Always set GCP_REQUIRE_WORKSPACE_DOMAIN for corporate environments
• Use specific group names, avoid generic names like "admin" or "user"
• Test authorization rules in staging environments first

Troubleshooting

Common Issues

Authentication fails but environment variables look correct:

# Check if BoilStream can reach JWKS endpoints
curl -v https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ABC123DEF/.well-known/jwks.json

Authorization denies access unexpectedly:

# Enable debug logging
export RUST_LOG="boilstream::auth=debug"

Multiple providers but wrong one being used:

• Check JWT token issuer claim matches expected provider
• Verify JWKS endpoints are accessible
• Review provider order in AUTH_PROVIDERS

For detailed troubleshooting, see the Troubleshooting Guide.

Next Steps

Now that you understand the environment variables, configure your specific identity provider:

• AWS Cognito Setup
• Azure AD Setup
• Google Cloud Setup