http

Documentation

Overview

Package http provides HTTP utilities and handler middleware.

Index

• func RequireHeaderAuthorization(opts ...AuthorizationOption) func(http.Handler) http.Handler
• func WithHeaderAuthorization(opts ...AuthorizationOption) func(http.Handler) http.Handler
• type AuthorizationOption
  • func AuthorizationFailureHandler(h http.Handler) AuthorizationOption
  • func AuthorizationJWTExtractor(extractor func(r *http.Request) string) AuthorizationOption
  • func AuthorizedParty(handler func(string) bool) AuthorizationOption
  • func AuthorizedPartyMatches(parties ...string) AuthorizationOption
  • func Clock(c clerk.Clock) AuthorizationOption
  • func CustomClaimsConstructor(constructor func(context.Context) any) AuthorizationOption
  • func JSONWebKey(key string) AuthorizationOption
  • func JWKSClient(client *jwks.Client) AuthorizationOption
  • func Leeway(leeway time.Duration) AuthorizationOption
  • func ProxyURL(proxyURL string) AuthorizationOption
  • func Satellite(isSatellite bool) AuthorizationOption
• type AuthorizationParams

Functions

func RequireHeaderAuthorization

func RequireHeaderAuthorization(opts ...AuthorizationOption) func(http.Handler) http.Handler

RequireHeaderAuthorization will respond with HTTP 403 Forbidden if the Authorization header does not contain a valid session token.

func WithHeaderAuthorization

func WithHeaderAuthorization(opts ...AuthorizationOption) func(http.Handler) http.Handler

WithHeaderAuthorization checks the Authorization request header for a valid Clerk authorization JWT. The token is parsed and verified and the active session claims are written to the http.Request context. The middleware uses Bearer authentication, so the Authorization header is expected to have the following format: Authorization: Bearer <token>

Types

type AuthorizationOption

type AuthorizationOption func(*AuthorizationParams) error

AuthorizationOption is a functional parameter for configuring authorization options.

func AuthorizationFailureHandler

func AuthorizationFailureHandler(h http.Handler) AuthorizationOption

AuthorizationFailureHandler allows to provide a handler that writes the response in case of authorization failures. The default behavior is a response with an empty body and 401 Unauthorized status.

func AuthorizationJWTExtractor

func AuthorizationJWTExtractor(extractor func(r *http.Request) string) AuthorizationOption

AuthorizationJWTExtractor allows to provide a custom function to extract the JWT from the http.Request.

func AuthorizedParty

func AuthorizedParty(handler func(string) bool) AuthorizationOption

AuthorizedParty allows to provide a handler that accepts the 'azp' claim. The handler can be used to perform validations on the azp claim and should return false to indicate that something is wrong.

func AuthorizedPartyMatches

func AuthorizedPartyMatches(parties ...string) AuthorizationOption

AuthorizedPartyMatches registers a handler that checks that the 'azp' claim's value is included in the provided parties.

func Clock

func Clock(c clerk.Clock) AuthorizationOption

Clock allows to pass a clock implementation that will be the authority for time related operations. You can use a custom clock for testing purposes, or to eliminate clock skew if your code runs on different servers.

func CustomClaimsConstructor

func CustomClaimsConstructor(constructor func(context.Context) any) AuthorizationOption

CustomClaimsConstructor allows to pass a constructor function which returns a pointer to a type (struct) to hold custom token claims. The instance of the custom claims type will be then made available through the clerk.SessionClaims struct.

// Define a type to describe the custom claims.
type MyCustomClaims struct {
	ACustomClaim string `json:"a_custom_claim"`
}

// In your HTTP server mux, configure the middleware with
// the custom claims constructor.
WithHeaderAuthorization(CustomClaimsConstructor(func(_ context.Context) any {
	return &MyCustomClaims{}
})

// In the HTTP handler, access the active session claims. The
// custom claims are available in the SessionClaims.Custom field.
sessionClaims, ok := clerk.SessionClaimsFromContext(r.Context())
customClaims, ok := sessionClaims.Custom.(*MyCustomClaims)

func JSONWebKey

func JSONWebKey(key string) AuthorizationOption

JSONWebKey allows to provide a custom JSON Web Key (JWK) based on which the authorization JWT will be verified. When verifying the authorization JWT without a custom key, the JWK will be fetched from the Clerk API and cached for one hour, then the JWK will be fetched again from the Clerk API. Passing a custom JSON Web Key means that no request to fetch JSON web keys will be made. It's the caller's responsibility to refresh the JWK when keys are rolled.

func JWKSClient

func JWKSClient(client *jwks.Client) AuthorizationOption

JWKSClient allows to provide a custom jwks.Client that will be used when fetching the JSON Web Key Set with which the JWT will be verified. The JSONWebKey option takes precedence. If a web key is already provided through the JSONWebKey option, the JWKS client will not be used at all.

func Leeway

func Leeway(leeway time.Duration) AuthorizationOption

Leeway allows to set a custom leeway when comparing time values for JWT verification. The leeway gives some extra time to the token. That is, if the token is expired, it will still be accepted for 'leeway' amount of time. This option accomodates for clock skew.

func ProxyURL

func ProxyURL(proxyURL string) AuthorizationOption

ProxyURL can be used to set the URL that proxies the Clerk Frontend API. Useful for proxy based setups. See https://clerk.com/docs/advanced-usage/using-proxies

func Satellite

func Satellite(isSatellite bool) AuthorizationOption

Satellite can be used to signify that the authorization happens on a satellite domain. See https://clerk.com/docs/advanced-usage/satellite-domains

type AuthorizationParams

type AuthorizationParams struct {
	jwt.VerifyParams
	// AuthorizationFailureHandler gets executed when request authorization
	// fails. Pass a custom http.Handler to control the http.Response for
	// invalid authorization. The default is a Response with an empty body
	// and 401 Unauthorized status.
	AuthorizationFailureHandler http.Handler
	// JWKSClient is the jwks.Client that will be used to fetch the
	// JSON Web Key Set. A default client will be used if none is
	// provided.
	JWKSClient *jwks.Client
	// AuthorizationJWTExtractor is a custom function to extract the Clerk
	// authorization JWT from the http.Request.
	AuthorizationJWTExtractor func(r *http.Request) string
}