auth Package

Overview#

Package auth provides comprehensive authentication and authorization services for the incident management platform.

This package implements a flexible authentication system supporting multiple authentication methods including local accounts, OIDC/OAuth providers, and SAML integration. It provides JWT-based session management, role-based access control, group management, and automated user provisioning through SCIM 2.0.

Key Features:

• Multi-provider authentication (local, OIDC, OAuth, SAML)
• JWT token generation and validation with configurable expiration
• Role-based access control with hierarchical permissions
• Group-based access management for team-based authorization
• SCIM 2.0 automated user and group provisioning
• Session management with secure token handling
• Password policies and account security features
• Integration with external identity providers
• Comprehensive audit logging for authentication events

Architecture:

The auth system follows a modular provider-based architecture:

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ Auth Service    │◄──►│ Provider Manager │◄──►│ Auth Providers  │
│ (Orchestration) │    │ (Routing)        │    │ (OIDC/LOCAL/etc)│
└─────────────────┘    └──────────────────┘    └─────────────────┘

      │                        │                        │

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│ Token Manager   │    │ Group Service    │    │ SCIM Service    │
│ (JWT/Sessions)  │    │ (RBAC/Teams)     │    │ (Provisioning)  │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Example usage:

// Create authentication service
config := &auth.Config{
	JWTSecret:     "your-secret-key-at-least-32-chars",
	JWTExpiration: 24 * time.Hour,
	Provider:      "local",
}

authService, err := auth.NewService(config, db)
if err != nil {
	log.Fatal(err)
}

// Authenticate user
user, err := authService.AuthenticateUser(ctx, "username", "password")
if err != nil {
	return err
}

// Generate JWT token
token, err := authService.GenerateToken(ctx, user)
if err != nil {
	return err
}

// Validate token and extract user
claims, err := authService.ValidateToken(ctx, token)
if err != nil {
	return err
}

Supported Authentication Methods:

• Local: Username/password authentication with secure password hashing
• OIDC: OpenID Connect integration (Google, Azure AD, Okta, etc.)
• OAuth: OAuth 2.0 providers (GitHub, GitLab, etc.)
• SAML: SAML 2.0 identity provider integration (future)

Role Hierarchy:

• admin: Full system access including user management and configuration
• incident_commander: Incident management and escalation authority
• viewer: Read access to incident data based on group membership
• readonly: Limited read access with automatic data redaction

Import Path: github.com/systmms/incidents/internal/auth

Constants#

RoleAdmin (and others)#

Re-export constants

const RoleAdmin const RoleIncidentCommander const RoleViewer const RoleReadonly const ProviderLocal const ProviderOIDC const ProviderOAuth const ProviderSAML

Variables#

IsValidRole#

Re-export functions

var IsValidRole

Types#

AuthClaims#

{<nil> 34158 type 0 [0x140002763c0] 0}

AuthProvider#

AuthProvider interface defines the contract that all authentication providers must implement.

This interface enables a pluggable authentication system where different providers (local, OIDC, SAML, etc.) can be used interchangeably while maintaining consistent behavior and integration patterns.

{<nil> 50661 type 0 [0x14000291a00] 0}

ChangePasswordRequest#

{<nil> 34312 type 0 [0x140002765c0] 0}

Config#

Config holds comprehensive authentication service configuration.

The configuration supports multiple authentication providers, JWT token management, and external identity provider integration. It’s designed to be loaded from environment variables, configuration files, or programmatically configured.

Security considerations:

• JWT secrets must be at least 32 characters for adequate security
• Token expiration should balance security and user experience
• Admin passwords are excluded from JSON serialization for security
• OIDC client secrets should be handled securely in production

{<nil> 728 type 0 [0x140001e3080] 0}

Methods#

DefaultConfig#

DefaultConfig returns a default configuration

{<nil> <nil> DefaultConfig 0x140001a5c60 <nil>}

ConflictResolutionStrategy#

ConflictResolutionStrategy defines how to handle conflicts

{<nil> 43112 type 0 [0x140002903c0] 0}

Constants#

const ConflictResolutionSkip const ConflictResolutionOverwrite const ConflictResolutionMerge

Group#

Group represents a user group

{<nil> 8114 type 0 [0x14000208a00] 0}

GroupMember#

GroupMember represents a group membership

{<nil> 8550 type 0 [0x14000208cc0] 0}

GroupService#

GroupService handles group management

{<nil> 7851 type 0 [0x140002087c0] 0}

Methods#

NewGroupService#

NewGroupService creates a new group service

{<nil> <nil> NewGroupService 0x1400020aea0 <nil>}

Handler#

Handler handles HTTP requests for authentication

{<nil> 20174 type 0 [0x14000233d40] 0}

Methods#

NewHandler#

NewHandler creates a new authentication handler

{<nil> <nil> NewHandler 0x14000237aa0 <nil>}

LoginRequest#

{<nil> 34193 type 0 [0x14000276440] 0}

LoginResponse#

{<nil> 34232 type 0 [0x140002764c0] 0}

OIDCProvider#

OIDCProvider interface extends AuthProvider with OIDC-specific functionality.

OIDC providers require additional methods for handling the OAuth 2.0 authorization code flow, including URL generation for redirecting users to identity providers.

{<nil> 51438 type 0 [0x14000291cc0] 0}

OIDCProviderConfig#

OIDCProviderConfig represents OIDC/OAuth provider configuration with service-specific extensions.

This configuration extends the base OIDC provider configuration with additional fields needed by the authentication service for provider management and user interface.

{<nil> 3893 type 0 [0x140001e35c0] 0}

ProviderConfig#

ProviderConfig represents configuration for a specific authentication provider.

This flexible configuration structure allows different authentication providers to be configured with provider-specific settings while maintaining a consistent interface for provider management.

{<nil> 2915 type 0 [0x140001e33c0] 0}

ProvisioningOptions#

ProvisioningOptions contains options for provisioning operations

{<nil> 43432 type 0 [0x140002904c0] 0}

ProvisioningResult#

ProvisioningResult represents the result of a provisioning operation

{<nil> 35503 type 0 [0x14000276b00] 0}

ProvisioningService#

ProvisioningService handles user provisioning from external identity providers

{<nil> 35066 type 0 [0x14000276800] 0}

Methods#

NewProvisioningService#

NewProvisioningService creates a new provisioning service

{<nil> <nil> NewProvisioningService 0x14000265a80 <nil>}

Service#

Service handles authentication and authorization for the incident management platform.

The Service coordinates multiple authentication providers, manages JWT tokens, handles user sessions, and integrates with group management and provisioning systems. It serves as the central orchestrator for all authentication operations.

{<nil> 52157 type 0 [0x14000291f40] 0}

Methods#

NewService#

NewService creates a new authentication service with the specified configuration and database.

This constructor initializes all authentication components including:

• JWT token manager with configurable expiration
• Authentication providers (local, OIDC) based on configuration
• Group management service for role-based access control
• User provisioning service for SCIM integration
• Database schema validation and initial setup

The service supports multiple authentication providers simultaneously, allowing users to authenticate using local accounts or external identity providers.

Configuration validation ensures:

• JWT secret is provided and sufficiently secure (minimum 32 characters)
• Token expiration is valid and reasonable
• Database connection is available
• OIDC provider configurations are valid if enabled

Returns an error if configuration is invalid, database connection fails, or provider initialization encounters errors. OIDC provider failures are logged but don’t prevent service creation to maintain availability.

{<nil> <nil> NewService 0x140002b6a20 <nil>}

Session#

{<nil> 34129 type 0 [0x14000276300] 0}

SetupRequest#

{<nil> 34273 type 0 [0x14000276540] 0}

TokenManager#

TokenManager handles JWT token operations

{<nil> 71016 type 0 [0x140002d9e40] 0}

Methods#

NewTokenManager#

NewTokenManager creates a new token manager

{<nil> <nil> NewTokenManager 0x140002e2ca0 <nil>}

User#

{<nil> 34106 type 0 [0x14000276280] 0}

Functions#

CreateTables#

CreateTables creates the authentication tables

{<nil> <nil> CreateTables 0x14000264b00 <nil>}

GenerateSessionID#

GenerateSessionID generates a new session ID

{<nil> <nil> GenerateSessionID 0x140002fee20 <nil>}

GetUserFromContext#

GetUserFromContext extracts the user from request context

{<nil> <nil> GetUserFromContext 0x140002c4ec0 <nil>}

createTablesWithEmbeddedSchema#

createTablesWithEmbeddedSchema creates tables using embedded schema

{<nil> <nil> createTablesWithEmbeddedSchema 0x14000264e40 <nil>}

generateJWTSecret#

generateJWTSecret generates a secure random JWT secret

{<nil> <nil> generateJWTSecret 0x140002b6da0 <nil>}

nilIfEmpty#

{<nil> <nil> nilIfEmpty 0x140002363e0 <nil>}

nullStringValue#

{<nil> <nil> nullStringValue 0x14000236240 <nil>}

stringValue#

{<nil> <nil> stringValue 0x14000236080 <nil>}

Generated automatically from Go source code. Last updated: 2025-08-25T07:51:05-04:00