aclcore

Documentation

Overview

Package aclcore manage what an API consumer is granted to do, and issue access tokens to represent it.

This package supports the following use-cases:

1. an admin can create a new owner and administrate the site 2. an owner can back up and retrieve his medias through the API (WEB, CLI and MOBILE) 3. a guest can see albums and medias that have been shared with him 4. an owner can share an album to the rest of the family, and contribute to family albums

Index

• Variables
• type AccessTokenDecoder
  • func (a *AccessTokenDecoder) Decode(accessToken string) (Claims, error)
• type Authentication
• type Claims
• type CoreRules
  • func (a *CoreRules) Owner() (string, error)
• type CreateUser
  • func (c *CreateUser) CreateUser(email, ownerOptional string) error
• type Identity
• type OAuth2IssuerConfig
  • func (i *OAuth2IssuerConfig) String() string
• type OAuthConfig
• type OAuthTokenMethod
  • func (t *OAuthTokenMethod) String() string
• type ReverseScopesReader
• type SSOAuthenticator
  • func (s *SSOAuthenticator) AuthenticateFromExternalIDProvider(identityJWT string) (*Authentication, *Identity, error)
• type Scope
• type ScopeId
• type ScopeType
• type ScopeWriter
• type ScopesReader
• type TokenGenerator
  • func (t *TokenGenerator) GenerateAccessToken(email string) (*Authentication, error)

Variables

var (
	InvalidTokenError         = errors.New("authenticated failed")
	InvalidTokenExplicitError = errors.New("authentication failed: token invalid")
	NotPreregisteredError     = errors.New("user must be pre-registered")
	AccessUnauthorisedError   = errors.New("access unauthorised")
	AccessForbiddenError      = errors.New("access forbidden")
	InvalidUserEmailError     = errors.New("user email is mandatory")

	// TrustedIdentityProvider is the default list of trusted identity providers
	TrustedIdentityProvider = []string{
		"https://accounts.google.com/.well-known/openid-configuration",
	}
)

var TimeFunc = time.Now

Types

type AccessTokenDecoder

type AccessTokenDecoder struct {
	Config OAuthConfig
	Now    func() time.Time // Now is defaulted to time.Now
}

func (*AccessTokenDecoder) Decode

func (a *AccessTokenDecoder) Decode(accessToken string) (Claims, error)

type Authentication

type Authentication struct {
	AccessToken string
	ExpiryTime  time.Time
	ExpiresIn   int64 // ExpiresIn is the number of seconds before access token expires
}

Authentication is generated upon successful authentication

type Claims

type Claims struct {
	Subject string                 // Subject is the user id (its email)
	Scopes  map[string]interface{} // Scopes is the list of permissions stored eagerly in access token
	Owner   string                 // Owner is deviated from Scopes (extract of the MainOwnerScope)
}

type CoreRules

type CoreRules struct {
	ScopeReader ScopesReader
	Email       string
}

func (*CoreRules) Owner

func (a *CoreRules) Owner() (string, error)

Owner returns empty if the user own nothing, or the identifier of its owner

type CreateUser

type CreateUser struct {
	ScopesReader ScopesReader
	ScopeWriter  ScopeWriter
}

func (*CreateUser) CreateUser

func (c *CreateUser) CreateUser(email, ownerOptional string) error

CreateUser create a user capable of backup as 'owner', or update an existing owner to be 'owner'

type Identity

type Identity struct {
	Email   string
	Name    string
	Picture string
}

Identity is read from token created by the Identity Provider (google, ...)

type OAuth2IssuerConfig

type OAuth2IssuerConfig struct {
	ConfigSource     string
	PublicKeysLookup func(method OAuthTokenMethod) (interface{}, error)
}

func (*OAuth2IssuerConfig) String

func (i *OAuth2IssuerConfig) String() string

type OAuthConfig

type OAuthConfig struct {
	ValidityDuration time.Duration // ValidityDuration for generated access token
	Issuer           string        // Issuer is the application instance ID, used in both 'iss' and 'aud'
	SecretJwtKey     []byte        // SecretJwtKey is the key used to sign and validate DPhoto JWT
}

type OAuthTokenMethod

type OAuthTokenMethod struct {
	Algorithm string
	Kid       string
}

func (*OAuthTokenMethod) String

func (t *OAuthTokenMethod) String() string

type ReverseScopesReader

type ReverseScopesReader interface {
	// ListOwnerScopes is a reverse query to find to whom has been shared owner resources.
	ListOwnerScopes(owner string, types ...ScopeType) ([]*Scope, error)
}

type SSOAuthenticator

type SSOAuthenticator struct {
	TokenGenerator
	TrustedIdentityIssuers map[string]OAuth2IssuerConfig // TrustedIdentityIssuers is the list of accepted 'iss', and their public key
}

SSOAuthenticator use a known identity token issued by a known and trusted identity provider (google, facebook, ...) to create an access token

func (*SSOAuthenticator) AuthenticateFromExternalIDProvider

func (s *SSOAuthenticator) AuthenticateFromExternalIDProvider(identityJWT string) (*Authentication, *Identity, error)

type Scope

type Scope struct {
	Type          ScopeType // Type is mandatory, it defines what fields on this structure is used and allow to filter the results
	GrantedAt     time.Time // GrantedAt is the date the scope has been granted to the user for the first time
	GrantedTo     string    // GrantedTo is the consumer, usually an email address
	ResourceOwner string    // ResourceOwner (optional) is used has part of the ID of the catalog resources
	ResourceId    string    // ResourceId if a unique identifier of the resource (in conjunction of the ResourceOwner for most catalog resources) ; ex: 'admin' (for 'api' type)
	ResourceName  string    // ResourceName (optional) used for user-friendly display of the shared albums
}

Scope is attached to a user (a consumer of the API) and define the role it has on resource basis

type ScopeId

type ScopeId struct {
	Type          ScopeType // Type is mandatory, it defines what fields on this structure is used and allow to filter the results
	GrantedTo     string    // GrantedTo is the consumer, usually an email address
	ResourceOwner string    // ResourceOwner (optional) is used has part of the ID of the catalog resources
	ResourceId    string    // ResourceId if a unique identifier of the resource (in conjunction of the ResourceOwner for most catalog resources) ; ex: 'admin' (for 'api' type)
}

ScopeId are the properties of a Scope that identity it

type ScopeType

type ScopeType string

ScopeType is a type of API (admin) or a catalog resource (owner, album, ...)

const (
	ApiScope          ScopeType = "api"           // ApiScope represents a set of API endpoints, like 'admin'
	MainOwnerScope    ScopeType = "owner:main"    // MainOwnerScope is limited to 1 per user, it's the tenant all backups of the user will be stored against
	AlbumVisitorScope ScopeType = "album:visitor" // AlbumVisitorScope gives read access to an album and the media it contains
	MediaVisitorScope ScopeType = "media:visitor" // MediaVisitorScope gives read access to medias directly

	JWTScopeOwnerPrefix = "owner:"
)

type ScopeWriter

type ScopeWriter interface {
	// DeleteScopes deletes the scope(s) if it exists, do nothing otherwise
	DeleteScopes(id ...ScopeId) error

	// SaveIfNewScope persists the scope if it doesn't exist yet, no error is returned if it already exists
	SaveIfNewScope(scope Scope) error
}

type ScopesReader

type ScopesReader interface {
	// ListUserScopes returns all access of a certain type that have been granted to a user
	ListUserScopes(email string, types ...ScopeType) ([]*Scope, error)

	// FindScopesById returns scopes that have been granted (exists in DB)
	FindScopesById(ids ...ScopeId) ([]*Scope, error)
}

type TokenGenerator

type TokenGenerator struct {
	PermissionsReader ScopesReader
	Config            OAuthConfig
}

TokenGenerator generate an access token pre-authorising consumer to perform most operations

func (*TokenGenerator) GenerateAccessToken

func (t *TokenGenerator) GenerateAccessToken(email string) (*Authentication, error)