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

rmarinn · 2025-02-18T04:38:08Z

Is your feature request related to a problem? Please describe.

Currently, defining and using tokens into requires a user to do 4 things:

1. Have the token defined in the CEDARLING_TOKEN_CONFIGS

CEDARLING_TOKEN_CONFIGS = {
    "access_token": {
        "entity_type_name": "Access_token",
        "iss": "enabled",
        "aud": "enabled",
        "sub": "enabled",
        "exp": "enabled"
    }
}

2. Have the entity of the token defined in the cedar schema

entity Access_token = {
    "iss": TrustedIssuer, 
    "aud": __cedar::String, 
    "sub": __cedar::String, 
    "exp": __cedar::Long, 
    "scope": __cedar::String
};

3. And define it in the Trusted Issuer Metadata Schema:

{
    "name": "Google", 
    "description": "Consumer IDP", 
    "openid_configuration_endpoint": "https://accounts.google.com/.well-known/openid-configuration",
    "tokens_metadata": {
        "access_token": {
            "trusted": true,
            "principal_identifier": "jti",
            "user_id": "OPTIONAL email | sub | uid",
            "role_mapping": "OPTIONAL role | group | memberOf",
            "claim_mapping": { ... }
        },
    },
}

Set the CEDARLING_TOKEN_ENTITY_MAPPER bootstrap property as follows:

{
    "id_token": "Jans::User",
    "userinfo_token": "Jans::User",
    "access_token": "Jans::Workload",
    "customer1_token": "Customer::Widget"
}

This having to look at four places to figure out where the token entity will go introduces some confusion and could be improved.

Describe the solution you'd like

We can reduce this into two steps by moving removing the CEDARLING_TOKEN_CONFIGS then moving it's contents to the Trusted Issuer Metadata schema:

{
    "name": "Google", 
    "description": "Consumer IDP", 
    "openid_configuration_endpoint": "https://accounts.google.com/.well-known/openid-configuration",
    "tokens_metadata": {
        "access_token": {
            "trusted": true,
            "entity_type_name": "Jans::AccessToken",        <-- Cedar Object of token
            "principal_mapping": ["Jans::Workload"],          <-- Where to put this token
            "token_id": "jti",                            <-- Should always be jti 
            "user_id": "email | sub | uid",               <--- OPTIONAL
            "role_mapping": "role | group | memberOf",       <--- OPTIONAL
            "workload_id" : "client_id | rp_id",               <--- OPTIONAL 
            "claim_mapping": { ... },
            "required_claims": ["jti", "iss", "aud", "sub", "exp", "nbf", "some_custom_claim"]
        },
    },
}

Implementation:

Token Validation: This will be implemented through the "required_claims" field in the respective token entity. If a required claim is a registered claim name under RFC 7519 Section 4.1, the claim will be validated.
Token Entity Name: This field defines the Cedar entity name of the token. This is implemented through the "token_entity_name" field in the respective token entity. Note that the token entity defined here MUST also be defined in the Cedar schema. Also note that the token name here will be how we reference the token in when calling Cedarling.authorize().
Token -> Entity Mapping: This mapping defines which entities the token will be in. This will be implemented through the "entity_mapping" field in the respective token entity. Note that if an entity mapping is defined here, the entity MUST also be defined in the Cedar schema.

Describe alternatives you've considered

Having a single JSON/YAML/TOML config where we define everything then compile it into the cedar schema.
Defining the tokens in the cedar schema using comments, drawing inspiration from JSDoc.

Additional context

At the time of this writing, it was discussed that we'll settle for having to define the tokens in two places since it's still better than 3 places but we don't really want to touch the cedar schema.

The text was updated successfully, but these errors were encountered:

olehbozhok · 2025-02-18T15:14:18Z

why we need "required_claims": ["jti", "iss", "aud", "sub", "exp", "nbf", "some_custom_claim"] if it is defined in schema?

olehbozhok · 2025-02-18T15:14:40Z

and why we need "entity_type_name": "Jans::AccessToken" and "entity_mapping": ["Jans::Workload", "Jans::User"], if it makes actually the same things?

olehbozhok · 2025-02-18T15:19:48Z

Also, we need to define what key will be used as UID for cedar-policy entity.
It means that entity_mapping should be object:

"entity_mapping": {"Jans::AccessToken":{"uid_claim":"jti"}}

or array of object:

"entity_mapping": [
  {
    "entity":"Jans::AccessToken",
    "uid_claim":"jti"
  }
]

Also, this approach allows extending if some requirements will be changed.

__
P.S.: And using this approach we no need key role_mapping because can be used entity_mapping

nynymike · 2025-02-18T17:40:24Z

We missed something--part of this was already done https://github.com/JanssenProject/jans/wiki/Cedarling-Nativity-Plan#token-entity-mapper

{
    "id_token": "Jans::User",
    "userinfo_token": "Jans::User",
    "access_token": "Jans::Workload",
    "customer1_token": "Customer::Widget"
}

rmarinn · 2025-02-19T05:13:11Z

We missed something--part of this was already done https://github.com/JanssenProject/jans/wiki/Cedarling-Nativity-Plan#token-entity-mapper

we should probably just remove that too so the user doesn't have to look at the bootstrap config for the mapping.

I think it's a better user experience to have the settings regarding tokens with the token entity metadata schema.

rmarinn · 2025-02-19T07:10:52Z

Also, we need to define what key will be used as UID for cedar-policy entity. It means that entity_mapping should be object:
"entity_mapping": {"Jans::AccessToken":{"uid_claim":"jti"}}
or array of object:
"entity_mapping": [
  {
    "entity":"Jans::AccessToken",
    "uid_claim":"jti"
  }
]
Also, this approach allows extending if some requirements will be changed.

__ P.S.: And using this approach we no need key role_mapping because can be used entity_mapping

The entity_mapping says in which principal entities the token entity can appear.
The entity_type_name is the name of the token entity, e.g. "Access_token".

rmarinn · 2025-02-19T07:12:45Z

why we need "required_claims": ["jti", "iss", "aud", "sub", "exp", "nbf", "some_custom_claim"] if it is defined in schema?

It was discussed to not use the Cedar schema as a way to define behavior anymore.

olehbozhok · 2025-02-19T15:19:36Z

The entity_mapping says in which principal entities the token entity can appear.

The entity_type_name is the name of the token entity, e.g. "Access_token".

Thanks for explanation, please don't forget to add it to documentation

olehbozhok · 2025-02-20T18:14:19Z

just for note

ossdhaval · 2025-02-25T08:32:21Z

@rmarinn If this is a breaking change (requiring a major release) then you can change the title to refactor(jans-cedarling)! instead of refactor!(jans-cedarling). Refer here

rmarinn · 2025-02-25T22:24:49Z

@rmarinn If this is a breaking change (requiring a major release) then you can change the title to refactor(jans-cedarling)! instead of refactor!(jans-cedarling). Refer here

Okay, i changed it. I misplaced the exclamation point !.

rmarinn added the enhancement label Feb 18, 2025

rmarinn self-assigned this Feb 18, 2025

mo-auto added comp-jans-cedarling Touching folder /jans-cedarling kind-enhancement Issue or PR is an enhancement to an existing functionality labels Feb 18, 2025

rmarinn changed the title ~~refactor!(jans-cedarling): move TOKEN_CONFIGS into the token_metadata schema~~ refactor(jans-cedarling)!: move TOKEN_CONFIGS into the token_metadata schema Feb 25, 2025

rmarinn linked a pull request Mar 3, 2025 that will close this issue

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

Open

6 tasks

moabu added this to the next-release milestone Mar 6, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

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

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

rmarinn commented Feb 18, 2025 •

edited by nynymike

Loading

olehbozhok commented Feb 18, 2025

olehbozhok commented Feb 18, 2025

olehbozhok commented Feb 18, 2025 •

edited

Loading

nynymike commented Feb 18, 2025 •

edited

Loading

rmarinn commented Feb 19, 2025

rmarinn commented Feb 19, 2025

rmarinn commented Feb 19, 2025 •

edited

Loading

olehbozhok commented Feb 19, 2025 •

edited

Loading

olehbozhok commented Feb 20, 2025

ossdhaval commented Feb 25, 2025 •

edited

Loading

rmarinn commented Feb 25, 2025

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

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

Comments

rmarinn commented Feb 18, 2025 • edited by nynymike Loading

Is your feature request related to a problem? Please describe.

Describe the solution you'd like

Describe alternatives you've considered

Additional context

olehbozhok commented Feb 18, 2025

olehbozhok commented Feb 18, 2025

olehbozhok commented Feb 18, 2025 • edited Loading

nynymike commented Feb 18, 2025 • edited Loading

rmarinn commented Feb 19, 2025

rmarinn commented Feb 19, 2025

rmarinn commented Feb 19, 2025 • edited Loading

olehbozhok commented Feb 19, 2025 • edited Loading

olehbozhok commented Feb 20, 2025

ossdhaval commented Feb 25, 2025 • edited Loading

rmarinn commented Feb 25, 2025

rmarinn commented Feb 18, 2025 •

edited by nynymike

Loading

olehbozhok commented Feb 18, 2025 •

edited

Loading

nynymike commented Feb 18, 2025 •

edited

Loading

rmarinn commented Feb 19, 2025 •

edited

Loading

olehbozhok commented Feb 19, 2025 •

edited

Loading

ossdhaval commented Feb 25, 2025 •

edited

Loading