Project: CyberArk Conjur (Provisioning / Key Management)
File: complex_token.md

* * * + - - * + + * * * * | Term | Description | | - | | | JWT Claims | Claims are pieces of information asserted about a subject | | Host Annotation | Defines the checks that we should do on authentication request for host. In JWT authentication its a claim check. | | Enforced Claims | JWT-specific claims that a host must validate their existance and value | | Aliased Claims | Mapping between claim name and name of host annotation | | Listed Annotation | Giving list instead of single value to the host annotation | | Listed Values | Giving list instead of single value to claim in the token | | Nested Claims | Claims that are not in the first level of "JSON hirerchy". JSON supports dictioneries and lists inside of keys. | | Name | Link | | -- | | | JWT Claims | https://auth0.com/docs/tokens/json-web-tokens/json-web-token-claims | | Design Of JWT Authenticator | https://github.com/cyberark/conjur/blob/master/design/authenticators/authnjwt/authnjwtsolutiondesign.md | | Design Of Aliased Claims And Enforced Claims | https://github.com/cyberark/conjur/blob/master/design/authenticators/authnjwt/tokenschema.md | | Ruby dig Function | https://apidock.com/ruby/v255/Hash/dig | Functional signof document (Confluence: JWT Authenticator - re-scope) Extending the JWT generic authenticator by providing a more complex schema to help map JWT fields to host annotation. Still, have the end user be responsible for setting this schema. JWT Authenticator will support: Nested claims inside dictioneries and arrays. Retrivial of Identity from nested claims Arrays of values in token and in host annotation and in token. Include releationship between each element of host annotation to list in token. User will be able to define host annotations and configuration variables in the generic JWT authenticator using hirarchy to mention the wanted claims. When there is a list in host annotation each value of the list needs to be included in the token in order to authentication to pass. New format changes that need to be validated and if authentication is not according to them we fail the authentication. Annotations - Now support nested access using / to go inside of dict and [] to access element of array, counting starts from zero Claim Aliases - Can't contain slashes and []. They should simplify the token and not make it more harder to use. For example we this complex token ```json { "sub": "1234567890", "iat": 1516239022, "platform":"linux" "details": [ # NEW: This is example of nested array in JWT token { "identity": "myapp"}, # NEW: This is example of nested identity in token { "branch": "main"}, { "subdomains":

# NEW: This is example of listed values "load_balancers": "ec2-address" } ] } ``` ```yaml !host: id: myapp annotations: authn-jwt/vendor/details[2]/load_balancers: ec2-address # NEW: This is example of aliased claim. See example below authn-jwt/vendor/details[1]/branch: main # NEW: This is example of JSON array in token stracture authn-jwt/vendor/details[2]/subdomains: # NEW: This is example for array in host annotation. Each one should be included in token google.com amazon.com authn-jwt/vendor/details[2]/subdomains: facebook.com # NEW: This is another example for include relationship between host annotation and value in token both cases work. ``` | Name | Value | Description | | - | | | | token-app-property | details[0]/identity | The identity in the token is inside details section in the first value in the of array in claim called "identity". | | aliased-claims | loadbalancers:details[2]/loadbalancers | Example of usage of aliased claims to simplify usage of nested claim. Instead<br />of writing annotation with full path to "loadbalancers" claim user use just loadbalancers for the annotation. | | Enforced-claims | details[2]/load_balancers | Nested claim can be enforced similar to a regular claim | Token-App-Property ignored claim aliasing Token-app-propery cant support claim that its value is array. We don't support token with claims that contain "/" and [] in their name. Enforced claims ignore aliases and are according to the claims in token. Status API will also validate that : New format of enforced claims (same as format for host annotations) New format for claim-aliases Token-App-Property not ending with access to array element The following class diagram, represent the points in the generic JWT authenticator that need to change in order to support complex token. Currently the validation of single host annotation happens inside `ValidateRestrictionsOneToOne` and until this usecase it was enough for the one to one validation. But now when we need to support nested access to the token and listed values and annotations and support also the old form of annotation and values we need a smarter restriction validatior. Therefore we will remove the `ValidateRestrictionsOneToOne ` and will create a new class called `ValidateGenericRestritction` `ValidateGenericRestriction` will retrieve value from token and decide to which class forward the validation according the type of the value of the token. It will forward strings to `ValitateRestrictionOneToOne` and lists to `ValitateRestrictionInclude` `ValidateRestrictionOneToOne` will support nested claims and do the regular one to one validation like we done until now `ValidateRestrictionInclude` will check if the value in the host annotation included in the list in the token. If the host annotation is also a list it will check that every element in host annotation is included in the list in the token. It will support nested

`ParseClaimPath` a util class for accessing for converting annotation name to array representing the path in the token. Which will be used to access it in the token using built in `dig` function. `IdentityFromDecodedToken` will use the `ExtractNestedValue` util to access the claim holding the identity doing the authentication request.Backwards Compatibility `ValidateClaimName` should validate claims according to new format Validation to annotation according to the nested format should be added. The restriction validation will be backward compatible and old way of usage of the JWT authenticator will work on it. The flow don't change from what it was before but this flow diagram has green backgroud areas where there should be change @sashacher alredy created a draft PR for accessing nested claims using ruby dig function. https://github.com/cyberark/conjur/pull/2352 JWT Authenticator Changing this for other authenticators Support for 1 to 1 validation inside array When the step is `number.number` it means it can be done concurrently Tests also can be done by more then one person | Step | Mission | Estimation | | - | | - | | 1.1 | `ValidateRestrictionIncluded` that check each element in restriction included in token | 1 SP | | 1.2 | `ValidateGenericRestriction` to route the validation relevant restriction validator | 2 SP | | 1.3 | Add `ParseClaimPath` with proper UT | 2 SP | | 1.4 | Validate aliases format | 1 SP | | 1.5 | Add validation of host valdiation keys to resource restrictions | 2 SP | | 2.1 | Call `ParseClaimPath` from the restriction validators | 1 SP | | 2.2 | Call `ExtractNestedValue` from `IdentityFromDecodedToken` | 1 SP | | 3 | Tests | 2 SP | | | Documentation | | Total 11 SP Confluence - Different Cases Of Complex Token Document the new format for annotations Documentat new format for claims Document the disclaimers `token-app-property` supports nested claims in dicts and lists but not supports array as a value. The token-app-propery validation and host annotation validation may break if vendor changes order of claims if it includes nesting in array. Add details about strength of host annotation for array. Solution designed is approved Test plan is reviewed Acceptance criteria have been met Tests are implemented according to test plan The behaviour is documented in Conjur Open Source and Enterprise All relevant components are released | Persona | Name | Approved | | | -- | -- | | Team leader | @benoaviram | Approved | | Product owner | @hilagross | Approved | | System architect | @oburstein-hub | Approved | | Security architect | @sashacher | Approved | | QA architect | @eladkug | Approved |