refactor(jans-cedarling)!: move TOKEN_CONFIGS into the token_metadata schema

docs/cedarling/cedarling-entities.md

@@ -0,0 +1,140 @@
+---
+tags:
+  - administration
+  - Cedar
+  - Cedarling
+  - Principal
+  - Mappings
+---
+
+# Cedarling Principal Mappings
+
+Cedarling automatically creates the following entities:
+
+- [Trusted Issuer](#trusted-issuer-entity)
+- [Workload](#workload-entity)
+- [User](#user-entity)
+- [Role](#role-entity)
+- [JWT Entities](#jwt-entities)
+
+The entity type names of the Workload and User entities can be customized via the `CEDARLING_MAPPING_USER` and `CEDARLING_MAPPING_WORKLOAD` [properties](./cedarling-properties.md) respectively.
+
+>  ***Notes***
+> - All entity creation and attribute population logic is configurable via the [Token Metadata Schema (TEMS)](./cedarling-policy-store.md#token-metadata-schema) and [Cedarling bootstrap properties](./cedarling-properties.md).
+> - Attribute presence depends on token contents and policy store configuration.
+> - Role inheritance simplifies **user-role mapping** for RBAC policy enforcement.
+
+## Trusted Issuer
+
+Cedarling creates a Trusted Issuer entity at startup for each trusted issuer defined in the [policy store](./cedarling-policy-store.md#trusted-issuers-schema).
+
+- *Default Type Name:* `Jans::TrustedIssuer`
+- *Entity ID:*  Set using the name of the trusted issuer object in the policy store.
+
+## Workload Entity
+
+Cedarling creates a **Workload** entity for each request when the `CEDARLING_WORKLOAD_AUTHZ`  [bootstrap property](./cedarling-properties.md) is set to `enabled`.
+
+- *Default Type Name:* `Jans::Workload`
+- *Entity ID:* Determined by the `workload_id` attribute from the [Token Entity Metadata Schema (TEMS)](./cedarling-policy-store.md#token-metadata-schema).
+- If `workload_id` is **not set**, Cedarling will fall back to the following claims (in order):
+
+  1. `aud` from the `access_token`
+  2. `client_id` from the `access_token`
+
+### Example Workload Schema
+
+```cedarschema/
+entity Workload = {
+  iss: TrustedIssuer,
+  client_id?: String,
+  aud?: String,
+  name?: String,
+  rp_id?: String,
+  spiffe_id?: String,
+  access_token?: Access_token,
+};
+```
+
+#### Attribute Mappings
+
+| Attribute | Source |
+| `iss` | Reference to the Trusted Issuer entity created at startup |
+| `client_id` | the `"lient_id` claim from the JWT |
+| `aud` | the `aud` claim from the JWT |
+| `name` | the `name` claim from the JWT |
+| `spiffe_id` | the `spiffe_id` claim from the JWT |
+| `rp_id` | Derived from either the `aud` or the `client_id` claim from the JWT |
+
+## User Entity
+
+Cedarling creates a **User** entity for each request when the `CEDARLING_USER_AUTHZ`  [bootstrap property](./cedarling-properties.md) is set to `enabled`.
+
+- *Default Type Name:* `Jans::User`
+- *Entity ID:* Determined by the `user_id` attribute from the [TEMS](./cedarling-policy-store.md#token-metadata-schema).
+- If `user_id` is **not set**, Cedarling will fall back to the following claims (in order):
+
+  1. `sub` from the `userinfo_token`
+  2. `sub` from the `id_token`
+
+### Default User Schema
+
+```cedarschema
+entity User in [Role] = {
+  sub?: String,
+  email?: email_address,
+  phone_number?: String,
+  role?: Set<String>,
+  username?: String,
+  id_token?: Id_token,
+  userinfo_token?: Userinfo_token,
+};
+```
+
+#### **Attribute Mappings**
+
+User attributes are derived from the combined claims in the `id_token` and the `userinfo_token` if available.
+
+**Standard Claims**
+
+- `sub`
+- `role`
+- `email`
+- `phone_number`
+- `username`
+- `birthdate`
+- `country`
+
+## Role Entity
+
+Cedarling automatically attempts to create **Role** entities for each request.
+
+- **Default Type Name:** `Jans::Role`
+- **Entity ID:** Determined by the `role_mapping` attribute from the [TEMS](./cedarling-policy-store.md#token-metadata-schema).
+- If `role_mapping` is **not set**, Cedarling will try to create Role entities based on the following claims (in order):
+
+  1. `role` from the `userinfo_token`
+  2. `role` from the `id_token`
+
+### RBAC Support
+
+Since Role entities are automatically assigned as parents of User entities, you can easily define RBAC policies like:
+
+```cedarschema
+permit (
+   principal == Jans::Role::"Admin",
+   action in [Jans::Action::"Compare",Jans::Action::"Execute"],
+)
+```
+
+## JWT Entities
+
+Cedarling creates **JWT entities** for each token defined in the [trusted issuers schema](./cedarling-properties.md#trusted-issuers-schema). 
+
+
+- *Type Name:* Determined by the `entity_type_name` attribute from the [TEMS](./cedarling-policy-store.md#token-metadata-schema).
+- *Entity ID:* Determined by the `token_id` attribute from the [TEMS](./cedarling-policy-store.md#token-metadata-schema).
+
+### Attribute Mappings
+
+Each **claim** in the JWT is automatically added to the JWT entity's attributes.

docs/cedarling/cedarling-policy-store.md

@@ -156,22 +156,25 @@ Here is a non-normative example of the `policies` field:
 This record contains the information needed to validate tokens from this issuer:
 
 ```json
-"identity_source": {
-  "some_unique_id" : {
+"trusted_issuers": {
+  "trusted_issuer_id" : {
     "name": "name_of_the_trusted_issuer",
     "description": "description for the trusted issuer",
     "openid_configuration_endpoint": "https://<trusted-issuer-hostname>/.well-known/openid-configuration",
     "tokens_metadata": {
       "access_tokens": {
         "trusted": true,
-        "principal_identifier": "jti",
+        "token_id": "jti",
         ...
       },
       "id_tokens": { ... },
       "userinfo_tokens": { ... },
       "tx_tokens": { ... },
       ...
     }
+  },
+  "another_issuer_id": {
+    ...
   }
   ...
 }
@@ -180,7 +183,7 @@ This record contains the information needed to validate tokens from this issuer:
 - **name** : (*String*) The name of the trusted issuer.
 - **description** : (*String*) A brief description of the trusted issuer, providing context for administrators.
 - **openid_configuration_endpoint** : (*String*) The HTTPS URL for the OpenID Connect configuration endpoint (usually found at `/.well-known/openid-configuration`).
-- **identity_source** : (*Object*, *optional*) Metadata related to the tokens issued by this issuer.
+- **trusted_issuer_id** : (*Object*, *optional*) Metadata related to a particular issuer. You can add as many trusted issuers you want. Furthermore, the name this object is what will be used as the entity ID of the [Trusted Issuer](./cedarling-entities.md#trusted-issuer) that Cedarling automatically creates at startup.
 - **tokens_metadata** : (*Object*, *optional*) Tokens metadata in a map of *token name* -> *token metadata*. See  [Token Metadata Schema](#token-metadata-schema).
 
 ### Token Metadata Schema
@@ -189,8 +192,12 @@ The Token Entity Metadata Schema defines how tokens are mapped, parsed, and tran
 
 ```json
 {
-  "user_id": "<field name in token (e.g., 'email', 'sub', 'uid', etc.) or '' if not used>",
-  "role_mapping": "<field for role assignment (e.g., 'role', 'memberOf', etc.) or '' if not used>",
+  "trusted": true,
+  "token_id": "jti",
+  "workload_id": "aud | client_id",
+  "user_id": "sub | uid | email",
+  "role_mapping": "role | group | memberOf",
+  "required_claims": ["iss", "exp", "some_custom_claim", ...],
   "claim_mapping": {
     "mapping_target": {
       "parser": "<type of parser ('regex' or 'json')>",
@@ -288,7 +295,7 @@ Here is a non-normative example of a `cedarling_store.json` file:
         }
     },
     "schema": "schema_encoded_in_base64",
-    "identity_source": {
+    "trusted_issuers": {
         "08c6c18a654f492adcf3fe069d729b4d9e6bf82605cb" : {
             "name": "Google",
             "description": "Consumer IDP",
@@ -312,7 +319,7 @@ Here is a non-normative example of a `cedarling_store.json` file:
               "trusted": true,
               "principal_identifier": "",
               "role_mapping": "",
-            },            
+            },
         }
     }
 }
@@ -334,18 +341,18 @@ Here is example of a minimum supported `cedar-policy schema`:
 
 ```cedar-policy_schema
 namespace Jans {
-entity id_token = {"aud": String,"iss": String, "sub": String};
-entity Role;
-entity User in [Role] = {};
-entity Access_token = {"aud": String,"iss": String, "jti": String, "client_id": String};
-entity Workload = {};
-
-entity Issue = {};
-action "Update" appliesTo {
-  principal: [Workload, User, Role],
-  resource: [Issue],
-  context: {}
-};
+  entity id_token = {"aud": String,"iss": String, "sub": String};
+  entity Role;
+  entity User in [Role] = {};
+  entity Access_token = {"aud": String,"iss": String, "jti": String, "client_id": String};
+  entity Workload = {};
+
+  entity Issue = {};
+  action "Update" appliesTo {
+    principal: [Workload, User, Role],
+    resource: [Issue],
+    context: {}
+  };
 }
 ```
 

docs/cedarling/cedarling-properties.md

@@ -42,7 +42,6 @@ These Bootstrap Properties control default application level behavior.
 * **`CEDARLING_JWT_SIG_VALIDATION`** : `enabled` | `disabled` -- Whether to check the signature  of all JWT tokens. This requires an `iss` is present.
 * **`CEDARLING_JWT_STATUS_VALIDATION`** : `enabled` | `disabled` -- Whether to check the status of the JWT. On startup, the Cedarling should fetch and retreive the latest Status List JWT from the `.well-known/openid-configuration` via the `status_list_endpoint` claim and cache it. See the [IETF Draft](https://datatracker.ietf.org/doc/draft-ietf-oauth-status-list/) for more info.
 * **`CEDARLING_JWT_SIGNATURE_ALGORITHMS_SUPPORTED`** : Only tokens signed with these algorithms are acceptable to the Cedarling.
-* **`CEDARLING_TOKEN_CONFIGS`** : JSON object containing token specific configs. See: [Token Configs](#token-configs).
 * **`CEDARLING_ID_TOKEN_TRUST_MODE`** :  `Strict` | `None`. Varying levels of validations based on the preference of the developer.
 `Strict` mode requires (1) id_token `aud` matches the access_token `client_id`; (2) if a Userinfo token is present, the `sub` matches the id_token, and that the `aud` matches the access token client_id.
 
@@ -60,7 +59,6 @@ These Bootstrap Properties control default application level behavior.
 ## Required keys for startup
 
 * **`CEDARLING_APPLICATION_NAME`
-* **`CEDARLING_TOKEN_CONFIGS` - check if default implementation of Token Config is suitable for you.
 
 To enable usage of principals at least one of the following keys must be provided:
 
@@ -84,91 +82,6 @@ The `CEDARLING_USER_WORKLOAD_BOOLEAN_OPERATION` property specifies what boolean
 * **AND**: authz will be successful if `USER` **AND** `WORKLOAD` is valid.
 * **OR**: authz will be successful if `USER` **OR** `WORKLOAD` is valid.
 
-## Token Configs
-
-The token configs property sets the entity type name of a token and it's validation settings. Below is an example of the `CEDARLING_TOKEN_CONFIGS`:
-
-```js
-CEDARLING_TOKEN_CONFIGS = {
-  "access_token": {
-    "entity_type_name": "Jans::Access_token",
-    "iss": "enabled",
-    "aud": "enabled",
-    "sub": "enabled",
-    "jti": "enabled",
-    "nbf": "enabled",
-    "iat": "enabled",
-    "exp": "enabled",
-  },
-  "id_token": {
-    "entity_type_name": "Jans::id_token",
-    "exp": "enabled",
-  },
-  "userinfo_token": {
-    "entity_type_name": "Jans::Userinfo_token",
-    "exp": "enabled",
-  },
-  "custom_token1": {
-    "entity_type_name": "Jans::SomeCustom_token",
-    "exp": "enabled",
-  },
-  "custom_token2": {
-    "entity_type_name": "Jans::AnotherCustom_token",
-    "exp": "enabled",
-  },
-  // more custom tokens can be added here
-}
-```
-
-## Default implementation of Token Config
-
-Here is rust code default implementation of Token Configs (`CEDARLING_TOKEN_CONFIGS`). This is used when no custom token config is provided.
-
-```rust
-impl Default for TokenConfigs {
-    fn default() -> Self {
-        Self(HashMap::from([
-            ("access_token".to_string(), TokenConfig {
-                entity_type_name: "Jans::Access_token".to_string(),
-                claims: ClaimsValidationConfig {
-                    iss: FeatureToggle::Enabled,
-                    sub: FeatureToggle::Disabled,
-                    aud: FeatureToggle::Disabled,
-                    exp: FeatureToggle::Enabled,
-                    nbf: FeatureToggle::Disabled,
-                    iat: FeatureToggle::Disabled,
-                    jti: FeatureToggle::Enabled,
-                },
-            }),
-            ("id_token".to_string(), TokenConfig {
-                entity_type_name: "Jans::id_token".to_string(),
-                claims: ClaimsValidationConfig {
-                    iss: FeatureToggle::Enabled,
-                    sub: FeatureToggle::Enabled,
-                    aud: FeatureToggle::Enabled,
-                    exp: FeatureToggle::Enabled,
-                    nbf: FeatureToggle::Disabled,
-                    iat: FeatureToggle::Disabled,
-                    jti: FeatureToggle::Disabled,
-                },
-            }),
-            ("userinfo_token".to_string(), TokenConfig {
-                entity_type_name: "Jans::Userinfo_token".to_string(),
-                claims: ClaimsValidationConfig {
-                    iss: FeatureToggle::Enabled,
-                    sub: FeatureToggle::Enabled,
-                    aud: FeatureToggle::Enabled,
-                    exp: FeatureToggle::Enabled,
-                    nbf: FeatureToggle::Disabled,
-                    iat: FeatureToggle::Disabled,
-                    jti: FeatureToggle::Disabled,
-                },
-            }),
-        ]))
-    }
-}
-```
-
 ## ID Token Trust Mode
 
 The level of validation for the ID Token JWT can be set to either `None` or `Strict`.
@@ -233,17 +146,6 @@ Below is an example of a bootstrap config in JSON format. Not all fields should
   "CEDARLING_POLICY_STORE_URI": null,
   "CEDARLING_POLICY_STORE_LOCAL": null,
   "CEDARLING_POLICY_STORE_LOCAL_FN": "./example_files/policy-store.json",
-  "CEDARLING_TOKEN_CONFIGS": {
-    "access_token": {
-      "entity_type_name": "Jans::Access_token"
-    },
-    "id_token": {
-      "entity_type_name": "Jans::id_token"
-    },
-    "userinfo_token": {
-      "entity_type_name": "Jans::Userinfo_token"
-    }
-  },
   "CEDARLING_POLICY_STORE_ID": "gICAgcHJpbmNpcGFsIGlz",
   "CEDARLING_LOG_TYPE": "std_out",
   "CEDARLING_LOG_LEVEL": "INFO",
@@ -304,11 +206,6 @@ CEDARLING_WORKLOAD_AUTHZ: enabled
 CEDARLING_POLICY_STORE_URI: null
 CEDARLING_POLICY_STORE_LOCAL: null
 CEDARLING_POLICY_STORE_LOCAL_FN: ./example_files/policy-store.json
-CEDARLING_TOKEN_CONFIGS:
-    access_token: { entity_type_name: "Jans::Access_token" }
-    id_token: { entity_type_name: "Jans::id_token" }
-    userinfo_token: { entity_type_name: "Jans::Userinfo_token" }
-
 CEDARLING_POLICY_STORE_ID: gICAgcHJpbmNpcGFsIGlz
 CEDARLING_LOG_TYPE: std_out
 CEDARLING_LOG_LEVEL: INFO
@@ -322,7 +219,6 @@ CEDARLING_JWT_STATUS_VALIDATION: disabled
 CEDARLING_JWT_SIGNATURE_ALGORITHMS_SUPPORTED:
     - HS256
     - RS256
-
 CEDARLING_ID_TOKEN_TRUST_MODE: strict
 CEDARLING_LOCK: disabled
 CEDARLING_LOCK_SERVER_CONFIGURATION_URI: null