docs: split apart Cedarling Docs into Multiple Pages (#9670)

* docs: Updated Cedarling Docs

* docs: Updated Mkdocs Navidation

* docs: proofreading changes

Signed-off-by: ossdhaval <343411+ossdhaval@users.noreply.github.com>

---------

Signed-off-by: ossdhaval <343411+ossdhaval@users.noreply.github.com>
Co-authored-by: Mohammad Abudayyeh <47318409+moabu@users.noreply.github.com>
Co-authored-by: ossdhaval <343411+ossdhaval@users.noreply.github.com>

docs/cedarling/cedarling-authz.md

@@ -0,0 +1,79 @@
+---
+tags:
+  - administration
+  - lock
+  - authorization / authz
+  - Cedar
+  - Cedarling
+---
+
+# Authorization Using Cedarling
+
+The __Policy Store__ contains the Cedar Policies, Cedar Schema, and optionally, a list of the 
+Trusted IDPs. The Cedarling loads its Policy Store during initialization as a static JSON file
+or fetched via HTTPS. In enterprise deployments, the Cedarling can retrieve its Policy Store from
+a Jans Lock Server OAuth protected endpoint.
+
+Developers need to define Cedar Schema that makes sense for their application. For example, a 
+developer writing a customer support application might define an "Issue" Resource and Actions like
+"Reply" or "Close". Once the schema is defined, developers can author policies to model the fine 
+grain access controls needed to implement the business rules of their application. The easiest way
+to define schema and policies is to use the [AgamaLab](https://cloud.gluu.org/agama-lab) Policy 
+Designer. This is a free developer tool hosted by [Gluu](https://gluu.org).
+
+![](../assets/lock-cedarling-diagram-2.jpg)
+
+The JWTs, Resource, Action, and Context are sent in the authz request. Cedar Pricipals entities 
+are derived from JWT tokens. The OpenID Connect ("OIDC") JWTs are joined by the Cedarling to create 
+User and Role entities; the OAuth access token is used to create a Workload entity, which is the 
+software that is acting on behalf of the Person (or autonomously). The Cedarling validates that
+given its policies, both the Person and Workload are authorized.
+
+The Cedarling maps "Roles" out-of-the-box. In Cedar, Roles are a special kind of Principal. Instead
+of saying "User can perform action", we can say "Role can perform action"--a convenient way to 
+implement RBAC. Developers can specify which JWT claim is used to map Cedar Roles. For example, one
+domain may use the `role` user claim of the OpenID Userinfo token; another domain may use the 
+`memberOf` claim in the OIDC id_token.
+
+Developers can also express a variety of policies beyond the limitations of RBAC by expressing ABAC 
+conditions, or combining ABAC and RBAC conditions. For example, a policy like Admins can access a 
+"private" Resource from the private network, during business hours. In this case "Admins" is the role, 
+but the other conditions are ABAC. Policy evaluation is fast because Cedar uses the RBAC role to 
+"slice" the data, minimizing the number of entries on which to evaluate the ABAC conditions.
+
+The OIDC id_token JWT represents a Person authentication event. The access token JWT represents a 
+Workload authentication event. These tokens contain other interesting contextual data. The id_token 
+tells you who authenticated, when they authenticated, how they authenticatated, and optionally other 
+claims like the User's roles. An OAuth access token can tell you information about the Workload that 
+obtained the JWT, its extent of access as defined by the OAuth Authorization Server (*i.e.* the 
+values of the `scope` claim), or other claims--domains frequently enhance the access token to
+contain business specific data needed for policy evaluation.
+
+The Cedarling authorizes a Person using a certain piece of software, which is called a "Workload". 
+From a logical perspective, `person_allowed AND workload_allowed` must be `True`. The JWT's, 
+Action, Resource and Context is sent by the application in the authorization request. For example, 
+this is a sample request from a hypothetical application:
+
+```
+input = { 
+           "access_token": "eyJhbGc....", 
+           "id_token": "eyJjbGc...", 
+           "userinfo_token": "eyJjbGc...",
+           "tx_token": "eyJjbGc...",
+           "action": "View",
+           "resource": {"Ticket": {
+                                  "id": "ticket-10101", 
+                                  "owner": "bob@acme.com", 
+                                  "org_id": "Acme"
+                                  }
+                        },
+           "context": {
+                       "ip_address": "54.9.21.201",
+                       "network_type": "VPN",
+                       "user_agent": "Chrome 125.0.6422.77 (Official Build) (arm64)",
+                       "time": "1719266610.98636",
+                      }
+         }
+
+decision_result = authz(input)
+```

docs/cedarling/cedarling-jwt.md

@@ -0,0 +1,78 @@
+---
+tags:
+  - administration
+  - lock
+  - authorization / authz
+  - Cedar
+  - Cedarling
+  - JWT
+---
+
+# Cedarling JWT Flow
+
+![](../assets/lock-cedarling-diagram-4.jpg)
+
+### Trusted Issuer Schema
+
+* **`name`** : String, no spaces
+* **`description`** : String
+* **`openid_configuration_endpoint`** : String with `https` url of `.well-known` for domain.
+* **`access_tokens`** : Object with claims:
+  * `trusted`: `True | False` 
+* **`id_tokens`** : Object with claims: 
+  * `trusted`: `True | False`
+  * `principal_identifier`: the token claim used to identify the User entity (in SAML jargon it's
+  the "NameID format"). This claim is optional--it may be present in the Userinfo token. Defaults to `sub`. 
+  * `role_mapping`: A list of the User's roles
+* **`userinfo_tokens`** :
+  * `trusted`: `True | False`
+  * `principal_identifier`: the token claim used to identify the User entity (in SAML jargon it's
+  the "NameID format"). This claim is optional--it may be present in the Userinfo token. Defaults to `sub`. 
+  * `role_mapping`: A list of the User's roles
+* **`tx_tokens`** :
+  * `trusted`: `True | False`
+
+Non-normative example:
+```
+[
+{"name": "IDP-1", 
+ "description": "Acme IDP", 
+ "openid_configuration_endpoint": "https://acme.com/.well-known/openid-configuration",
+ "access_tokens": {"trusted": True}, 
+ "id_tokens": {"trusted": True, "principal_identifier": "email"},
+ "userinfo_tokens": {"trusted": True},
+ "tx_tokens": {"trusted": True}
+},
+{IDP-2},
+{IDP-3}...
+]
+```
+
+### JWT Validation
+
+Optionally, the Cedarling can validate the signatures of the JWTs for developers. To enable this, 
+set the `CEDARLING_JWT_VALIDATION` bootstrap property to `True`. For testing, developers can set 
+this property to `False` and submit an unsigned JWT, for example a JWT generated on 
+[JWT.io](https://jwt.io). 
+
+If token validation is enabled, on initiatilization the Cedarling downloads the public keys of 
+the Trusted IDPs specified in the Cedarling policy store. The Cedarling uses the JWT `iss` 
+claim to determine the right keys for validation.
+
+In an enterprise deployment, the Cedarling can also check for JWT revocation. The Cedarling
+checks the status following a mechanism described in the 
+[OAuth Status Lists](https://datatracker.ietf.org/doc/draft-ietf-oauth-status-list/)
+draft. Enforcing the status of tokens helps limit the damage of account takeover--i.e. to immediately 
+recursively revoke all the tokens issued to an attacker. Domains may want to use Token Status also to 
+implement single-transaction tokens.
+
+Here is a summary of the ways the Cedarling may validate a JWT, depending on your bootstrap properties:
+
+* Validate signature from Trusted Issuer 
+* Check JWT status
+* Discard id_token if `aud` does not match access_token `client_id` 
+* Discard Userinfo token not associated with a `sub` from the id_token
+* Check access token and id_token `exp` and `nbf` claims if time sent in Context
+
+
+![](./assets/lock-cedarling-diagram-4.jpg)

docs/cedarling/cedarling-logs.md

@@ -0,0 +1,40 @@
+---
+tags:
+  - administration
+  - lock
+  - authorization / authz
+  - Cedar
+  - Cedarling
+  - logging
+  - audit
+---
+
+
+# Cedarling Logs
+
+## Cedarling Audit Logs
+
+The Cedarling logs contains a record of all a Cedarling's decisions and token validations. 
+Cedarling has four logging options, which are configurable via the `CEDARLING_LOG_TYPE`
+bootstrap property: 
+
+* `off` - no logging
+* `memory` - logs stored in Cedarling in-memory KV store, fetched by client via logging interface. This 
+  is ideal for batching logs without impeding authz performance
+* `std_out` - write logs synchronously to std_out
+* `lock` - periodically POST logs to Jans Lock Server `/audit` endpoint for central archiving. 
+
+There are three different log records produced by the Cedarling:
+
+* `Decision` - The result and diagnostics of an authz decision
+* `System` - Startup, debug and other Cedarling messages not related to authz
+* `Metric`- Performance and usage data
+
+## Jans Lock Server
+
+In enterprise deployments, [Janssen Lock Server](../janssen-server/lock/) collects Cedarling 
+logs and can stream to a database or S3 bucket. The Cedarling decision logs provide compliance 
+evidence of usage of the domain's externalized policies. The logs are also useful for forensic 
+analysis to show everything the attacker attempted, both allowed and denied.
+
+

docs/cedarling/cedarling-overview.md

@@ -0,0 +1,138 @@
+---
+tags:
+  - administration
+  - lock
+  - authorization / authz
+  - Cedar
+  - Cedarling
+---
+
+# Cedarling Overview
+
+## What is Cedar
+
+[Cedar](https://www.cedarpolicy.com/en) is a policy syntax invented by Amazon and used by their 
+[Verified Permission](https://aws.amazon.com/verified-permissions/) service. Cedar policies
+enable developers to implement fine-grain access control and externalize policies. To learn more
+about why the design of Cedar is **intuitive**, **fast** and **safe**, read this 
+[article](https://aws.amazon.com/blogs/security/how-we-designed-cedar-to-be-intuitive-to-use-fast-and-safe/) 
+or watch this [video](https://www.youtube.com/watch?v=k6pPcnLuOXY&t=1779s)
+
+Cedar uses the **PARC** syntax: 
+
+* **P**rincipal
+* **A**ction
+* **R**esource
+* **C**ontext 
+
+For example, you may have a policy that says *Admins* can *write* to the */config* folder. The *Admin* role 
+is the Principal, *write* is the Action, and the */config* folder is the Resource. The Context is used to 
+specify information about the enivironment, like the time of day or network address.
+
+![](../assets/lock-cedarling-diagram-3.jpg)
+
+Fine grain access control makes sense in both the frontend and backend. In the frontend, mastery of 
+authz can help developers build better UX. For example, why display form fields a user is not 
+authorized to see? In the backend, fine grain policies are necessary for a zero trust architecture.
+
+## What is the Cedarling
+
+![](../assets/lock-cedarling-diagram-1.jpg)
+
+Architecturally, the Cedarling is an embeddable stateful Policy Decision Point, or "PDP". It is 
+stateful because it implements an in-memory cache which makes it possible to batch logs and 
+implement other performance optimizations. The Cedarling is written in Rust with bindings 
+to WASM, iOS, Android, and Python--this makes it possible for web, mobile, and cloud developers
+to incorporate the Cedarling into their applications.
+
+The Cedarling is used for both frontend and backend security. Because the frontend is more 
+constrained with regard to memory and compute, this requirement was critical to the design.
+For example, in the backend, a PDP could run in a Linux container. But in the frontend, the 
+Cedarling must run in a browser, using the browser WASM engine. 
+
+How does the Cedarling get the data to calculate a decision? The Principal data is contained in 
+the JWTs--a person, a workload, or both. The Action, Resource and Context are sent by the 
+application as arguments in the authz request. The Cedarling is fast because it has all the data it 
+needs to make a local decision. No cloud round-trips are needed to return an authz decision--a 
+cloud roundtrip may kill the performance of a frontend application. The Cedarling can execute many 
+requests in less then 1ms--this is critical for UX fine grain authorization.
+
+Below is a conceptual diagram showing how you can archiect the Cedarling for frontend and backend
+security. 
+
+![](../assets/lock-cedarling-mobile-generic.jpg)
+
+1. The Cedarling is used to determine if the Mobile Application should be allowed to register. 
+For example, perhaps the IDP wants to execute a policy that restricts registration to mobile
+applications that present a Google Integrity API attestation to indicate the checksum of the binary 
+has not changed, and that the phone is not rooted. 
+1. The Cedarling is used to authenticate the person using the mobile application, i.e. the "User". 
+For example, perhaps the IDP wants to execute a policy that says that 2FA is required from a non
+trusted network. 
+1. The Cedarling is used to determine which scopes to add to the OAuth access token. For example, 
+perhaps if the mobile application presents a software statement assertion JWT (i.e. and "SSA")
+issued by the IDP, the application may request the `financial` scope. 
+1. Once JWT tokens are issued by the IDP, the frontend can use these tokens to evaluate local policies. 
+For example, perhaps the mobile application only allows access to certain features if the Userinfo JWT
+contains a role claim for a "Manager". 
+1. The mobile application may send an OAuth access token to call an API. This API Gateway may route this
+request to a backend service, but only after evaluating certain security policies. For example, perhaps
+the Action POST is only allowed on a Resource (e.g. "URI") when the access token JWT contains a certain 
+scope.
+1. Finally, the Backend API can use the Cedarling to perform its own fine grain authorization. For example, 
+perhaps the Backend only allows transaction greater than $10,000 if the access token contains scope value
+`high-net-worth`. 
+
+This is just a hypothetical example, but hopefully you can see how the Cedarling is used to achieve 
+multilayer security. Each Cedarling has it's own specific policy store. The API Gateway Cedarling instance
+does not need to know the policies or schema for the mobile application. By layering security, you can 
+implement a zero trust architecture.
+
+### Cedarling Interfaces
+
+The developer using the Cedarling to build an application uses three easy interfaces: ("`init`"), 
+authorization ("`authz`") and logging ("`log`"). 
+
+Developers call the `init` interface on startup of their application, causing the Cedarling to read
+its [bootstrap properties](./cedarling-properties) and load its [policy store](./cedarling-policy-store).
+If configured, the Cedarling will also retrieve the most  recent IDP public keys and request JWT 
+status updates.
+
+The `authz` interface provides the main functionality of the Cedarling: to authorize a PARC 
+request from the application by mapping the data sent in the request, and evaluating it with 
+the embedded [Rust Cedar Engine](https://github.com/cedar-policy/cedar). The authz interface 
+answers the question: "Is this action, on this resource, given this context, allowed with 
+these JWTs?". The Cedarling returns the decion--*allow* or *deny*. If denied, the Cedarling
+returns "diagnostics"--additional context if the decision is denied.  During `authz`, the 
+Cedarling can perform two more important jobs: (1) validate JWT tokens; (2) log the resulting
+decision. 
+
+The `log` interface enables developers to retrieve decision and system logs from the Cedarling's 
+in-memory cache. See the Cedarling [log](./cedarling-logs) documentation for more information. 
+
+### Cedarling Components
+
+As a developer, you don't really need to understand how the Cedarling is constructed. But this 
+section is meant to give you an idea to help you get a better understand of what it's actually
+doing. The following diagram is a very high level picture:
+
+![](../assets/lock-cedarling-rust-core-components.jpg)
+
+* **Cedar Engine** is the latest code released from the open source Rust Cedar project. Thanks
+Amazon for supporting this fabulous technology! 
+* **SparKV** is an in-memory key-value store that support automatic expiration of data. For example,
+we don't want to store logs for more then a few minutes. The Cedarling is a *stateful* PDP, but 
+of course it doesn't write anything to disk. The state is stored entirely in Memory, and SparKV
+provides an easy way to do this. 
+* **Init, Authz, and Log Engines** perform actions similar to those described in the interfaces 
+above.
+* **JWT Engine** is used to validate JWT signatures and to check the status of a JWT token. 
+* **Lock Engine** is used for enterprise deployments, where the Cedarling is one of many instances,
+and it needs to pick up its Policy Store from a trusted source and send to store its logs centrally, 
+for example in a SIEM.
+
+So you can see that the Cedar Engine is central to the functionality of the Cedarling. However, the 
+other helper engines make it easier for developer to use Cedar for application security when they 
+are using JWT tokens as the source of Person and Workload identity.
+
+

docs/cedarling/cedarling-policy-store.md

@@ -0,0 +1,40 @@
+---
+tags:
+  - administration
+  - lock
+  - authorization / authz
+  - Cedar
+  - Cedarling
+  - policy store
+---
+
+# Cedarling Policy Store
+
+By convention, the filename is `cedarling_store.json`. It contains all the data the 
+Cedarling needs to evaluate policies and verify JWT tokens:
+
+1. Cedar Schema - Base64 encoded human format
+2. Cedar Policies - Base64 encoded human format
+3. Trusted Issuers - See below syntax
+
+The JSON schema looks like this:
+
+```
+{
+    "app_id": "...",
+    "policies": "...",
+    "schema": "...",
+    "trusted_idps": [...]
+}
+```
+
+
+## Policy and Schema Authoring
+
+You can hand create your Cedar policies and schema in 
+[Visual Studio](https://marketplace.visualstudio.com/items?itemName=cedar-policy.vscode-cedar). 
+Make sure you run the cedar command line tool to validate both your schema and policies. 
+
+The easiest way to author your policy store is to use the Policy Designer in 
+[Agama Lab](https://cloud.gluu.org/agama-lab). This tool helps you define the policies, schema and
+trusted IDPs and to publish a policy store to a Github repository.