authentication

Documentation

Index

• Variables
• func Context[T Ctx](ctx context.Context) (t T)
• func IsAuthenticated(ctx context.Context) bool
• func WithAuthContext[T Ctx](ctx context.Context, c T) context.Context
• type Authenticator
  • func New[T Ctx](ctx context.Context, zitadel *zitadel.Zitadel, encryptionKey string, ...) (*Authenticator[T], error)
  • func (a *Authenticator[T]) Authenticate(w http.ResponseWriter, r *http.Request, requestedURI string)
  • func (a *Authenticator[T]) Callback(w http.ResponseWriter, req *http.Request)
  • func (a *Authenticator[T]) IsAuthenticated(req *http.Request) (T, error)
  • func (a *Authenticator[T]) Logout(w http.ResponseWriter, req *http.Request)
  • func (a *Authenticator[T]) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Ctx
• type Handler
• type HandlerInitializer
• type InMemorySessions
  • func (s *InMemorySessions[T]) Get(id string) (T, error)
  • func (s *InMemorySessions[T]) Set(id string, session T) error
• type Interceptor
  • func Middleware[T Ctx](authenticator *Authenticator[T]) *Interceptor[T]
  • func (i *Interceptor[T]) CheckAuthentication() func(next http.Handler) http.Handler
  • func (i *Interceptor[T]) Context(ctx context.Context) T
  • func (i *Interceptor[T]) RequireAuthentication() func(next http.Handler) http.Handler
• type Option
  • func WithExternalSecure[T Ctx](externalSecure bool) Option[T]
  • func WithLogger[T Ctx](logger *slog.Logger) Option[T]
  • func WithSessionCookieName[T Ctx](cookieName string) Option[T]
  • func WithSessionStore[T Ctx](sessions Sessions[T]) Option[T]
• type Sessions
• type State
  • func DecryptState(data, key string) (*State, error)
  • func (s *State) Encrypt(key string) (string, error)

Variables

var (
	ErrNoCookie  = errors.New("no cookie")
	ErrNoSession = errors.New("no session")
)

Functions

func Context

func Context[T Ctx](ctx context.Context) (t T)

Context returns a typed implementation the authentication context Ctx. It can be used to get information about the (authenticated) user.

func IsAuthenticated

func IsAuthenticated(ctx context.Context) bool

IsAuthenticated returns if the user is authenticated

func WithAuthContext

func WithAuthContext[T Ctx](ctx context.Context, c T) context.Context

WithAuthContext allows to set the authentication context (Ctx), which can later be retrieved by calling the Context function.

Types

type Authenticator

type Authenticator[T Ctx] struct {
	// contains filtered or unexported fields
}

Authenticator provides the functionality to handle authentication including check for existing session, starting a new authentication by redirecting the user to the Login UI and more.

func New

func New[T Ctx](ctx context.Context, zitadel *zitadel.Zitadel, encryptionKey string, initAuthentication HandlerInitializer[T], options ...Option[T]) (*Authenticator[T], error)

func (*Authenticator[T]) Authenticate

func (a *Authenticator[T]) Authenticate(w http.ResponseWriter, r *http.Request, requestedURI string)

Authenticate starts a new authentication (by redirecting the user to the Login UI) The initially requested URI (in the application) is passed as encrypted state.

func (*Authenticator[T]) Callback

func (a *Authenticator[T]) Callback(w http.ResponseWriter, req *http.Request)

Callback handles the redirect back from the Login UI. On successful authentication a new session will be created and its id will be stored in a cookie. The user will be redirected to the initially requested UI (passed as encrypted state)

func (*Authenticator[T]) IsAuthenticated

func (a *Authenticator[T]) IsAuthenticated(req *http.Request) (T, error)

IsAuthenticated checks whether there is an existing session of not. In case there is one, it will be returned.

func (*Authenticator[T]) Logout

func (a *Authenticator[T]) Logout(w http.ResponseWriter, req *http.Request)

Logout will terminate the exising session.

func (*Authenticator[T]) ServeHTTP

func (a *Authenticator[T]) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP serves the authentication handler and its three subroutes.

type Ctx

type Ctx interface {
	IsAuthenticated() bool
}

Ctx represents the authentication context with information about the authenticated user.

type Handler

type Handler[T Ctx] interface {
	Authenticate(w http.ResponseWriter, r *http.Request, state string)
	Callback(w http.ResponseWriter, r *http.Request) (t T, state string)
	Logout(w http.ResponseWriter, r *http.Request, authCtx T, state, optionalRedirectURI string)
}

Handler defines the handling of authentication and logout

type HandlerInitializer

type HandlerInitializer[T Ctx] func(ctx context.Context, zitadel *zitadel.Zitadel) (Handler[T], error)

HandlerInitializer abstracts the initialization of a Handler by providing the ZITADEL domain, port and if tls is set

type InMemorySessions

type InMemorySessions[T Ctx] struct {
	// contains filtered or unexported fields
}

InMemorySessions implements the Sessions interface by storing the sessions in-memory. This is obviously not suitable for production and only meant for testing purposes.

func (*InMemorySessions[T]) Get

func (s *InMemorySessions[T]) Get(id string) (T, error)

func (*InMemorySessions[T]) Set

func (s *InMemorySessions[T]) Set(id string, session T) error

type Interceptor

type Interceptor[T Ctx] struct {
	// contains filtered or unexported fields
}

func Middleware

func Middleware[T Ctx](authenticator *Authenticator[T]) *Interceptor[T]

func (*Interceptor[T]) CheckAuthentication

func (i *Interceptor[T]) CheckAuthentication() func(next http.Handler) http.Handler

CheckAuthentication will check if there is a valid session and provide it in the context. Unlike [RequireAuthentication] it will not start a new authentication if there is none.

func (*Interceptor[T]) Context

func (i *Interceptor[T]) Context(ctx context.Context) T

func (*Interceptor[T]) RequireAuthentication

func (i *Interceptor[T]) RequireAuthentication() func(next http.Handler) http.Handler

RequireAuthentication will check if there is a valid session and provide it in the context. If there is no session, it will automatically start a new authentication (by redirecting the user to the Login UI)

type Option

type Option[T Ctx] func(authorizer *Authenticator[T])

Option allows customization of the Authenticator such as logging and more.

func WithExternalSecure

func WithExternalSecure[T Ctx](externalSecure bool) Option[T]

WithExternalSecure allows using https redirects when the service is behind a reverse proxy.

func WithLogger

func WithLogger[T Ctx](logger *slog.Logger) Option[T]

WithLogger allows a logger other than slog.Default().

EXPERIMENTAL: Will change to log/slog import after we drop support for Go 1.20

func WithSessionCookieName

func WithSessionCookieName[T Ctx](cookieName string) Option[T]

WithSessionCookieName allows a session cookie name other than "zitadel.session".

func WithSessionStore

func WithSessionStore[T Ctx](sessions Sessions[T]) Option[T]

WithSessionStore allows a session store other than InMemorySessions.

type Sessions

type Sessions[T Ctx] interface {
	Set(id string, session T) error
	Get(id string) (T, error)
}

Sessions is an abstraction of the session storage

type State

type State struct {
	RequestedURI string
}

State represents the state of the users application before an authentication process starts, It is used to transfer the state from the application to the Login UI and back, e.g. when starting the login flow.

func DecryptState

func DecryptState(data, key string) (*State, error)

func (*State) Encrypt

func (s *State) Encrypt(key string) (string, error)