Documentation

Overview

    Package auth provides authentication and authorization capability

    Index

    Constants

    View Source
    const (
    	// BearerScheme used for Authorization header
    	BearerScheme = "Bearer "
    	// ScopePublic is the scope applied to a rule to allow access to the public
    	ScopePublic = ""
    	// ScopeAccount is the scope applied to a rule to limit to users with any valid account
    	ScopeAccount = "*"
    )

    Variables

    View Source
    var (
    	// ErrInvalidToken is when the token provided is not valid
    	ErrInvalidToken = errors.New("invalid token provided")
    	// ErrForbidden is when a user does not have the necessary scope to access a resource
    	ErrForbidden = errors.New("resource forbidden")
    )
    View Source
    var (
    	DefaultAuth = NewAuth()
    )

    Functions

    func ContextWithAccount

    func ContextWithAccount(ctx context.Context, account *Account) context.Context

      ContextWithAccount sets the account in the context

      func Verify

      func Verify(rules []*Rule, acc *Account, res *Resource) error

        Verify an account has access to a resource using the rules provided. If the account does not have access an error will be returned. If there are no rules provided which match the resource, an error will be returned

        Types

        type Access

        type Access int

          Access defines the type of access a rule grants

          const (
          	// AccessGranted to a resource
          	AccessGranted Access = iota
          	// AccessDenied to a resource
          	AccessDenied
          )

          type Account

          type Account struct {
          	// ID of the account e.g. email
          	ID string `json:"id"`
          	// Type of the account, e.g. service
          	Type string `json:"type"`
          	// Issuer of the account
          	Issuer string `json:"issuer"`
          	// Any other associated metadata
          	Metadata map[string]string `json:"metadata"`
          	// Scopes the account has access to
          	Scopes []string `json:"scopes"`
          	// Secret for the account, e.g. the password
          	Secret string `json:"secret"`
          }

            Account provided by an auth provider

            func AccountFromContext

            func AccountFromContext(ctx context.Context) (*Account, bool)

              AccountFromContext gets the account from the context, which is set by the auth wrapper at the start of a call. If the account is not set, a nil account will be returned. The error is only returned when there was a problem retrieving an account

              type Auth

              type Auth interface {
              	// Init the auth
              	Init(opts ...Option)
              	// Options set for auth
              	Options() Options
              	// Generate a new account
              	Generate(id string, opts ...GenerateOption) (*Account, error)
              	// Inspect a token
              	Inspect(token string) (*Account, error)
              	// Token generated using refresh token or credentials
              	Token(opts ...TokenOption) (*Token, error)
              	// String returns the name of the implementation
              	String() string
              }

                Auth provides authentication and authorization

                func NewAuth

                func NewAuth(opts ...Option) Auth

                type GenerateOption

                type GenerateOption func(o *GenerateOptions)

                func WithMetadata

                func WithMetadata(md map[string]string) GenerateOption

                  WithMetadata for the generated account

                  func WithProvider

                  func WithProvider(p string) GenerateOption

                    WithProvider for the generated account

                    func WithScopes

                    func WithScopes(s ...string) GenerateOption

                      WithScopes for the generated account

                      func WithSecret

                      func WithSecret(s string) GenerateOption

                        WithSecret for the generated account

                        func WithType

                        func WithType(t string) GenerateOption

                          WithType for the generated account

                          type GenerateOptions

                          type GenerateOptions struct {
                          	// Metadata associated with the account
                          	Metadata map[string]string
                          	// Scopes the account has access too
                          	Scopes []string
                          	// Provider of the account, e.g. oauth
                          	Provider string
                          	// Type of the account, e.g. user
                          	Type string
                          	// Secret used to authenticate the account
                          	Secret string
                          }

                          func NewGenerateOptions

                          func NewGenerateOptions(opts ...GenerateOption) GenerateOptions

                            NewGenerateOptions from a slice of options

                            type ListOption

                            type ListOption func(o *ListOptions)

                            func RulesContext

                            func RulesContext(ctx context.Context) ListOption

                            type ListOptions

                            type ListOptions struct {
                            	Context context.Context
                            }

                            type Option

                            type Option func(o *Options)

                            func Addrs

                            func Addrs(addrs ...string) Option

                              Addrs is the auth addresses to use

                              func ClientToken

                              func ClientToken(token *Token) Option

                                ClientToken sets the auth token to use when making requests

                                func Credentials

                                func Credentials(id, secret string) Option

                                  Credentials sets the auth credentials

                                  func Namespace

                                  func Namespace(n string) Option

                                    Namespace the service belongs to

                                    func PrivateKey

                                    func PrivateKey(key string) Option

                                      PrivateKey is the JWT private key

                                      func PublicKey

                                      func PublicKey(key string) Option

                                        PublicKey is the JWT public key

                                        type Options

                                        type Options struct {
                                        	// Namespace the service belongs to
                                        	Namespace string
                                        	// ID is the services auth ID
                                        	ID string
                                        	// Secret is used to authenticate the service
                                        	Secret string
                                        	// Token is the services token used to authenticate itself
                                        	Token *Token
                                        	// PublicKey for decoding JWTs
                                        	PublicKey string
                                        	// PrivateKey for encoding JWTs
                                        	PrivateKey string
                                        	// Addrs sets the addresses of auth
                                        	Addrs []string
                                        }

                                        func NewOptions

                                        func NewOptions(opts ...Option) Options

                                        type Resource

                                        type Resource struct {
                                        	// Name of the resource, e.g. go.micro.service.notes
                                        	Name string `json:"name"`
                                        	// Type of resource, e.g. service
                                        	Type string `json:"type"`
                                        	// Endpoint resource e.g NotesService.Create
                                        	Endpoint string `json:"endpoint"`
                                        }

                                          Resource is an entity such as a user or

                                          type Rule

                                          type Rule struct {
                                          	// ID of the rule, e.g. "public"
                                          	ID string
                                          	// Scope the rule requires, a blank scope indicates open to the public and * indicates the rule
                                          	// applies to any valid account
                                          	Scope string
                                          	// Resource the rule applies to
                                          	Resource *Resource
                                          	// Access determines if the rule grants or denies access to the resource
                                          	Access Access
                                          	// Priority the rule should take when verifying a request, the higher the value the sooner the
                                          	// rule will be applied
                                          	Priority int32
                                          }

                                            Rule is used to verify access to a resource

                                            type Rules

                                            type Rules interface {
                                            	// Verify an account has access to a resource using the rules
                                            	Verify(acc *Account, res *Resource, opts ...VerifyOption) error
                                            	// Grant access to a resource
                                            	Grant(rule *Rule) error
                                            	// Revoke access to a resource
                                            	Revoke(rule *Rule) error
                                            	// List returns all the rules used to verify requests
                                            	List(...ListOption) ([]*Rule, error)
                                            }

                                              Rules manages access to resources

                                              func NewRules

                                              func NewRules() Rules

                                              type Token

                                              type Token struct {
                                              	// The token to be used for accessing resources
                                              	AccessToken string `json:"access_token"`
                                              	// RefreshToken to be used to generate a new token
                                              	RefreshToken string `json:"refresh_token"`
                                              	// Time of token creation
                                              	Created time.Time `json:"created"`
                                              	// Time of token expiry
                                              	Expiry time.Time `json:"expiry"`
                                              }

                                                Token can be short or long lived

                                                func (*Token) Expired

                                                func (t *Token) Expired() bool

                                                  Expired returns a boolean indicating if the token needs to be refreshed

                                                  type TokenOption

                                                  type TokenOption func(o *TokenOptions)

                                                  func WithCredentials

                                                  func WithCredentials(id, secret string) TokenOption

                                                  func WithExpiry

                                                  func WithExpiry(ex time.Duration) TokenOption

                                                    WithExpiry for the token

                                                    func WithToken

                                                    func WithToken(rt string) TokenOption

                                                    type TokenOptions

                                                    type TokenOptions struct {
                                                    	// ID for the account
                                                    	ID string
                                                    	// Secret for the account
                                                    	Secret string
                                                    	// RefreshToken is used to refesh a token
                                                    	RefreshToken string
                                                    	// Expiry is the time the token should live for
                                                    	Expiry time.Duration
                                                    }

                                                    func NewTokenOptions

                                                    func NewTokenOptions(opts ...TokenOption) TokenOptions

                                                      NewTokenOptions from a slice of options

                                                      type VerifyOption

                                                      type VerifyOption func(o *VerifyOptions)

                                                      func VerifyContext

                                                      func VerifyContext(ctx context.Context) VerifyOption

                                                      type VerifyOptions

                                                      type VerifyOptions struct {
                                                      	Context context.Context
                                                      }