docs(jans-cedarling): update sidecar docs (#10690)

* docs(jans-cedarling): update sidecar docs Signed-off-by: SafinWasi <[email protected]> * docs(jans-cedarling): update sidecar readme Signed-off-by: SafinWasi <[email protected]> --------- Signed-off-by: SafinWasi <[email protected]> Co-authored-by: Mohammad Abudayyeh <[email protected]>
JanssenProject · Jan 20, 2025 · d389979 · d389979
1 parent e9be6fa
commit d389979
Show file tree

Hide file tree

Showing 6 changed files with 114 additions and 28 deletions.
diff --git a/docs/cedarling/python/sidecar.md → docs/cedarling/cedarling-sidecar.md b/docs/cedarling/python/sidecar.md → docs/cedarling/cedarling-sidecar.md
@@ -1,7 +1,6 @@
 ---
 tags:
   - cedarling
-  - python
   - sidecar
 ---
 
@@ -11,21 +10,37 @@ The sidecar is a containerized Flask project that uses the `cedarling_python` bi
 
 ## Docker setup
 
-- Ensure that you have installed [docker](https://docs.docker.com/engine/install/) and [docker compose](https://docs.docker.com/compose/install/). 
-- Clone the [Janssen](https://github.com/JanssenProject/jans) repository
-- Navigate to `jans/jans-cedarling/flask-sidecar`
-- Edit the provided `secrets/bootstrap.json` file to your specifications. The configuration keys are described [here](https://github.com/JanssenProject/jans/blob/main/jans-cedarling/bindings/cedarling_python/cedarling_python.pyi#L10). 
-- Run `docker compose up`
-  - For cloud deployments, please use the provided Dockerfile and pass your bootstrap configuration via the environment variable `CEDARLING_BOOTSTRAP_CONFIG_FILE`.
-- The sidecar runs on port 5000. OpenAPI documentation is available at `http://0.0.0.0:5000/swagger-ui`
+- Ensure that you have installed [docker](https://docs.docker.com/engine/install/) 
+- Create a file called `bootstrap.json`. You may use this [sample](https://github.com/JanssenProject/jans/blob/main/jans-cedarling/flask-sidecar/secrets/bootstrap.json) 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](https://github.com/JanssenProject/jans/blob/main/jans-cedarling/bindings/cedarling_python/cedarling_python.pyi#L10).
+- 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: 
+
+	```bash 
+	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
+	```
+
+    - `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:
 
-```
+```json
 {
 	"subject": {
 		"type": "JWT",
@@ -71,21 +86,21 @@ Example request to the evaluation endpoint:
 }
 ```
 
-Cedarling requires OpenID Userinfo, Access, and ID tokens to construct the principal entity, as described [here](../cedarling-authz.md). As per AuthZen specification, these values are sent in the `context` field of the payload. Conversely, the `subject` field is currently not used by cedarling. These 3 tokens are subsequently removed from the context object before it is passed to cedarling.
+Cedarling requires OpenID Userinfo, Access, and ID tokens to construct the principal entity, as described [here](./cedarling-authz.md). These values are sent in the subject field's properties. 
 
 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:
 
-```
+```json
 {
   "decision": true
 }
 ```
 
 Example of `false` case:
 
-```
+```json
 {
   "context": {
     "reason_admin": {
@@ -101,4 +116,4 @@ Example of `false` case:
 }
 ```
 
-In this example both the person and workload evaluations were `DENY`, so the decision was false. Additional information is returned in the `context` field as per AuthZen specification.
+In this example both the person and workload evaluations were `DENY`, so the decision was false. Additional information is returned in the `context` field.
diff --git a/docs/cedarling/python/README.md b/docs/cedarling/python/README.md
@@ -33,14 +33,18 @@ The recommended way to include cedarling in a Python project is to compile it to
   ```
 - The wheel will be available in `target/wheels/`
 
-## Including in projects
+- If you are developing a simple project in a `venv` setup, you can run `maturin develop --release` and maturin will install the wheel into the currently activated virtual environment. After that, you may run your code directly from the command line.
 
-If you are developing a simple project in a `venv` setup, in the previous section you can run `maturin develop --release` and maturin will install the wheel into the currently activated virtual environment. After that, you may run your code directly from the command line.
+## Including in projects
 
 In case of more complicated projects with a dependency manager such as [poetry](https://python-poetry.org/), you can either install the wheel via the command line:
 ```
 poetry add path/to/wheel.whl
 ```
+Or install it into the virtual environment managed by poetry:
+```
+poetry run pip install path/to/wheel.whl
+```
 or include it as a static dependency in the [dependencies](https://python-poetry.org/docs/pyproject/#dependencies-and-dependency-groups) section of your `pyproject.toml`:
 ```
 ...

diff --git a/docs/cedarling/python/usage.md b/docs/cedarling/python/usage.md
@@ -16,12 +16,8 @@ In this example, we will show an example Python script that calls the `cedarling
 
 ```
 (venv) $ python example.py
-Policy store location not provided, use 'CEDARLING_LOCAL_POLICY_STORE' environment variable
-Used default policy store path: example_files/policy-store.json
-
-{"id":"0193414e-9672-786a-986c-57f48d41c4e4","time":1731967489,"log_type":"System","pdp_id":"c0ec33ff-9482-4bdc-83f6-2925a41a3280","msg":"configuration parsed successfully"}
-{"id":"0193414e-9672-786a-986c-57f5379086c3","time":1731967489,"log_type":"System","pdp_id":"c0ec33ff-9482-4bdc-83f6-2925a41a3280","msg":"Cedarling Authz initialized successfully","application_id":"TestApp"}
-{"id":"0193414e-9676-7d8a-b55b-3f0097355851","time":1731967489,"log_type":"Decision","pdp_id":"c0ec33ff-9482-4bdc-83f6-2925a41a3280","msg":"Result of authorize.","application_id":"TestApp","action":"Jans::Action::\"Read\"","resource":"Jans::Application::\"some_id\"","context":{"user_agent":"Linux","operating_system":"Linux","network_type":"Local","network":"127.0.0.1","geolocation":["America"],"fraud_indicators":["Allowed"],"device_health":["Healthy"],"current_time":1731967489},"person_principal":"Jans::User::\"qzxn1Scrb9lWtGxVedMCky-Ql_ILspZaQA6fyuYktw0\"","person_diagnostics":{"reason":["840da5d85403f35ea76519ed1a18a33989f855bf1cf8"],"errors":[]},"person_decision":"ALLOW","workload_principal":"Jans::Workload::\"d7f71bea-c38d-4caf-a1ba-e43c74a11a62\"","workload_diagnostics":{"reason":["444da5d85403f35ea76519ed1a18a33989f855bf1cf8"],"errors":[]},"workload_decision":"ALLOW","authorized":true}
+{"request_id":"019474da-12ee-7315-bb12-35f46a9bc2b2","timestamp":"2025-01-17T09:20:36.334Z","log_kind":"System","pdp_id":"4cf7864b-50d4-4492-8cd1-3ddb424e2711","level":"INFO","msg":"Cedarling Authz initialized successfully","application_id":"My App","cedar_lang_version":"4.1.0","cedar_sdk_version":"4.2.2"}
+{"request_id":"019474da-12f3-74f1-8f3e-da7624806135","timestamp":"2025-01-17T09:20:36.339Z","log_kind":"Decision","pdp_id":"4cf7864b-50d4-4492-8cd1-3ddb424e2711","policystore_id":"gICAgcHJpbmNpcGFsIGlz","policystore_version":"undefined","principal":"User & Workload","User":{"email":{"domain":"jans.test","uid":"admin"},"sub":"qzxn1Scrb9lWtGxVedMCky-Ql_ILspZaQA6fyuYktw0"},"Workload":{"client_id":"d7f71bea-c38d-4caf-a1ba-e43c74a11a62"},"diagnostics":{"reason":[{"id":"840da5d85403f35ea76519ed1a18a33989f855bf1cf8","description":"simple policy example for principal user"}],"errors":[]},"action":"Jans::Action::\"Read\"","resource":"Jans::Application::\"some_id\"","decision":"ALLOW","tokens":{"id_token":{"jti":"ijLZO1ooRyWrgIn7cIdNyA"},"Userinfo":{"jti":"OIn3g1SPSDSKAYDzENVoug"},"access":{"jti":"uZUh1hDUQo6PFkBPnwpGzg"}},"decision_time_ms":3}
 Result of workload authorization: ALLOW
 Policy ID used:
 444da5d85403f35ea76519ed1a18a33989f855bf1cf8
@@ -35,7 +31,8 @@ Errors during authorization: 0
 
 ## Explanation
 
-Cedarling creates principal entities from the access, ID and userinfo tokens. The action, resource and context entities are declared in code. These four entities together form the `PARC` format that cedarling evaluates against policies provided in the policy store. The principal entities can be either User, Workload or Role. After forming the entities, cedarling evaluates them against the policies provided in the policy store. If entity is explicitly permitted by a policy, the result of the evaluation is `ALLOW`, otherwise it is `DENY`.
+Cedarling creates principal entities from either the access, ID and userinfo tokens, or a combination of the three depending on bootstrap configurations. For example, to create a Workload entity only one token is sufficient. But to create a user entity at least ID or Userinfo tokens are needed. This is defined by `CEDARLING_USER_AUTHZ` and `CEDARLING_WORKLOAD_AUTHZ` in the [bootstrap configuration](https://github.com/JanssenProject/jans/blob/main/jans-cedarling/bindings/cedarling_python/cedarling_python.pyi#L10). Cedarling will make a best attempt to create entities based on tokens provided; if it is unable to do so it will raise an `EntitiesError` exception.
+The action, resource and context entities are declared in code. These four entities together form the `PARC` format that cedarling evaluates against policies provided in the policy store. The principal entities can be either User, Workload or Role. After forming the entities, cedarling evaluates them against the policies provided in the policy store. If entity is explicitly permitted by a policy, the result of the evaluation is `ALLOW`, otherwise it is `DENY`.
 
 In this case there are two policies in the store, one for User entities and one for Workload entities:
 
@@ -91,17 +88,15 @@ context = {
 }
 
 request = Request(
-    access_token,
-    id_token,
-    userinfo_token,
+    tokens=Tokens(access_token, id_token, userinfo_token),
     action=action,
     resource=resource, context=context)
 
 authorize_result = instance.authorize(request)
 assert authorize_result.is_allowed()
 ```
 
-Cedarling will return `is_allowed()` as `True` only if both the User and Workload entity evaluations are `ALLOW`.
+Cedarling will return `is_allowed()` as `True` only if the authorization queries set in the bootstrap return `True`. In case of the example, both `CEDARLING_USER_AUTHZ` and `CEDARLING_WORKLOAD_AUTHZ` were set to `enabled`, so cedarling will only return True if both user and workload evaluations are true. 
 
 ## Exposed functions
 

diff --git a/jans-cedarling/bindings/cedarling_python/example_files/sample_bootstrap_props.json b/jans-cedarling/bindings/cedarling_python/example_files/sample_bootstrap_props.json
@@ -0,0 +1,49 @@
+{
+    "CEDARLING_APPLICATION_NAME": "My App",
+    "CEDARLING_POLICY_STORE_URI": null,
+    "CEDARLING_POLICY_STORE_ID": "gICAgcHJpbmNpcGFsIGlz",
+    "CEDARLING_LOG_TYPE": "std_out",
+    "CEDARLING_LOG_LEVEL": "INFO",
+    "CEDARLING_LOG_TTL": null,
+    "CEDARLING_DECISION_LOG_USER_CLAIMS": [
+        "sub",
+        "email"
+    ],
+    "CEDARLING_DECISION_LOG_WORKLOAD_CLAIMS": [
+        "client_id",
+        "rp_id"
+    ],
+    "CEDARLING_USER_AUTHZ": "enabled",
+    "CEDARLING_WORKLOAD_AUTHZ": "enabled",
+    "CEDARLING_USER_WORKLOAD_BOOLEAN_OPERATION": "AND",
+    "CEDARLING_LOCAL_JWKS": null,
+    "CEDARLING_LOCAL_POLICY_STORE": null,
+    "CEDARLING_POLICY_STORE_LOCAL_FN": "./example_files/policy-store.json",
+    "CEDARLING_JWT_SIG_VALIDATION": "disabled",
+    "CEDARLING_JWT_STATUS_VALIDATION": "disabled",
+    "CEDARLING_JWT_SIGNATURE_ALGORITHMS_SUPPORTED": [
+        "HS256",
+        "RS256"
+    ],
+    "CEDARLING_AT_ISS_VALIDATION": "disabled",
+    "CEDARLING_AT_JTI_VALIDATION": "disabled",
+    "CEDARLING_AT_NBF_VALIDATION": "disabled",
+    "CEDARLING_AT_EXP_VALIDATION": "disabled",
+    "CEDARLING_IDT_ISS_VALIDATION": "disabled",
+    "CEDARLING_IDT_SUB_VALIDATION": "disabled",
+    "CEDARLING_IDT_EXP_VALIDATION": "disabled",
+    "CEDARLING_IDT_IAT_VALIDATION": "disabled",
+    "CEDARLING_IDT_AUD_VALIDATION": "disabled",
+    "CEDARLING_USERINFO_ISS_VALIDATION": "disabled",
+    "CEDARLING_USERINFO_SUB_VALIDATION": "disabled",
+    "CEDARLING_USERINFO_AUD_VALIDATION": "disabled",
+    "CEDARLING_USERINFO_EXP_VALIDATION": "disabled",
+    "CEDARLING_ID_TOKEN_TRUST_MODE": "strict",
+    "CEDARLING_LOCK": "disabled",
+    "CEDARLING_LOCK_MASTER_CONFIGURATION_URI": null,
+    "CEDARLING_DYNAMIC_CONFIGURATION": "disabled",
+    "CEDARLING_LOCK_SSA_JWT": 0,
+    "CEDARLING_AUDIT_HEALTH_INTERVAL": 0,
+    "CEDARLING_AUDIT_TELEMETRY_INTERVAL": 0,
+    "CEDARLING_LISTEN_SSE": "disabled"
+}
diff --git a/jans-cedarling/flask-sidecar/README.md b/jans-cedarling/flask-sidecar/README.md
@@ -43,13 +43,36 @@ For running via poetry, the sidecar supports the following environment variables
 - Set environment variables like so:
 ```
 APP_MODE=development
+CEDARLING_BOOTSTRAP_CONFIG_FILE=/path/to/bootstrap.json
+SIDECAR_DEBUG_RESPONSE=False
 ```
 
 ## Tests
 
 Not yet implemented
 
-## Docker Instructions
+# Docker Instructions
+
+- Create a file called `bootstrap.json`. You may use this [sample](https://github.com/JanssenProject/jans/blob/main/jans-cedarling/flask-sidecar/secrets/bootstrap.json) file. 
+- Modify the file to your specifications. Configuration values are described [here](https://github.com/JanssenProject/jans/blob/main/jans-cedarling/bindings/cedarling_python/cedarling_python.pyi).
+- 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: 
+
+	```bash 
+	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
+	```
+- The service is running on `http://0.0.0.0:5000`. OpenAPI documentation is available at `/swagger-ui`
+
+## Docker Compose Instructions (for development)
 
 - Clone the [Janssen](https://github.com/JanssenProject/jans) repository
 - Navigate to `jans/jans-cedarling/flask-sidecar/`

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -411,10 +411,10 @@ nav:
   - JWT: 'cedarling/cedarling-jwt.md'
   - Logs: 'cedarling/cedarling-logs.md'
   - Properties: 'cedarling/cedarling-properties.md'
+  - Sidecar: 'cedarling/cedarling-sidecar.md'
   - Python:
       - cedarling/python/README.md
       - How to use: cedarling/python/usage.md
-      - Sidecar: cedarling/python/sidecar.md
   - WASM: 'cedarling/cedarling-wasm.md'
   - iOS: 'cedarling/cedarling-ios.md'
   - Android: 'cedarling/cedarling-android.md'