oso

README

Oso Cloud Client for Go

The Oso Cloud client for Go provides a convenient wrapper around the Oso Cloud HTTP API for applications and services written in Go.

What is Oso Cloud?

Oso Cloud is authorization-as-a-service. It provides abstractions for building and iterating on authorization in your application – based on years of work with hundreds of engineering teams.

• Model: Build your authorization model using primitives for common patterns like multi-tenancy and RBAC. Express custom rules using Polar, a declarative policy language for authorization.

• Store: Store your authorization data using a best-practices data model and use it for access decisions across all of your services.

• Enforce & Query: Add enforcement calls to your application to perform yes/no permission checks, filter resources by permissions, list a user's roles, and show/hide pieces of your UI.

• Test & Watch: Write tests over your authorization policies before you push them live. See logs of authorization decisions in real time.

For more information on how Oso Cloud works and how it fits into your architecture, check out the introduction.

Documentation

• To get up and running with Oso Cloud, try the Quickstart guide.
• For method-level documentation, see the Go Client API documentation.
• Full documentation is available at osohq.com/docs.
• To learn about authorization best practices (not specific to Oso), read the Authorization Academy guides.

Community & Support

If you have any questions on Oso Cloud or authorization more generally, you can join our engineering team & hundreds of other developers using Oso in our community Slack:

Documentation

Overview

Oso Client cloud for Golang. For more detailed documentation, see https://www.osohq.com/docs/reference/client-apis/go

Index

• type AuthorizeResult
• type Fact
• type Instance
  • func Boolean(b bool) Instance
  • func Integer(i int64) Instance
  • func String(s string) Instance
• type OsoClient
  • func NewClient(url string, apiKey string) OsoClient
  • func NewClientWithDataBindings(url string, apiKey string, dataBindings string) OsoClient
  • func NewClientWithFallbackUrl(url string, apiKey string, fallbackUrl string) OsoClient
  • func NewClientWithFallbackUrlAndDataBindings(url string, apiKey string, fallbackUrl string, dataBindings string) OsoClient
  • func NewClientWithFallbackUrlAndLogger(url string, apiKey string, fallbackUrl string, logger interface{}) OsoClient
  • func NewClientWithFallbackUrlAndLoggerAndDataBindings(url string, apiKey string, fallbackUrl string, logger interface{}, ...) OsoClient
  • func NewClientWithLogger(url string, apiKey string, logger interface{}) OsoClient
  • func NewClientWithLoggerAndDataBindings(url string, apiKey string, logger interface{}, dataBindings string) OsoClient
• type PolicyMetadata
• type ResourceMetadata

Types

type AuthorizeResult

type AuthorizeResult authorizeResult

type Fact

type Fact struct {
	Name string
	Args []Instance
}

type Instance

type Instance struct {
	Type string
	ID   string
}

func Boolean

func Boolean(b bool) Instance

func Integer

func Integer(i int64) Instance

func String

func String(s string) Instance

type OsoClient

type OsoClient interface {
	// List authorized actions:
	// Fetches a list of actions which an actor can perform on a particular resource.
	Actions(actor Instance, resource Instance) ([]string, error)

	// List authorized actions for a list of resources
	// Fetches a list of actions which an actor can perform on a list of resources.
	//
	// Note: this only works for resources of the same type.
	BulkActions(actor Instance, resources []Instance, context_facts []Fact) ([][]string, error)

	// List authorized actions:
	// Fetches a list of actions which an actor can perform on a particular resource, considering the given context facts.
	ActionsWithContext(actor Instance, resource Instance, context_facts []Fact) ([]string, error)

	// Check a permission:
	// Determines whether or not an action is allowed, based on a combination of authorization data and policy logic.
	Authorize(actor Instance, action string, resource Instance) (bool, error)

	// Check authorized resources:
	// Returns a subset of resources on which an actor can perform a particular action.
	// Ordering and duplicates, if any exist, are preserved.
	AuthorizeResources(actor Instance, action string, resources []Instance) ([]Instance, error)

	// Check authorized resources:
	// Returns a subset of resources on which an actor can perform a particular action, considering the given context facts.
	// Ordering and duplicates, if any exist, are preserved.
	AuthorizeResourcesWithContext(actor Instance, action string, resources []Instance, context_facts []Fact) ([]Instance, error)
	// Check a permission:
	// Determines whether or not an action is allowed, based on a combination of authorization data (including the given context facts) and policy logic.
	AuthorizeWithContext(actor Instance, action string, resource Instance, context_facts []Fact) (bool, error)

	// Transactionally delete and add facts:
	// Deletes and adds many facts in one atomic transaction. The deletions are performed before the adds.
	// Does not throw an error when the facts to delete are not found.
	Bulk(delete []Fact, tell []Fact) error

	// Delete many facts:
	// Deletes many facts at once. Does not throw an error when some of the facts are not found.
	BulkDelete(facts []Fact) error

	// Add many facts:
	// Adds many facts at once.
	BulkTell(facts []Fact) error

	// Delete fact:
	// Deletes a fact. Does not throw an error if the fact is not found.
	Delete(predicate string, args ...Instance) error

	// List facts:
	// Lists facts that are stored in Oso Cloud. Can be used to check the existence of a particular fact, or used to fetch all facts that have a particular argument.
	Get(predicate string, args ...Instance) ([]Fact, error)

	// List authorized resources:
	// Fetches a list of resource ids on which an actor can perform a particular action.
	List(actor Instance, action string, resource string, context_facts []Fact) ([]string, error)

	// List authorized resources:
	// Fetches a list of resource ids on which an actor can perform a particular action, considering the given context facts.
	ListWithContext(actor Instance, action string, resource string, context_facts []Fact) ([]string, error)

	// Update the active policy:
	// Updates the policy in Oso Cloud. The string passed into this method should be written in Polar.
	Policy(policy string) error

	// Returns metadata about the currently active policy
	GetPolicyMetadata() (*PolicyMetadata, error)

	// Query Oso Cloud:
	// Query Oso Cloud for any predicate, and any combination of concrete and
	// wildcard arguments.
	Query(predicate string, args ...*Instance) ([]Fact, error)

	// Add fact:
	// Adds a fact named predicate with the provided arguments.
	Tell(predicate string, args ...Instance) error

	// Check a permission depending on data both in Oso Cloud and stored in a local database:
	// Returns a SQL query to run against the local database.
	AuthorizeLocal(actor Instance, action string, resource Instance) (string, error)

	// List authorized resources depending on data both in Oso Cloud and stored in a local database:
	// Returns a SQL query to run against the local database.
	ListLocal(actor Instance, action string, resource string, column string) (string, error)

	// Fetches a query that can be run against your database to determine the actions
	// an actor can perform on a resource.
	// Returns a SQL query to run against the local database.
	ActionsLocal(actor Instance, resource Instance) (string, error)
}

func NewClient

func NewClient(url string, apiKey string) OsoClient

Create a new default Oso client

func NewClientWithDataBindings

func NewClientWithDataBindings(url string, apiKey string, dataBindings string) OsoClient

func NewClientWithFallbackUrl

func NewClientWithFallbackUrl(url string, apiKey string, fallbackUrl string) OsoClient

Create a new Oso client with a fallback URL configured

func NewClientWithFallbackUrlAndDataBindings

func NewClientWithFallbackUrlAndDataBindings(url string, apiKey string, fallbackUrl string, dataBindings string) OsoClient

func NewClientWithFallbackUrlAndLogger

func NewClientWithFallbackUrlAndLogger(url string, apiKey string, fallbackUrl string, logger interface{}) OsoClient

func NewClientWithFallbackUrlAndLoggerAndDataBindings

func NewClientWithFallbackUrlAndLoggerAndDataBindings(url string, apiKey string, fallbackUrl string, logger interface{}, dataBindings string) OsoClient

Create a new Oso client with a fallbackURL and custom logger

See https://pkg.go.dev/github.com/hashicorp/go-retryablehttp@v0.7.1#LeveledLogger for documentation on the logger interfaces supported.

func NewClientWithLogger

func NewClientWithLogger(url string, apiKey string, logger interface{}) OsoClient

Create a new Oso client with a custom logger

See https://pkg.go.dev/github.com/hashicorp/go-retryablehttp@v0.7.1#LeveledLogger for documentation on the logger interfaces supported.

func NewClientWithLoggerAndDataBindings

func NewClientWithLoggerAndDataBindings(url string, apiKey string, logger interface{}, dataBindings string) OsoClient

type PolicyMetadata

type PolicyMetadata struct {
	Resources map[string]ResourceMetadata `json:"resources"`
}

type ResourceMetadata

type ResourceMetadata struct {
	Permissions []string          `json:"permissions"`
	Roles       []string          `json:"roles"`
	Relations   map[string]string `json:"relations"`
}