diff options
author | Ronny <ronny@apache.org> | 2022-10-25 09:22:25 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-10-25 09:22:25 +0200 |
commit | 61d4d045f9fce64f1a4fcdd1f2bacbf11ad51cc1 (patch) | |
tree | ce4ac34c27f8270cb4cc64a24a5e01c661c5c463 | |
parent | b80ded384ea1799f1fb5d4d98976169c91bb0222 (diff) | |
download | couchdb-61d4d045f9fce64f1a4fcdd1f2bacbf11ad51cc1.tar.gz |
Introduce roles_claim_path (#4232)
Introduce new roles_claim_path parameter and
add missing roles_claim_name description.
-rw-r--r-- | src/docs/src/api/server/authn.rst | 11 | ||||
-rw-r--r-- | src/docs/src/config/auth.rst | 152 |
2 files changed, 161 insertions, 2 deletions
diff --git a/src/docs/src/api/server/authn.rst b/src/docs/src/api/server/authn.rst index c5e2b7ba7..4c506b664 100644 --- a/src/docs/src/api/server/authn.rst +++ b/src/docs/src/api/server/authn.rst @@ -394,10 +394,17 @@ signature. The ``sub`` claim is mandatory and is used as the CouchDB user's name if the JWT token is valid. -A private claim called ``_couchdb.roles`` is optional. If presented, -as a JSON array of strings, it is used as the CouchDB user's roles +You can set the user roles claim name through the config setting +:config:option:`roles_claim_name <jwt_auth/roles_claim_name>`. If you don't set +an explicit value, then ``_couchdb.roles`` will be set as the default claim name. +If presented, as a JSON array of strings, it is used as the CouchDB user's roles list as long as the JWT token is valid. +.. warning:: + + ``roles_claim_name`` is deprecated in CouchDB 3.3, and will be removed later. + Please use :config:option:`roles_claim_path <jwt_auth/roles_claim_path>`. + .. code-block:: ini ; [jwt_keys] diff --git a/src/docs/src/config/auth.rst b/src/docs/src/config/auth.rst index ada470cd0..d43810054 100644 --- a/src/docs/src/config/auth.rst +++ b/src/docs/src/config/auth.rst @@ -389,3 +389,155 @@ Authentication Configuration [jwt_auth] required_claims = exp,iat + + .. config:option:: roles_claim_name :: Optional CouchDB roles claim in JWT token \ + (deprecated) + + .. warning:: + + ``roles_claim_name`` is deprecated in CouchDB 3.3, and will be removed later. + Please migrate to ``roles_claim_path``. + + If presented, as a JSON array of strings, it is used as the CouchDB user's roles + list as long as the JWT token is valid. The default value for ``roles_claim_name`` + is ``_couchdb.roles``. + + .. note:: + Values for ``roles_claim_name`` can only be top-level attributes in the JWT + token. If ``roles_claim_path`` is set, then ``roles_claim_name`` is ignored! + + Let's assume, we have the following configuration: + + .. code-block:: ini + + [jwt_auth] + roles_claim_name = my-couchdb.roles + + CouchDB will search for the attribute ``my-couchdb.roles`` in the JWT token. + + .. code-block:: json + + { + "my-couchdb.roles": [ + "role_1", + "role_2" + ] + } + + .. config:option:: roles_claim_path :: (Nested) CouchDB roles claim in JWT token + + .. versionadded:: 3.3 + + This parameter was introduced to overcome disadvantages of ``roles_claim_name``, + because it is not possible with ``roles_claim_name`` to map nested role + attributes in the JWT token. + + .. note:: + If ``roles_claim_path`` is set, then ``roles_claim_name`` is ignored! + + Now it is possible the read a nested roles claim from JWT tokens into CouchDB. As + always, there is some theory at the beginning to get things up and running. Don't + get scared now, it's really short and easy. Honestly! + + There are only two characters with a special meaning. These are + + - ``.`` for nesting json attributes and + - ``\.`` to skip nesting + + That's it. Really. + + Let's assume there is the following data-payload in the JWT token: + + .. code-block:: json + + { + "resource_access": { + "security.settings": { + "account": { + "roles": [ + "manage-account", + "view-profile" + ] + } + } + } + } + + Now, let's define the config variable ``roles_claim_path`` for this example. It + should look like this: + + .. code-block:: ini + + roles_claim_path = resource_access.security\.settings.account.roles + + If an attribute has a ``.`` in the key like ``security.settings``, you have to + escape it in the config parameter with ``\.``. If you use a ``.`` then it gets + interpreted as a nested sub-key. Let's illustrate the behavior with a second + example. There is the following config parameter for ``roles_claim_name`` (by the + way it was the default value if you didn't configured it): + + .. code-block:: ini + + roles_claim_name = _couchdb.roles + + .. note:: + CouchDB doesn't set any default or implicit value for ``roles_claim_path``. + + To migrate from ``roles_claim_name`` to ``roles_claim_path`` you need to change + the parameter name and escape the ``.`` to prevent CouchDB to read this as a + nested JSON key. + + .. code-block:: ini + + roles_claim_path = _couchdb\.roles + + Let's assume your JWT token have the following data-payload for your couchdb + roles claim: + + .. code-block:: json + + { + "_couchdb.roles": [ + "accounting-role", + "view-role" + ] + } + + If you did everything right, the response from the ``_session`` endpoint should + look something like this: + + .. code-block:: http + + GET /_session HTTP/1.1 + Host: localhost:5984 + Authorization: Bearer <JWT token> + + .. code-block:: http + + HTTP/1.1 200 OK + Content-Type: application/json + + .. code-block:: json + + { + "ok": true, + "userCtx": { + "name": "1234567890", + "roles": [ + "accounting-role", + "view-role" + ] + }, + "info": { + "authentication_handlers": [ + "jwt", + "proxy", + "cookie", + "default" + ], + "authenticated": "jwt" + } + } + + That's all, you are done with the migration from ``roles_claim_name`` to + ``roles_claim_path`` Easy, isn't it? |