This repository contains examples of using the Entitlements feature of Styra DAS in various languages and settings.
This repository contains several different sample applications (listed below)
which demonstrate various methods by which to integrate OPA with your
application in various languages. For convenience, all of these sample
applications are bundled into a single docker image, and which application is
launched depends on the setting of the SAMPLE_APP
environment variable (see
Influential Environment Variables).
Additionally, various environment variables need to be set which can be retrieved from a DAS instance (tip: you can create your own DAS instance for free via this link).
To get started, you need to first download the Docker image, or build it locally.
To build locally:
docker build -t styra/entitlements-samples:vlocal .
To download the image (substantially faster):
docker pull styra/entitlements-samples:latest
An example of running the Python sample application would be:
$ docker run -it \
-p 8080:8080 -p 8123:8123 -e DOCS_PORT=8080 -e API_PORT=8123 \
-e SAMPLE_APP=python-httpsample \
-e DAS_TOKEN='CHANGEME' \
-e DAS_URL='https://CHANGEME.styra.com/' \
-e DAS_SYSTEM='CHANGEME' \
styra/entitlements-samples:latest
Use styra/entitlements-samples:vlocal
instead of
styra/entitlements-samples:latest
if you used docker build
previously.
You can determine your DAS system ID (DAS_SYSTEM
) by looking in the top-left
corner of the screen while you have the system in question selected in the DAS,
it should be a long sequence of letters and numbers such as
ca8cef0d13134065bd7481f56f05537c
.
You can create a token (DAS_TOKEN
) via Workspace->Access Control->API Tokens.
Alternatively, if you view the quickstart for the "Entitlements" system type,
your DAS instance will automatically generate you an appropriate docker run
command with the necessary environment variables pre-filled (feel free to
change the SAMPLE_APP
variable to try out different samples).
The sample applications that you can choose from are:
python-httpsample
- the python sample using OPA as a sidecar over http.go-httpsample
- the go sample running in OPA sidecar mode.go-sdksample
- the go sample running OPA as an embedded Go library via the OPA SDK ("SDK mode").entz-playground
- the go sample running in SDK mode, with the "entitlements playground" web interface enabled.
You can use the following environment variables to influence the behavior of
the container via -e
.
These environment variables must be set for the container to work:
DAS_TOKEN
- the token to be used for retrieving the OPA configuration from the DAS.DAS_SYSTEM
- the DAS system ID we should pull rules from.DAS_URL
- the full URL of the DAS instance we are to pull the system down from.SAMPLE_APP
- which of the sample applications to run. See previous section for choices.
These environment variables may be specified, but have default values (shown in parenthesis) if they are omitted:
API_PORT
(8123) - the port on which the API server for the sample should listen. When using the "entitlements playground", it is served on this port as well.DOCS_PORT
(8080) - the port on which the API documentation server should listen.TEST
- if this variable is set to any non-empty value, then the test suite is run against the chosen sample app. This variable is normally used only during sample development.
To run the test suite, simply issue a normal docker run
command, but add -e TEST=YES
. The test suite will automatically run against the selected
SAMPLE_APP
.
Though it adds additional complexity to the end-to-end process, this approach means that users can get up and running with an environment that will allow them to experiment with the DAS quickly, and without having to install any dependencies (other than Docker and git) on their system. This is ideal, because users wishing to develop policies using DAS may not have the technical expertise to set up a development environment suitable to run each sample app. Even those users with the requisite knowledge may also prefer to get up and running with the DAS more quickly so as to focus on the task at hand.
The container image is built up from a plain Ubuntu base via the
Dockerfile
, which is configured to run
entrypoint.sh
on startup. This script does several things:
including downloading the OPA configuration from DAS based on the environment
variables, setting up the environment for the sample apps and their
dependencies, and launching the sample app, OPA and Redoc (to serve the API
documentation). It then launches splitwatcher.sh
, which
scripts tmux to display panes
tail
-ing the OPA and sample app logs, and
also providing the user with an interactive terminal. In essence, this is a
bunch of window dressing on top of running an OPA server and then launching the
selected sample app.
When running the sample application entz-playground
, you will be presented
with a web UI on the API_PORT
port (8123 by default) that will allow you to
view in real-time the result of various entitlements requests. The outcome of
each request is shown as a separate row, and will update in real-time as you
modify the policy in DAS. If you click the caret symbol (>
) on the left of a
row, it will expand to show you the full JSON response received from OPA for
the request, as well as the equivalent curl
command to run that request
against an instance of OPA configured with your Entitlements policy (e.g. via
the "OPA CLI" installation instructions for your Entitlements system in Styra
DAS).
You can find an appropriate command to launch the Entitlements Playground in the "Entitlements Playground" installation instructions for your Entitlements system. An example might look like:
docker run \
-i \
-p 8080:8080 \
-p 8123:8123 \
-e SAMPLE_APP=entz-playground \
-e DOCS_PORT=8080 \
-e API_PORT=8123 \
-e DAS_TOKEN='CHANGEME'
-e DAS_URL='https://CHANGEME.styra.com/' \
-e DAS_SYSTEM='CHANGEME' \
-t styra/entitlements-samples:latest
The Entitlements Playground includes a few example requests by default, which are designed to work with the sample data provided with the Entitlements system type. The default requests are as follows:
Subject | Action | Resource |
---|---|---|
alice |
GET |
/cars |
bob |
GET |
/cars/car0 |
bob |
POST |
/cars |
/entz-playground/buttons/edit |
||
/entz-playground/buttons/copy |
||
/entz-playground/buttons/remove |
From top to bottom, these correspond to the following curl
commands, if you
were to run them against a local OPA instance configured according to the "OPA
CLI" installation instructions for your Entitlements system:
curl -LSs -H "Content-Type: application/json" -X POST --data '{"input":{"subject":"alice","resource":"/cars","action":"GET"}}' http://localhost:8181/v1/data/main/main
curl -LSs -H "Content-Type: application/json" -X POST --data '{"input":{"subject":"bob","resource":"/cars/car0","action":"GET"}}' http://localhost:8181/v1/data/main/main
curl -LSs -H "Content-Type: application/json" -X POST --data '{"input":{"subject":"bob","resource":"/cars","action":"POST"}}' http://localhost:8181/v1/data/main/main
curl -LSs -H "Content-Type: application/json" -X POST --data '{"input":{"resource":"/entz-playground/buttons/edit"}}' http://localhost:8181/v1/data/main/main
curl -LSs -H "Content-Type: application/json" -X POST --data '{"input":{"resource":"/entz-playground/buttons/copy"}}' http://localhost:8181/v1/data/main/main
curl -LSs -H "Content-Type: application/json" -X POST --data '{"input":{"resource":"/entz-playground/buttons/remove"}}' http://localhost:8181/v1/data/main/main
Once you have merged new work in a pull request, to create a new Docker image you just need to
add a new tag (git tag ...
) where you bump the latest version by the lowest octet,
then push that tag to the repo (git push --tags origin main
).