Documentation
¶
Overview ¶
Package auth provides WebAuthn-based authentication functionality for the application.
The package implements user authentication using WebAuthn (Web Authentication), which allows for passwordless authentication using platform authenticators (like biometric sensors, security keys, etc).
Key components:
- Service: The main service that handles WebAuthn operations and user management
- User: Implements the webauthn.User interface and represents an authenticated user
- Session: Represents a user's authentication session with expiration
- Storage: Interface defining the required persistence operations
- Middleware: HTTP middleware for user session management
The authentication flow consists of two main operations:
Registration (BeginRegister/FinishRegister): - Creates new users with WebAuthn credentials - Requires resident keys and user verification - Manages temporary sessions during the registration process
Login (BeginLogin/FinishLogin): - Authenticates existing users using their WebAuthn credentials - Creates and manages user sessions
The package also provides a middleware that automatically populates the request context with the authenticated user information when a valid session is present.
Index ¶
- func GravatarUrlFromEmail(email string) string
- func GravatarUrlFromHash(hash string) string
- func GravatarUrlFromUsername(username string) string
- type Service
- func (svc *Service) BeginLogin(ctx context.Context, username string) (*protocol.CredentialAssertion, Session, error)
- func (svc *Service) BeginRegister(ctx context.Context, username string) (*protocol.CredentialCreation, Session, error)
- func (svc *Service) FinishLogin(ctx context.Context, token string, response *http.Request) (*Session, error)
- func (svc *Service) FinishRegister(ctx context.Context, token string, response *http.Request) (*Session, error)
- func (svc *Service) GetSession(ctx context.Context, token string) (session Session, err error)
- func (svc *Service) GetUser(ctx context.Context, username string) (user User, err error)
- func (svc *Service) UserSessionMiddleware() func(http.Handler) http.Handler
- type Session
- type Storage
- type User
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GravatarUrlFromEmail ¶
func GravatarUrlFromHash ¶
func GravatarUrlFromUsername ¶
Types ¶
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
func NewService ¶
NewService creates a new authentication service with the provided storage and WebAuthn configuration. It initializes the WebAuthn relying party with the specified server ID, display name and origins. Returns the configured service instance and any error encountered during initialization.
func (*Service) BeginLogin ¶
func (svc *Service) BeginLogin(ctx context.Context, username string) (*protocol.CredentialAssertion, Session, error)
BeginLogin initiates the WebAuthn login process for an existing user. It retrieves the user's information, creates a WebAuthn assertion challenge, and stores the login session data.
Returns:
- *protocol.CredentialAssertion: WebAuthn credential assertion options
- Session: The login session containing challenge data
- error: Any error encountered during the process
The method will return an error if:
- The user does not exist
- WebAuthn login initialization fails
- Session data encoding fails
- Session creation fails
func (*Service) BeginRegister ¶
func (svc *Service) BeginRegister(ctx context.Context, username string) (*protocol.CredentialCreation, Session, error)
BeginRegister initiates the WebAuthn registration process for a new user. It checks if the username is available, creates a new WebAuthn credential creation challenge, and stores the registration session data.
Returns:
- *protocol.CredentialCreation: WebAuthn credential creation options
- Session: The registration session containing challenge data
- error: Any error encountered during the process
The method will return an error if:
- The username is already taken
- WebAuthn registration initialization fails
- Session creation fails
func (*Service) FinishLogin ¶
func (svc *Service) FinishLogin(ctx context.Context, token string, response *http.Request) (*Session, error)
FinishLogin completes the WebAuthn login process for a user. It validates the login session, processes the WebAuthn credential response, and creates a new authenticated session.
Returns:
- *Session: The newly created authenticated session
- error: Any error encountered during login
The method will return an error if:
- The login session is invalid or expired
- The user cannot be found
- The WebAuthn credential validation fails
- User credential update fails
- Session creation fails
func (*Service) FinishRegister ¶
func (svc *Service) FinishRegister(ctx context.Context, token string, response *http.Request) (*Session, error)
FinishRegister completes the WebAuthn registration process for a new user. It validates the registration session, processes the WebAuthn credential response, and creates a new authenticated user session.
Returns:
- *Session: The newly created authenticated session
- error: Any error encountered during registration
The method will return an error if:
- The registration session is invalid or expired
- The WebAuthn credential validation fails
- User creation or session storage fails
func (*Service) GetSession ¶
GetUser retrieves a session from storage by its token. It returns the Session object and any error encountered during the retrieval.
func (*Service) GetUser ¶
GetUser retrieves a user from storage by their username. It returns the User object and any error encountered during the retrieval.
func (*Service) UserSessionMiddleware ¶
UserSessionMiddleware populates the context with a reference to the user that's currently performing the requests. This is only done if:
- there's a session cookie
- the session exists in the database
- the session is not expired
- the user with that username exists
It doesn't prevent in any way the request from going through. In order to retrieve the populated user from the context, use UserFromContext.
type Storage ¶
type Storage interface {
CreateUser(context.Context, User) error
UpdateUserCredentials(context.Context, User) error
UpdateUserAvatar(context.Context, User) error
GetSessionByToken(context.Context, string) (Session, error)
CreateSession(context.Context, Session) error
GetUserByUsername(context.Context, string) (User, error)
}
type User ¶
type User struct {
UUID string
Username string
Credentials []webauthn.Credential
Avatar string
}
User represents a WebAuthn user. It implements the webauthn.User interface.
func UserFromContext ¶
UserFromContext returns the user reference from the context, if it exists.
func (*User) WebAuthnCredentials ¶
func (u *User) WebAuthnCredentials() []webauthn.Credential
Source Files