Documentation
¶
Index ¶
- Constants
- Variables
- func Authenticate(opts ...AuthOption) (_ gin.HandlerFunc, err error)
- func Authorize(permissions ...string) gin.HandlerFunc
- func ClearAuthCookies(c *gin.Context, domain string)
- func ContextFromRequest(c *gin.Context) (ctx context.Context, err error)
- func DoubleCookie() gin.HandlerFunc
- func GenerateCSRFToken() (_ string, err error)
- func GetAccessToken(c *gin.Context) (tks string, err error)
- func GetClaims(c *gin.Context) (*tokens.Claims, error)
- func GetRefreshToken(c *gin.Context) (tks string, err error)
- func RateLimiter(conf config.RateLimitConfig) gin.HandlerFunc
- func Reauthenticate(conf AuthOptions, validator tokens.Validator) func(c *gin.Context) (string, error)
- func SetAuthCookies(c *gin.Context, accessToken, refreshToken, domain string) (err error)
- func SetDoubleCookieToken(c *gin.Context, domain string, expires time.Time) error
- func TaskContext(c *gin.Context) (ctx context.Context)
- type AuthOption
- func WithAudience(audience string) AuthOption
- func WithAuthOptions(opts AuthOptions) AuthOption
- func WithContext(ctx context.Context) AuthOption
- func WithIssuer(issuer string) AuthOption
- func WithJWKSEndpoint(url string) AuthOption
- func WithMinRefreshInterval(interval time.Duration) AuthOption
- func WithReauthenticator(reauth api.Reauthenticator) AuthOption
- func WithValidator(validator tokens.Validator) AuthOption
- type AuthOptions
- type IPRateLimiter
Constants ¶
const ( ContextUserClaims = "user_claims" ContextAccessToken = "access_token" ContextRequestID = "request_id" DefaultKeysURL = "https://auth.rotational.app/.well-known/jwks.json" DefaultAudience = "https://rotational.app" DefaultIssuer = "https://auth.rotational.app" DefaultMinRefreshInterval = 5 * time.Minute DefaultCookieDomain = "rotational.app" AccessTokenCookie = "access_token" RefreshTokenCookie = "refresh_token" )
const ( CSRFCookie = "csrf_token" CSRFReferenceCookie = "csrf_reference_token" CSRFHeader = "X-CSRF-TOKEN" )
Parameters and headers for double-cookie submit CSRF protection
const ( HeaderRateLimitLimit = "X-RateLimit-Limit" HeaderRateLimitRemaining = "X-RateLimit-Remaining" HeaderRateLimitReset = "X-RateLimit-Reset" )
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") 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") ErrIncompleteUser = errors.New("user is missing required fields") ErrUnverifiedUser = errors.New("user is not verified") ErrCSRFVerification = errors.New("csrf verification failed for request") ErrParseBearer = errors.New("could not parse Bearer token from Authorization header") ErrNoAuthorization = errors.New("no authorization header in request") ErrNoRequest = errors.New("no request found on the context") ErrRateLimit = errors.New("rate limit reached: too many requests") ErrNoRefreshToken = errors.New("no refresh token available on request") ErrRefreshDisabled = errors.New("reauthentication with refresh tokens disabled") )
Functions ¶
func Authenticate ¶
func Authenticate(opts ...AuthOption) (_ gin.HandlerFunc, err error)
Authenticate middleware ensures that the request has a valid Bearer JWT in the Authenticate header of the request otherwise it stops processing of the request and returns a 401 unauthorized error. A valid Bearer JWT means that the access token is supplied as the Bearer token, it is unexpired, and it was issued by Quarterdeck by checking with the Quarterdeck public keys.
In order to perform authorization, this middleware fetches public JSON Web Key Sets (JWKS) from the authorizing Quarterdeck server and then caches them according to the Cache-Control or Expires headers in the response. As Quarterdeck keys are rotated, the cache must refresh the public keys in a background routine in order to correctly authorize incoming JWT tokens. Users can control how the JWKS are fetched and cached using AuthOptions (which are particularly helpful for tests).
func Authorize ¶
func Authorize(permissions ...string) gin.HandlerFunc
Authorize is a middleware that requires specific permissions in an authenticated user's claims. If the request is unauthenticated the middleware returns a 401 response. If the claims have insufficient permissions the middleware returns a 403. The Authorize middleware must be chained following the Authenticate middleware.
func ClearAuthCookies ¶ added in v0.11.0
ClearAuthCookies is a helper function to clear authentication cookies on a gin request to effectively log out a user.
func ContextFromRequest ¶
ContextFromRequest creates a context from the gin request context, copying fields that may be required for forwarded requests. This method should be called by handlers which need to forward requests to other services and need to preserve data from the original request such as the user's credentials.
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 GetAccessToken ¶
GetAccessToken retrieves the bearer token from the authorization header and parses it to return only the JWT access token component of the header. Alternatively, if the authorization header is not present, then the token is fetched from cookies. If the header is missing or the token is not available, an error is returned.
NOTE: the authorization header takes precedence over access tokens in cookies.
func GetClaims ¶
GetClaims fetches and parses Quarterdeck claims from the gin context. Returns an error if no claims exist on the context; panics if the claims are not the correct type -- however the panic should be recovered by middleware.
func GetRefreshToken ¶ added in v0.10.0
GetRefreshToken retrieves the refresh token from the cookies in the request. If the cookie is not present or expired then an error is returned.
func RateLimiter ¶ added in v0.5.2
func RateLimiter(conf config.RateLimitConfig) gin.HandlerFunc
func Reauthenticate ¶ added in v0.10.0
func Reauthenticate(conf AuthOptions, validator tokens.Validator) func(c *gin.Context) (string, error)
Reauthenticate is a middleware helper that can use refresh tokens in the gin context to obtain a new access token. If it is unable to obtain a new valid access token, then an error is returned and processing should stop.
func SetAuthCookies ¶ added in v0.10.0
SetAuthCookies is a helper function to set authentication cookies on a gin request. The access token cookie (access_token) is an http only cookie that expires when the access token expires. The refresh token cookie is not an http only cookie (it can be accessed by client-side scripts) and it expires when the refresh token expires. Both cookies require https and will not be set (silently) over http connections.
func SetDoubleCookieToken ¶
SetDoubleCookieToken is a helper function to set cookies on a gin request.
func TaskContext ¶ added in v0.7.0
TaskContext creates a cloned context specifically for tasks that services need to perform outside of the request context. For example, tasks that interact with Quarterdeck need to have access to user credentials but the original context cannot be used because it will be cancelled when the original request completes.
Types ¶
type AuthOption ¶
type AuthOption func(opts *AuthOptions)
AuthOption allows users to optionally supply configuration to the Authorization middleware.
func WithAudience ¶
func WithAudience(audience string) AuthOption
WithAudience allows the user to specify an alternative audience.
func WithAuthOptions ¶
func WithAuthOptions(opts AuthOptions) AuthOption
WithAuthOptions allows the user to update the default auth options with an auth options struct to set many options values at once. Zero values are ignored, so if using this option, the defaults will still be preserved if not set on the input.
func WithContext ¶
func WithContext(ctx context.Context) AuthOption
WithContext allows the user to specify an external, cancelable context to control the background refresh behavior of the JWKS cache.
func WithIssuer ¶
func WithIssuer(issuer string) AuthOption
WithIssuer allows the user to specify an alternative issuer.
func WithJWKSEndpoint ¶
func WithJWKSEndpoint(url string) AuthOption
WithJWKSEndpoint allows the user to specify an alternative endpoint to fetch the JWKS public keys from. This is useful for testing or for different environments.
func WithMinRefreshInterval ¶
func WithMinRefreshInterval(interval time.Duration) AuthOption
WithMinRefreshInterval allows the user to specify an alternative minimum duration between cache refreshes to control refresh behavior for the JWKS public keys.
func WithReauthenticator ¶ added in v0.10.0
func WithReauthenticator(reauth api.Reauthenticator) AuthOption
WithReauthenticator allows the user to specify a reauthenticator to the auth middleware.
func WithValidator ¶
func WithValidator(validator tokens.Validator) AuthOption
WithValidator allows the user to specify an alternative validator to the auth middleware. This is particularly useful for testing authentication.
type AuthOptions ¶
type AuthOptions struct {
KeysURL string // The URL endpoint to the JWKS public keys on the Quarterdeck server
Audience string // The audience to verify on tokens
Issuer string // The issuer to verify on tokens
MinRefreshInterval time.Duration // Minimum amount of time the JWKS public keys are cached
CookieDomain string // The domain to use for auth cookies
Context context.Context // The context object to control the lifecycle of the background fetch routine
// contains filtered or unexported fields
}
AuthOptions is constructed from variadic AuthOption arguments with reasonable defaults.
func NewAuthOptions ¶
func NewAuthOptions(opts ...AuthOption) (conf AuthOptions)
NewAuthOptions creates an AuthOptions object with reasonable defaults and any user supplied input from the AuthOption variadic arguments.
type IPRateLimiter ¶ added in v0.5.2
IPRateLimiter is an IP address based limiter that controls how frequently requests can be made from a single IP address. limit: represents the number of tokens that can be added to the token bucket per second burst: maximum number of tokens/requests in a "token bucket" and is initially full each request consumes tokens from the token bucket and if the bucket is empty when the request is made, the request is rejected
func NewIPRateLimiter ¶ added in v0.5.2
func NewIPRateLimiter(limit rate.Limit, burst int) *IPRateLimiter
func (*IPRateLimiter) AddIP ¶ added in v0.5.2
func (i *IPRateLimiter) AddIP(ip string) *rate.Limiter
AddIP creates a new rate limiter and adds it to the ips map, using the IP address as the key
func (*IPRateLimiter) GetLimiter ¶ added in v0.5.2
func (i *IPRateLimiter) GetLimiter(ip string) *rate.Limiter
GetLimiter returns the rate limiter for the provided IP address if it exists. Otherwise calls AddIP to add IP address to the map
Source Files