go-micro.dev/v5@v5.12.0/auth/auth.go (about)

     1  // Package auth provides authentication and authorization capability
     2  package auth
     3  
     4  import (
     5  	"context"
     6  	"errors"
     7  	"time"
     8  )
     9  
    10  const (
    11  	// BearerScheme used for Authorization header.
    12  	BearerScheme = "Bearer "
    13  	// ScopePublic is the scope applied to a rule to allow access to the public.
    14  	ScopePublic = ""
    15  	// ScopeAccount is the scope applied to a rule to limit to users with any valid account.
    16  	ScopeAccount = "*"
    17  )
    18  
    19  var (
    20  	// ErrInvalidToken is when the token provided is not valid.
    21  	ErrInvalidToken = errors.New("invalid token provided")
    22  	// ErrForbidden is when a user does not have the necessary scope to access a resource.
    23  	ErrForbidden = errors.New("resource forbidden")
    24  )
    25  
    26  // Auth provides authentication and authorization.
    27  type Auth interface {
    28  	// Init the auth
    29  	Init(opts ...Option)
    30  	// Options set for auth
    31  	Options() Options
    32  	// Generate a new account
    33  	Generate(id string, opts ...GenerateOption) (*Account, error)
    34  	// Inspect a token
    35  	Inspect(token string) (*Account, error)
    36  	// Token generated using refresh token or credentials
    37  	Token(opts ...TokenOption) (*Token, error)
    38  	// String returns the name of the implementation
    39  	String() string
    40  }
    41  
    42  // Rules manages access to resources.
    43  type Rules interface {
    44  	// Verify an account has access to a resource using the rules
    45  	Verify(acc *Account, res *Resource, opts ...VerifyOption) error
    46  	// Grant access to a resource
    47  	Grant(rule *Rule) error
    48  	// Revoke access to a resource
    49  	Revoke(rule *Rule) error
    50  	// List returns all the rules used to verify requests
    51  	List(...ListOption) ([]*Rule, error)
    52  }
    53  
    54  // Account provided by an auth provider.
    55  type Account struct {
    56  	// Any other associated metadata
    57  	Metadata map[string]string `json:"metadata"`
    58  	// ID of the account e.g. email
    59  	ID string `json:"id"`
    60  	// Type of the account, e.g. service
    61  	Type string `json:"type"`
    62  	// Issuer of the account
    63  	Issuer string `json:"issuer"`
    64  	// Secret for the account, e.g. the password
    65  	Secret string `json:"secret"`
    66  	// Scopes the account has access to
    67  	Scopes []string `json:"scopes"`
    68  }
    69  
    70  // Token can be short or long lived.
    71  type Token struct {
    72  	// Time of token creation
    73  	Created time.Time `json:"created"`
    74  	// Time of token expiry
    75  	Expiry time.Time `json:"expiry"`
    76  	// The token to be used for accessing resources
    77  	AccessToken string `json:"access_token"`
    78  	// RefreshToken to be used to generate a new token
    79  	RefreshToken string `json:"refresh_token"`
    80  }
    81  
    82  // Expired returns a boolean indicating if the token needs to be refreshed.
    83  func (t *Token) Expired() bool {
    84  	return t.Expiry.Unix() < time.Now().Unix()
    85  }
    86  
    87  // Resource is an entity such as a user or.
    88  type Resource struct {
    89  	// Name of the resource, e.g. go.micro.service.notes
    90  	Name string `json:"name"`
    91  	// Type of resource, e.g. service
    92  	Type string `json:"type"`
    93  	// Endpoint resource e.g NotesService.Create
    94  	Endpoint string `json:"endpoint"`
    95  }
    96  
    97  // Access defines the type of access a rule grants.
    98  type Access int
    99  
   100  const (
   101  	// AccessGranted to a resource.
   102  	AccessGranted Access = iota
   103  	// AccessDenied to a resource.
   104  	AccessDenied
   105  )
   106  
   107  // Rule is used to verify access to a resource.
   108  type Rule struct {
   109  	// Resource the rule applies to
   110  	Resource *Resource
   111  	// ID of the rule, e.g. "public"
   112  	ID string
   113  	// Scope the rule requires, a blank scope indicates open to the public and * indicates the rule
   114  	// applies to any valid account
   115  	Scope string
   116  	// Access determines if the rule grants or denies access to the resource
   117  	Access Access
   118  	// Priority the rule should take when verifying a request, the higher the value the sooner the
   119  	// rule will be applied
   120  	Priority int32
   121  }
   122  
   123  type accountKey struct{}
   124  
   125  // AccountFromContext gets the account from the context, which
   126  // is set by the auth wrapper at the start of a call. If the account
   127  // is not set, a nil account will be returned. The error is only returned
   128  // when there was a problem retrieving an account.
   129  func AccountFromContext(ctx context.Context) (*Account, bool) {
   130  	acc, ok := ctx.Value(accountKey{}).(*Account)
   131  	return acc, ok
   132  }
   133  
   134  // ContextWithAccount sets the account in the context.
   135  func ContextWithAccount(ctx context.Context, account *Account) context.Context {
   136  	return context.WithValue(ctx, accountKey{}, account)
   137  }