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 to True. 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.