From 576dd15090690356676771a71db684284e8a5f75 Mon Sep 17 00:00:00 2001 From: Agis Anastasopoulos Date: Tue, 17 Oct 2023 13:46:35 +0300 Subject: [PATCH] docs: Deprecate the old middlewares WithSessionV2/RequireSessionV2 are for quite some time the de-facto way to use Clerk. Therefore, deprecate WithSession and update examples to use WithSessionV2 instead. Resolves #154 --- README.md | 24 +++++++----------------- clerk/middleware.go | 2 ++ clerk/middleware_v2.go | 6 +++--- examples/middleware/main.go | 14 +++++++++----- 4 files changed, 21 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 9b7911a0..818c8442 100644 --- a/README.md +++ b/README.md @@ -66,34 +66,24 @@ For more examples on how to use the client, refer to the [examples](https://gith ## Middleware -In addition to the API operations, the SDK also provides a middleware that can be used to inject the active session into the request's context. -The Clerk middleware expects a `clerk.Client` and resolves the active session using the incoming session cookie. +The SDK provides a middleware, [`WithSessionV2`](https://pkg.go.dev/github.com/clerkinc/clerk-sdk-go/v2/clerk#WithSessionV2), that injects the active session into the request's context. -The active session object will be added in the request's context using the key `clerk.ActiveSession`. +The active session's claims can then be fetched using [`SessionFromContext`](https://pkg.go.dev/github.com/clerkinc/clerk-sdk-go/v2/clerk#SessionFromContext). ```go mux := http.NewServeMux() -injectActiveSession := clerk.WithSession(client) +injectActiveSession := clerk.WithSessionV2(client) mux.Handle("/your-endpoint", injectActiveSession(yourEndpointHandler)) ``` -For a full example of how to use the middleware, refer to -[this](https://github.com/clerkinc/clerk-sdk-go/tree/main/examples/middleware). +Additionally, there's [`RequireSessionV2`](https://pkg.go.dev/github.com/clerkinc/clerk-sdk-go/v2/clerk#RequireSessionV2) that will halt the request and respond with 403 if the user is not authenticated. This can be used to restrict access to certain routes unless the user is authenticated. -### Auth v2 - -If you're using the newly-introduced [Auth v2](https://clerk.com/docs/upgrade-guides/auth-v2) scheme, you'll have to use the -`clerk.WithSessionV2()` middleware, instead of `clerk.WithSession()`. - -Additionally, there's also `clerk.RequireSessionV2()` that will halt the request -and respond with 403 if the user is not authenticated. - -Finally, to retrieve the authenticated session's claims you can use -`clerk.SessionFromContext()`. +For more info on how to use the middleware, refer to the +[example](https://github.com/clerkinc/clerk-sdk-go/tree/main/examples/middleware). ### Additional options -The new middlewares (`clerk.WithSessionV2()` & `clerk.RequireSessionV2()`) also support the ability to pass some additional options. +The middleware supports the following options: - clerk.WithAuthorizedParty() to set the authorized parties to check against the azp claim of the token - clerk.WithLeeway() to set a custom leeway that gives some extra time to the token to accommodate for clock skew diff --git a/clerk/middleware.go b/clerk/middleware.go index 8bedb2ee..47ade1ae 100644 --- a/clerk/middleware.go +++ b/clerk/middleware.go @@ -14,6 +14,8 @@ const ( // with other packages ) +// Deprecated: this middleware handles the old authentication scheme. Use +// WithSessionV2 instead. func WithSession(client Client) func(handler http.Handler) http.Handler { return func(next http.Handler) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { diff --git a/clerk/middleware_v2.go b/clerk/middleware_v2.go index dc2184e6..72145cfe 100644 --- a/clerk/middleware_v2.go +++ b/clerk/middleware_v2.go @@ -40,9 +40,9 @@ func SessionFromContext(ctx context.Context) (*SessionClaims, bool) { return c, ok } -// WithSessionV2 is the new middleware that supports Auth v2. If the session is -// authenticated, it adds the corresponding session claims found in the JWT to -// request's context. +// WithSessionV2 is the de-facto authentication middleware and should be used +// over WithSession. If the session is authenticated, it adds the corresponding +// session claims found in the JWT to request's context. func WithSessionV2(client Client, verifyTokenOptions ...VerifyTokenOption) func(handler http.Handler) http.Handler { return func(next http.Handler) http.Handler { return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { diff --git a/examples/middleware/main.go b/examples/middleware/main.go index eee39221..7866340a 100644 --- a/examples/middleware/main.go +++ b/examples/middleware/main.go @@ -10,14 +10,18 @@ import ( ) func returnActiveSession(w http.ResponseWriter, req *http.Request) { - session := req.Context().Value(clerk.ActiveSession) - jsonResp, _ := json.Marshal(session) + sessionClaims, ok := clerk.SessionFromContext(req.Context()) + if ok { + jsonResp, _ := json.Marshal(sessionClaims) + fmt.Fprintf(w, string(jsonResp)) + } else { + // handle non-authenticated user + } - fmt.Fprintf(w, string(jsonResp)) } func main() { - fmt.Print("Clerk API Key: ") + fmt.Print("Clerk secret key: ") var apiKey string fmt.Scanf("%s", &apiKey) @@ -27,7 +31,7 @@ func main() { } mux := http.NewServeMux() - injectActiveSession := clerk.WithSession(client) + injectActiveSession := clerk.WithSessionV2(client) mux.Handle("/session", injectActiveSession(http.HandlerFunc(returnActiveSession))) err = http.ListenAndServe(":3000", mux)