DOC.md 5.58 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148
# grpc_auth
`import "github.com/grpc-ecosystem/go-grpc-middleware/auth"`

* [Overview](#pkg-overview)
* [Imported Packages](#pkg-imports)
* [Index](#pkg-index)
* [Examples](#pkg-examples)

## <a name="pkg-overview">Overview</a>
`grpc_auth` a generic server-side auth middleware for gRPC.

### Server Side Auth Middleware
It allows for easy assertion of `:authorization` headers in gRPC calls, be it HTTP Basic auth, or
OAuth2 Bearer tokens.

The middleware takes a user-customizable `AuthFunc`, which can be customized to verify and extract
auth information from the request. The extracted information can be put in the `context.Context` of
handlers downstream for retrieval.

It also allows for per-service implementation overrides of `AuthFunc`. See `ServiceAuthFuncOverride`.

Please see examples for simple examples of use.

#### Example:

<details>
<summary>Click to expand code.</summary>

```go
package grpc_auth_test

import (
    "github.com/grpc-ecosystem/go-grpc-middleware/auth"
    "github.com/grpc-ecosystem/go-grpc-middleware/tags"
    "golang.org/x/net/context"
    "google.golang.org/grpc"
    "google.golang.org/grpc/codes"
)

var (
    cc *grpc.ClientConn
)

func parseToken(token string) (struct{}, error) {
    return struct{}{}, nil
}

func userClaimFromToken(struct{}) string {
    return "foobar"
}

// Simple example of server initialization code.
func Example_serverConfig() {
    exampleAuthFunc := func(ctx context.Context) (context.Context, error) {
        token, err := grpc_auth.AuthFromMD(ctx, "bearer")
        if err != nil {
            return nil, err
        }
        tokenInfo, err := parseToken(token)
        if err != nil {
            return nil, grpc.Errorf(codes.Unauthenticated, "invalid auth token: %v", err)
        }
        grpc_ctxtags.Extract(ctx).Set("auth.sub", userClaimFromToken(tokenInfo))
        newCtx := context.WithValue(ctx, "tokenInfo", tokenInfo)
        return newCtx, nil
    }

    _ = grpc.NewServer(
        grpc.StreamInterceptor(grpc_auth.StreamServerInterceptor(exampleAuthFunc)),
        grpc.UnaryInterceptor(grpc_auth.UnaryServerInterceptor(exampleAuthFunc)),
    )
}
```

</details>

## <a name="pkg-imports">Imported Packages</a>

- [github.com/grpc-ecosystem/go-grpc-middleware](./..)
- [github.com/grpc-ecosystem/go-grpc-middleware/util/metautils](./../util/metautils)
- [golang.org/x/net/context](https://godoc.org/golang.org/x/net/context)
- [google.golang.org/grpc](https://godoc.org/google.golang.org/grpc)
- [google.golang.org/grpc/codes](https://godoc.org/google.golang.org/grpc/codes)

## <a name="pkg-index">Index</a>
* [func AuthFromMD(ctx context.Context, expectedScheme string) (string, error)](#AuthFromMD)
* [func StreamServerInterceptor(authFunc AuthFunc) grpc.StreamServerInterceptor](#StreamServerInterceptor)
* [func UnaryServerInterceptor(authFunc AuthFunc) grpc.UnaryServerInterceptor](#UnaryServerInterceptor)
* [type AuthFunc](#AuthFunc)
* [type ServiceAuthFuncOverride](#ServiceAuthFuncOverride)

#### <a name="pkg-examples">Examples</a>
* [Package (ServerConfig)](#example__serverConfig)

#### <a name="pkg-files">Package files</a>
[auth.go](./auth.go) [doc.go](./doc.go) [metadata.go](./metadata.go) 

## <a name="AuthFromMD">func</a> [AuthFromMD](./metadata.go#L24)
``` go
func AuthFromMD(ctx context.Context, expectedScheme string) (string, error)
```
AuthFromMD is a helper function for extracting the :authorization header from the gRPC metadata of the request.

It expects the `:authorization` header to be of a certain scheme (e.g. `basic`, `bearer`), in a
case-insensitive format (see rfc2617, sec 1.2). If no such authorization is found, or the token
is of wrong scheme, an error with gRPC status `Unauthenticated` is returned.

## <a name="StreamServerInterceptor">func</a> [StreamServerInterceptor](./auth.go#L51)
``` go
func StreamServerInterceptor(authFunc AuthFunc) grpc.StreamServerInterceptor
```
StreamServerInterceptor returns a new unary server interceptors that performs per-request auth.

## <a name="UnaryServerInterceptor">func</a> [UnaryServerInterceptor](./auth.go#L34)
``` go
func UnaryServerInterceptor(authFunc AuthFunc) grpc.UnaryServerInterceptor
```
UnaryServerInterceptor returns a new unary server interceptors that performs per-request auth.

## <a name="AuthFunc">type</a> [AuthFunc](./auth.go#L23)
``` go
type AuthFunc func(ctx context.Context) (context.Context, error)
```
AuthFunc is the pluggable function that performs authentication.

The passed in `Context` will contain the gRPC metadata.MD object (for header-based authentication) and
the peer.Peer information that can contain transport-based credentials (e.g. `credentials.AuthInfo`).

The returned context will be propagated to handlers, allowing user changes to `Context`. However,
please make sure that the `Context` returned is a child `Context` of the one passed in.

If error is returned, its `grpc.Code()` will be returned to the user as well as the verbatim message.
Please make sure you use `codes.Unauthenticated` (lacking auth) and `codes.PermissionDenied`
(authed, but lacking perms) appropriately.

## <a name="ServiceAuthFuncOverride">type</a> [ServiceAuthFuncOverride](./auth.go#L29-L31)
``` go
type ServiceAuthFuncOverride interface {
    AuthFuncOverride(ctx context.Context, fullMethodName string) (context.Context, error)
}
```
ServiceAuthFuncOverride allows a given gRPC service implementation to override the global `AuthFunc`.

If a service implements the AuthFuncOverride method, it takes precedence over the `AuthFunc` method,
and will be called instead of AuthFunc for all method invocations within that service.

- - -
Generated by [godoc2ghmd](https://github.com/GandalfUK/godoc2ghmd)