grpcauth

package
v1.0.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 13, 2026 License: Apache-2.0 Imports: 10 Imported by: 3

Documentation

Overview

`grpcauth` is an authentication and authorization gRPC server side authentication wrappers.

Please see examples for simple examples of use.

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultAdminGroup 

func DefaultAdminGroup() string

DefaultAdminGroup is the default admin group

func DefaultAdminGroups 

func DefaultAdminGroups() []string

DefaultAdminGroups returns the default administrators group

func DefaultSuperAdminGroup 

func DefaultSuperAdminGroup() string

DefaultSuperAdminGroup is the default super admin group

func DefaultUserGroup 

func DefaultUserGroup() string

DefaultUserGroup is the default user group 

func Header() string

Header returns authentication header

func Scheme 

func Scheme() string

Scheme returns authentication scheme

Types

type API 

type API struct {
	// contains filtered or unexported fields
}

func NewAPI 

func NewAPI(signingKey []byte, issuer, audience string) *API

NewAPI creates a JWT authentication and authorization helper using HS256.

Example 
api := NewAPI([]byte("secret"), "users", "users-api")
api.AddAdminGroups(DefaultAdminGroup())
api.AddSuperAdminGroups(DefaultSuperAdminGroup())

token, err := api.GenToken(context.Background(), &Payload{
	ID:        "user-1",
	ProjectID: "project-1",
	Group:     DefaultUserGroup(),
}, time.Now().Add(time.Hour))
if err != nil {
	panic(err)
}

md, err := api.GetMetadataFromJwt(token)
if err != nil {
	panic(err)
}

_ = md

func (*API) AddAdminGroups 

func (api *API) AddAdminGroups(groups ...string)

AddAdminGroups appends groups treated as administrator groups.

func (*API) AddSuperAdminGroups added in v0.1.4 

func (api *API) AddSuperAdminGroups(groups ...string)

AddSuperAdminGroups appends groups treated as super-administrator groups.

func (*API) AdminGroups 

func (api *API) AdminGroups() []string

AdminGroups returns the configured admin and super-admin groups.

func (*API) Authenticator added in v0.0.3 

func (api *API) Authenticator(ctx context.Context) (context.Context, error)

Authenticator is the 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

func (*API) AuthenticatorWithKey added in v0.0.3 

func (api *API) AuthenticatorWithKey(ctx context.Context, signingKey []byte) (context.Context, error)

AuthenticatorWithKey behaves like Authenticator but uses the supplied key.

func (*API) AuthorizeGroups added in v0.0.3 

func (api *API) AuthorizeGroups(ctx context.Context, groups ...string) (*Payload, error)

AuthorizeGroups checks whether the claims Group in the context metadata.MD Authorization JWT is a member the allowed groups set

If it's a member, Authorization will succeed, otherwise it will fail with codes.PermissionDenied.

The function will attempt to extract JWT token from gRPC metadata.MD Authorization key from the Context.

If getting metadata.MD object from Context fails i.e due to missing metadata.MD object OR missing Authorization key in the metadata.MD object, the function will fail with codes.Unauthenticated

It is expected that before calling this method, Authentication ought to have happened.

func (*API) AuthorizeIds added in v0.0.3 

func (api *API) AuthorizeIds(ctx context.Context, ids ...string) (*Payload, error)

AuthorizeIds checks whether the claims Id in the context metadata.MD Authorization JWT is a member the allowed Ids set

If it's a member, Authorization will succeed, otherwise it will fail with codes.PermissionDenied.

The function will attempt to extract JWT token from gRPC metadata.MD Authorization key from the Context.

If getting metadata.MD object from Context fails i.e due to missing metadata.MD object OR missing Authorization key in the metadata.MD object, the function will fail with codes.Unauthenticated

It is expected that before calling this method, Authentication ought to have happened.

func (*API) GenToken 

func (api *API) GenToken(ctx context.Context, payload *Payload, expirationTime time.Time) (string, error)

GenToken generates JWT token with given payload that expire after expirationTime elapses.

It uses the receivers SigningMethod and SigningKey to sign the token.

func (*API) GenTokenFromClaims 

func (api *API) GenTokenFromClaims(ctx context.Context, claims *Claims, expirationTime time.Time) (string, error)

GenTokenFromClaims generates JWT token with given claims that expire after expirationTime elapses.

It uses the receivers SigningMethod and default secret to sign the token.

func (*API) GenTokenUsingKey 

func (api *API) GenTokenUsingKey(ctx context.Context, claims *Claims, expirationTime time.Time, signingKey []byte) (string, error)

GenTokenUsingKey generates JWT token with given payload that expire after expirationTime elapses.

It uses the provided signingKey and the receiver SigningMethod to sign the token.

func (*API) GetClaims 

func (api *API) GetClaims(ctx context.Context) (*Claims, error)

GetClaims returns the authenticated claims stored in ctx.

func (*API) GetClaimsFromJwt 

func (api *API) GetClaimsFromJwt(jwt string) (*Claims, error)

GetClaimsFromJwt parses a token string using the API signing key.

func (*API) GetMetadataFromCtx 

func (api *API) GetMetadataFromCtx(ctx context.Context) metadata.MD

GetMetadataFromCtx returns incoming gRPC metadata from ctx, or an empty map if none exists.

func (*API) GetMetadataFromJwt 

func (api *API) GetMetadataFromJwt(jwt string) (metadata.MD, error)

GetMetadataFromJwt constructs incoming gRPC metadata for a bearer token.

func (*API) GetPayload added in v0.0.3 

func (api *API) GetPayload(ctx context.Context) (*Payload, error)

GetPayload returns the authenticated payload stored in ctx.

func (*API) GetSigningKey added in v0.0.3 

func (api *API) GetSigningKey() []byte

GetSigningKey returns the signing key configured for the API.

func (*API) IsAdmin 

func (api *API) IsAdmin(group string) bool

IsAdmin reports whether group is in any configured admin group.

func (*API) IsGroupAllowed added in v0.1.4 

func (api *API) IsGroupAllowed(group string, allowedGroups ...string) bool

IsGroupAllowed reports whether group is in allowedGroups.

func (*API) IsSuperAdmin added in v0.1.4 

func (api *API) IsSuperAdmin(group string) bool

IsSuperAdmin reports whether group is in any configured super-admin group.

func (*API) SetPayloadProvider added in v1.0.1 

func (api *API) SetPayloadProvider(provider PayloadProvider)

SetPayloadProvider sets the provider used to fetch full payload data (e.g. from MySQL/Redis) for JWTs that only contain the user ID.

type Claims 

type Claims struct {
	*Payload
	jwt.StandardClaims
}

Claims contains JWT claims information

type Payload 

type Payload struct {
	ID           string   `json:"id"`
	ProjectID    string   `json:"project_id"`
	Names        string   `json:"-"`
	PhoneNumber  string   `json:"-"`
	EmailAddress string   `json:"-"`
	Group        string   `json:"-"`
	Roles        []string `json:"-"`
	ExternalID   string   `json:"-"`
}

Payload contains jwt payload

type PayloadProvider added in v1.0.1 

type PayloadProvider interface {
	GetPayload(ctx context.Context, id string) (*Payload, error)
}

PayloadProvider defines an interface for fetching full payload details (e.g. from MySQL/Redis) when the JWT only contains the user ID.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.