vendor/github.com/go-kit/kit/auth/jwt/README.md

   1 # package auth/jwt
   2
   3 `package auth/jwt` provides a set of interfaces for service authorization
   4 through [JSON Web Tokens](https://jwt.io/).
   5
   6 ## Usage
   7
   8 NewParser takes a key function and an expected signing method and returns an
   9 `endpoint.Middleware`. The middleware will parse a token passed into the
  10 context via the `jwt.JWTTokenContextKey`. If the token is valid, any claims
  11 will be added to the context via the `jwt.JWTClaimsContextKey`.
  12
  13 ```go
  14 import (
  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
  21 func 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
  31 NewSigner takes a JWT key ID header, the signing key, signing method, and a
  32 claims object. It returns an `endpoint.Middleware`. The middleware will build
  33 the token string and add it to the context via the `jwt.JWTTokenContextKey`.
  34
  35 ```go
  36 import (
  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
  43 func 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
  57 In order for the parser and the signer to work, the authorization headers need
  58 to be passed between the request and the context. `ToHTTPContext()`,
  59 `FromHTTPContext()`, `ToGRPCContext()`, and `FromGRPCContext()` are given as
  60 helpers to do this. These functions implement the correlating transport's
  61 RequestFunc interface and can be passed as ClientBefore or ServerBefore
  62 options.
  63
  64 Example of use in a client:
  65
  66 ```go
  67 import (
  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
  75 func main() {
  76
  77         options := []httptransport.ClientOption{}
  78         var exampleEndpoint endpoint.Endpoint
  79         {
  80                 exampleEndpoint = grpctransport.NewClient(..., grpctransport.ClientBefore(jwt.FromGRPCContext())).Endpoint()
  81                 exampleEndpoint = jwt.NewSigner(
  82                         "kid-header",
  83                         []byte("SigningString"),
  84                         stdjwt.SigningMethodHS256,
  85                         jwt.Claims{},
  86                 )(exampleEndpoint)
  87         }
  88 }
  89 ```
  90
  91 Example of use in a server:
  92
  93 ```go
  94 import (
  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
 102 func 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.ToGRPCContext()))...,
 112                 ),
 113                 getUser: grpctransport.NewServer(
 114                         ctx,
 115                         endpoints.GetUserEndpoint,
 116                         DecodeGRPCGetUserRequest,
 117                         EncodeGRPCGetUserResponse,
 118                         options...,
 119                 ),
 120         }
 121 }
 122 ```