fgax

package
v0.3.5 Latest Latest
Warning

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

 Go to latest Published: Nov 21, 2024 License: Apache-2.0 Imports: 18 Imported by: 2

Documentation

Overview

Package fgax includes client libraries to interact with openfga authorization credit to https://github.com/canonical/ofga/blob/main/tuples.go

Index

Constants

View Source 
const (
	// SystemAdminRelation is the relation for system admins that have the highest level of access
	SystemAdminRelation = "system_admin"
	// MemberRelation is the relation for members of an entity
	MemberRelation = "member"
	// AdminRelation is the relation for admins of an entity
	AdminRelation = "admin"
	// OwnerRelation is the relation for owners of an entity
	OwnerRelation = "owner"
	// AuditorRelation is the relation for auditors of an entity
	AuditorRelation = "auditor"
	// CollaboratorRelation is the relation for collaborators of an entity
	CollaboratorRelation = "collaborator"

	// SelfRelation is the relation for the object to itself, usually for user relations
	SelfRelation = "_self"
	// ParentRelation is the relation for parents of an entity
	ParentRelation = "parent"
	// EditorRelation is the relation to assign editors to an entity
	EditorRelation = "editor"
	// BlockedRelation is the relation to block access to an entity
	BlockedRelation = "blocked"
	// ViewerRelation is the relation to assign viewers to an entity
	ViewerRelation = "viewer"

	// AssigneeRelation is the relation for assignee of an entity
	AssigneeRelation = "assignee"

	// CanView is the relation for viewing an entity
	CanView = "can_view"
	// CanEdit is the relation for editing an entity
	CanEdit = "can_edit"
	// CanDelete is the relation for deleting an entity
	CanDelete = "can_delete"
	// CanInviteMembers is the relation for inviting members to an entity
	CanInviteMembers = "can_invite_members"
	// CanInviteAdmins is the relation for inviting admins to an entity
	CanInviteAdmins = "can_invite_admins"
)

setup relations for use in creating tuples

Variables

View Source 
var (
	// ErrFGAMissingHost is returned when a host is not provided
	ErrFGAMissingHost = errors.New("invalid OpenFGA config: missing host")

	// ErrMissingRelation is returned when a relation is empty in a tuple creation
	ErrMissingRelation = errors.New("unable to create tuple, missing relation")

	// ErrInvalidAccessCheck is returned when a field required to check a tuple is empty
	ErrInvalidAccessCheck = errors.New("unable to check tuple, missing required field")

	// ErrMissingObject is returned when a object is empty in a tuple creation
	ErrMissingObject = errors.New("unable to create tuple, missing object")

	// ErrMissingObjectOnDeletion is returned when a object is empty in a tuple deletion
	ErrMissingObjectOnDeletion = errors.New("unable to delete tuple, missing object")

	// ErrFailedToTransformModel is returned when the FGA model cannot be transformed to JSON
	ErrFailedToTransformModel = errors.New("failed to transform fga model")

	// ErrMissingRequiredField is returned when a required field is missing
	ErrMissingRequiredField = errors.New("missing required field")
)

Functions

func GetEntityIDs 

func GetEntityIDs(l *ofgaclient.ClientListObjectsResponse) ([]string, error)

GetEntityIDs returns a list of identifiers from a list of objects

func Healthcheck 

func Healthcheck(client Client) func(ctx context.Context) error

Healthcheck reads the model to check if the connection is working

func ListContains 

func ListContains(entityType string, l []string, i string) bool

ListContains checks the results of an fga ListObjects and parses the entities to get the identifier to compare to another identifier based on entity type

Types

type AccessCheck 

type AccessCheck struct {
	// ObjectType is the type of object being checked
	ObjectType Kind
	// ObjectID is the ID of the object being checked
	ObjectID string
	// SubjectID is the ID of the user making the request
	SubjectID string
	// SubjectType is the type of subject being checked
	SubjectType string
	// Relation is the relationship being checked (e.g. "view", "edit", "delete")
	Relation string
}

AccessCheck is a struct to hold the information needed to check access

type Client 

type Client struct {
	// Ofga is the openFGA client
	Ofga ofgaclient.SdkClient
	// Config is the client configuration
	Config ofgaclient.ClientConfiguration
}

Client is an ofga client with some configuration

func CreateFGAClientWithStore 

func CreateFGAClientWithStore(ctx context.Context, c Config) (*Client, error)

CreateFGAClientWithStore returns a Client with a store and model configured

func NewClient 

func NewClient(host string, opts ...Option) (*Client, error)

NewClient returns a wrapped OpenFGA API client ensuring all calls are made to the provided authorization model (id) and returns what is necessary.

func NewMockFGAClient 

func NewMockFGAClient(t *testing.T, c *mock_fga.MockSdkClient) *Client

NewMockFGAClient is a mock client based on the mockery testing framework

func (*Client) AddOrReplaceRole 

func (c *Client) AddOrReplaceRole(ctx context.Context, r RoleRequest) error

AddOrReplaceRole adds (or replaces the existing) the role to the model and updates the config with the new model id

func (*Client) CheckAccess 

func (c *Client) CheckAccess(ctx context.Context, ac AccessCheck) (bool, error)

CheckAccess checks if the user has access to the object type with the given relation

func (*Client) CheckGroupAccess 

func (c *Client) CheckGroupAccess(ctx context.Context, ac AccessCheck) (bool, error)

CheckGroupAccess checks if the user has access to the group with the given relation

func (*Client) CheckOrgAccess 

func (c *Client) CheckOrgAccess(ctx context.Context, ac AccessCheck) (bool, error)

CheckOrgAccess checks if the user has access to the organization with the given relation

func (*Client) CheckOrgReadAccess 

func (c *Client) CheckOrgReadAccess(ctx context.Context, ac AccessCheck) (bool, error)

CheckOrgReadAccess checks if the user has read access to the organization

func (*Client) CheckOrgWriteAccess 

func (c *Client) CheckOrgWriteAccess(ctx context.Context, ac AccessCheck) (bool, error)

CheckOrgWriteAccess checks if the user has write access to the organization

func (*Client) CheckSystemAdminRole 

func (c *Client) CheckSystemAdminRole(ctx context.Context, userID string) (bool, error)

CheckSystemAdminRole checks if the user has system admin access

func (*Client) CreateModel 

func (c *Client) CreateModel(ctx context.Context, model ofgaclient.ClientWriteAuthorizationModelRequest) (string, error)

CreateModel creates a new authorization model and returns the new model ID

func (*Client) CreateModelFromDSL 

func (c *Client) CreateModelFromDSL(ctx context.Context, dsl []byte) (string, error)

CreateModelFromDSL creates a new fine grained authorization model from the DSL and returns the model ID

func (*Client) CreateModelFromFile 

func (c *Client) CreateModelFromFile(ctx context.Context, fn string, forceCreate bool) (string, error)

CreateModelFromFile creates a new fine grained authorization model and returns the model ID

func (*Client) CreateStore 

func (c *Client) CreateStore(ctx context.Context, storeName string) (string, error)

CreateStore creates a new fine grained authorization store and returns the store ID

func (*Client) DeleteAllObjectRelations 

func (c *Client) DeleteAllObjectRelations(ctx context.Context, object string, excludeRelations []string) error

DeleteAllObjectRelations deletes all the relationship tuples for a given object

func (*Client) GetModelID 

func (c *Client) GetModelID() string

func (*Client) ListObjectsRequest 

func (c *Client) ListObjectsRequest(ctx context.Context, req ListRequest) (*ofgaclient.ClientListObjectsResponse, error)

ListObjectsRequest creates the ClientListObjectsRequest and queries the FGA store for all objects with the user+relation

func (*Client) ListRelations 

func (c *Client) ListRelations(ctx context.Context, ac ListAccess) ([]string, error)

ListRelations returns the list of relations the user has with the object

func (*Client) ListUserRequest 

func (c *Client) ListUserRequest(ctx context.Context, req ListRequest) (*ofgaclient.ClientListUsersResponse, error)

ListUserRequest creates the ClientListUserRequest and queries the FGA store for all users with the object+relation

func (*Client) WriteTupleKeys 

func (c *Client) WriteTupleKeys(ctx context.Context, writes []TupleKey, deletes []TupleKey) (*ofgaclient.ClientWriteResponse, error)

WriteTupleKeys takes a tuples keys, converts them to a client write request, which can contain up to 10 writes and deletes, and executes in a single transaction

type Config 

type Config struct {
	// Enabled - checks this first before reading the config
	Enabled bool `json:"enabled" koanf:"enabled" jsonschema:"description=enables authorization checks with openFGA" default:"true"`
	// StoreName of the FGA Store
	StoreName string `json:"storeName" koanf:"storeName" jsonschema:"description=name of openFGA store" default:"openlane"`
	// HostURL of the fga API, replaces Host and Scheme settings
	HostURL string `` /* 143-byte string literal not displayed */
	// StoreID of the authorization store in FGA
	StoreID string `json:"storeId" koanf:"storeId" jsonschema:"description=id of openFGA store"`
	// ModelID that already exists in authorization store to be used
	ModelID string `json:"modelId" koanf:"modelId" jsonschema:"description=id of openFGA model"`
	// CreateNewModel force creates a new model, even if one already exists
	CreateNewModel bool `` /* 138-byte string literal not displayed */
	// ModelFile is the path to the model file
	ModelFile string `json:"modelFile" koanf:"modelFile" jsonschema:"description=path to the fga model file" default:"fga/model/openlane.fga"`
	// Credentials for the client
	Credentials Credentials `json:"credentials" koanf:"credentials" jsonschema:"description=credentials for the openFGA client"`
}

Config configures the openFGA setup

type Credentials 

type Credentials struct {
	// APIToken is the token to use for the client, required if using API token authentication
	APIToken string `` /* 139-byte string literal not displayed */
	// ClientID is the client ID to use for the client, required if using client credentials
	ClientID string `` /* 143-byte string literal not displayed */
	// ClientSecret is the client secret to use for the client, required if using client credentials
	ClientSecret string `` /* 155-byte string literal not displayed */
	// Audience is the audience to use for the client, required if using client credentials
	Audience string `json:"audience" koanf:"audience" jsonschema:"description=audience for the openFGA client"`
	// Issuer is the issuer to use for the client, required if using client credentials
	Issuer string `json:"issuer" koanf:"issuer" jsonschema:"description=issuer for the openFGA client"`
	// Scopes is the scopes to use for the client, required if using client credentials
	Scopes string `json:"scopes" koanf:"scopes" jsonschema:"description=scopes for the openFGA client"`
}

Credentials for the openFGA client

type Entity 

type Entity struct {
	Kind       Kind
	Identifier string
	Relation   Relation
}

Entity represents an entity/entity-set in OpenFGA. Example: `user:<user-id>`, `org:<org-id>#member`

func ParseEntity 

func ParseEntity(s string) (Entity, error)

ParseEntity will parse a string representation into an Entity. It expects to find entities of the form:

  • <entityType>:<Identifier> eg. organization:openlane
  • <entityType>:<Identifier>#<relationship-set> eg. organization:openlane#member

func (*Entity) String 

func (e *Entity) String() string

String returns a string representation of the entity/entity-set.

type InvalidEntityError 

type InvalidEntityError struct {
	EntityRepresentation string
}

InvalidEntityError is returned when an invalid openFGA entity is configured

func (*InvalidEntityError) Error 

func (e *InvalidEntityError) Error() string

Error returns the InvalidEntityError in string format

type Kind 

type Kind string

Kind represents the type of the entity in OpenFGA.

func (Kind) String 

func (k Kind) String() string

String implements the Stringer interface.

type ListAccess 

type ListAccess struct {
	// ObjectType is the type of object being checked
	ObjectType Kind
	// ObjectID is the ID of the object being checked
	ObjectID string
	// SubjectID is the ID of the user making the request
	SubjectID string
	// SubjectType is the type of subject being checked
	SubjectType string
	// Relations is the relationship being checked (e.g. "can_view", "can_edit", "can_delete")
	Relations []string
}

ListAccess is a struct to hold the information needed to list all relations

type ListRequest 

type ListRequest struct {
	// ObjectID is the identifier of the object that the subject is related to, required on ListUsers
	ObjectID string
	// ObjectType is the type of object that the subject is related to, required on ListUsers
	ObjectType string
	// SubjectID is the identifier of the subject that is related to the object, required on ListObjects
	SubjectID string
	// SubjectType is the type of subject that is related to the object, required on ListObjects
	SubjectType string
	// Relation is the relationship between the subject and object
	Relation string
}

ListRequest is the fields needed to list objects or users

type Option 

type Option func(c *Client)

Option is a functional configuration option for openFGA client

func WithAPITokenCredentials 

func WithAPITokenCredentials(token string) Option

WithAPITokenCredentials sets the credentials for the client with an API token

func WithAuthorizationModelID 

func WithAuthorizationModelID(authModelID string) Option

WithAuthorizationModelID sets the authorization model ID

func WithClientCredentials 

func WithClientCredentials(clientID, clientSecret, aud, issuer, scopes string) Option

WithClientCredentials sets the client credentials for the client with a client ID and secret

func WithStoreID 

func WithStoreID(storeID string) Option

WithStoreID sets the store IDs, not needed when calling `CreateStore` or `ListStores`

func WithToken 

func WithToken(token string) Option

WithToken sets the client credentials

type Relation 

type Relation string

Relation represents the type of relation between entities in OpenFGA.

func (Relation) String 

func (r Relation) String() string

String implements the Stringer interface.

type RelationCombination 

type RelationCombination string

RelationCombination is the combination of the relation as an `and`, `or`, or `not` 

const (
	// Union is an `or` relation
	Union RelationCombination = "union"
	// Intersection is an `and` relation
	Intersection RelationCombination = "intersection"
)

type RelationSetting 

type RelationSetting struct {
	// Relation is the relation to the object
	Relation string
	// IsDirect is the direct relation to another fga object type
	IsDirect bool
	// FromRelation is the relation from another relation, leave empty if not a from relation
	FromRelation string
}

RelationSetting includes the name of the relation as well as flags to determine the type of relation

type RoleRequest 

type RoleRequest struct {
	// Role is the relation to add to the model
	Role string
	// Relation is the relation to the object
	Relations []RelationSetting
	// RelationCombination is the combination of the relation
	RelationCombination RelationCombination
	// ObjectType is the object type to add the role to
	ObjectType string
}

RoleRequest is the request to add a role to the model for an existing object

type TupleKey 

type TupleKey struct {
	// Subject is the entity that is the subject of the relationship, usually a user
	Subject Entity
	// Object is the entity that is the object of the relationship, (e.g. organization, project, document, etc)
	Object Entity
	// Relation is the relationship between the subject and object
	Relation Relation `json:"relation"`
}

TupleKey represents a relationship tuple in OpenFGA

func GetTupleKey 

func GetTupleKey(req TupleRequest) TupleKey

GetTupleKey creates a Tuple key with the provided subject, object, and role

func NewTupleKey 

func NewTupleKey() TupleKey

type TupleRequest 

type TupleRequest struct {
	// ObjectID is the identifier of the object that the subject is related to
	ObjectID string
	// ObjectType is the type of object that the subject is related to
	ObjectType string
	// ObjectRelation is the tuple set relation for the object (e.g #member)
	ObjectRelation string
	// SubjectID is the identifier of the subject that is related to the object
	SubjectID string
	// SubjectType is the type of subject that is related to the object
	SubjectType string
	// SubjectRelation is the tuple set relation for the subject (e.g #member)
	SubjectRelation string
	// Relation is the relationship between the subject and object
	Relation string
}

TupleRequest is the fields needed to check a tuple in the FGA store

type WritingTuplesError 

type WritingTuplesError struct {
	User          string
	Relation      string
	Object        string
	Operation     string
	ErrorResponse error
}

WritingTuplesError is returned when an error is returned writing a relationship tuple

func (*WritingTuplesError) Error 

func (e *WritingTuplesError) Error() string

Error returns the InvalidEntityError in string format

Source Files

View all Source files

Directories

Path Synopsis
Package client includes the mock FGA client generated by testify mockery
 Package client includes the mock FGA client generated by testify mockery

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.