Integrate Entitlements with your Application

Use the following methods to add support for Entitlements to your application, differing in how OPA is accessed.

1. Use OPA as a sidecar, run it alongside your application as a separate process and communicate with it via a REST API.

2. To embed OPA directly into your application as a library; this requires your application to be written in Go, but may offer some additional flexibility and performance benefits.

note

This tutorial discusses the minimum requirements to get started with Entitlements. For more information on the above two approaches, see the OPA integration documentation.

OPA Configuration

Before you can begin to integrate OPA with your application, you must first determine how it is to be configured. In-depth documentation is available on the OPA Configuration page.

Currently, the Styra DAS UI provides a suitable OPA configuration. You can find a curl command to download this configuration on the Install tab under OPA CLI.

caution

The bearer token generated in the install tab to download this configuration expires after 24 hours. In other words, do not save this token for long-term use. Instead, you must obtain an API token with a longer expiration time by navigating to Workspace > Settings > API Tokens.

OPA as a Sidecar

If you intend to deploy OPA as a sidecar, then create a plan to deploy the OPA binary and configuration alongside your application.

Both the Go and Python sample apps can use OPA and provide examples on how to interact with the OPA REST API.

The REST API exposes a substantial amount of functionality, you must look at one endpoint: v1/data/main/main to obtain Entitlements decisions. The expected response format is described in Entitlements Responses.

OPA as a Library

If your application is written in Go, you can directly embed OPA into your application. You can use the OPA SDK package to provide the OPA configuration and to obtain decisions. The Go sample application provides an example, with most of the code being implemented in opa.go.

Entitlements Requests

To learn more about how Entitlements requests should be structured, seeRequests. All Entitlements requests are JSON objects.

An Entitlements request includes the following fields:

• action: The changes that users and service accounts can make.
• resource: The resources that users and service accounts can act on.
• subject: The person (or program) which is attempting to perform the action.

The following shows a valid Entitlements request example:

{
    "action": "GET",
    "resource": "/cars",
    "subject": "alice"
}

Entitlements Responses

To learn more about the schema of an Entitlements decision, see the Responses page. Your application will receive from OPA, whether being used as a library or a sidecar, a JSON object using the standard Entitlements decision format.

The following shows a valid Entitlements response.

{
    "decision_id": "0f10f686-ebd7-4136-a209-6978cc2c1bfb",
    "result": {
        "allowed": true,
        "entz": [],
        "outcome": {
            "allow": true,
            "decision_type": "ALLOWED",
            "enforced": [
                {
                    "allowed": true,
                    "entz": [],
                    "message": "Request was matched"
                }
            ],
            "monitored": [],
            "policy_type": "rules",
            "stacks": {},
            "system_type": "template.entitlements:0.1"
        }
    }
}

To use this in your application, minimally extract the result.allowed boolean. If result.allowed: true then allow the request to proceed, otherwise stop the action with an HTTP 403 error or an equivalent that is relevant for your use case and stack.

The decision_id field is also especially useful, as it allows you to cross-reference the decision received by your application to the corresponding decision logged in Styra DAS. The outcome and entz fields allow you to obtain more rich and detailed information about the decision being made, such as which specific rules contributed to it being allowed or denied, or other contextual information inserted by rules.