session

package module
v0.7.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 22, 2026 License: MIT Imports: 20 Imported by: 0

README

Session

Overview

The Session repository is designed to handle the management of user sessions, including authorization, storage, and expiration. It provides a framework for manageing sessions across different databases and supports multiple login types.

Features

  • Session Management: Efficient handling of user session creation, storage, and expiration.
  • Database Support: Seamless integration with multiple databases.
    • PostgreSQL
    • Google Cloud Spanner
  • Login Types: Supports multiple authentication methods.
    • Azure OIDC
    • Username/Password
Created and maintained by the CCC team.

Documentation

Overview

Package session provides session handlers for various authentication implementations. Currently supported are: 1) Azure OIDC Authorization Code Flow with PKCE 2) Preauth: Allows you to implement your own authentication, but still use session handlers 3) Username/Password: Implements user storage and password management

Index

Constants

View Source
const (
	// RouterSessionUserID is a constant used for matching the SessionUserID in the router path
	RouterSessionUserID = "sessionUserID"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type BaseSessionOption added in v0.6.0

type BaseSessionOption func(*basesession.BaseSession)

BaseSessionOption defines a function signature for setting session options.

func WithLogHandler added in v0.6.0

func WithLogHandler(l LogHandler) BaseSessionOption

WithLogHandler sets the LogHandler. (default: httpio.Log)

func WithSessionTableName added in v0.6.1

func WithSessionTableName(name string) BaseSessionOption

WithSessionTableName sets the name of the session table. (default: Sessions)

func WithSessionTimeout added in v0.6.0

func WithSessionTimeout(d time.Duration) BaseSessionOption

WithSessionTimeout sets the session timeout. (default: 10m)

func WithUserTableName added in v0.6.1

func WithUserTableName(name string) BaseSessionOption

WithUserTableName sets the name of the user table. (default: SessionUsers)

type ChangeSessionUserPasswordRequest added in v0.6.2

type ChangeSessionUserPasswordRequest struct {
	OldPassword string
	NewPassword string
}

ChangeSessionUserPasswordRequest takes in the user information for changing a SessionUser password

type CookieOption added in v0.5.8

type CookieOption cookie.Option

CookieOption defines a function signature for setting cookie client options.

func WithCookieDomain added in v0.5.8

func WithCookieDomain(domain string) CookieOption

WithCookieDomain sets the domain for the session cookie.

func WithCookieName added in v0.5.8

func WithCookieName(name string) CookieOption

WithCookieName sets the cookie name for the session cookie.

func WithXSRFCookieName added in v0.7.0

func WithXSRFCookieName(name string) CookieOption

WithXSRFCookieName sets the cookie name for the XSRF cookie.

func WithXSRFHeaderName added in v0.7.0

func WithXSRFHeaderName(name string) CookieOption

WithXSRFHeaderName sets the header name for the XSRF header.

type CreateUserRequest added in v0.6.2

type CreateUserRequest struct {
	Username string  `json:"username"`
	Password *string `json:"password"`
	Disabled bool    `json:"disabled"`
}

CreateUserRequest takes in the user information for creating a new SessionUser

type DisabledUserRoleManager added in v0.6.0

type DisabledUserRoleManager struct{}

DisabledUserRoleManager implements the UserManager interface but disables all user management functions.

func DisableUserRoleManagement added in v0.6.0

func DisableUserRoleManagement() DisabledUserRoleManager

DisableUserRoleManagement returns a DisabledUserRoleManager instance.

func (DisabledUserRoleManager) AddUserRoles added in v0.6.0

AddUserRoles does nothing and returns nil.

func (DisabledUserRoleManager) DeleteUserRoles added in v0.6.0

DeleteUserRoles does nothing and returns nil.

func (DisabledUserRoleManager) Domains added in v0.6.0

Domains returns a default global domain.

func (DisabledUserRoleManager) RoleExists added in v0.6.0

RoleExists always returns true, indicating that any role exists.

func (DisabledUserRoleManager) UserRoles added in v0.6.0

UserRoles always returns an empty RoleCollection.

type LogHandler

type LogHandler = basesession.LogHandler

LogHandler defines the handler signature required for handling logs.

type OIDCAzure added in v0.6.0

type OIDCAzure struct {
	// contains filtered or unexported fields
}

OIDCAzure implements the OIDCAzureHandlers interface for handling OIDC authentication with Azure.

func NewOIDCAzure

func NewOIDCAzure(
	storage sessionstorage.OIDCStore, userRoleManager UserRoleManager,
	cookieKey string,
	issuerURL, clientID, clientSecret, redirectURL string,
	options ...OIDCAzureOption,
) (*OIDCAzure, error)

NewOIDCAzure creates a new OIDCAzure. cookieKey: A Base64-encoded string representing at least 32 bytes of cryptographically secure random data.

func (*OIDCAzure) API added in v0.7.0

func (o *OIDCAzure) API() *OIDCAzureAPI

API provides programatic access to OIDCAzure

func (*OIDCAzure) Authenticated added in v0.7.0

func (o *OIDCAzure) Authenticated() http.HandlerFunc

Authenticated is the handler reports if the session is authenticated

func (*OIDCAzure) CallbackOIDC added in v0.6.0

func (o *OIDCAzure) CallbackOIDC() http.HandlerFunc

CallbackOIDC is the handler for the callback from the OIDC auth provider

func (*OIDCAzure) FrontChannelLogout added in v0.6.0

func (o *OIDCAzure) FrontChannelLogout() http.HandlerFunc

FrontChannelLogout is a handler which destroys the current session for a logout request initiated by the OIDC provider

func (*OIDCAzure) Login added in v0.6.0

func (o *OIDCAzure) Login() http.HandlerFunc

Login initiates the OIDC login flow by redirecting the user to the authorization URL.

func (*OIDCAzure) Logout added in v0.7.0

func (o *OIDCAzure) Logout() http.HandlerFunc

Logout destroys the current session

func (*OIDCAzure) SetXSRFToken added in v0.7.0

func (o *OIDCAzure) SetXSRFToken(next http.Handler) http.Handler

SetXSRFToken sets the XSRF Token

func (*OIDCAzure) StartSession added in v0.7.0

func (o *OIDCAzure) StartSession(next http.Handler) http.Handler

StartSession initializes a session by restoring it from a cookie, or if that fails, initializing a new session. The session cookie is then updated and the sessionID is inserted into the context.

func (*OIDCAzure) ValidateSession added in v0.7.0

func (o *OIDCAzure) ValidateSession(next http.Handler) http.Handler

ValidateSession checks the sessionID in the database to validate that it has not expired and updates the last activity timestamp if it is still valid. StartSession handler must be called before calling ValidateSession

func (*OIDCAzure) ValidateXSRFToken added in v0.7.0

func (o *OIDCAzure) ValidateXSRFToken(next http.Handler) http.Handler

ValidateXSRFToken validates the XSRF Token

type OIDCAzureAPI added in v0.7.0

type OIDCAzureAPI struct {
	// contains filtered or unexported fields
}

OIDCAzureAPI provides programatic access to OIDCAzure

func (*OIDCAzureAPI) Cookie added in v0.7.0

func (p *OIDCAzureAPI) Cookie() *cookie.Client

Cookie returns the underlying cookie.Client

func (*OIDCAzureAPI) ValidateSession added in v0.7.1

func (p *OIDCAzureAPI) ValidateSession(ctx context.Context) (context.Context, error)

ValidateSession checks the session cookie and if it is valid, stores the session data into the context

type OIDCAzureHandlers

type OIDCAzureHandlers interface {
	CallbackOIDC() http.HandlerFunc
	FrontChannelLogout() http.HandlerFunc
	Login() http.HandlerFunc
	basesession.Handlers
}

OIDCAzureHandlers defines the interface for OIDC Azure session handlers.

type OIDCAzureOption added in v0.5.8

type OIDCAzureOption interface {
	// contains filtered or unexported methods
}

OIDCAzureOption defines the interface for functional options used when creating a new OIDCAzure.

type OIDCOption added in v0.6.0

type OIDCOption func(*azureoidc.OIDC)

OIDCOption defines a function signature for setting OIDC options.

func WithLoginURL added in v0.6.0

func WithLoginURL(l string) OIDCOption

WithLoginURL sets the LoginURL for the SPA. (default: /login)

type PasswordAuth added in v0.6.1

type PasswordAuth struct {
	// contains filtered or unexported fields
}

PasswordAuth implements the PasswordHandlers interface for handling password authentication.

func NewPasswordAuth added in v0.6.1

func NewPasswordAuth(storage sessionstorage.PasswordAuthStore, cookieKey string, options ...PasswordOption) (*PasswordAuth, error)

NewPasswordAuth creates a new PasswordAuth. cookieKey: A Base64-encoded string representing at least 32 bytes of cryptographically secure random data.

func (*PasswordAuth) API added in v0.7.0

func (p *PasswordAuth) API() *PasswordAuthAPI

API provides programatic access to PasswordAuth handler internals

func (*PasswordAuth) ActivateUser added in v0.6.2

func (p *PasswordAuth) ActivateUser() http.HandlerFunc

ActivateUser handles activating a user account.

func (*PasswordAuth) Authenticated added in v0.6.1

func (p *PasswordAuth) Authenticated() http.HandlerFunc

Authenticated is the handler that reports if the session is authenticated

func (*PasswordAuth) ChangeUserPassword added in v0.6.1

func (p *PasswordAuth) ChangeUserPassword() http.HandlerFunc

ChangeUserPassword handles modifications to a user password

func (*PasswordAuth) CreateUser added in v0.6.2

func (p *PasswordAuth) CreateUser() http.HandlerFunc

CreateUser handles creating a user account.

func (*PasswordAuth) DeactivateUser added in v0.6.2

func (p *PasswordAuth) DeactivateUser() http.HandlerFunc

DeactivateUser handles deactivating a user account.

func (*PasswordAuth) DeleteUser added in v0.6.2

func (p *PasswordAuth) DeleteUser() http.HandlerFunc

DeleteUser handles deleting a user account.

func (*PasswordAuth) Login added in v0.6.1

func (p *PasswordAuth) Login() http.HandlerFunc

Login validates the username and password and establishes the sessoin cookie.

func (*PasswordAuth) Logout added in v0.7.0

func (p *PasswordAuth) Logout() http.HandlerFunc

Logout destroys the current session

func (*PasswordAuth) SetXSRFToken added in v0.7.0

func (p *PasswordAuth) SetXSRFToken(next http.Handler) http.Handler

SetXSRFToken sets the XSRF Token

func (*PasswordAuth) StartSession added in v0.7.0

func (p *PasswordAuth) StartSession(next http.Handler) http.Handler

StartSession initializes a session by restoring it from a cookie, or if that fails, initializing a new session. The session cookie is then updated and the sessionID is inserted into the context.

func (*PasswordAuth) ValidateSession added in v0.6.1

func (p *PasswordAuth) ValidateSession(next http.Handler) http.Handler

ValidateSession checks the sessionID in the database to validate that it has not expired and updates the last activity timestamp if it is still valid. StartSession handler must be called before calling ValidateSession

func (*PasswordAuth) ValidateXSRFToken added in v0.7.0

func (p *PasswordAuth) ValidateXSRFToken(next http.Handler) http.Handler

ValidateXSRFToken validates the XSRF Token

type PasswordAuthAPI added in v0.7.0

type PasswordAuthAPI struct {
	// contains filtered or unexported fields
}

PasswordAuthAPI provides programatic access to PasswordAuth handler internals

func (*PasswordAuthAPI) ActivateSessionUser added in v0.7.0

func (p *PasswordAuthAPI) ActivateSessionUser(ctx context.Context, sessionUserUUID ccc.UUID) error

ActivateSessionUser handles activating a user

func (*PasswordAuthAPI) ChangeSessionUserHash added in v0.7.0

func (p *PasswordAuthAPI) ChangeSessionUserHash(ctx context.Context, userID ccc.UUID, hash *securehash.Hash) error

ChangeSessionUserHash handles modifications to a user hash.

func (*PasswordAuthAPI) ChangeSessionUserPassword added in v0.7.0

func (p *PasswordAuthAPI) ChangeSessionUserPassword(ctx context.Context, userID ccc.UUID, req *ChangeSessionUserPasswordRequest) error

ChangeSessionUserPassword handles modifications to a user password

func (*PasswordAuthAPI) Cookie added in v0.7.0

func (p *PasswordAuthAPI) Cookie() *cookie.Client

Cookie returns the underlying cookie.Client

func (*PasswordAuthAPI) CreateSessionUser added in v0.7.0

func (p *PasswordAuthAPI) CreateSessionUser(ctx context.Context, req *CreateUserRequest) (ccc.UUID, error)

CreateSessionUser handles creating a user account

func (*PasswordAuthAPI) DeactivateSessionUser added in v0.7.0

func (p *PasswordAuthAPI) DeactivateSessionUser(ctx context.Context, sessionUserID ccc.UUID) error

DeactivateSessionUser handles deactivating a user account

func (*PasswordAuthAPI) DeleteSessionUser added in v0.7.0

func (p *PasswordAuthAPI) DeleteSessionUser(ctx context.Context, sessionUserID ccc.UUID) error

DeleteSessionUser handles deleting a user account

func (*PasswordAuthAPI) Login added in v0.7.0

func (p *PasswordAuthAPI) Login(ctx context.Context, w http.ResponseWriter, username, password string) error

Login validates the username and password.

func (*PasswordAuthAPI) Logout added in v0.7.0

func (p *PasswordAuthAPI) Logout(ctx context.Context) error

Logout destroys the current session

func (*PasswordAuthAPI) StartSession added in v0.7.0

StartSession initializes a session by restoring it from a cookie, or if that fails, initializing a new session. The session cookie is then updated and the sessionID is inserted into the context.

func (*PasswordAuthAPI) ValidateSession added in v0.7.0

func (p *PasswordAuthAPI) ValidateSession(ctx context.Context) (context.Context, error)

ValidateSession checks the sessionID in the database to validate that it has not expired and updates the last activity timestamp if it is still valid. StartSession handler must be called before calling ValidateSession

type PasswordAuthHandlers added in v0.6.1

type PasswordAuthHandlers interface {
	// ActivateUser handles activating a user account.
	ActivateUser() http.HandlerFunc
	// Authenticated is the handler reports if the session is authenticated.
	Authenticated() http.HandlerFunc
	// ChangeUserPassword handles modifications to a user password.
	ChangeUserPassword() http.HandlerFunc
	// CreateUser handles creating a user account.
	CreateUser() http.HandlerFunc
	// DeactivateUser handles deactivating a user account.
	DeactivateUser() http.HandlerFunc
	// DeleteUser handles deleting a user account.
	DeleteUser() http.HandlerFunc
	// Login validates the username and password.
	Login() http.HandlerFunc
	// ValidateSession checks the sessionID in the database to validate that it has not expired
	// and updates the last activity timestamp if it is still valid.
	ValidateSession(next http.Handler) http.Handler
	basesession.Handlers
}

PasswordAuthHandlers defines the interface for password authentication handlers.

type PasswordOption added in v0.6.1

type PasswordOption interface {
	// contains filtered or unexported methods
}

PasswordOption defines the interface for functional options used when creating a new Password.

func AutoUpgradeHashes added in v0.6.1

func AutoUpgradeHashes(a bool) PasswordOption

AutoUpgradeHashes controls if password hashes will be auto upgraded (default: true)

func HashAlgorithm added in v0.6.1

func HashAlgorithm(hasher securehash.HashAlgorithm) PasswordOption

HashAlgorithm controls hashing algrorithm (default: securehash.Argon2())

type Preauth added in v0.6.0

type Preauth struct {
	// contains filtered or unexported fields
}

Preauth handles session management for pre-authentication scenarios.

func NewPreauth added in v0.4.0

func NewPreauth(storage sessionstorage.PreauthStore, cookieKey string, options ...PreauthOption) (*Preauth, error)

NewPreauth creates a new PreauthSession instance. cookieKey: A Base64-encoded string representing at least 32 bytes of cryptographically secure random data.

func (*Preauth) API added in v0.7.0

func (p *Preauth) API() *PreauthAPI

API provides programatic access to Preauth handler internals

func (*Preauth) Authenticated added in v0.7.0

func (p *Preauth) Authenticated() http.HandlerFunc

Authenticated is the handler reports if the session is authenticated

func (*Preauth) Logout added in v0.7.0

func (p *Preauth) Logout() http.HandlerFunc

Logout destroys the current session

func (*Preauth) NewSession deprecated added in v0.6.0

func (p *Preauth) NewSession(ctx context.Context, w http.ResponseWriter, _ *http.Request, username string) (ccc.UUID, error)

NewSession creates a new session for a pre-authenticated user.

Deprecated: Use p.API().Login() instead

func (*Preauth) SetXSRFToken added in v0.7.0

func (p *Preauth) SetXSRFToken(next http.Handler) http.Handler

SetXSRFToken sets the XSRF Token

func (*Preauth) StartSession added in v0.7.0

func (p *Preauth) StartSession(next http.Handler) http.Handler

StartSession initializes a session by restoring it from a cookie, or if that fails, initializing a new session. The session cookie is then updated and the sessionID is inserted into the context.

func (*Preauth) ValidateSession added in v0.7.0

func (p *Preauth) ValidateSession(next http.Handler) http.Handler

ValidateSession checks the sessionID in the database to validate that it has not expired and updates the last activity timestamp if it is still valid. StartSession handler must be called before calling ValidateSession

func (*Preauth) ValidateXSRFToken added in v0.7.0

func (p *Preauth) ValidateXSRFToken(next http.Handler) http.Handler

ValidateXSRFToken validates the XSRF Token

type PreauthAPI added in v0.7.0

type PreauthAPI struct {
	// contains filtered or unexported fields
}

PreauthAPI provides programatic access to Preauth handler internals

func (*PreauthAPI) Cookie added in v0.7.0

func (p *PreauthAPI) Cookie() *cookie.Client

Cookie returns the underlying cookie.Client

func (*PreauthAPI) Login added in v0.7.0

func (p *PreauthAPI) Login(ctx context.Context, w http.ResponseWriter, username string) (ccc.UUID, error)

Login creates a new session for a pre-authenticated user.

func (*PreauthAPI) Logout added in v0.7.0

func (p *PreauthAPI) Logout(ctx context.Context) error

Logout destroys the current session

func (*PreauthAPI) StartSession added in v0.7.0

func (p *PreauthAPI) StartSession(ctx context.Context, w http.ResponseWriter, r *http.Request) (context.Context, error)

StartSession initializes a session by restoring it from a cookie, or if that fails, initializing a new session. The session cookie is then updated and the sessionID is inserted into the context.

func (*PreauthAPI) ValidateSession added in v0.7.0

func (p *PreauthAPI) ValidateSession(ctx context.Context) (context.Context, error)

ValidateSession checks the sessionID in the database to validate that it has not expired and updates the last activity timestamp if it is still valid. StartSession handler must be called before calling ValidateSession

type PreauthHandlers added in v0.6.0

type PreauthHandlers interface {
	basesession.Handlers
	NewSession(ctx context.Context, w http.ResponseWriter, r *http.Request, username string) (ccc.UUID, error)
}

PreauthHandlers defines the interface for pre-authentication session handlers.

type PreauthOption added in v0.6.0

type PreauthOption interface {
	// contains filtered or unexported methods
}

PreauthOption defines the functional option type for configuring PreauthSession.

type UserRoleManager added in v0.6.0

type UserRoleManager interface {
	Domains(ctx context.Context) ([]accesstypes.Domain, error)
	UserRoles(ctx context.Context, user accesstypes.User, domains ...accesstypes.Domain) (accesstypes.RoleCollection, error)
	RoleExists(ctx context.Context, domain accesstypes.Domain, role accesstypes.Role) bool
	AddUserRoles(ctx context.Context, domain accesstypes.Domain, user accesstypes.User, roles ...accesstypes.Role) error
	DeleteUserRoles(ctx context.Context, domain accesstypes.Domain, user accesstypes.User, roles ...accesstypes.Role) error
}

UserRoleManager defines an interface for managing user roles.

Directories

Path Synopsis
Package cookie provides cookie encryption using PASETO
Package cookie provides cookie encryption using PASETO
internal
azureoidc
Package azureoidc implements a client for Azure OIDC Authorization Code Flow with PKCE (Proof Key for Code Exchange).
Package azureoidc implements a client for Azure OIDC Authorization Code Flow with PKCE (Proof Key for Code Exchange).
azureoidc/loader
Package loader contains interfaces for safely accessing an OIDC Provider.
Package loader contains interfaces for safely accessing an OIDC Provider.
basesession
Package basesession implements the session management for the application.
Package basesession implements the session management for the application.
cookie
Package cookie implements all cookie handling for the session package
Package cookie implements all cookie handling for the session package
dbtype
Package dbtype contains types used by the database driver packages for session storage.
Package dbtype contains types used by the database driver packages for session storage.
util
Package util is used for general utility function such as generic sorting/filtering and more.
Package util is used for general utility function such as generic sorting/filtering and more.
Package mock is used to generate mock files for testing.
Package mock is used to generate mock files for testing.
mock_azureoidc
Package mock_azureoidc is a generated GoMock package.
Package mock_azureoidc is a generated GoMock package.
mock_azureoidc/mock_loader
Package mock_loader is a generated GoMock package.
Package mock_loader is a generated GoMock package.
mock_basesession
Package mock_basesession is a generated GoMock package.
Package mock_basesession is a generated GoMock package.
mock_cookie
Package mock_cookie is a generated GoMock package.
Package mock_cookie is a generated GoMock package.
mock_postgres
Package mock_postgres is a generated GoMock package.
Package mock_postgres is a generated GoMock package.
mock_session
Package mock_session is a generated GoMock package.
Package mock_session is a generated GoMock package.
Package sessioninfo handles session information.
Package sessioninfo handles session information.
Package sessionstorage implements database storage for session data.
Package sessionstorage implements database storage for session data.
internal/postgres
Package postgres implements the session storage driver for PostgreSQL.
Package postgres implements the session storage driver for PostgreSQL.
internal/spanner
Package spanner provides the session storage driver for Spanner.
Package spanner provides the session storage driver for Spanner.
mock/mock_sessionstorage
Package mock_sessionstorage is a generated GoMock package.
Package mock_sessionstorage is a generated GoMock package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL