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

• Constants
• Variables
• func CreateString(input StringParams) ([]byte, error)
• type AccessTokenDecoder
  • func (a *AccessTokenDecoder) Decode(accessToken string) (Claims, error)
• type AccessTokenGenerator
  • func (t *AccessTokenGenerator) GenerateAccessToken(email string) (*Authentication, error)
• type Authentication
• type Claims
• type CoreRules
  • func (a *CoreRules) Owner() (string, error)
• type CreateUser
  • func (c *CreateUser) CreateUser(email, ownerOptional string) error
• type IAccessTokenGenerator
• type IRefreshTokenGenerator
• type Identity
• type IdentityDetailsStore
• type IdentityQueries
  • func (i *IdentityQueries) FindIdentities(emails []string) ([]*Identity, error)
  • func (i *IdentityQueries) FindOwnerIdentities(owners []string) (map[string][]*Identity, error)
• type IdentityQueriesIdentityRepository
• type IdentityQueriesScopeRepository
• type Logout
  • func (l *Logout) RevokeSession(refreshToken string) error
• type OAuth2IssuerConfig
  • func (i *OAuth2IssuerConfig) String() string
• type OAuthConfig
• type OAuthTokenMethod
  • func (t *OAuthTokenMethod) String() string
• type RefreshTokenAuthenticator
  • func (s *RefreshTokenAuthenticator) AuthenticateFromRefreshToken(refreshToken string) (*Authentication, *Identity, error)
• type RefreshTokenGenerator
  • func (t *RefreshTokenGenerator) GenerateRefreshToken(spec RefreshTokenSpec) (string, error)
• type RefreshTokenPurpose
• type RefreshTokenRepository
• type RefreshTokenSpec
• type ReverseScopesReader
• type RevokeAccessTokenAdapter
• type SSOAuthenticator
  • func (s *SSOAuthenticator) AuthenticateFromExternalIDProvider(identityJWT string, refreshTokenPurpose RefreshTokenPurpose) (*Authentication, *Identity, error)
• type Scope
• type ScopeId
• type ScopeType
• type ScopeWriter
• type ScopesReader
• type StringParams

Constants

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 FIXME The role is NOT YET MAPPED
	AlbumContributorScope ScopeType = "album:contributor" // AlbumContributorScope gives read access and ability to contribute (add medias) to an album
	MediaVisitorScope     ScopeType = "media:visitor"     // MediaVisitorScope gives read access to medias directly

	JWTScopeOwnerPrefix = "owner:"

	RefreshTokenPurposeWeb RefreshTokenPurpose = "web" // RefreshTokenPurposeWeb is used for WEB sessions
)

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") // AccessUnauthorisedError is used when the request doesn't have valid credentials (no bearer token, or invalid token)
	AccessForbiddenError         = errors.New("access forbidden")    // AccessForbiddenError is used when the request has valid credentials, but the access to the resource has been denied
	InvalidUserEmailError        = errors.New("user email is mandatory")
	ExpiredRefreshTokenError     = errors.New("refresh token has expired")
	InvalidRefreshTokenError     = errors.New("refresh token is not valid")
	IdentityDetailsNotFoundError = errors.New("no identity details stored for this identity") // IdentityDetailsNotFoundError is an internal error between the domain and the repository

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

var TimeFunc = time.Now

Functions

func CreateString

func CreateString(input StringParams) ([]byte, error)

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 AccessTokenGenerator

type AccessTokenGenerator struct {
	PermissionsReader     ScopesReader
	Config                OAuthConfig
	AccessTokenRepository RefreshTokenRepository
}

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

func (*AccessTokenGenerator) GenerateAccessToken

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

type Authentication

type Authentication struct {
	AccessToken  string
	RefreshToken string // RefreshToken is optional
	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 IAccessTokenGenerator

type IAccessTokenGenerator interface {
	GenerateAccessToken(email string) (*Authentication, error)
}

type IRefreshTokenGenerator

type IRefreshTokenGenerator interface {
	GenerateRefreshToken(spec RefreshTokenSpec) (string, error)
}

type Identity

type Identity struct {
	Email   string
	Name    string
	Picture string
}

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

type IdentityDetailsStore

type IdentityDetailsStore interface {
	StoreIdentity(identity Identity) error
	FindIdentity(email string) (*Identity, error)
}

type IdentityQueries

type IdentityQueries struct {
	IdentityRepository IdentityQueriesIdentityRepository
	ScopeRepository    IdentityQueriesScopeRepository
}

func (*IdentityQueries) FindIdentities

func (i *IdentityQueries) FindIdentities(emails []string) ([]*Identity, error)

func (*IdentityQueries) FindOwnerIdentities

func (i *IdentityQueries) FindOwnerIdentities(owners []string) (map[string][]*Identity, error)

type IdentityQueriesIdentityRepository

type IdentityQueriesIdentityRepository interface {
	FindIdentities(emails []string) ([]*Identity, error)
}

type IdentityQueriesScopeRepository

type IdentityQueriesScopeRepository interface {
	ListScopesByOwners(owners []string, types ...ScopeType) ([]*Scope, error)
}

type Logout

type Logout struct {
	RevokeAccessTokenAdapter RevokeAccessTokenAdapter
}

func (*Logout) RevokeSession

func (l *Logout) RevokeSession(refreshToken string) error

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 {
	AccessDuration  time.Duration                         // AccessDuration for generated access tokens
	RefreshDuration map[RefreshTokenPurpose]time.Duration // RefreshDuration for generated refresh token (based on the purpose)
	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 RefreshTokenAuthenticator

type RefreshTokenAuthenticator struct {
	AccessTokenGenerator   IAccessTokenGenerator
	RefreshTokenGenerator  IRefreshTokenGenerator
	RefreshTokenRepository RefreshTokenRepository
	IdentityDetailsStore   IdentityDetailsStore
}

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

func (*RefreshTokenAuthenticator) AuthenticateFromRefreshToken

func (s *RefreshTokenAuthenticator) AuthenticateFromRefreshToken(refreshToken string) (*Authentication, *Identity, error)

type RefreshTokenGenerator

type RefreshTokenGenerator struct {
	RefreshTokenRepository RefreshTokenRepository
	RefreshDuration        map[RefreshTokenPurpose]time.Duration
}

func (*RefreshTokenGenerator) GenerateRefreshToken

func (t *RefreshTokenGenerator) GenerateRefreshToken(spec RefreshTokenSpec) (string, error)

type RefreshTokenPurpose

type RefreshTokenPurpose string

type RefreshTokenRepository

type RefreshTokenRepository interface {
	StoreRefreshToken(token string, spec RefreshTokenSpec) error

	FindRefreshToken(token string) (*RefreshTokenSpec, error)
	DeleteRefreshToken(token string) error

	// HouseKeepRefreshToken removes any token that have expired
	HouseKeepRefreshToken() (int, error)
}

type RefreshTokenSpec

type RefreshTokenSpec struct {
	Email               string
	RefreshTokenPurpose RefreshTokenPurpose // RefreshTokenPurpose is mandatory
	AbsoluteExpiryTime  time.Time           // AbsoluteExpiryTime will be generated from RefreshTokenPurpose if not defined
	Scopes              []string            // Scopes is the list of scopes for which an access token can be generated
}

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 RevokeAccessTokenAdapter

type RevokeAccessTokenAdapter interface {
	DeleteRefreshToken(token string) error
}

type SSOAuthenticator

type SSOAuthenticator struct {
	AccessTokenGenerator
	RefreshTokenGenerator  IRefreshTokenGenerator
	IdentityDetailsStore   IdentityDetailsStore
	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, refreshTokenPurpose RefreshTokenPurpose) (*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, ...)

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 StringParams

type StringParams struct {
	Length          int64
	Upper           bool
	MinUpper        int64
	Lower           bool
	MinLower        int64
	Numeric         bool
	MinNumeric      int64
	Special         bool
	MinSpecial      int64
	OverrideSpecial string
}