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
