Go v1 Client API
The Go v2 client is released! Bugfixes and security patches will be backported to v1, and there is currently no end-of-life date. However, we recommend migrating to the v2 client to take advantage of new features and improvements.
Before going through this guide, make sure you follow the Oso Cloud Quickstart to get your Oso Cloud API Key properly set in your environment.
First, install the go-oso-cloud
package:
go get github.com/osohq/go-oso-cloud
Instantiating an Oso Cloud client
The Oso Cloud client provides an oso.NewClient
function that takes your Oso Cloud URL and API key:
import ( ... oso "github.com/osohq/go-oso-cloud")osoClient := oso.NewClient("https://cloud.osohq.com", YOUR_API_KEY)// Later:e := osoClient.Tell("has_role", user, role, resource)if e != nil { // Handle error.}// Wherever authorization needs to be performed:allowed, e := osoClient.Authorize(user, action, resource)if e != nil { // Handle error.}if allowed { // Action is allowed.}
You should instantiate one client and share it across your application. Under the hood, it reuses connections to avoid paying the cost of negotiating a new connection on every request.
Specifying an Oso Fallback host
If you have deployed Oso Fallback nodes to your infrastructure, you may specify the host when instantiating the Oso Cloud client.
// Assumes Oso Fallback is hosted at http://localhost:8080osoClient := oso.NewClientWithFallbackUrl("https://cloud.osohq.com", YOUR_API_KEY, "http://localhost:8080")
Passing application entities into the client
Under the hood, Oso Cloud represents an entity in your application as a combination of a type and an ID, which together uniquely identify the entity.
The Go client represents these entities as oso.Instance
structs with both Type
and ID
properties.
For example:
alice := oso.Instance{Type: "User", ID: "alice"}anvilsRepository := oso.Instance{Type: "Repository", ID: "anvils"}
You will pass structs like these into nearly every function call you make to the Go client.
Centralized Authorization Data API
Oso Cloud clients provide an API to manage authorization data stored directly in Oso Cloud.
Add fact: osoClient.Tell(name, ...args)
Adds a fact named name
with the provided arguments. Example:
osoClient.Tell( "has_role", oso.Instance{Type: "User", ID: "bob"}, oso.String("owner"), oso.Instance{Type: "Organization", ID: "acme"})
Add many facts: osoClient.BulkTell(facts)
For Oso Cloud developer accounts, BulkTell
, BulkDelete
, and Bulk
calls
are limited to 20 facts. If you attempt to send more than 20 facts, the CLI
will return an error.
Adds many facts at once. Example:
osoClient.bulkTell([]oso.Fact{ { Name: "has_role", Args: []oso.Instance{ oso.Instance{Type: "User", ID: "bob"}, oso.String("owner"), oso.Instance{Type: "Organization", ID: "acme"}, } }, { Name: "has_role", Args: []oso.Instance{ oso.Instance{Type: "User", ID: "bob"}, oso.String("maintainer"), oso.Instance{Type: "Repository", ID: "anvil"}, } },})
Delete fact: osoClient.Delete(name, ...args)
Deletes a fact. Does not throw an error if the fact is not found. Example:
osoClient.Delete( "has_role", oso.Instance{Type: "User", ID: "bob"}, oso.String("maintainer"), oso.Instance{Type: "Repository", ID: "anvil"})
Delete many facts: osoClient.BulkDelete(facts)
Deletes many facts at once. Does not throw an error when some of the facts are not found. Example:
osoClient.BulkDelete([]oso.Fact{ oso.Fact{ Name: "has_role", Args: []oso.Instance{ oso.Instance{Type: "User", ID: "bob"}, oso.String("owner"), oso.Instance{Type: "Organization", ID: "acme"} }, }, oso.Fact{ Name: "has_role", Args: []oso.Instance{ oso.Instance{Type: "User", ID: "bob"}, oso.String("maintainer"), oso.Instance{Type: "Repository", ID: "anvil"} }, },})
Transactionally delete and add facts: oso.Bulk(delete, tell)
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. Example:
oso.Bulk([]oso.Fact{ oso.Fact{ Name: "has_role", Args: []oso.Instance{ oso.Instance{Type: "User", ID: "bob"}, oso.String("viewer"), oso.Instance{Type: "Repository", ID: "anvil"} }, }}, []oso.Fact{ oso.Fact{ Name: "has_role", Args: []oso.Instance{ oso.Instance{Type: "User", ID: "bob"}, oso.String("maintainer"), oso.Instance{Type: "Repository", ID: "anvil"} }, }})
List facts: oso.Get(name, ...args)
For Oso Cloud developer accounts, Get
calls are limited to 1000 results. If
you have more than 1000 facts, the function will return an error.
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 one fact:oso.Get( "has_role", oso.Instance{Type: "User", ID: "bob"}, oso.String("admin"), oso.Instance{Type: "Repository", ID: "anvils"})// => []oso.Fact{oso.Fact{// Name: "has_role",// Args: []oso.Instance{// {Type: "User", ID: "bob"},// {Type: "String", ID: "admin"},// {Type: "Repository", ID: "anvils"}// }// }}// List all roles on the `anvils` repooso.Get("has_role", oso.Instance{Type: "User"}, oso.Instance{}, oso.Instance{Type: "Repository", ID: "anvils"})// => []oso.Fact{oso.Fact{// Name: "has_role",// Args: []oso.Instance{// {Type: "User", ID: "bob"},// {Type: "String", ID: "admin"},// {Type: "Repository", ID: "anvils"}// }// },// ...other has_role facts// }
Note that nil
fields for Type
or ID
behave like a wildcard: the above
means "find all has_role
facts where the first argument is a User
and the
Repository:anvils
is the third argument.".
Check API
For Oso Cloud developer accounts, the number of context facts per request is limited to 20; and the number of records returned is limited to 1000.
Context facts
The Check AP lets you provide context facts with each request. When Oso Cloud performs a check, it considers the request's context facts in addition to any other centralized authorization data. Context facts are only used in the API call in which they're provided-- they do not persist across requests.
For more details, see Context Facts.
Check a permission: osoClient.Authorize(actor, action, resource)
Determines whether or not an action is allowed, based on a combination of authorization data and policy logic. Example:
allowed, e := osoClient.Authorize(user, "read", anvilsRepository)if e != nil { // Handle error.}if allowed { // Action is allowed.}
You may use osoClient.AuthorizeWithContext
to provide a slice of context facts.
Example:
allowed, e := osoClient.AuthorizeWithContext(user, "read", issueOnAnvilsRepository, []Fact{ { // a context fact Name: "has_relation", Args: []oso.Instance{issueOnAnvilsRepository, oso.String("parent"), anvilsRepository}, },})
Check authorized resources: osoClient.AuthorizeResources(actor, action, resources)
Returns a subset of resources
on which an actor can perform a particular action.
Ordering and duplicates, if any exist, are preserved.
For Oso Cloud developer accounts, the number of input resources is limited to 1000.
Example:
results, e := osoClient.AuthorizeResources(user, "read", []oso.Instance{anvilsRepository, acmeRepository})
You may use osoClient.AuthorizeResourcesWithContext
to provide a slice of context facts.
Example:
results, e := osoClient.AuthorizeResourcesWithContext(user, "read", []oso.Instance{issueOnAnvilsRepository, issueOnAcmeRepository}, []Fact{ // context facts { Name: "has_relation", Args: []oso.Instance{issueOnAnvilsRepository, oso.String("parent"), anvilsRepository}, }, { Name: "has_relation", Args: []oso.Instance{issueOnAcmeRepository, oso.String("parent"), acmeRepository}, },})
List authorized resources: osoClient.List(actor, action, resourceType)
Fetches a list of resource IDs on which an actor can perform a particular action. Example:
repositoryIds, e := osoClient.List(user, "read", "Repository")
You may use osoClient.ListWithContext
to provide a slice of context facts.
Example:
repositoryIds, e := osoClient.ListWithContext(user, "read", "Issue", []Fact{ // context facts Fact{ Name: "has_relation", Args: []oso.Instance{issueOnAnvilsRepository, oso.String("parent"), anvilsRepository}, }, { Name: "has_relation", Args: []oso.Instance{issueOnAcmeRepository, oso.String("parent"), acmeRepository}, },})
List authorized actions: osoClient.Actions(actor, resource)
Fetches a list of actions which an actor can perform on a particular resource. Example:
actions, e := osoClient.Actions(user, anvilsRepository)
You may use osoClient.ActionsWithContext
to provide a slice of context facts.
Example:
actions, e := osoClient.ActionsWithContext(user, issueOnAnvilsRepository, []Fact{ { // a context fact Name: "has_relation", Args: []oso.Instance{issueOnAnvilsRepository, oso.String("parent"), anvilsRepository}, },})
Query for anything: oso.Query(rule)
Query Oso Cloud for any predicate and any combination of concrete and wildcard arguments.
Unlike oso.Get
, which only lists facts you've added, you can use oso.query
to list derived
information about any rule in your policy.
Example:
// Query for all the repos `User:bob` can `read`osoClient.Query( "allow", &oso.Instance{Type: "User", ID: "bob"}, &oso.String("read"), &oso.Instance{Type: "Repository"})// => []oso.Fact{{// Name: "allow",// Args: []oso.Instance{// {Type: "User", ID: "bob"},// {Type: "String", ID: "read"},// {Type: "Repository", ID: "acme"}// }// }, {// Name: "allow",// Args: []oso.Instance{// {Type: "User", ID: "bob"},// {Type: "String", ID: "read"},// {Type: "Repository", ID: "anvils"}// }// }// Query for all the objects `User:admin` can `read`osoClient.Query( "allow", &oso.Instance{Type: "User", ID: "admin"}, &oso.String("read"), nil)// => []oso.Fact{{// // `User:admin` can `read` anything// Name: "allow",// Args: []oso.Instance{// oso.Instance{Type: "User", ID: "admin"},// oso.Instance{Type: "String", ID: "read"},// nil// }// }}
Note that nil
behaves like a wildcard. Passing "allow", nil, nil, anvils
means "find
anyone who can do anything to anvils
". nil
also behaves like a wildcard
in return values from osoClient.Query
. Additionally, if you want to query over
all instances of a particular type, pass an oso.Instance
with a Type
but no ID
. For example, "allow", bob, "read", oso.Instance{Type: "Repository"}
will query for all the objects of type "Repository"
that bob
can read
.
Learn more about how to query Oso Cloud.
Local Check API
The local check API lets you perform authorization using data that's distributed across Oso Cloud and your own database.
After creating your local authorization configuration, provide the path to the YAML file that specifies how to resolve facts in your database.
osoClient = oso.NewClientWithDataBindings(..., "path/to/data_bindings.yaml");
For more information, see Local Authorization.
List authorized resources with local data: osoClient.ListLocal(actor, action, resourceType, column)
Fetches a filter that can be applied to a database query to return just the resources on which an actor can perform an action. Example with GORM (opens in a new tab):
var issues []Issuedb.Find(&issues, osoClient.ListLocal(user, "read", "Issue", "id"))
You may use the GORM query interface (opens in a new tab) to combine this authorization filter with other things such as ordering and pagination.
Check a permission with local data: osoClient.AuthorizeLocal(actor, action, resource)
Fetches a query that can be run against your database to determine whether an actor can perform an action on a resource. Example with GORM (opens in a new tab):
var authorizeResult AuthorizeResultdb.Raw(osoClient.AuthorizeLocal(alice, "read", swageIssue)).Scan(&authorizeResult)if (!authorizeResult.Allowed) { throw new Error("Action is not allowed");}
List authorized actions with local data: osoClient.ActionsLocal(actor, resource)
Fetches a query that can be run against your database to fetch the actions an actor can perform on a resource. Example with GORM (opens in a new tab):
query, err := osoClient.ActionsLocal(alice, swageIssue)if err != nil { ...}var actions []stringdb.Raw(query).Pluck("actions", &actions)
Policy API
Update the active policy: oso.Policy(policy)
Updates the policy in Oso Cloud. The string passed into this method should be written in Polar. Example:
e := oso.Policy("actor User {}")
This command will run any tests defined in your policy. If one or more of these tests fail, your policy will not be updated.
Get policy metadata: oso.GetPolicyMetadata()
Returns metadata about the currently active policy. Example:
metadata, err := oso.getPolicyMetadata();
returns:
PolicyMetadata{ Resources: map[string]ResourceMetadata{ "Organization": { Permissions: []string{ "add_member", "read", "repository.create", "repository.delete", "repository.read", }, Roles: []string{"admin", "member"}, Relations: map[string]string{ "parent": "Organization", }, }, "User": { Permissions: []string{}, Roles: []string{}, Relations: map[string]string{}, }, "global": { Permissions: []string{}, Roles: []string{}, Relations: map[string]string{}, }, },}
See the Policy Metadata guide for more information on use cases.
Talk to an Oso Engineer
If you'd like to learn more about using Oso Cloud in your app or have any questions about this guide, schedule a 1x1 with an Oso engineer. We're happy to help.
query]: /app-integration/integrate-authorization/query-oso-cloud "Query Oso Cloud"