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