integration.md

title	kind	weight	restrictedtoc
Integrating OPA	documentation	65	true

OPA exposes domain-agnostic APIs that your service can call to manage and enforce policies. Read this page if you want to integrate an application, service, or tool with OPA.

When integrating with OPA there are two interfaces to consider:

• Evaluation: OPA's interface for asking for policy decisions. Integrating OPA is primarily focused on integrating an application, service, or tool with OPA's policy evaluation interface. This integration results in policy decisions being decoupled from that application, service, or tool.
• Management: OPA's interface for deploying policies, understanding status, uploading logs, and so on. This integration is typically the same across all OPA instances, regardless what software the evaluation interface is integrated with. Distributing policy, retrieving status, and storing logs in the same way across all OPAs provides a unified management plane for policy across many different software systems.

This page focuses predominantly on different ways to integrate with OPA's policy evaluation interface and how they compare. For more information about the management interface:

• See the Bundle API for distributing policy and data to OPA.
• See the Status API for collecting status reports on bundle activation and agent health.
• See the Decision Log API for collecting a log of policy decisions made by agents.
• See the Health API for checking agent deployment readiness and health.
• See the Prometheus API endpoint to obtain insight into performance and errors.

Evaluating Policies

OPA supports different ways to evaluate policies.

• The REST API returns decisions as JSON over HTTP.
• The Go API (GoDoc) returns decisions as simple Go types (bool, string, map[string]interface{}, etc.)
• WebAssembly compiles Rego policies into WASM instructions so they can be embedded and evaluated by any WebAssembly runtime

Integrating with the REST API

To integrate with OPA outside of Go, we recommend you deploy OPA as a host-level daemon or sidecar container. When your application or service needs to make policy decisions it can query OPA locally via HTTP. Running OPA locally on the same host as your application or service helps ensure policy decisions are fast and highly-available.

Named Policy Decisions

Use the Data API to query OPA for named policy decisions:

POST /v1/data/<path>
Content-Type: application/json

{
    "input": <the input document>
}

The <path> in the HTTP request identifies the policy decision to ask for. In OPA, every rule generates a policy decision. In the example below there are two decisions: example/authz/allow and example/authz/is_admin.

package example.authz

default allow = false

allow {
    some id
    input.method = "GET"
    input.path = ["salary", id]
    input.subject.user = id
}

allow {
    is_admin
}

is_admin {
    input.subject.groups[_] = "admin"
}

You can request specific decisions by querying for <package path>/<rule name>. For example to request the allow decision execute the following HTTP request:

POST /v1/data/example/authz/allow
Content-Type: application/json

{
    "input": <the input document>
}

The body of the request specifies the value of the input document to use during policy evaluation. For example:

POST /v1/data/example/authz/allow
Content-Type: application/json

{
    "input": {
        "method": "GET",
        "path": ["salary", "bob"],
        "subject": {
            "user": "bob"
        }
    }
}

OPA returns an HTTP 200 response code if the policy was evaluated successfully. Non-HTTP 200 response codes indicate configuration or runtime errors. The policy decision is contained in the "result" key of the response message body. For example, the above request returns the following response:

200 OK
Content-Type: application/json

{
    "result": true
}

If the requested policy decision is undefined OPA returns an HTTP 200 response without the "result" key. For example, the following request for is_admin is undefined because there is no default value for is_admin and the input does not satisfy the is_admin rule body:

POST /v1/data/example/authz/is_admin
Content-Type: application/json

{
    "input": {
        "subject": {
            "user": "bob",
            "groups": ["sales", "marketing"]
        }
    }
}

The response:

200 OK
Content-Type: application/json

{}

For another example of how to integrate with OPA via HTTP see the HTTP API Authorization tutorial.

Integrating with the Go API

Use the github.com/open-policy-agent/opa/rego package to embed OPA as a library inside services written in Go. To get started import the rego package:

import "github.com/open-policy-agent/opa/rego"

The rego package exposes different options for customizing how policies are evaluated. Through the rego package you can supply policies and data, enable metrics and tracing, toggle optimizations, etc. In most cases you will:

1. Use the rego package to construct a prepared query.
2. Execute the prepared query to produce policy decisions.
3. Interpret and enforce the policy decisions.

Preparing queries in advance avoids parsing and compiling the policies on each query and improves performance considerably. Prepared queries are safe to share across multiple Go routines.

To prepare a query create a new rego.Rego object by calling rego.New(...) and then invoke rego.Rego#PrepareForEval. The rego.New(...) call can be parameterized with different options like the query, policy module(s), data store, etc.

module := `
package example.authz

default allow = false

allow {
    some id
    input.method = "GET"
    input.path = ["salary", id]
    input.subject.user = id
}

allow {
    is_admin
}

is_admin {
    input.subject.groups[_] = "admin"
}
`

query, err := rego.New(
    rego.Query("x = data.example.authz.allow"),
    rego.Module("example.rego", module),
    ).PrepareForEval(ctx)

if err != nil {
    // Handle error.
}

Using the query returned by rego.Rego#PrepareForEval call the Eval function to evaluate the policy:

input := map[string]interface{}{
    "method": "GET",
    "path": []interface{}{"salary", "bob"},
    "subject": map[string]interface{}{
        "user": "bob",
        "groups": []interface{}{"sales", "marketing"},
    },
}

ctx := context.TODO()
results, err := query.Eval(ctx, rego.EvalInput(input))

The rego.PreparedEvalQuery#Eval function returns a result set that contains the query results. If the result set is empty it indicates the query could not be satisfied. Each element in the result set contains a set of variable bindings and a set of expression values. The query from above includes a single variable x so we can lookup the value and interpret it to enforce the policy decision.

if err != nil {
    // Handle evaluation error.
} else if len(results) == 0 {
    // Handle undefined result.
} else if result, ok := results[0].Bindings["x"].(bool); !ok {
    // Handle unexpected result type.
} else {
    // Handle result/decision.
    // fmt.Printf("%+v", results) => [{Expressions:[true] Bindings:map[x:true]}]
}

For more examples of embedding OPA as a library see the rego package in the Go documentation.

WebAssembly (Wasm)

Policies can be evaluated as compiled Wasm binaries.

See OPA Wasm docs for more details.

Comparison

A comparison of the different integration choices are summarized below.

Dimension	REST API	Go Lib	WASM (WIP)
Evaluation	Fast	Faster	Fastest
Language	Any	Only Go	Any with WASM
Operations	Update just OPA	Update entire service	Update service rarely
Security	Must secure API	Enable only what is needed	Enable only what is needed

Integrating OPA via the REST API is the most common, at the time of writing. OPA is most often deployed either as a sidecar or less commonly as an external service. Operationally this makes it easy to upgrade OPA and to configure it to use its management services (bundles, status, decision logs, etc.). Because it is a separate process it requires monitoring and logging (though this happens automatically for any sidecar-aware environment like Kubernetes). OPA's configuration and APIs must be secured according to the security guide.

Integrating OPA via the Go API only works for Go software. Updates to OPA require re-vendoring and re-deploying the software. Evaluation has less overhead than the REST API because all the communication happens in the same operating-system process. All of the management functionality (bundles, decision logs, etc.) must be either enabled or implemented. Security concerns are limited to those management features that are enabled or implemented.

Integrating via WASM is still a work-in-progress. But once it is finished, WASM policies will be embeddable in any programming language that has a WASM runtime. Evaluation will have less overhead than the REST API (because it is evaluated in the same operating-system process) and should outperform the Go API (because the policies have been compiled to a lower-level instruction set). Each programming language will need its own SDKs (also a WIP) that implement the management functionality and the evaluation interface. Typically new OPA language features will not require updating the service since neither the WASM runtime nor the SDKs will be impacted. Updating the SDKs will require re-deploying the service. Security will be analogous to the Go API integration: it is mainly the management functionality that presents security risks.