auth

Documentation

Index

• func ConfigBasicAuth() goyave.Middleware
• func GenerateToken(username interface{}) (string, error)
• func GenerateTokenWithClaims(claims jwt.MapClaims, signingMethod jwt.SigningMethod) (string, error)
• func JWTRoutes(router *goyave.Router, model interface{}) *goyave.Router
• func Middleware(model interface{}, authenticator Authenticator) goyave.Middleware
• type Authenticator
• type BasicAuthenticator
  • func (a *BasicAuthenticator) Authenticate(request *goyave.Request, user interface{}) error
• type BasicUser
• type Column
  • func FindColumns(strct interface{}, fields ...string) []*Column
• type JWTAuthenticator
  • func (a *JWTAuthenticator) Authenticate(request *goyave.Request, user interface{}) error
• type JWTController
  • func NewJWTController(model interface{}) *JWTController
  • func (c *JWTController) Login(response *goyave.Response, request *goyave.Request)
• type TokenFunc
• type Unauthorizer

Functions

func ConfigBasicAuth

func ConfigBasicAuth() goyave.Middleware

ConfigBasicAuth create a new authenticator middleware for config-based Basic authentication. On auth success, the request user is set to a "BasicUser". The user is authenticated if the "auth.basic.username" and "auth.basic.password" config entries match the request's Authorization header.

func GenerateToken

func GenerateToken(username interface{}) (string, error)

GenerateToken generate a new JWT. The token is created using the HMAC SHA256 method and signed using the `auth.jwt.secret` config entry. The token is set to expire in the amount of seconds defined by the `auth.jwt.expiry` config entry.

The generated token will contain the following claims: - `sub`: has the value of the `id` parameter - `nbf`: "Not before", the current timestamp is used - `exp`: "Expiry", the current timestamp plus the `auth.jwt.expiry` config entry.

func GenerateTokenWithClaims

func GenerateTokenWithClaims(claims jwt.MapClaims, signingMethod jwt.SigningMethod) (string, error)

GenerateTokenWithClaims generates a new JWT with custom claims. The token is set to expire in the amount of seconds defined by the `auth.jwt.expiry` config entry. Depending on the given signing method, the following configuration entries will be used:

• RSA: `auth.jwt.rsa.private`: path to the private PEM-encoded RSA key. `auth.jwt.rsa.password`: optional password for the private RSA key.
• ECDSA: `auth.jwt.ecdsa.private`: path to the private PEM-encoded ECDSA key.
• HMAC: `auth.jwt.secret`: HMAC secret

The generated token will also contain the following claims:

• `nbf`: "Not before", the current timestamp is used
• `exp`: "Expiry", the current timestamp plus the `auth.jwt.expiry` config entry.

`nbf` and `exp` can be overridden if they are set in the `claims` parameter.

func JWTRoutes

func JWTRoutes(router *goyave.Router, model interface{}) *goyave.Router

JWTRoutes create a "/auth" route group and registers the "POST /auth/login" validated route. Returns the new route group.

Validation rules are as follows:

• "username": required string
• "password": required string

The given model is used for username and password retrieval and for instantiating an authenticated request's user.

func Middleware

func Middleware(model interface{}, authenticator Authenticator) goyave.Middleware

Middleware create a new authenticator middleware to authenticate the given model using the given authenticator.

Types

type Authenticator

type Authenticator interface {

	// Authenticate fetch the user corresponding to the credentials
	// found in the given request and puts the result in the given user pointer.
	// If no user can be authenticated, returns the error detailing why the
	// authentication failed. The error message is already localized.
	Authenticate(request *goyave.Request, user interface{}) error
}

Authenticator is an object in charge of authenticating a model.

type BasicAuthenticator

type BasicAuthenticator struct {

	// Optional defines if the authenticator allows requests that
	// don't provide credentials. Handlers should therefore check
	// if request.User is not nil before accessing it.
	Optional bool
}

BasicAuthenticator implementation of Authenticator with the Basic authentication method.

func (*BasicAuthenticator) Authenticate

func (a *BasicAuthenticator) Authenticate(request *goyave.Request, user interface{}) error

Authenticate fetch the user corresponding to the credentials found in the given request and puts the result in the given user pointer. If no user can be authenticated, returns an error.

The database request is executed based on the model name and the struct tags `auth:"username"` and `auth:"password"`. The password is checked using bcrypt. The username field should unique.

type BasicUser

type BasicUser struct {
	Name string
}

BasicUser a simple user for config-based basic authentication.

type Column

type Column struct {
	Field *reflect.StructField
	Name  string
}

Column matches a column name with a struct field.

func FindColumns

func FindColumns(strct interface{}, fields ...string) []*Column

FindColumns in given struct. A field matches if it has a "auth" tag with the given value. Returns a slice of found fields, ordered as the input "fields" slice. If the nth field is not found, the nth value of the returned slice will be nil.

Promoted fields are matched as well.

Given the following struct and "username", "notatag", "password":

 type TestUser struct {
		gorm.Model
		Name     string `gorm:"type:varchar(100)"`
		Password string `gorm:"type:varchar(100)" auth:"password"`
		Email    string `gorm:"type:varchar(100);uniqueIndex" auth:"username"`
 }

The result will be the "Email" field, "nil" and the "Password" field.

type JWTAuthenticator

type JWTAuthenticator struct {

	// SigningMethod expected by this authenticator when parsing JWT.
	// Defaults to HMAC.
	SigningMethod jwt.SigningMethod

	// ClaimName the name of the claim used to retrieve the user.
	// Defaults to "sub".
	ClaimName string

	// Optional defines if the authenticator allows requests that
	// don't provide credentials. Handlers should therefore check
	// if request.User is not nil before accessing it.
	Optional bool
}

JWTAuthenticator implementation of Authenticator using a JSON Web Token.

func (*JWTAuthenticator) Authenticate

func (a *JWTAuthenticator) Authenticate(request *goyave.Request, user interface{}) error

Authenticate fetch the user corresponding to the token found in the given request and puts the result in the given user pointer. If no user can be authenticated, returns an error.

The database request is executed based on the model name and the struct tag `auth:"username"`.

If the token is valid and has claims, those claims will be added to `request.Extra` with the key "jwt_claims".

This implementation is a JWT-based authentication using HMAC SHA256, supporting only one active token.

type JWTController

type JWTController struct {

	// SigningMethod used to generate the token using the default
	// TokenFunc. By default, uses `jwt.SigningMethodHS256`.
	SigningMethod jwt.SigningMethod

	TokenFunc TokenFunc

	// UsernameField the name of the request's body field
	// used as username in the authentication process
	UsernameField string
	// PasswordField the name of the request's body field
	// used as password in the authentication process
	PasswordField string
	// contains filtered or unexported fields
}

JWTController a controller for JWT-based authentication, using HMAC SHA256. Its model fields are used for username and password retrieval.

func NewJWTController

func NewJWTController(model interface{}) *JWTController

NewJWTController create a new JWTController that will be using the given model for login and token generation.

func (*JWTController) Login

func (c *JWTController) Login(response *goyave.Response, request *goyave.Request)

Login POST handler for token-based authentication. Creates a new token for the user authenticated with the body fields defined in the controller and returns it as a response. (the "username" and "password" body field are used by default)

The database request is executed based on the model name and the struct tags `auth:"username"` and `auth:"password"`. The password is checked using bcrypt. The username field should unique.

type TokenFunc

type TokenFunc func(request *goyave.Request, user interface{}) (string, error)

TokenFunc is the function used by JWTController to generate tokens during login process.

type Unauthorizer

type Unauthorizer interface {
	OnUnauthorized(*goyave.Response, *goyave.Request, error)
}

Unauthorizer can be implemented by Authenticators to define custom behavior when authentication fails.