[couchdb] branch 3.2.2-docs updated: Backport missing `roles_claim_name` to 3.2.2-docs (#4250)

[ro...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

ronny pushed a commit to branch 3.2.2-docs
in repository https://gitbox.apache.org/repos/asf/couchdb.git


The following commit(s) were added to refs/heads/3.2.2-docs by this push:
     new aeb754de0 Backport missing `roles_claim_name` to 3.2.2-docs (#4250)
aeb754de0 is described below

commit aeb754de0c057cb80774e06a002d356e2ecbc98c
Author: Ronny Berndt <ro...@apache.org>
AuthorDate: Mon Oct 31 14:32:18 2022 +0100

    Backport missing `roles_claim_name` to 3.2.2-docs (#4250)
    
    Add missing configuration option to the 3.2.2 docs.
---
 src/docs/src/config/auth.rst | 28 ++++++++++++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/src/docs/src/config/auth.rst b/src/docs/src/config/auth.rst
index 70ec276e5..a72eb701d 100644
--- a/src/docs/src/config/auth.rst
+++ b/src/docs/src/config/auth.rst
@@ -366,3 +366,31 @@ Authentication Configuration
 
             [jwt_auth]
                 required_claims = exp,iat
+
+.. config:option:: roles_claim_name :: Optional CouchDB roles claim in JWT token
+
+    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.
+
+    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"
+            ]
+        }