Open Policy Agent, Part I - The Introduction

recently i was looking for a way to implement access control for microservices. i needed a solution that would allow defining complex authorization rules that could be enforced across many services. after searching the web, i discovered a very promising open policy agent project that seems to be the right tool for the job. in this series of three blog posts, i am going to introduce open policy agent to you and highlight how it can help you.

what is open policy agent?

open policy agent (opa) is a policy engine that can be used to implement fine-grained access control for your application. for example, you can use opa to implement authorization across microservices. however, there is much more that can be accomplished with opa.

for your inspiration, there are several open source projects that integrate with opa to implement fine-grained access control like docker , istio and others . furthermore, opa as a general-purpose policy engine, can be leveraged in use cases beyond access control, for instance to make advanced pod placement decisions in kubernetes .

you may also like: application and data security.

opa can be deployed as a standalone service along with your microservices. in order to protect your application, each request coming to a microservice must be authorized before it can be processed. to check the authorization, the microservice makes an api call to opa to decide whether the request is authorized or not.

note, that while you can offload authorization decisions from your application to opa, your application still has to implement the enforcement of those decisions. for example, your application can ask opa the question, "is user alice allowed to invoke get /protected/resource?" and if opa answers "no" , your application has to send http 403 forbidden back to alice.

opa is written in go languagem, and its source code is available on github under the apache license 2.0. the open policy agent project is hosted by cncf as an incubating project.

making policy decisions

in this section, i am going to explain how opa works. don't worry if everything is not clear to you right away. in the following section, we are going to work through a practical example that will help clarify the details.

what does it take for opa to make a policy decision? in opa, there are three inputs into the decision-making process:

1. data is a set of facts about the outside world that opa refers to while making a decision. for example, when controlling access based on the access control list, the data would be a list of users along with the permissions they were granted.
   
   another example: when deciding where to place the next pod on the kubernetes cluster, the data would be a list of kubernetes nodes and their currently available capacity. note that data may change over time, and opa caches its latest state in memory. the data must be provided to opa in the json format.
2. query input triggers the decision computation. it specifies the question that opa should decide upon. the query input must be formatted as json. for instance, for the question "is user alice allowed to invoke get /protected/resource?" the query input would contain parameters: alice , get , and /protected/resource .
3. policy specifies the computational logic that, for the given data and query input , yields a policy decision a.k.a. the query result. the computational logic is described as a set of policy rules in the opa's custom policy language called rego . note that opa doesn't come with any pre-defined policies. opa is a policy engine that is able to interpret a policy; however, in order to make use of it you have to create a policy yourself and provide it to opa.

in order to make a policy decision, all three inputs (data, query input, and the policy) are fed into the policy engine. the policy engine interprets the rules included in the policy and based on the data and the query input makes a policy decision. the policy decision generated by the policy engine is a json document.

that is how opa works from a high-level perspective. in the next section, we will dive into a practical example.

hands-on tutorial

this section is a hands-on tutorial where i will walk you through an example of working with opa. although all sorts of access control models can be implemented using opa, the goal of this exercise is to implement access control using an access control list (acl). so, let's get started!

creating data

access control list specifies which users have access to the application, as well as what operations they are allowed to invoke. for the purposes of this tutorial, i came up with a simple acl definition:

{
  "alice": [
    "read",
    "write"
  ],
  "bob": [
    "read"
  ]
}

according to this acl, a user named alice was granted read and write access to the application. in addition, a user named bob was given read access. no other users were given any access to the application. for now, you can save this acl definition as a file called myapi-acl.json .

note that later on we are going to inject this access control list as data into opa to allow it to make policy decisions based on this list. how did we know what the structure of the acl document looks like? as a matter of fact, opa doesn't prescribe how you should structure your data. it only requires the data to be in a json format. the recommendation is to structure your data in a way that makes it easy to write policy rules against it. i followed this recommendation and the above access control list is what i came up with.

defining query input

next, we are going to define a structure of the query input . on each access to our application, we are going to ask opa whether the given access is authorized or not. to answer that question, opa needs to know the name of the user that is trying to access the application and the operation that the user is trying to invoke. here is a sample query input that conveys the two query arguments to opa:

{
  "input": {
    "user": "alice",
    "operation": "write"
  }
}

you can interpret this query input as the question: "is user alice allowed write access to the application?" note that it's up to you how you structure your query input. opa's only requirement is for the input to be in the json format.

writing rego policy

after we decided how our data and the query input look like, we can create a policy that implements the acl semantics. using the rego language, let's create a policy with two rules allow and whocan :

package myapi.policy

import data.myapi.acl
import input

default allow = false

allow {
        access = acl[input.user]
        access[_] == input.access
}

whocan[user] {
        access = acl[user]
        access[_] == input.access
}

the allow rule checks whether the user is allowed access according to the acl. it instructs the policy engine to first look up the user's record in acl and then to check whether the operation the user is trying to invoke is included on user's permission list. only if there is an acl record for the given user and the user was granted given access permission. the allow rule outputs true . otherwise, it returns false .

the second rule in our policy is the whocan rule. this rule takes the operation as the input argument. for the given operation, the whocan rule returns a list of all users that are allowed to invoke the given operation.

you can save the above policy as a file called myapi-policy.rego . we are going to upload it into opa in just a moment. at this point, both the acl file myapi-acl.json we created earlier and the policy file myapi-policy.rego are sitting in our working directory. it's now time to put opa to work!

starting up open policy agent service

you can grab the opa binary for your platform (linux, macos, or windows) from github . after downloading the binary, start the opa service by issuing the command:

$ opa run --server

opa service is now up and listening on port 8181 . next, we are going to upload the acl file, and the policy file into opa. note that opa stores both the data and policies in memory, and so if you restart the opa service, you will have to reload both of the files.

first, upload the acl file myapi-acl.json into opa using the following curl command:

$ curl -x put http://localhost:8181/v1/data/myapi/acl --data-binary @myapi-acl.json

next, upload the policy file myapi-policy.rego into opa by issuing:

$ curl -x put http://localhost:8181/v1/policies/myapi --data-binary @myapi-policy.rego

invoking policy queries

finally, if everything went well, we are now ready to issue our first query.

let's ask opa whether the user alice can invoke a write operation on our application:

$ curl -x post http://localhost:8181/v1/data/myapi/policy/allow \
--data-binary '{ "input": { "user": "alice", "access": "write" } }' \
| jq
{
  "result": true
}

the query result returned by opa says that the user alice is authorized for writing. our application would now proceed with executing the write operation. and what about bob ? is user bob allowed to write?

$ curl -x post http://localhost:8181/v1/data/myapi/policy/allow \
--data-binary '{ "input": { "user": "bob", "access": "write" } }' \
| jq
{
  "result": false
}

the query result says it clearly. user bob is denied write access. our application would return http 403 forbidden to bob at this point.

from what we have seen so far, a query result can be a simple true or false value. however, this is not a limitation that opa would impose. opa allows you to write policy rules that can yield an arbitrarily complex json structure. for example, the whocan rule that we defined in our policy, returns a json list.

let's give it a try and ask opa to return a list of users that were granted the read permission:

$ curl -x post http://localhost:8181/v1/data/myapi/policy/whocan \
--data-binary '{ "input": { "access": "read" } }' \
| jq
{
  "result": [
    "alice",
    "bob"
  ]
}

conclusion

in this article, we took an initial look at open policy agent. after discussing how opa works, we went through an example of implementing an access control list policy. in the next entry to this series, we are going to dive deeper into developing policies with opa.

i hope that you found this article useful. if you have any questions or comments, please add them to the comment section below. i look forward to hearing from you.