Project: CyberArk Conjur (Provisioning / Key Management)
File: token_schema.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 | | Claims Mapping | Mapping between claim name and name of host annotation | | Name | Link | | - | | | JWT Claims | https://auth0.com/docs/tokens/json-web-tokens/json-web-token-claims | Required fields In the authenticator policy, the user will have the ability to declare which claims must be in host annotations. As a result, also in the JWT token When sending an authentication request, the authenticator MUST validate those claims - existence and content Mapping The user should have the ability to map a given "technical" claim name to a more familiar / business one - i.e, in git-lab. Instead of mentioning in the policy "sub" claim, the user will have the ability to mention "job" User will define the enforced claims and claims mapping variables in the authenticator policy. The variables will be checked in the JWT authentication request. The usage of this variables is optional and non enforced. User can authenticate to JWT in the same way he authenticated in stage 1. Using the feature adds more security checks to the authentication. Two new variables will be added to the authenticator policy: enforced-claims mapping-claims ```yaml !policy id: conjur/authn-jwt/VendorY body: !webservice !variable id: enforced-claims !variable id: mapping-claims ``` | Name | Value | Description | | - | | | | enforced-claims | ref, sub | List of claims as they appear in host annotation | | mapping-claims | branch: ref, job: sub | Mapping between host annotation to JWT claim | For any claim mapped, we will add the host annotation to the `enforced-claims` variable and not the JWT claim name. The values above are examples and they can be any claims. If one of the values of this variables contain these words from deny list authentication request will be denied: iss exp iat nbf The following class diagram, represent the flow of checking the enforced claims and the claim mapping. When validate_restrictions is called in JWTVendorConfiguration class the following will happen as a result: The `validate_restrictions` function will call `CreateConstraintsFromPolicy` that create constraints object checking the hosts annotations. It create instance of `NonEmptyConstraint` to check we have at least one host annotation. Will call `LoadEnforcedClaims` command class to load the list of enforced claims for the `enforced-claims` variable. This class will create and return `RequiredConstraint`

If variable configured but not populated error be thrown If variiable with invalid value error be thrown If variable not configured empty list will be returned Will call LoadClaimsMapping to load mapping and convert relevant enforced claims from mapping It create `RequiredConstraint` object from it Will create `NonPremmitedConstraint` from deneid claims const ("iat","exp"...) With Create `MultipleConstraints` object with all the constraint objects above and return it The `validate_restrictions` functon will call `CreateValidatorFromPolicy` to create validator with the claims mapping loaded Will call the `LoadClaimsMapping` command class to get dictionary between claim to annotation. If variable configured but not populated error be thrown If variiable with invalid value error be thrown If variable not configured empty hash will be returned It create ValidateRestrictionOneToOne object and will return it The logic of ValidateRestrictionOneToOne will check restriction by this order: If there is mapping for it will use mapping. If the mapped claim not in token we raise error If there is no mapping we will check token has claim from annotation. If its not there we throw error `ValidateResourceRestrictions` will be called with the constraints and the validator from the previous steps. This run will check the claims in the token and annotations. If anything wrong like a missing claim in the host annotation or a claim has an invalid value, an error with be thrown and the authentication request will be denied. Enforced claims and mapping are not enforced therefore the JWT authentication will remain backwards compatible. JWT Authenticator | Mission | Estimation | | | - | | Add LoadEnforcedClaims | 1 SP | | Add NonPremmitedConstraint | 1 SP | | Add LoadClaimsMapping | 1 SP | | Change ValidateRestrictionOneToOne to work with mapping | 2 SP | | Add CreateConstraintsFromPolicy Command Class and use it | 2 SP | | Add CreateValidatorFromPolicy and use it | 2 SP | | Add status checks for enforced claims and claims mapping configuration | 3 SP | | Add Cucumber tests for enforced claims and mapping | 5 SP | | Check "aud" annotation with list | 3 SP | | Documentation | | If enforced claims or clamins mapping has invalid value we should fail the authentication. Confluence: "Token Schema Test Plan" What happens if host already exists and than we configure enforced claims that he doesn't check - Documentation What about claims that are dictioneires - Out Of Scope. When enforced claims or mapping is changed all relevant hosts need to be updated. When mapping of enforced claim is changed or added enforced claims need to be added. 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 | | | | | Team leader | @benoaviram | | Product owner | @hilagross | | System architect | @tzheleznyak | | Security architect | @sashacher | | QA architect | @eladkug |