Sidecar Overview#
The sidecar is a containerized Flask project that uses the cedarling_python
binding and implements the AuthZen specification. This image can run alongside another service and uses cedarling to validate evaluation requests against a policy store.
Docker setup#
- Ensure that you have installed docker
- Create a file called
bootstrap.json
. You may use this sample file. - Modify the bootstrap file to your specifications. In particular you need to provide a link to your policy store in
CEDARLING_POLICY_STORE_URI
. The configuration keys are described here. - Pull the docker image:
docker pull ghcr.io/janssenproject/jans/cedarling-flask-sidecar:0.0.0-nightly
-
Run the docker image, replacing
</absolute/path/to/bootstrap.json>
with the absolute path to your bootstrap file:docker run -d \ -e APP_MODE='development' \ -e CEDARLING_BOOTSTRAP_CONFIG_FILE=/bootstrap.json \ -e SIDECAR_DEBUG_RESPONSE=False \ --mount type=bind,src=</absolute/path/to/bootstrap.json>,dst=/bootstrap.json \ -p 5000:5000\ ghcr.io/janssenproject/jans/cedarling-flask-sidecar:0.0.0-nightly
-d
runs the sidecar in daemon mode in the background. Omit this if you want to run the sidecar in the foreground to monitor logs in real time.SIDECAR_DEBUG_RESPONSE
is an option that will cause the sidecar to return extra diagnostic information for each query if set toTrue
. This may be useful to check which policies are being used to reach a decision.- Take note of the output of the command. This is the container ID of the sidecar.
- The sidecar runs in the background on port 5000. OpenAPI documentation is available at
http://0.0.0.0:5000/swagger-ui
- To stop the sidecar, run
docker container stop <container ID>
Usage#
The sidecar has one endpoint: /cedarling/evaluation
.
Example request to the evaluation endpoint:
Note
The request shown below is designed against the AuthZen specification and should not be used for a regular cedarling deployment.
{
"subject": {
"type": "JWT",
"id": <SHA256 hash of the properties dictionary>,
"properties": {
"access_token": "",
"id_token": "",
"userinfo_token": ""
}
},
"resource": {
"type": "Application",
"id": <SHA256 hash of the properties dictionary>,
"properties": {
"cedar_entity_mapping": {
"entity_type": "Jans::Application",
"id": "some_id"
},
"app_id": "application_id",
"name": "Some Application",
"url": {
"host": "jans.test",
"path": "/protected-endpoint",
"protocol": "http"
}
}
},
"action": {
"name": "Jans::Action::\"Read\""
},
"context": {
"device_health": ["Healthy"],
"fraud_indicators": ["Allowed"],
"geolocation": ["America"],
"network": "127.0.0.1",
"network_type": "Local",
"operating_system": "Linux",
"user_agent": "Linux",
"current_time": 1
}
}
Cedarling requires OpenID Userinfo, Access, and ID tokens to construct the principal entity, as described here. These values are sent in the subject field's properties. Furthermore, the sidecar expects the SHA256 checksum of the subject and resource's properties
dictionary to be passed as their corresponding IDs, as shown in the example above. A more detailed example of creating an AuthZen request can be seen in the gateway example
Upon creating the principal, action, resource, and context entities, cedarling will evaluate these entities against the policies defined in the policy store. Then it will return a true/false decision. If the decision is false, the sidecar will analyze cedarling diagnostics and provide additional information for the admin.
Example of true
case:
{
"decision": true
}
Example of false
case:
{
"context": {
"reason_admin": {
"person diagnostics": [],
"person error": [],
"person evaluation": "DENY",
"workload diagnostics": [],
"workload evaluation": "DENY",
"workload_error": []
}
},
"decision": false
}
In this example both the person and workload evaluations were DENY
, so the decision was false. Additional information is returned in the context
field.