Re: [DISCUSS] Should roles_claim_name be marked as deprecated and replaced in favor of roles_claim_path

[Ronny Berndt <ro...@apache.org>]

The feature is already included in main and I want to finish and add the documentation for it.

Are there any further hints and comments?

New PR at: https://github.com/apache/couchdb/pull/4232

Summary:
The question is, if we want to deprecate the old setting roles_claim_name and replace
it with roles_claim_path or do we want to have both settings in parallel with overlapping (sub-) functionality?

Cheers,
Ronny

> Am 01.09.2022 um 06:53 schrieb Nick Vatamaniuc <va...@gmail.com>:
> 
> If RCPs have all the functionality of RCNs, I think it makes sense to
> deprecate RCNs.
> 
> On Tue, Aug 30, 2022 at 9:02 AM Ronny Berndt <ro...@apache.org> wrote:
>> 
>> Overview
>> 
>> In a JWT token it is possible to add an attribute for role claims.
>> If the roles are presented as top-level attribute like
>> 
>> {
>>  "couchdb-roles": [
>>    "my_role_1",
>>    "my_role_2"
>>  ]
>> }
>> 
>> and setting the parameter roles_claim_name in the config file to
>> 
>> [jwt_auth]
>> roles_claim_name = couchdb-roles
>> 
>> CouchDB was able to read that attributed and take over that roles.
>> This doesn't work, if the claim roles are nested, eg:
>> 
>> {
>>  "my" :{
>>    "nested": {
>>       "couchdb-roles": [
>>         "my_role_1",
>>         "my_role_2"
>>       ]
>>    }
>>  }
>> }
>> 
>> To allow this and for backwards compatibility, a new config parameter `roles_claim_path`
>> is introduced to allow nested role claims. To allow the example from above, yo can use
>> the following syntax:
>> 
>> [jwt_auth]
>> roles_claim_path = my.nested.couchdb-roles
>> 
>> It is now possible to specify nested (& unnested "\." prevents interpreting as nested)
>> JSON paths in role_claim_path, like
>> roles_claim_path = foo.bar\.zonk.baz\.buu.baa.baa\.bee.roles which is equivalent to
>> 
>> "foo": {
>>  "bar.zonk": {
>>    "baz.buu": {
>>      "baa": {
>>        "baa.bee": {
>>          "roles": [
>>            "my_nested_role_1",
>>            "my_nested_role_2"
>>          ]
>>        }
>>      }
>>    }
>>  }
>> }
>> 
>> After merging the functionality with PR#4041 [3], I wanted to know, if we should
>> deprecated the existing parameter `roles_claim_name` (RCN) in favor of `roles_claim_path`
>> (RCP). RCP has all the functionality of RCN plus it allows nested & unnested JWT JSON
>> role claims. If `roles_claim_path` is defined, then `roles_claim_name` is ignored.
>> 
>> In the docs PR#737, I already "marked" RCN as deprecated in the next version (3.3),
>> because RCP acts as successor of RCN. We could also remove the deprecation note and
>> have both options in CouchDB with overlapping functionality.
>> 
>> What do you think?
>> 
>> Related Issues or Pull Requests:
>> 
>> #3758 [1]
>> #3166 [2]
>> 
>> [1] https://github.com/apache/couchdb/issues/3758
>> [2] https://github.com/apache/couchdb/pull/3166
>> [3] https://github.com/apache/couchdb/pull/4041
>> [4] https://github.com/apache/couchdb-documentation/pull/737