auth

Overview ¶

Package auth provides authentication and authorization utilities. This file implements API key authentication for agents.

SECURITY: Agent API Key Authentication

Agents authenticate using API keys instead of JWT tokens because:

• Agents are not users (no username/password)
• Agents are long-running services (no interactive login)
• API keys are simpler and more suitable for service-to-service auth

API Key Format:

• 64 hexadecimal characters (32 bytes of randomness)
• Generated using crypto/rand
• Example: "a1b2c3d4e5f6...789" (64 chars)

API Key Storage:

• Plaintext key given to agent ONCE during deployment
• Bcrypt hash stored in database (cost factor 12)
• Hash never exposed in API responses

API Key Usage:

• Agent sends key in X-Agent-API-Key header
• API validates key against bcrypt hash in database
• Updates api_key_last_used_at on successful auth

API Key Rotation:

• Admin can generate new key via /api/v1/admin/agents/:id/rotate-key
• Old key immediately invalidated
• New key returned ONCE (must be saved by admin)

Package auth provides authentication and authorization mechanisms for StreamSpace. This file implements HTTP handlers for authentication endpoints including local, SAML, and password management operations.

AUTHENTICATION HANDLERS: - Local authentication (username/password) - SAML SSO authentication (enterprise identity providers) - Token refresh (JWT token renewal) - Password change (local users only) - Logout (session termination)

SUPPORTED AUTHENTICATION FLOWS:

1. Local Authentication (POST /auth/login):

• User submits username and password
• System verifies credentials against database
• Returns JWT token for subsequent requests
• Supports account status validation (active/disabled)

2. SAML SSO Authentication (GET /auth/saml/login):

• User initiates SSO flow
• Redirects to enterprise IdP (Okta, Azure AD, etc.)
• IdP sends SAML assertion after authentication
• System validates assertion and creates local session
• Returns JWT token for API access

3. Token Refresh (POST /auth/refresh):

• Client submits existing JWT token
• System validates token is within refresh window
• Issues new token with extended expiration
• Prevents indefinite token refresh (7-day window)

4. Password Change (POST /auth/password):

• Local users can change their password
• Requires current password verification
• Not available for SSO users (SAML/OIDC)

SECURITY FEATURES:

- Password verification with bcrypt hashing - Account status validation (prevent disabled accounts from logging in) - JWT token generation with configurable expiration - SAML group synchronization for role-based access control - Secure cookie handling for SAML return URLs - Auto-provisioning of SSO users on first login

SAML GROUP SYNCHRONIZATION:

When users authenticate via SAML, their group memberships are automatically synchronized with StreamSpace groups: - SAML assertion contains groups claim from IdP - System matches SAML group names to local groups - Adds user to matching groups (does not remove from other groups by default) - Enables role-based access control based on IdP group membership

SECURITY CONSIDERATIONS:

1. Password Security:

• Passwords hashed with bcrypt (cost factor 10+)
• Never return password hashes in API responses
• Minimum password length enforced (8 characters)

2. Account Lockout:

• Disabled accounts cannot authenticate
• Returns 403 Forbidden for disabled accounts
• Prevents unauthorized access to suspended accounts

3. Token Security:

• JWT tokens include user ID, role, and groups
• Tokens expire after configured duration (default: 24 hours)
• Refresh tokens only valid within 7-day window
• See jwt.go for detailed token security

4. SAML Security:

• Assertion signatures validated by middleware
• Return URLs stored in secure cookies
• SAML groups synced on every login
• See saml.go for detailed SAML security

EXAMPLE USAGE:

// Initialize handler with dependencies
handler := NewAuthHandler(userDB, jwtManager, samlAuth)

// Register routes
router := gin.Default()
handler.RegisterRoutes(router.Group("/api/v1"))

// Routes will be available at:
// - POST /api/v1/auth/login (local authentication)
// - POST /api/v1/auth/refresh (token refresh)
// - POST /api/v1/auth/logout (logout)
// - GET  /api/v1/auth/saml/login (initiate SAML SSO)
// - POST /api/v1/auth/saml/acs (SAML callback)
// - GET  /api/v1/auth/saml/metadata (SAML SP metadata)

THREAD SAFETY:

All handler methods are thread-safe and can handle concurrent requests. Database operations use connection pooling for safe concurrent access.

Package auth provides authentication and authorization mechanisms for StreamSpace. This file implements JSON Web Token (JWT) authentication using HMAC-SHA256 signing.

JWT AUTHENTICATION OVERVIEW:

StreamSpace uses JWTs as the primary authentication mechanism for API requests. Tokens are issued after successful login and must be included in the Authorization header of subsequent requests.

TOKEN LIFECYCLE:

1. User logs in with username/password (or SSO) 2. System validates credentials 3. GenerateToken creates a signed JWT with user claims 4. Client stores token (typically in localStorage or httpOnly cookie) 5. Client includes token in Authorization header: "Bearer <token>" 6. Middleware validates token on each request 7. Token expires after configured duration (default: 24 hours) 8. User can refresh token within 7-day window before expiration 9. After expiration, user must re-authenticate

SECURITY FEATURES:

- HMAC-SHA256 signing prevents token tampering - Tokens include expiration time to limit exposure window - Refresh tokens only work within 7-day window (prevents infinite refresh) - Issuer claim prevents cross-site token reuse - NotBefore claim prevents premature token usage - Algorithm verification prevents algorithm substitution attacks

TOKEN STRUCTURE:

Header:

{
  "alg": "HS256",       // HMAC-SHA256 signing algorithm
  "typ": "JWT"          // Token type
}

Payload (Claims):

{
  "user_id": "user123",      // Internal user ID
  "username": "john.doe",    // Username for display
  "email": "john@example.com", // Email address
  "role": "user",            // Role: "admin", "operator", or "user"
  "groups": ["team-a"],      // Group memberships
  "iss": "streamspace-api",  // Issuer (prevents cross-site reuse)
  "sub": "user123",          // Subject (same as user_id)
  "iat": 1700000000,         // Issued at timestamp
  "exp": 1700086400,         // Expiration timestamp
  "nbf": 1700000000          // Not before timestamp
}

Signature:

HMACSHA256(
  base64UrlEncode(header) + "." + base64UrlEncode(payload),
  secret_key
)

SECURITY BEST PRACTICES:

1. Secret Key Management:

• NEVER hardcode secret keys in source code
• Load from environment variables or secret management systems
• Use cryptographically random keys (at least 256 bits)
• Rotate keys periodically (requires token invalidation strategy)

2. Token Storage (Client-Side):

• Prefer httpOnly cookies over localStorage (prevents XSS attacks)
• Use SameSite=Strict cookie attribute (prevents CSRF)
• Set Secure flag for HTTPS-only transmission
• Consider short-lived tokens with refresh token strategy

3. Token Validation:

• Always verify signature before trusting claims
• Check expiration time (exp claim)
• Verify issuer matches expected value (iss claim)
• Validate algorithm to prevent algorithm substitution attacks
• Consider implementing token revocation list for compromised tokens

4. Attack Prevention:

• Algorithm substitution: Verify signing method is HMAC (not "none")
• Token replay: Use short expiration times and refresh mechanism
• XSS: Store tokens in httpOnly cookies, not localStorage
• CSRF: Include CSRF tokens or use SameSite cookies
• Token theft: Use HTTPS only, short-lived tokens, rotation

COMMON VULNERABILITIES TO AVOID:

❌ Accepting tokens with "alg": "none" (no signature) ❌ Not validating token expiration ❌ Using weak secret keys (< 256 bits) ❌ Storing sensitive data in token payload (it's base64, not encrypted!) ❌ Not using HTTPS (tokens can be intercepted) ❌ Infinite token refresh (allows stolen tokens to live forever)

For more details on JWT security, see: - https://auth0.com/blog/critical-vulnerabilities-in-json-web-token-libraries/ - https://owasp.org/www-project-web-security-testing-guide/latest/4-Web_Application_Security_Testing/06-Session_Management_Testing/10-Testing_JSON_Web_Tokens

Package auth provides authentication and authorization mechanisms for StreamSpace. This file implements Gin middleware for JWT token validation and role-based access control.

MIDDLEWARE COMPONENTS: - JWT authentication middleware (required authentication) - Optional authentication middleware (authentication not required) - Role-based authorization middleware (require specific roles) - Helper functions for extracting user context

AUTHENTICATION FLOW:

1. Client Request:

• Client includes JWT token in Authorization header
• Format: "Authorization: Bearer <token>"
• Example: "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

2. Token Extraction:

• Middleware extracts token from Authorization header
• Validates header format (must start with "Bearer ")
• Rejects requests with missing or malformed headers

3. Token Validation:

• Validates JWT signature using secret key
• Checks token expiration (exp claim)
• Verifies token issuer (iss claim)
• Ensures algorithm is HMAC (prevents algorithm substitution)

4. User Validation:

• Extracts user ID from validated token claims
• Queries database to verify user still exists
• Checks if user account is active (not disabled)
• Rejects requests from disabled or deleted users

5. Context Population:

• Stores user information in Gin context
• Available to downstream handlers via c.Get()
• Includes: userID, username, email, role, groups

MIDDLEWARE TYPES:

1. Middleware (Required Authentication):

• Rejects requests without valid JWT token
• Returns 401 Unauthorized for invalid/missing tokens
• Returns 403 Forbidden for disabled accounts
• Use for protected API endpoints

2. OptionalAuth (Optional Authentication):

• Accepts requests with or without token
• Validates token if present, ignores if absent
• Useful for endpoints that behave differently for authenticated users
• Example: Public catalog with favorites for logged-in users

3. RequireRole (Role-Based Authorization):

• Requires specific role (admin, operator, user)
• Must be used after Middleware (requires authentication)
• Returns 403 Forbidden if user lacks required role

4. RequireAnyRole (Multi-Role Authorization):

• Accepts any of multiple roles
• Example: RequireAnyRole("admin", "operator") for management endpoints
• Returns 403 if user has none of the allowed roles

SECURITY FEATURES:

- Token signature validation prevents tampering - Expiration checking limits token lifetime - Active user validation prevents disabled account access - Role checking enforces principle of least privilege - Context isolation prevents request cross-contamination

SECURITY CONSIDERATIONS:

1. Token Transmission:

• Tokens must be sent over HTTPS in production
• Never log or expose tokens in error messages
• Clear tokens from memory after use

2. Account Status:

• Always check user.Active before allowing access
• Disabled accounts cannot authenticate even with valid token
• Supports immediate access revocation

3. Token Expiration:

• Tokens expire after configured duration (default: 24 hours)
• Expired tokens rejected with 401 Unauthorized
• Forces periodic re-authentication

4. Role Validation:

• Roles stored in JWT claims (tamper-proof via signature)
• Role hierarchy: admin > operator > user
• Always validate role before privileged operations

EXAMPLE USAGE:

// Require authentication for all /api routes
api := router.Group("/api")
api.Use(auth.Middleware(jwtManager, userDB))
{
    api.GET("/sessions", listSessions)  // Requires valid token
}

// Admin-only endpoints
admin := api.Group("/admin")
admin.Use(auth.RequireRole("admin"))
{
    admin.GET("/users", listAllUsers)  // Requires admin role
}

// Optional authentication (public + user features)
router.GET("/catalog", auth.OptionalAuth(jwtManager, userDB), showCatalog)

// Extract user info in handler
func listSessions(c *gin.Context) {
    userID, _ := auth.GetUserID(c)
    role, _ := auth.GetUserRole(c)
    // ... use user info
}

CONTEXT KEYS:

The middleware stores the following keys in Gin context: - "userID": string - Unique user identifier - "username": string - Username for display - "userEmail": string - User's email address - "userRole": string - Role (admin, operator, user) - "userGroups": []string - Group memberships - "claims": *Claims - Full JWT claims object

THREAD SAFETY:

All middleware functions are thread-safe and can handle concurrent requests. Each request gets its own Gin context, preventing data leakage between requests.

Package auth provides authentication and authorization mechanisms for StreamSpace. This file implements OpenID Connect (OIDC) authentication for integration with modern identity providers supporting OAuth 2.0 and OIDC standards.

OIDC AUTHENTICATION OVERVIEW:

OpenID Connect is an identity layer built on top of OAuth 2.0 that provides: - User authentication (not just authorization like OAuth 2.0) - Standard claims for user identity (sub, email, name, etc.) - ID tokens (JWT) containing user information - UserInfo endpoint for additional user details - Discovery mechanism for automatic configuration

SUPPORTED IDENTITY PROVIDERS:

- Keycloak (open source identity provider) - Okta (enterprise SSO platform) - Auth0 (identity as a service) - Google Workspace (Google accounts) - Azure AD / Microsoft Entra ID - GitHub (limited OIDC support) - GitLab (self-hosted or cloud) - Generic OIDC providers

OIDC AUTHENTICATION FLOW (Authorization Code Flow):

1. User Initiates Login:

• User clicks "Login with [Provider]"
• App redirects to /auth/oidc/login

2. Authorization Request:

• App generates state parameter (CSRF protection)
• App redirects user to IdP's authorization endpoint
• URL includes: client_id, redirect_uri, scope, state
• Example: https://accounts.google.com/o/oauth2/v2/auth?client_id=...

3. User Authentication:

• User authenticates at IdP (username/password, MFA, etc.)
• IdP shows consent screen (if first time)
• User approves requested scopes (openid, profile, email)

4. Authorization Code:

• IdP redirects back to app with authorization code
• URL: https://streamspace.example.com/auth/oidc/callback?code=abc123&state=xyz
• App validates state matches (CSRF protection)

5. Token Exchange:

• App exchanges authorization code for tokens
• POST to IdP's token endpoint with code and client_secret
• IdP returns: access_token, id_token, refresh_token (optional)

6. ID Token Validation:

• App validates ID token signature using IdP's public key
• App verifies claims: issuer, audience, expiration
• App extracts user info from ID token claims

7. UserInfo Request (Optional):

• App calls IdP's UserInfo endpoint with access token
• Retrieves additional user attributes not in ID token
• Merges with ID token claims

8. User Provisioning:

• App creates or updates user in local database
• Syncs user attributes from OIDC claims
• Syncs group memberships if provided

9. Session Creation:

• App generates JWT token for StreamSpace API
• User is authenticated and can access protected resources

SECURITY FEATURES:

- State parameter validation (CSRF protection) - ID token signature validation (prevents tampering) - Nonce validation (prevents replay attacks) - Token expiration checking - TLS certificate validation for IdP connections - Client secret protection (never exposed to browser)

CONFIGURATION EXAMPLE:

config := &OIDCConfig{
    Enabled:      true,
    ProviderURL:  "https://accounts.google.com",  // Discovery URL
    ClientID:     "123456.apps.googleusercontent.com",
    ClientSecret: "your-client-secret",
    RedirectURI:  "https://streamspace.example.com/auth/oidc/callback",
    Scopes:       []string{"openid", "profile", "email", "groups"},
    UsernameClaim: "preferred_username",
    EmailClaim:    "email",
    GroupsClaim:   "groups",
}

SECURITY BEST PRACTICES:

1. Discovery URL:

• Use HTTPS for provider URL
• Validate TLS certificates (don't skip verification in production)
• Provider URL should end at issuer root (not /...well-known/...)

2. Client Secret:

• Never commit to version control
• Load from environment variables or secret manager
• Rotate periodically
• Use separate secrets for dev/staging/production

3. Redirect URI:

• Must exactly match URI registered with IdP
• Use HTTPS in production (HTTP only for localhost dev)
• Validate redirect URI to prevent open redirect attacks

4. State Parameter:

• Generate cryptographically random state for each request
• Store in cookie or session for validation
• Prevents CSRF attacks

5. Token Validation:

• Always validate ID token signature
• Check expiration (exp claim)
• Verify audience matches client_id (aud claim)
• Verify issuer matches provider (iss claim)

COMMON OIDC VULNERABILITIES TO AVOID:

1. Missing State Validation:

• Attack: Attacker initiates flow, tricks victim to complete
• Prevention: Always validate state parameter matches

2. ID Token Signature Not Verified:

• Attack: Attacker creates fake ID token with elevated privileges
• Prevention: Always verify signature using IdP's public key

3. Open Redirect:

• Attack: Attacker uses redirect_uri to redirect to malicious site
• Prevention: Whitelist allowed redirect URIs

4. Client Secret Exposure:

• Attack: Secret leaked in client-side code or logs
• Prevention: Never include secret in frontend, use environment variables

ATTRIBUTE MAPPING:

Different IdPs use different claim names for user attributes. The OIDCConfig allows mapping IdP-specific claims to StreamSpace fields:

Keycloak:

UsernameClaim: "preferred_username"
EmailClaim:    "email"
GroupsClaim:   "groups"

Google:

UsernameClaim: "email"
EmailClaim:    "email"
GroupsClaim:   "groups" (Google Workspace only)

Azure AD:

UsernameClaim: "preferred_username"
EmailClaim:    "email"
GroupsClaim:   "groups"

EXAMPLE USAGE:

// Initialize OIDC authenticator
oidcAuth, err := NewOIDCAuthenticator(config)
if err != nil {
    log.Fatal(err)
}

// Register routes
router.GET("/auth/oidc/login", oidcAuth.OIDCLoginHandler)
router.GET("/auth/oidc/callback", oidcAuth.OIDCCallbackHandler(userManager))

// User flow:
// 1. Visit /auth/oidc/login
// 2. Redirect to IdP
// 3. Authenticate at IdP
// 4. Redirect to /auth/oidc/callback with code
// 5. Receive JWT token and user info

THREAD SAFETY:

The OIDCAuthenticator is thread-safe and can handle concurrent authentication requests. Each request maintains its own state and session isolation.

Package auth provides authentication and authorization mechanisms for StreamSpace. This file implements identity provider configuration templates and certificate management utilities for SAML and OIDC authentication.

IDENTITY PROVIDER SUPPORT:

This module provides pre-configured templates for popular identity providers, making it easier to integrate StreamSpace with enterprise SSO systems. It supports both SAML 2.0 and OpenID Connect (OIDC) protocols.

SUPPORTED SAML PROVIDERS:

- Okta: Enterprise SSO platform with comprehensive SAML support - Azure AD / Microsoft Entra ID: Microsoft's cloud identity provider - Google Workspace: Google's enterprise suite with SSO - Auth0: Identity as a Service platform - Keycloak: Open source identity and access management - Authentik: Modern open source identity provider - Generic: Template for any SAML 2.0 compliant provider

SUPPORTED OIDC PROVIDERS:

- Keycloak: Open source with full OIDC support - Okta: Enterprise OIDC provider - Auth0: OIDC identity service - Google: Google accounts with OIDC - Azure AD: Microsoft's OIDC implementation - GitHub: Developer accounts (limited OIDC) - GitLab: Self-hosted or cloud OIDC - Generic: Any OIDC-compliant provider

PROVIDER CONFIGURATION TEMPLATES:

Each provider has a pre-configured template that includes: - Default attribute mappings (email, username, groups, etc.) - Metadata URL template (for SAML) - Discovery URL template (for OIDC) - Default scopes (for OIDC) - Claim names for user attributes

WHY PROVIDER TEMPLATES?

Different identity providers use different attribute names and URL patterns:

Example - Email attribute: - Okta: "email" - Azure AD: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" - Google: "email" - Authentik: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"

Provider templates eliminate manual configuration and reduce integration errors.

SAML ATTRIBUTE MAPPING:

SAML attributes map user information from IdP to StreamSpace fields:

Okta Mapping:

Email:     "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
Username:  "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
FirstName: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
LastName:  "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
Groups:    "groups"

Azure AD Mapping:

Email:     "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
Username:  "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
FirstName: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
LastName:  "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
Groups:    "http://schemas.microsoft.com/ws/2008/06/identity/claims/groups"

Keycloak Mapping:

Email:     "email"
Username:  "username"
FirstName: "firstName"
LastName:  "lastName"
Groups:    "groups"

OIDC CLAIM MAPPING:

OIDC providers use simpler claim names than SAML:

Standard OIDC Claims:

UsernameClaim: "preferred_username"
EmailClaim:    "email"
GroupsClaim:   "groups"

Provider-Specific Variations:

Google:  username = "email" (no preferred_username)
Auth0:   groups = "https://{domain}/claims/groups" (namespaced)
GitHub:  username = "login", groups = "orgs"

METADATA URL TEMPLATES:

SAML providers expose metadata at predictable URLs. Templates use placeholders that are replaced with actual values during configuration:

Okta:

Template: "https://{domain}/app/{app_id}/sso/saml/metadata"
Example:  "https://dev-12345.okta.com/app/abc123/sso/saml/metadata"

Azure AD:

Template: "https://login.microsoftonline.com/{tenant_id}/federationmetadata/2007-06/federationmetadata.xml"
Example:  "https://login.microsoftonline.com/00000000-0000-0000-0000-000000000000/federationmetadata/..."

Keycloak:

Template: "https://{domain}/auth/realms/{realm}/protocol/saml/descriptor"
Example:  "https://auth.example.com/auth/realms/master/protocol/saml/descriptor"

CERTIFICATE MANAGEMENT:

SAML requires X.509 certificates for signing and encryption. This module provides utilities for loading certificates and private keys from PEM files:

- LoadCertificate: Loads X.509 certificate from PEM file - LoadPrivateKey: Loads RSA private key from PEM file (PKCS1 or PKCS8)

SECURITY CONSIDERATIONS:

1. Certificate Storage:

• Store private keys securely (file permissions 0600)
• Never commit private keys to version control
• Use secrets management systems (Vault, AWS Secrets Manager)
• Rotate certificates regularly (annually recommended)

2. Attribute Mapping Validation:

• Verify attribute mappings with IdP administrator
• Test with real user accounts before production
• Log missing attributes for debugging

3. Metadata URLs:

• Always use HTTPS for metadata fetching
• Validate TLS certificates
• Consider caching metadata to reduce dependencies

4. Provider Trust:

• Only configure trusted identity providers
• Verify IdP metadata before accepting
• Monitor IdP configuration changes

EXAMPLE USAGE:

// Get Okta SAML configuration template
config := GetProviderConfig(ProviderOkta)
fmt.Printf("Email attribute: %s\n", config.DefaultMapping.Email)
// Output: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

// Get Keycloak OIDC configuration template
oidcConfig := GetOIDCProviderConfig(OIDCProviderKeycloak)
fmt.Printf("Discovery URL: %s\n", oidcConfig.DiscoveryURL)
// Output: https://{domain}/auth/realms/{realm}

// Load SAML certificate
cert, err := LoadCertificate("/path/to/cert.pem")
if err != nil {
    log.Fatal(err)
}

// Load SAML private key
key, err := LoadPrivateKey("/path/to/key.pem")
if err != nil {
    log.Fatal(err)
}

AUTHENTICATION MODE CONFIGURATION:

StreamSpace supports multiple authentication modes:

- AuthModeJWT: Local authentication only (username/password + JWT) - AuthModeSAML: SAML SSO only (enterprise identity provider) - AuthModeOIDC: OIDC authentication only (modern IdPs) - AuthModeHybrid: Both local and SAML (flexible deployment)

Mode selection depends on deployment requirements: - Small teams: AuthModeJWT (simpler setup) - Enterprise: AuthModeSAML or AuthModeOIDC (centralized identity) - Mixed: AuthModeHybrid (support both employee SSO and external users)

THREAD SAFETY:

All functions in this module are thread-safe and can be called concurrently. Provider configuration templates are read-only and immutable.

Package auth provides authentication implementations for StreamSpace.

SAML 2.0 AUTHENTICATION ¶

This file implements SAML 2.0 (Security Assertion Markup Language) authentication, enabling Single Sign-On (SSO) with enterprise identity providers like: - Okta - Azure AD / Microsoft Entra ID - Google Workspace - OneLogin - Auth0 - Keycloak

SAML 2.0 AUTHENTICATION FLOW:

The SAML authentication process follows the Service Provider (SP) initiated flow:

1. User visits StreamSpace (Service Provider)
2. User clicks "Login with SSO"
3. SP generates SAML AuthnRequest (authentication request)
4. User's browser redirects to IdP with AuthnRequest
5. User authenticates with IdP (username/password, MFA, etc.)
6. IdP generates SAML Assertion (signed XML with user attributes)
7. User's browser POSTs assertion to SP's Assertion Consumer Service (ACS)
8. SP validates assertion signature and extracts user attributes
9. SP creates local session and issues JWT token
10. User is authenticated and can access StreamSpace

SAML SECURITY FEATURES:

1. XML Signature Validation:

• All assertions must be digitally signed by the IdP
• SP verifies signature using IdP's public certificate
• Prevents tampering with user attributes or session data

2. TLS Transport Security:

• All SAML exchanges occur over HTTPS
• Prevents man-in-the-middle attacks
• Protects assertions in transit

3. Assertion Time Validation:

• NotBefore: Assertion not valid before this time
• NotOnOrAfter: Assertion expires after this time
• Prevents replay attacks with old assertions

4. Audience Restriction:

• Assertion specifies intended audience (SP entity ID)
• Prevents assertions from being used at wrong service

5. InResponseTo Validation (SP-initiated flow):

• Links assertion to original AuthnRequest
• Prevents unsolicited assertions (unless AllowIDPInitiated=true)

CONFIGURATION EXAMPLE:

config := &SAMLConfig{
    Enabled:              true,
    EntityID:             "https://streamspace.example.com",
    MetadataURL:          "https://idp.example.com/metadata",
    AssertionConsumerURL: "https://streamspace.example.com/saml/acs",
    SingleLogoutURL:      "https://streamspace.example.com/saml/slo",
    Certificate:          spCert,      // SP's X.509 certificate
    PrivateKey:           spKey,       // SP's RSA private key
    AllowIDPInitiated:    false,       // Require SP-initiated flow
    SignRequest:          true,        // Sign AuthnRequests
    ForceAuthn:           false,       // Don't require re-authentication
    AttributeMapping: AttributeMapping{
        Email:     "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
        Username:  "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
        FirstName: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
        LastName:  "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",
        Groups:    "http://schemas.xmlsoap.org/claims/Group",
    },
}

SECURITY BEST PRACTICES:

1. Always validate assertion signatures 2. Use TLS for all SAML endpoints 3. Set short assertion validity periods (5-10 minutes) 4. Disable IdP-initiated flow (AllowIDPInitiated=false) unless required 5. Sign AuthnRequests (SignRequest=true) when IdP supports it 6. Regularly rotate SP certificates 7. Validate SAML responses before creating sessions 8. Log all SAML authentication events for audit

COMMON SAML VULNERABILITIES TO AVOID:

1. XML Signature Wrapping (XSW):

• Attack: Manipulate XML structure to bypass signature validation
• Prevention: Use robust XML parsing library (crewjam/saml)

2. XML External Entity (XXE) Injection:

• Attack: Reference external entities in XML to read files
• Prevention: Disable external entity resolution in XML parser

3. Replay Attacks:

• Attack: Reuse old SAML assertions
• Prevention: Validate NotOnOrAfter, track assertion IDs

4. Man-in-the-Middle:

• Attack: Intercept SAML assertion
• Prevention: Use TLS, validate certificate chains

SUPPORTED IDENTITY PROVIDERS:

- Okta: Full support with metadata URL - Azure AD: Full support, map attributes correctly - Google Workspace: Requires custom attribute mapping - OneLogin: Full support with metadata URL - Auth0: Full support via SAML addon - Keycloak: Open source IdP, full support

Package auth provides authentication and authorization mechanisms for StreamSpace. This file implements server-side session tracking using Redis.

SESSION TRACKING:

StreamSpace uses server-side session tracking to provide: - Session invalidation on logout - Force re-login on application restart - Ability to revoke all sessions for a user - Session audit trail

HOW IT WORKS:

1. Token Generation:

• Each JWT gets a unique session ID (jti claim)
• Session metadata stored in Redis: session:{jti}
• TTL matches token expiration

2. Token Validation:

• Middleware checks if session exists in Redis
• Missing session = invalid token (expired, revoked, or from before restart)
• Valid session = allow request

3. Logout:

• Delete session from Redis
• Token immediately becomes invalid

4. Application Restart:

• Redis pattern delete clears all sessions
• All users must re-login

SECURITY BENEFITS:

- True logout: Sessions can be immediately invalidated - Compromise response: Revoke all user sessions on suspected breach - Multi-device management: Users can see and revoke active sessions - Forced re-authentication: Restart clears all sessions

Package auth provides authentication and authorization mechanisms for StreamSpace. This file implements secure token generation and hashing for API tokens, session tokens, and other authentication credentials.

TOKEN TYPES AND USE CASES:

StreamSpace uses different token types for different purposes:

1. API Tokens (Long-lived):

• Used for programmatic API access
• Stored in database with bcrypt hash
• 384 bits of entropy (48 bytes)
• Never expire (until revoked by user)
• Example: Personal access tokens, integration keys

2. Session Tokens (Short-lived):

• Used for web session management
• Stored in database with SHA256 hash
• 256 bits of entropy (32 bytes)
• Expire after inactivity or logout
• Example: Browser session cookies

3. Generic Secure Tokens:

• Used for password reset, email verification, etc.
• Stored with bcrypt hash for security
• Configurable length
• Single-use tokens with expiration

HASHING ALGORITHMS:

Two hashing algorithms are provided based on use case requirements:

1. bcrypt (For API Tokens):

• Intentionally slow (prevents brute force attacks)
• Adaptive work factor (can increase over time)
• Salt included automatically
• Recommended for long-lived tokens
• Cost factor: 10 (good security/performance balance)

2. SHA256 (For Session Tokens):

• Fast hashing (suitable for high-volume lookups)
• 256-bit output (sufficient for session tokens)
• No built-in salt (tokens are cryptographically random)
• Recommended for short-lived, high-frequency tokens

WHY DIFFERENT ALGORITHMS?

bcrypt vs SHA256 trade-offs:

bcrypt Advantages: - Slow hashing prevents brute force attacks - Adaptive cost factor (security improves over time) - Best practice for password-like credentials

bcrypt Disadvantages: - Slower performance (intentional, but impacts throughput) - Not suitable for high-frequency validation

SHA256 Advantages: - Fast validation (thousands of lookups per second) - Suitable for session tokens with high request rates - Simple implementation

SHA256 Disadvantages: - Fast hashing makes brute force easier - No adaptive cost factor - Not recommended for long-lived credentials

SECURITY BEST PRACTICES:

1. Token Generation:

• Use crypto/rand for cryptographically secure randomness
• Never use math/rand (predictable, insecure)
• Sufficient entropy: 32+ bytes for session, 48+ bytes for API
• Base64 URL encoding for safe transmission

2. Token Storage:

• NEVER store plain tokens in database
• Always hash before storage (bcrypt or SHA256)
• Store hash only, discard plain token after giving to user
• Use prepared statements to prevent SQL injection

3. Token Transmission:

• Send tokens over HTTPS only
• Use secure, httpOnly cookies for session tokens
• Never log or expose tokens in error messages
• Clear tokens from memory after use

4. Token Expiration:

• Session tokens: Short lifetime (hours to days)
• API tokens: Long lifetime but allow user revocation
• Reset tokens: Very short lifetime (minutes to hours)
• Always enforce expiration checks

5. Token Revocation:

• Support manual revocation by users
• Revoke all tokens on password change
• Track last used timestamp for auditing
• Remove expired tokens regularly

TOKEN GENERATION PROCESS:

1. Generate Random Bytes:

• Use crypto/rand.Read() for secure randomness
• Generate sufficient bytes for desired entropy
• Check for errors (rare, but possible on some systems)

2. Encode Plain Token:

• Base64 URL encode random bytes
• URL-safe encoding (no +, /, or = padding issues)
• Result is alphanumeric string safe for URLs

3. Hash Token:

• Hash plain token with bcrypt or SHA256
• Store hash in database
• Return plain token to user (shown only once)

4. User Storage:

• User stores plain token securely (password manager, env var)
• User includes token in API requests
• Server hashes incoming token and compares with stored hash

EXAMPLE USAGE:

hasher := NewTokenHasher()

// Generate API token (long-lived, bcrypt)
plainToken, hashedToken, err := hasher.GenerateAPIToken()
if err != nil {
    log.Fatal(err)
}
// Store hashedToken in database
// Give plainToken to user (show only once!)

// Generate session token (short-lived, SHA256)
plainSession, hashedSession, err := hasher.GenerateSessionToken()
if err != nil {
    log.Fatal(err)
}
// Store hashedSession in database
// Set plainSession as secure cookie

// Verify API token (bcrypt)
valid := hasher.VerifyToken(userProvidedToken, storedHash)
if !valid {
    return errors.New("invalid token")
}

// Verify session token (SHA256 - faster)
valid := hasher.VerifyTokenSHA256(cookieToken, storedSessionHash)
if !valid {
    return errors.New("invalid session")
}

COMMON VULNERABILITIES TO AVOID:

1. Weak Random Number Generation:

• ❌ DON'T use math/rand (predictable)
• ✅ DO use crypto/rand (cryptographically secure)

2. Storing Plain Tokens:

• ❌ DON'T store plain tokens in database
• ✅ DO store only hashed tokens

3. Insufficient Entropy:

• ❌ DON'T use short tokens (< 16 bytes)
• ✅ DO use 32+ bytes for sessions, 48+ for API tokens

4. No Expiration:

• ❌ DON'T allow tokens to live forever
• ✅ DO enforce expiration and support revocation

5. Timing Attacks:

• ❌ DON'T use == for token comparison
• ✅ DO use bcrypt.CompareHashAndPassword (constant-time)

PERFORMANCE CONSIDERATIONS:

bcrypt Cost Factor Trade-offs:

Cost 10 (Default): - ~60ms per hash on modern CPU - ~16 hashes per second per core - Suitable for login and API token validation

Cost 12 (Higher Security): - ~240ms per hash - ~4 hashes per second per core - Use for extra-sensitive tokens

Cost 14 (Maximum Security): - ~960ms per hash - ~1 hash per second per core - May impact user experience

SHA256 Performance: - Microseconds per hash - Millions of hashes per second - Use for session tokens with high request rates

THREAD SAFETY:

All methods are thread-safe and can be called concurrently from multiple goroutines. Each token generation operation is independent.