auth

Documentation

Index

• Constants
• Variables
• func Authenticate(conf config.AuthConfig, options ...jwks.ProviderOption) (_ gin.HandlerFunc, err error)
• func Authorize(permissions ...string) gin.HandlerFunc
• func DoubleCookie() gin.HandlerFunc
• func GenerateCSRFToken() (_ string, err error)
• func GetRegisteredClaims(c *gin.Context) (*validator.RegisteredClaims, error)
• func GetUserInfo(c *gin.Context) (*management.User, error)
• func NewClaims() validator.CustomClaims
• func SetDoubleCookieToken(c *gin.Context, domain string, expires time.Time) error
• func UserInfo(conf config.AuthConfig) (_ gin.HandlerFunc, err error)
• func WithHTTPClient(client *http.Client) jwks.ProviderOption
• type AppMetadata
  • func (meta *AppMetadata) Dump() (appdata map[string]interface{}, err error)
  • func (meta *AppMetadata) Load(appdata map[string]interface{}) (err error)
• type Claims
  • func GetClaims(c *gin.Context) (*Claims, error)
  • func (c Claims) HasAllPermissions(requiredPermissions ...string) bool
  • func (c Claims) HasPermission(requiredPermission string) bool
  • func (c Claims) HasScope(requiredScope string) bool
  • func (c Claims) IsAnonymous() bool
  • func (c Claims) Validate(ctx context.Context) error
• type VASPs

Constants

const (
	ScopeAnonymous          = "anonymous"
	ContextUserInfo         = "auth0_user_info"
	ContextBFFClaims        = "auth0_bff_claims"
	ContextRegisteredClaims = "auth0_registered_claims"
)

const (
	CSRFCookie          = "csrf_token"
	CSRFReferenceCookie = "csrf_reference_token"
	CSRFHeader          = "X-CSRF-TOKEN"
)

Parameters and headers for double-cookie submit CSRF protection

Variables

var (
	ErrUnauthenticated  = errors.New("request is unauthenticated")
	ErrNoClaims         = errors.New("no claims found on the request context")
	ErrNoUserInfo       = errors.New("no user info found on the request context")
	ErrInvalidAuthToken = errors.New("invalid authorization token")
	ErrNoAuthorization  = errors.New("could not authorize request")
	ErrAuthRequired     = errors.New("this endpoint requires authentication")
	ErrNoPermission     = errors.New("user does not have permission to perform this operation")
	ErrNoAuthUser       = errors.New("could not identify authenticated user in request")
	ErrNoAuthUserData   = errors.New("could not retrieve user data")
	ErrCSRFVerification = errors.New("csrf verification failed for request")
)

var AnonymousClaims = Claims{Scope: ScopeAnonymous, Permissions: nil}

AnonymousClaims are used to identify unauthenticated requests that have no permissions.

Functions

func Authenticate

func Authenticate(conf config.AuthConfig, options ...jwks.ProviderOption) (_ gin.HandlerFunc, err error)

Authenticate is a middleware that will parse and validate any Auth0 token provided in the header of the request and will add the claims to the request context for downstream processing. If no JWT token is present in the header, this middleware will mark the request as unauthenticated but it does not perform any authorization. If the JWT token is invalid this middleware will return a 403 Forbidden response.

func Authorize

func Authorize(permissions ...string) gin.HandlerFunc

Authorize is a middleware that requires specific permissions in an authenticated user's claims. If those permissions do not match or the request is unauthenticated the middleware returns a 401 Unauthorized response. The Authorize middleware must follow the Authenticate middleware.

func DoubleCookie

func DoubleCookie() gin.HandlerFunc

DoubleCookie is a Cross-Site Request Forgery (CSR/XSRF) protection middleware that checks the presence of an X-CSRF-TOKEN header containing a cryptographically random token that matches a token contained in the CSRF-TOKEN cookie in the request. Because of the same-origin poicy, an attacker cannot access the cookies or scripts of the safe site, therefore the X-CSRF-TOKEN header cannot be forged, and if it is omitted because it is being re-posted by an attacker site then the request will be rejected with a 403 error. Note that this protection requires TLS to prevent MITM.

func GenerateCSRFToken

func GenerateCSRFToken() (_ string, err error)

func GetRegisteredClaims

func GetRegisteredClaims(c *gin.Context) (*validator.RegisteredClaims, error)

GetRegisteredClaims fetches and parses the access token claims from the gin context. Returns an error if no claims exist on the context rather than returning zero-valued claims. Panics if the claims are an incorrect type, but should be recovered.

func GetUserInfo

func GetUserInfo(c *gin.Context) (*management.User, error)

GetUserInfo fetches the user info from the gin context. Returns an error if no user exists on the context or if the user value is nil. Panics if user is incorrect type.

func NewClaims

func NewClaims() validator.CustomClaims

NewClaims implements the validator custom claims initializer interface.

func SetDoubleCookieToken

func SetDoubleCookieToken(c *gin.Context, domain string, expires time.Time) error

SetDoubleCookieToken is a helper function to set cookies on a gin request.

func UserInfo

func UserInfo(conf config.AuthConfig) (_ gin.HandlerFunc, err error)

UserInfo is a middleware that requires an authenticated user's claims, it then fetches the user profile including app_data from Auth0 and adds them to the Gin context. This middleware is primarily used for endpoints that manage the user state, not for endpoints that simply need access to resources or permissions (those should be added to the claims to prevent calls to Auth0 on every RPC). If the user is not authenticated before this step, a 401 is returned.

func WithHTTPClient

func WithHTTPClient(client *http.Client) jwks.ProviderOption

WithHTTPClient configures the authentication provider to use the specified client. This is used in tests to configure the client to use a localhost TLS httptest server. This option should NOT be used in production.

NOTE: this has been added to the jwks code but not tagged yet. Once the library gets updated we can remove this function and use their implementation. https://github.com/auth0/go-jwt-middleware/blob/master/jwks/provider.go#L55

Types

type AppMetadata

type AppMetadata struct {
	OrgID string `json:"orgid"`
	VASPs VASPs  `json:"vasps"`
}

AppMetadata makes it easier to serialize and deserialize JSON from the auth0 app_metadata assigned to the user by the BFF (and ensures the data is structured).

func (*AppMetadata) Dump

func (meta *AppMetadata) Dump() (appdata map[string]interface{}, err error)

func (*AppMetadata) Load

func (meta *AppMetadata) Load(appdata map[string]interface{}) (err error)

type Claims

type Claims struct {
	Scope       string   `json:"scope"`
	Permissions []string `json:"permissions"`
	OrgID       string   `json:"https://vaspdirectory.net/orgid"`
	VASPs       VASPs    `json:"https://vaspdirectory.net/vasps"`
	Email       string   `json:"https://vaspdirectory.net/email"`
}

Claims extracts custom data from the JWT token provided by Auth0

func GetClaims

func GetClaims(c *gin.Context) (*Claims, error)

GetClaims fetches and parses the BFF claims from the gin context. Returns an error if no claims exist on the context rather than returning anonymous claims. Panics if the claims are an incorrect type, but the panic should be recovered by middleware.

func (Claims) HasAllPermissions

func (c Claims) HasAllPermissions(requiredPermissions ...string) bool

HasAllPermissions checks if all specified permissions are in the claims.

func (Claims) HasPermission

func (c Claims) HasPermission(requiredPermission string) bool

HasPermission checks if the claims contain the specified permission.

func (Claims) HasScope

func (c Claims) HasScope(requiredScope string) bool

HasScope checks if the claims contain the specified scope.

func (Claims) IsAnonymous

func (c Claims) IsAnonymous() bool

IsAnonymous returns true if the claims refer to an anonymous user

func (Claims) Validate

func (c Claims) Validate(ctx context.Context) error

Validate implements the validator.CustomClaims interface for Auth0 parsing. Claims can have empty scope (e.g. no permissions) and no associated VASP.

type VASPs

type VASPs struct {
	MainNet string `json:"mainnet"`
	TestNet string `json:"testnet"`
}