Go Authorization Library

Oso is a batteries-included library for building authorization in Go.

• It's embedded in your application—no extra processes to run.
• Oso uses your data models. Pass Go structs to Oso, and your authorization policy can refer to properties on those objects.
• Oso comes with built-in primitives for common authorization patterns like role-based access control (RBAC) and relationship-based access control (ReBAC).
• Oso provides APIs for yes/no authorization decisions, as well as authorization over list endpoints.

A single-line Go authorization API.

The Go authorization API is:

oso.Authorize(actor, action, resource)

Here's an example in a Go server:

oso.Authorize(GetCurrentUser(), "read", GetRepositoryByName(repoName))

Express your authorization model.

To model authorization with Oso, you write a policy in Polar, Oso’s declarative policy language.

For instance:

• Individual permissions take the form:

allow(actor, _action, _resource) if
  actor.Email = "alice@example.com";

• RBAC means grouping permissions into roles (e.g., User, Moderator, and Admin roles—or whichever roles your app needs), and assigning those roles to users. Oso supports role-based access control (RBAC) natively.

allow(actor, action, resource) if has_permission(actor, action, resource);

has_role(actor: User, role_name: String, post: Post) if
  role in actor.Roles and
  role_name = role.Name and
  post = role.Post;

actor User {}

resource Post {
  permissions = ["read", "edit", "delete"];
  roles = ["user", "moderator", "admin"];

  "read" if "user";
  "edit" if "moderator";
  "delete" if "admin";

  "user" if "moderator";
  "moderator" if "admin";
}

For an implementation guide, read our guide on building role-based access control with Oso, or for background reading, see our technology-agnostic Authorization Academy guide to RBAC.

• Relationship-based authorization, or ReBAC, means organizing permissions based on relationships between resources. For instance, allowing only the user who created a post to edit it. Relationships include data ownership, parent-child relationships, groups, and hierarchies. Oso provides primitives for hierarchies, relationship-based access control (ReBAC) and attribute-based access control (ABAC).

allow(actor, action, resource) if has_permission(actor, action, resource);

resource Organization {
    permissions = ["read", "add_member"];
    roles = ["member", "owner"];
}

resource Repository {
    permissions = ["read", "push"];
    roles = ["contributor", "maintainer", "admin"];
    relations = { parent: Organization };

    "admin" if "owner" on "parent";
}

For a guide on parent-child implementing role relationships like the one shown above, see our documentation on granting a role on a child resource to a role on the parent. For a guide to building resource hierarchies (e.g., things that look like filesystems), take a look at our guide on building authorization for resource hierarchies. You can also read our technology-agnostic Authorization Academy guide to ReBAC.

Test your authorization.

You can test the surface of your policy by testing the return value of your Oso.authorize call. Here's an example with the testing package:

func TestMaintainersCannotDeleteRepos(t *testing.T) {
    repo := Repository{ Id: 1, Name: "oso" }
    user := RepositoryRole{ Role: "maintainer", RepoId: 1 }
    e := oso.Authorize(user, "delete", repo)
    if e == nil {
        t.Error("expected an error, got nil")
    }
    _, te := e.(*errors.NotFoundError)
    if !te {
        t.Error("expected a NotFoundError")
    }
}

You can also query individual policy rules to rest them. This allows you to TDD your authorization.

Learn authorization concepts, architecture, and best practices.

We've written the Authorization Academy to help you get started with authorization. These guides aren't specific to Oso, and cover industry-standard authorization concepts. Learn:

• Patterns for authorization in microservices
• How to architect your app for authorization.
• Common authorization models like role-based access control (RBAC) and relationship-based access control (ReBAC) – like when to use them and how to implement them.
• Where to enforce authorization at various layers in your app.

How to get started

Add Oso to your app with go get [github.com/osohq/go-oso](http://github.com/osohq/go-oso), then start modeling your authorization logic.

If you’re building a microservices-based app, you may find Oso Cloud useful. Feel free to set up a 1x1 with an Oso engineer to learn more about it.

Then, join the community of hundreds of developers in the Oso Slack! We'd love to talk about what you're working on and answer any questions you have.