README.md
1# package auth/jwt
2
3`package auth/jwt` provides a set of interfaces for service authorization
4through [JSON Web Tokens](https://jwt.io/).
5
6## Usage
7
8NewParser takes a key function and an expected signing method and returns an
9`endpoint.Middleware`. The middleware will parse a token passed into the
10context via the `jwt.JWTTokenContextKey`. If the token is valid, any claims
11will be added to the context via the `jwt.JWTClaimsContextKey`.
12
13```go
14import (
15 stdjwt "github.com/dgrijalva/jwt-go"
16
17 "github.com/go-kit/kit/auth/jwt"
18 "github.com/go-kit/kit/endpoint"
19)
20
21func main() {
22 var exampleEndpoint endpoint.Endpoint
23 {
24 kf := func(token *stdjwt.Token) (interface{}, error) { return []byte("SigningString"), nil }
25 exampleEndpoint = MakeExampleEndpoint(service)
26 exampleEndpoint = jwt.NewParser(kf, stdjwt.SigningMethodHS256, jwt.StandardClaimsFactory)(exampleEndpoint)
27 }
28}
29```
30
31NewSigner takes a JWT key ID header, the signing key, signing method, and a
32claims object. It returns an `endpoint.Middleware`. The middleware will build
33the token string and add it to the context via the `jwt.JWTTokenContextKey`.
34
35```go
36import (
37 stdjwt "github.com/dgrijalva/jwt-go"
38
39 "github.com/go-kit/kit/auth/jwt"
40 "github.com/go-kit/kit/endpoint"
41)
42
43func main() {
44 var exampleEndpoint endpoint.Endpoint
45 {
46 exampleEndpoint = grpctransport.NewClient(...).Endpoint()
47 exampleEndpoint = jwt.NewSigner(
48 "kid-header",
49 []byte("SigningString"),
50 stdjwt.SigningMethodHS256,
51 jwt.Claims{},
52 )(exampleEndpoint)
53 }
54}
55```
56
57In order for the parser and the signer to work, the authorization headers need
58to be passed between the request and the context. `HTTPToContext()`,
59`ContextToHTTP()`, `GRPCToContext()`, and `ContextToGRPC()` are given as
60helpers to do this. These functions implement the correlating transport's
61RequestFunc interface and can be passed as ClientBefore or ServerBefore
62options.
63
64Example of use in a client:
65
66```go
67import (
68 stdjwt "github.com/dgrijalva/jwt-go"
69
70 grpctransport "github.com/go-kit/kit/transport/grpc"
71 "github.com/go-kit/kit/auth/jwt"
72 "github.com/go-kit/kit/endpoint"
73)
74
75func main() {
76
77 options := []httptransport.ClientOption{}
78 var exampleEndpoint endpoint.Endpoint
79 {
80 exampleEndpoint = grpctransport.NewClient(..., grpctransport.ClientBefore(jwt.ContextToGRPC())).Endpoint()
81 exampleEndpoint = jwt.NewSigner(
82 "kid-header",
83 []byte("SigningString"),
84 stdjwt.SigningMethodHS256,
85 jwt.Claims{},
86 )(exampleEndpoint)
87 }
88}
89```
90
91Example of use in a server:
92
93```go
94import (
95 "context"
96
97 "github.com/go-kit/kit/auth/jwt"
98 "github.com/go-kit/kit/log"
99 grpctransport "github.com/go-kit/kit/transport/grpc"
100)
101
102func MakeGRPCServer(ctx context.Context, endpoints Endpoints, logger log.Logger) pb.ExampleServer {
103 options := []grpctransport.ServerOption{grpctransport.ServerErrorLogger(logger)}
104
105 return &grpcServer{
106 createUser: grpctransport.NewServer(
107 ctx,
108 endpoints.CreateUserEndpoint,
109 DecodeGRPCCreateUserRequest,
110 EncodeGRPCCreateUserResponse,
111 append(options, grpctransport.ServerBefore(jwt.GRPCToContext()))...,
112 ),
113 getUser: grpctransport.NewServer(
114 ctx,
115 endpoints.GetUserEndpoint,
116 DecodeGRPCGetUserRequest,
117 EncodeGRPCGetUserResponse,
118 options...,
119 ),
120 }
121}
122```
123