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
- Variables
- func GetEntityIDs(l *ofgaclient.ClientListObjectsResponse) ([]string, error)
- func Healthcheck(client Client) func(ctx context.Context) error
- func ListContains(entityType string, l []string, i string) bool
- type AccessCheck
- type Client
- func (c *Client) AddOrReplaceRole(ctx context.Context, r RoleRequest) error
- func (c *Client) BatchCheckObjectAccess(ctx context.Context, checks []AccessCheck) ([]string, error)
- func (c *Client) CheckAccess(ctx context.Context, ac AccessCheck) (bool, error)
- func (c *Client) CheckAccessHighConsistency(ctx context.Context, ac AccessCheck) (bool, error)
- func (c *Client) CheckGroupAccess(ctx context.Context, ac AccessCheck) (bool, error)
- func (c *Client) CheckOrgAccess(ctx context.Context, ac AccessCheck) (bool, error)
- func (c *Client) CheckOrgReadAccess(ctx context.Context, ac AccessCheck) (bool, error)
- func (c *Client) CheckOrgWriteAccess(ctx context.Context, ac AccessCheck) (bool, error)
- func (c *Client) CheckSystemAdminRole(ctx context.Context, userID string) (bool, error)
- func (c *Client) CreateModel(ctx context.Context, model ofgaclient.ClientWriteAuthorizationModelRequest) (string, error)
- func (c *Client) CreateModelFromDSL(ctx context.Context, dsl []byte) (string, error)
- func (c *Client) CreateModelFromFile(ctx context.Context, fn string, forceCreate bool) (string, error)
- func (c *Client) CreateStore(storeName string) (string, error)
- func (c *Client) DeleteAllObjectRelations(ctx context.Context, object string, excludeRelations []string) error
- func (c *Client) GetModelID() string
- func (c *Client) ListObjectsRequest(ctx context.Context, req ListRequest) (*ofgaclient.ClientListObjectsResponse, error)
- func (c *Client) ListRelations(ctx context.Context, ac ListAccess) ([]string, error)
- func (c *Client) ListUserRequest(ctx context.Context, req ListRequest) (*ofgaclient.ClientListUsersResponse, error)
- func (c *Client) UpdateConditionalTupleKey(ctx context.Context, tuple TupleKey) (*ofgaclient.ClientWriteResponse, error)
- func (c *Client) WriteTupleKeys(ctx context.Context, writes []TupleKey, deletes []TupleKey) (*ofgaclient.ClientWriteResponse, error)
- type Condition
- type Config
- type Credentials
- type Entity
- type InvalidEntityError
- type Kind
- type ListAccess
- type ListRequest
- type Option
- func WithAPITokenCredentials(token string) Option
- func WithAuthorizationModelID(authModelID string) Option
- func WithClientCredentials(clientID, clientSecret, aud, issuer, scopes string) Option
- func WithIgnoreDuplicateKeyError(ignore bool) Option
- func WithStoreID(storeID string) Option
- func WithToken(token string) Option
- type Relation
- type RelationCombination
- type RelationSetting
- type RoleRequest
- type TupleKey
- type TupleRequest
- type WritingTuplesError
Constants ¶
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" // Wildcard allows for public access (any subject) // see: https://openfga.dev/docs/modeling/public-access // not allowed on the object side Wildcard = "*" // 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" // CanViewAuditLog is the relation for viewing the audit log of an entity CanViewAuditLog = "audit_log_viewer" )
setup relations for use in creating tuples
Variables ¶
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 ¶
Healthcheck reads the model to check if the connection is working
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 // Context is the context of the request used for conditional relationships Context *map[string]any }
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 // IgnoreDuplicateKeyError ignores the error when a key already exists or a delete request is made for a non-existent key IgnoreDuplicateKeyError bool }
Client is an ofga client with some configuration
func CreateFGAClientWithStore ¶
CreateFGAClientWithStore returns a Client with a store and model configured
func NewClient ¶
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(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) BatchCheckObjectAccess ¶ added in v0.9.4
func (c *Client) BatchCheckObjectAccess(ctx context.Context, checks []AccessCheck) ([]string, error)
BatchCheckObjectAccess checks if the user has access to the list of objects with the given relation It returns a list of objects id (e.g. 01JPWNAGM9S61G57DS364MFKGX) that the user has access to
func (*Client) CheckAccess ¶
CheckAccess checks if the user has access to the object type with the given relation
func (*Client) CheckAccessHighConsistency ¶ added in v0.14.0
CheckAccess checks if the user has access to the object type with the given relation
func (*Client) CheckGroupAccess ¶
CheckGroupAccess checks if the user has access to the group with the given relation
func (*Client) CheckOrgAccess ¶
CheckOrgAccess checks if the user has access to the organization with the given relation
func (*Client) CheckOrgReadAccess ¶
CheckOrgReadAccess checks if the user has read access to the organization
func (*Client) CheckOrgWriteAccess ¶
CheckOrgWriteAccess checks if the user has write access to the organization
func (*Client) CheckSystemAdminRole ¶
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 ¶
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 ¶
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 (*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 ¶
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) UpdateConditionalTupleKey ¶ added in v0.8.0
func (c *Client) UpdateConditionalTupleKey(ctx context.Context, tuple TupleKey) (*ofgaclient.ClientWriteResponse, error)
UpdateConditionalTupleKey will take a tuple key and delete the existing tuple and create a new tuple with the same key this is useful for updating a tuple with a condition because fga does not support conditional updates Because the delete doesn't take into account conditions, you can use the same key to delete the existing tuple It will return the response from the write request
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 Condition ¶ added in v0.8.0
type Condition struct { // Name of the relationship condition Name string // Context settings for the relationship condition Context *map[string]any }
Condition represents the type of relation condition for openFGA types
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/model.fga"` // Credentials for the client Credentials Credentials `json:"credentials" koanf:"credentials" jsonschema:"description=credentials for the openFGA client"` // IgnoreDuplicateKeyError ignores the error when a key already exists or a delete request is made for a non-existent key IgnoreDuplicateKeyError bool `` /* 129-byte string literal not displayed */ }
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 `` /* 156-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 `` /* 172-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 ¶
Entity represents an entity/entity-set in OpenFGA. Example: `user:<user-id>`, `org:<org-id>#member`
func ParseEntity ¶
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
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 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 // Context is the context of the request used for conditional relationships Context *map[string]any }
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 // ConditionContext for the relationship ConditionContext *map[string]any }
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 ¶
WithAPITokenCredentials sets the credentials for the client with an API token
func WithAuthorizationModelID ¶
WithAuthorizationModelID sets the authorization model ID
func WithClientCredentials ¶
WithClientCredentials sets the client credentials for the client with a client ID and secret
func WithIgnoreDuplicateKeyError ¶ added in v0.7.4
WithIgnoreDuplicateKeyError sets whether the client should ignore duplicate key errors
func WithStoreID ¶
WithStoreID sets the store IDs, not needed when calling `CreateStore` or `ListStores`
type Relation ¶
type Relation string
Relation represents the type of relation between entities in OpenFGA.
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"` // Condition for the relationship Condition Condition `json:"condition,omitempty"` }
TupleKey represents a relationship tuple in OpenFGA
func CreateWildcardViewerTuple ¶ added in v0.8.5
CreateWildcardViewerTuple creates a wildcard tuple with view access the provided object and role for users and service e.g user:* and service:*
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 // ConditionName for the relationship ConditionName string // ConditionContext for the relationship ConditionContext *map[string]any }
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