Cedarling KrakenD Plugin#

This is a KrakenD HTTP server plugin that intercepts a call to a selected endpoint, uses the embedded Cedarling PDP and allows access only if the authorization result is true.

Functionality#

During startup, the KrakenD plugin reads the environment variables and initializes a Cedarling instance
When the protected endpoint is called, the plugin intercepts the call and creates a Cedarling authorization request.
If the result of the authorization request is true, the plugin allows the endpoint to respond. Otherwise, the plugin responds with 403 Forbidden

Sequence Diagram

Downloading#

The cedarling-krakend plugin builds are available via Janssen releases. Please note that builds are architecture, platform, and KrakenD version specific. This means that builds compiled against KrakenD version 2.9.0 for Windows will not work on other versions or operating systems. The build tags are formatted as follows:

cedarling-krakend-<architecture>-<krakend version and platform>-<Janssen version>.so

Use the following table to find which build you need:

	amd64	arm64
Docker	`amd64-builder-2.9.0-0.0.0.so`	`arm64-builder-2.9.0-0.0.0.so`
On-premise	`amd64-builder-2.9.0-linux-generic-0.0.0.so`	`arm64-builder-2.9.0-linux-generic-0.0.0.so`

If you are running a different version of KrakenD, you can use the following steps to build the plugin yourself.

Building#

Clone the cedarling-krakend folder of the Janssen Repository:

git clone --filter blob:none --no-checkout https://github.com/JanssenProject/jans
cd jans
git sparse-checkout init --cone
git checkout main
git sparse-checkout set jans-cedarling 
cd cedarling-krakend

Download the dynamic shared object file(s) for the cedarling_go binding, compiled for your platform:
- Windows:
  - cedarling_go.dll
  - cedarling_go.lib
- Mac OS: cedarling_go.dylib
- Linux: libcedarling_go.so

Build the plugin, replacing <x.y.z> with the KrakenD version you want to build against:

For Docker targets:

docker run -it -v "$PWD:/app" -w /app krakend/builder:<x.y.z> go build -buildmode=plugin -o cedarling-krakend.so .

For on-premise installations:

docker run -it -v "$PWD:/app" -w /app krakend/builder:<x.y.z>-linux-generic go build -buildmode=plugin -o cedarling-krakend.so .

For ARM64 Docker targets:

docker run -it -v "$PWD:/app" -w /app \
    -e "CGO_ENABLED=1" \
    -e "CC=aarch64-linux-musl-gcc" \
    -e "GOARCH=arm64" \
    -e "GOHOSTARCH=amd64" \
    krakend/builder:<x.y.z> \
    go build -ldflags='-extldflags=-fuse-ld=bfd -extld=aarch64-linux-musl-gcc' \
    -buildmode=plugin -o cedarling-krakend.so .

For ARM64 on-premise installs:

docker run -it -v "$PWD:/app" -w /app \
    -e "CGO_ENABLED=1" \
    -e "CC=aarch64-linux-gnu-gcc" \
    -e "GOARCH=arm64" \
    -e "GOHOSTARCH=amd64" \
    krakend/builder:<x.y.z>-linux-generic \
    go build -ldflags='-extldflags=-fuse-ld=bfd -extld=aarch64-linux-gnu-gcc' \
    -buildmode=plugin -o cedarling-krakend.so .

Prerequisites for testing#

To test the plugin, you will need:

A cedarling policy store with a policy for our gateway. To create this, please follow these steps.

For our demo, we will use this sample policy as outlined in the instructions:

@id("allow_one")
permit(
  principal is gatewayDemo::Workload,
  action == gatewayDemo::Action::"GET",
  resource is gatewayDemo::HTTP_Request
)
when {
    principal has access_token.scope &&
    principal.access_token.scope.contains("profile")
};

This policy will allow access so long as the access token contains the profile scope.
A KrakenD server installation. For development purposes, the binary install is recommended. For production setups, the Docker method is recommended.
The plugin .so file for your architecture. For Mac OS hosts, ARM64 is required.
The dynamic shared object file(s) for the cedarling_go binding, compiled for your platform:
- Windows:
  - cedarling_go.dll
  - cedarling_go.lib
- Mac OS: cedarling_go.dylib
- Linux: libcedarling_go.so
A configuration file. Sample configuration is provided in krakend.json.

Configuration#

Check the sample configuration in krakend.json to see an example KrakenD configuration which loads the plugin. The following table describes the plugin-specific configuration keys. These keys are mandatory and must be provided. Additional configuration is described in KrakenD documentation.

The namespace field in the configuration needs to be the cedar namespace you used when creating the policy store. By default, Agama Lab sets the namespace to Jans. If you are following the demo, you will use the same name.

Field	Type	Example	Description
path	String	/protected	KrakenD endpoint to protect
namespace	String	Jans	Cedar namespace being used by the policy store

Running#

Warning: Windows and Mac OS are untested. Only Linux has been fully tested against KrakenD.

Place krakend.json and the dynamic shared object file(s) in your current working directory
Create a folder named plugin in the current working directory and place the plugin .so file in that folder
To properly load the shared library, Linux and Mac OS platforms need to be told where to find your shared object file. On Windows this is detected automatically so long as the object file is placed in the current working directory.
- Mac OS: export DYLD_LIBRARY_PATH=$(pwd):$DYLD_LIBRARY_PATH
- Linux: export LD_LIBRARY_PATH=$(pwd):$LD_LIBRARY_PATH
  
  On Linux, you can verify the dynamic linking like so:
```
$ ldd plugin/*.so 
...
libcedarling_go.so => /path/to/current/directory/libcedarling_go.so
```
  4. Set the Cedarling bootstrap variables in your environment. - For gateway functionality, at minimum you will need the following properties set:
```
CEDARLING_APPLICATION_NAME=Gateway
CEDARLING_POLICY_STORE_URI=<Your policy store URI>
CEDARLING_WORKLOAD_AUTHZ=enabled
CEDARLING_PRINCIPAL_BOOLEAN_OPERATION={\"===\":[{\"var\":\"Jans::Workload\"},\"ALLOW\"]}
CEDARLING_ID_TOKEN_TRUST_MODE=none
```
5. Run the KrakenD server: krakend run -c krakend.json 6. KrakenD is running on http://127.0.0.1:8080 7. Test with no authentication: curl http://127.0.0.1:8080/protected. You should get a 403 Forbidden 8. Test with authentication (a sample token is provided):

export ACCESS_TOKEN=eyJraWQiOiJjb25uZWN0X2Y5YTAwN2EyLTZkMGItNDkyYS05MGNkLWYwYzliMWMyYjVkYl9zaWdfcnMyNTYiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJxenhuMVNjcmI5bFd0R3hWZWRNQ2t5LVFsX0lMc3BaYVFBNmZ5dVlrdHcwIiwiY29kZSI6IjNlMmEyMDEyLTA5OWMtNDY0Zi04OTBiLTQ0ODE2MGMyYWIyNSIsImlzcyI6Imh0dHBzOi8vYWNjb3VudC5nbHV1Lm9yZyIsInRva2VuX3R5cGUiOiJCZWFyZXIiLCJjbGllbnRfaWQiOiJkN2Y3MWJlYS1jMzhkLTRjYWYtYTFiYS1lNDNjNzRhMTFhNjIiLCJhdWQiOiJkN2Y3MWJlYS1jMzhkLTRjYWYtYTFiYS1lNDNjNzRhMTFhNjIiLCJhY3IiOiJzaW1wbGVfcGFzc3dvcmRfYXV0aCIsIng1dCNTMjU2IjoiIiwibmJmIjoxNzMxOTUzMDMwLCJzY29wZSI6WyJyb2xlIiwib3BlbmlkIiwicHJvZmlsZSIsImVtYWlsIl0sImF1dGhfdGltZSI6MTczMTk1MzAyNywiZXhwIjoxNzMyMTIxNDYwLCJpYXQiOjE3MzE5NTMwMzAsImp0aSI6InVaVWgxaERVUW82UEZrQlBud3BHemciLCJ1c2VybmFtZSI6IkRlZmF1bHQgQWRtaW4gVXNlciIsInN0YXR1cyI6eyJzdGF0dXNfbGlzdCI6eyJpZHgiOjMwNiwidXJpIjoiaHR0cHM6Ly9qYW5zLnRlc3QvamFucy1hdXRoL3Jlc3R2MS9zdGF0dXNfbGlzdCJ9fX0.Pt-Y7F-hfde_WP7ZYwyvvSS11rKYQWGZXTzjH_aJKC5VPxzOjAXqI3Igr6gJLsP1aOd9WJvOPchflZYArctopXMWClbX_TxpmADqyCMsz78r4P450TaMKj-WKEa9cL5KtgnFa0fmhZ1ZWolkDTQ_M00Xr4EIvv4zf-92Wu5fOrdjmsIGFot0jt-12WxQlJFfs5qVZ9P-cDjxvQSrO1wbyKfHQ_txkl1GDATXsw5SIpC5wct92vjAVm5CJNuv_PE8dHAY-KfPTxOuDYBuWI5uA2Yjd1WUFyicbJgcmYzUSVt03xZ0kQX9dxKExwU2YnpDorfwebaAPO7G114Bkw208g

curl http://127.0.0.1:8080/protected -H "Authorization: Bearer $ACCESS_TOKEN"

KrakenD is configured to respond with the health check response if authentication succeeds.

Last update: 2025-05-13
Created: 2025-01-23