You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by ro...@apache.org on 2022/10/18 07:33:10 UTC
[couchdb] branch add-roles_claim_path-parameter created (now 14b759308)
This is an automated email from the ASF dual-hosted git repository.
ronny pushed a change to branch add-roles_claim_path-parameter
in repository https://gitbox.apache.org/repos/asf/couchdb.git
at 14b759308 Introduce roles_claim_path
This branch includes the following new commits:
new 14b759308 Introduce roles_claim_path
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
[couchdb] 01/01: Introduce roles_claim_path
Posted by ro...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
ronny pushed a commit to branch add-roles_claim_path-parameter
in repository https://gitbox.apache.org/repos/asf/couchdb.git
commit 14b759308ecdb3df2d78b67a222c42e365a644df
Author: Ronny Berndt <ro...@apache.org>
AuthorDate: Tue Oct 18 09:32:53 2022 +0200
Introduce roles_claim_path
Introduce new roles_claim_path parameter and
add missing roles_claim_name description
---
src/docs/src/api/server/authn.rst | 11 ++-
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?