[GitHub] [couchdb-documentation] flimzy commented on a change in pull request #524: JWT documentation

[GitBox <gi...@apache.org>]

flimzy commented on a change in pull request #524:
URL: https://github.com/apache/couchdb-documentation/pull/524#discussion_r411401234



##########
File path: src/api/server/authn.rst
##########
@@ -345,3 +345,124 @@ headers to CouchDB with related requests:
 
 Note that you don't need to request :ref:`session <api/auth/session>`
 to be authenticated by this method if all required HTTP headers are provided.
+
+.. _api/auth/jwt:
+
+JWT Authentication
+====================
+
+.. note::
+    To use this authentication method make sure that the
+    ``{chttpd_auth, jwt_authentication_handler}`` value in added to the

Review comment:
       ```suggestion
       ``{chttpd_auth, jwt_authentication_handler}`` value is added to the
   ```

##########
File path: src/api/server/authn.rst
##########
@@ -345,3 +345,124 @@ headers to CouchDB with related requests:
 
 Note that you don't need to request :ref:`session <api/auth/session>`
 to be authenticated by this method if all required HTTP headers are provided.
+
+.. _api/auth/jwt:
+
+JWT Authentication
+====================
+
+.. note::
+    To use this authentication method make sure that the
+    ``{chttpd_auth, jwt_authentication_handler}`` value in added to the
+    list of the active :config:option:`chttpd/authentication_handlers`:
+
+    .. code-block:: ini
+
+        [chttpd]
+        authentication_handlers = {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, jwt_authentication_handler}, {chttpd_auth, default_authentication_handler}
+
+`JWT authentication` enables CouchDB to use externally generated JWT tokens

Review comment:
       ```suggestion
   `JWT authentication` enables CouchDB to use externally-generated JWT tokens
   ```

##########
File path: src/api/server/authn.rst
##########
@@ -345,3 +345,124 @@ headers to CouchDB with related requests:
 
 Note that you don't need to request :ref:`session <api/auth/session>`
 to be authenticated by this method if all required HTTP headers are provided.
+
+.. _api/auth/jwt:
+
+JWT Authentication
+====================
+
+.. note::
+    To use this authentication method make sure that the
+    ``{chttpd_auth, jwt_authentication_handler}`` value in added to the
+    list of the active :config:option:`chttpd/authentication_handlers`:
+
+    .. code-block:: ini
+
+        [chttpd]
+        authentication_handlers = {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, jwt_authentication_handler}, {chttpd_auth, default_authentication_handler}
+
+`JWT authentication` enables CouchDB to use externally generated JWT tokens
+instead of defining users or roles in the _users database.
+
+The JWT authentication handler requires that all JWT tokens are signed by a key that
+CouchDB has been configured to trust (there is no support for JWT's "NONE" algorithm).
+
+Additionally, CouchDB can be configured to reject JWT tokens that are missing a
+configurable set of claims (e.g, a CouchDB administrator could insist on the exp claim).

Review comment:
       Not sure if this formatting is appropriate, since I'm not overly familiar with JWT
   
   ```suggestion
   configurable set of claims (e.g, a CouchDB administrator could insist on the ``exp`` claim).
   ```

##########
File path: src/api/server/authn.rst
##########
@@ -345,3 +345,124 @@ headers to CouchDB with related requests:
 
 Note that you don't need to request :ref:`session <api/auth/session>`
 to be authenticated by this method if all required HTTP headers are provided.
+
+.. _api/auth/jwt:
+
+JWT Authentication
+====================
+
+.. note::
+    To use this authentication method make sure that the
+    ``{chttpd_auth, jwt_authentication_handler}`` value in added to the
+    list of the active :config:option:`chttpd/authentication_handlers`:
+
+    .. code-block:: ini
+
+        [chttpd]
+        authentication_handlers = {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, jwt_authentication_handler}, {chttpd_auth, default_authentication_handler}
+
+`JWT authentication` enables CouchDB to use externally generated JWT tokens
+instead of defining users or roles in the _users database.

Review comment:
       ```suggestion
   instead of defining users or roles in the ``_users`` database.
   ```

##########
File path: src/api/server/authn.rst
##########
@@ -345,3 +345,124 @@ headers to CouchDB with related requests:
 
 Note that you don't need to request :ref:`session <api/auth/session>`
 to be authenticated by this method if all required HTTP headers are provided.
+
+.. _api/auth/jwt:
+
+JWT Authentication
+====================
+
+.. note::
+    To use this authentication method make sure that the
+    ``{chttpd_auth, jwt_authentication_handler}`` value in added to the
+    list of the active :config:option:`chttpd/authentication_handlers`:
+
+    .. code-block:: ini
+
+        [chttpd]
+        authentication_handlers = {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, jwt_authentication_handler}, {chttpd_auth, default_authentication_handler}
+
+`JWT authentication` enables CouchDB to use externally generated JWT tokens
+instead of defining users or roles in the _users database.
+
+The JWT authentication handler requires that all JWT tokens are signed by a key that
+CouchDB has been configured to trust (there is no support for JWT's "NONE" algorithm).
+
+Additionally, CouchDB can be configured to reject JWT tokens that are missing a
+configurable set of claims (e.g, a CouchDB administrator could insist on the exp claim).
+
+All claims presented in a JWT token are validated if presented, regardless of whether they
+are required.
+
+Two new sections of config have been introduced to configure JWT authentication;

Review comment:
       [Optional] More future-proof wording?
   
   ```suggestion
   Two sections of config exist to configure JWT authentication;
   ```

##########
File path: src/api/server/authn.rst
##########
@@ -345,3 +345,124 @@ headers to CouchDB with related requests:
 
 Note that you don't need to request :ref:`session <api/auth/session>`
 to be authenticated by this method if all required HTTP headers are provided.
+
+.. _api/auth/jwt:
+
+JWT Authentication
+====================
+
+.. note::
+    To use this authentication method make sure that the
+    ``{chttpd_auth, jwt_authentication_handler}`` value in added to the
+    list of the active :config:option:`chttpd/authentication_handlers`:
+
+    .. code-block:: ini
+
+        [chttpd]
+        authentication_handlers = {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, jwt_authentication_handler}, {chttpd_auth, default_authentication_handler}
+
+`JWT authentication` enables CouchDB to use externally generated JWT tokens
+instead of defining users or roles in the _users database.
+
+The JWT authentication handler requires that all JWT tokens are signed by a key that
+CouchDB has been configured to trust (there is no support for JWT's "NONE" algorithm).
+
+Additionally, CouchDB can be configured to reject JWT tokens that are missing a
+configurable set of claims (e.g, a CouchDB administrator could insist on the exp claim).
+
+All claims presented in a JWT token are validated if presented, regardless of whether they
+are required.
+
+Two new sections of config have been introduced to configure JWT authentication;
+
+.. code-block:: ini
+
+    ;[jwt_auth]
+    ; List of claims to validate
+    ; required_claims =
+
+The `required_claims` config setting is a comma-separate list of additional mandatory
+JWT claims that much be present in any presented JWT token. A 400 Bad Request is sent

Review comment:
       ```suggestion
   JWT claims that must be present in any presented JWT token. A ``400 Bad Request`` is sent
   ```
   
   Or consider linking to https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.1, as some other references to HTTP status codes do.

##########
File path: src/api/server/authn.rst
##########
@@ -345,3 +345,124 @@ headers to CouchDB with related requests:
 
 Note that you don't need to request :ref:`session <api/auth/session>`
 to be authenticated by this method if all required HTTP headers are provided.
+
+.. _api/auth/jwt:
+
+JWT Authentication
+====================
+
+.. note::
+    To use this authentication method make sure that the
+    ``{chttpd_auth, jwt_authentication_handler}`` value in added to the
+    list of the active :config:option:`chttpd/authentication_handlers`:
+
+    .. code-block:: ini
+
+        [chttpd]
+        authentication_handlers = {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, jwt_authentication_handler}, {chttpd_auth, default_authentication_handler}
+
+`JWT authentication` enables CouchDB to use externally generated JWT tokens
+instead of defining users or roles in the _users database.
+
+The JWT authentication handler requires that all JWT tokens are signed by a key that
+CouchDB has been configured to trust (there is no support for JWT's "NONE" algorithm).
+
+Additionally, CouchDB can be configured to reject JWT tokens that are missing a
+configurable set of claims (e.g, a CouchDB administrator could insist on the exp claim).
+
+All claims presented in a JWT token are validated if presented, regardless of whether they
+are required.
+
+Two new sections of config have been introduced to configure JWT authentication;
+
+.. code-block:: ini
+
+    ;[jwt_auth]
+    ; List of claims to validate
+    ; required_claims =
+
+The `required_claims` config setting is a comma-separate list of additional mandatory
+JWT claims that much be present in any presented JWT token. A 400 Bad Request is sent
+if any are missing.
+
+The `alg` claim is mandatory as it used to lookup the correct key for verifying the
+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, it is a JSON
+array of strings, as is used as the CouchDB user's roles list if the JWT token
+is valid.
+
+.. code-block:: ini
+
+    ; [jwt_keys]
+    ; Configure at least one key here if using the JWT auth handler.
+    ; If your JWT tokens do not include a "kid" attribute, use "_default"
+    ; as the config key, otherwise use the kid as the config key.
+    ; Examples
+    ; hmac:_default = aGVsbG8=
+    ; hmac:foo = aGVsbG8=
+    ; The config values can represent symmetric and asymmetrics keys.
+    ; For symmetrics keys, the value is base64 encoded;
+    ; hmac:_default = aGVsbG8= # base64-encoded form of "hello"
+    ; For asymmetric keys, the value is the PEM encoding of the public
+    ; key with newlines replaced with the escape sequence \n.
+    ; rsa:foo = -----BEGIN PUBLIC KEY-----\nMIIBIjAN...IDAQAB\n-----END PUBLIC KEY-----\n
+    ; ec:bar = -----BEGIN PUBLIC KEY-----\nMHYwEAYHK...AzztRs\n-----END PUBLIC KEY-----\n
+
+The `jwt_key` section lists all the keys that this CouchDB server trusts. You
+should ensure that all nodes of your cluster has the same list.
+
+JWT tokens that do not include a `kid` claim will be validated against the
+`$alg:_default` key.

Review comment:
       Is `$alg` intentional here? (Again, I know nothing about JWTs).  If so, does it belong in the other places `_default` (or other keys) are mentioned?

##########
File path: src/api/server/authn.rst
##########
@@ -345,3 +345,124 @@ headers to CouchDB with related requests:
 
 Note that you don't need to request :ref:`session <api/auth/session>`
 to be authenticated by this method if all required HTTP headers are provided.
+
+.. _api/auth/jwt:
+
+JWT Authentication
+====================
+
+.. note::
+    To use this authentication method make sure that the
+    ``{chttpd_auth, jwt_authentication_handler}`` value in added to the
+    list of the active :config:option:`chttpd/authentication_handlers`:
+
+    .. code-block:: ini
+
+        [chttpd]
+        authentication_handlers = {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, jwt_authentication_handler}, {chttpd_auth, default_authentication_handler}
+
+`JWT authentication` enables CouchDB to use externally generated JWT tokens
+instead of defining users or roles in the _users database.
+
+The JWT authentication handler requires that all JWT tokens are signed by a key that
+CouchDB has been configured to trust (there is no support for JWT's "NONE" algorithm).
+
+Additionally, CouchDB can be configured to reject JWT tokens that are missing a
+configurable set of claims (e.g, a CouchDB administrator could insist on the exp claim).
+
+All claims presented in a JWT token are validated if presented, regardless of whether they
+are required.
+
+Two new sections of config have been introduced to configure JWT authentication;
+
+.. code-block:: ini
+
+    ;[jwt_auth]
+    ; List of claims to validate
+    ; required_claims =
+
+The `required_claims` config setting is a comma-separate list of additional mandatory

Review comment:
       ```suggestion
   The `required_claims` config setting is a comma-separated list of additional mandatory
   ```

##########
File path: src/api/server/authn.rst
##########
@@ -345,3 +345,124 @@ headers to CouchDB with related requests:
 
 Note that you don't need to request :ref:`session <api/auth/session>`
 to be authenticated by this method if all required HTTP headers are provided.
+
+.. _api/auth/jwt:
+
+JWT Authentication
+====================
+
+.. note::
+    To use this authentication method make sure that the
+    ``{chttpd_auth, jwt_authentication_handler}`` value in added to the
+    list of the active :config:option:`chttpd/authentication_handlers`:
+
+    .. code-block:: ini
+
+        [chttpd]
+        authentication_handlers = {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, jwt_authentication_handler}, {chttpd_auth, default_authentication_handler}
+
+`JWT authentication` enables CouchDB to use externally generated JWT tokens
+instead of defining users or roles in the _users database.
+
+The JWT authentication handler requires that all JWT tokens are signed by a key that
+CouchDB has been configured to trust (there is no support for JWT's "NONE" algorithm).
+
+Additionally, CouchDB can be configured to reject JWT tokens that are missing a
+configurable set of claims (e.g, a CouchDB administrator could insist on the exp claim).
+
+All claims presented in a JWT token are validated if presented, regardless of whether they
+are required.
+
+Two new sections of config have been introduced to configure JWT authentication;
+
+.. code-block:: ini
+
+    ;[jwt_auth]
+    ; List of claims to validate
+    ; required_claims =
+
+The `required_claims` config setting is a comma-separate list of additional mandatory
+JWT claims that much be present in any presented JWT token. A 400 Bad Request is sent
+if any are missing.
+
+The `alg` claim is mandatory as it used to lookup the correct key for verifying the

Review comment:
       Maybe?  Should probably be consistent with "exp" on line 371 above, whichever formatting we choose.
   ```suggestion
   The ``alg`` claim is mandatory as it used to lookup the correct key for verifying the
   ```

##########
File path: src/api/server/authn.rst
##########
@@ -345,3 +345,124 @@ headers to CouchDB with related requests:
 
 Note that you don't need to request :ref:`session <api/auth/session>`
 to be authenticated by this method if all required HTTP headers are provided.
+
+.. _api/auth/jwt:
+
+JWT Authentication
+====================
+
+.. note::
+    To use this authentication method make sure that the
+    ``{chttpd_auth, jwt_authentication_handler}`` value in added to the
+    list of the active :config:option:`chttpd/authentication_handlers`:
+
+    .. code-block:: ini
+
+        [chttpd]
+        authentication_handlers = {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, jwt_authentication_handler}, {chttpd_auth, default_authentication_handler}
+
+`JWT authentication` enables CouchDB to use externally generated JWT tokens
+instead of defining users or roles in the _users database.
+
+The JWT authentication handler requires that all JWT tokens are signed by a key that
+CouchDB has been configured to trust (there is no support for JWT's "NONE" algorithm).
+
+Additionally, CouchDB can be configured to reject JWT tokens that are missing a
+configurable set of claims (e.g, a CouchDB administrator could insist on the exp claim).
+
+All claims presented in a JWT token are validated if presented, regardless of whether they
+are required.
+
+Two new sections of config have been introduced to configure JWT authentication;
+
+.. code-block:: ini
+
+    ;[jwt_auth]
+    ; List of claims to validate
+    ; required_claims =
+
+The `required_claims` config setting is a comma-separate list of additional mandatory
+JWT claims that much be present in any presented JWT token. A 400 Bad Request is sent
+if any are missing.
+
+The `alg` claim is mandatory as it used to lookup the correct key for verifying the
+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, it is a JSON
+array of strings, as is used as the CouchDB user's roles list if the JWT token
+is valid.
+
+.. code-block:: ini
+
+    ; [jwt_keys]
+    ; Configure at least one key here if using the JWT auth handler.
+    ; If your JWT tokens do not include a "kid" attribute, use "_default"
+    ; as the config key, otherwise use the kid as the config key.
+    ; Examples
+    ; hmac:_default = aGVsbG8=
+    ; hmac:foo = aGVsbG8=
+    ; The config values can represent symmetric and asymmetrics keys.
+    ; For symmetrics keys, the value is base64 encoded;
+    ; hmac:_default = aGVsbG8= # base64-encoded form of "hello"
+    ; For asymmetric keys, the value is the PEM encoding of the public
+    ; key with newlines replaced with the escape sequence \n.
+    ; rsa:foo = -----BEGIN PUBLIC KEY-----\nMIIBIjAN...IDAQAB\n-----END PUBLIC KEY-----\n
+    ; ec:bar = -----BEGIN PUBLIC KEY-----\nMHYwEAYHK...AzztRs\n-----END PUBLIC KEY-----\n
+
+The `jwt_key` section lists all the keys that this CouchDB server trusts. You
+should ensure that all nodes of your cluster has the same list.

Review comment:
       ```suggestion
   should ensure that all nodes of your cluster have the same list.
   ```

##########
File path: src/api/server/authn.rst
##########
@@ -345,3 +345,124 @@ headers to CouchDB with related requests:
 
 Note that you don't need to request :ref:`session <api/auth/session>`
 to be authenticated by this method if all required HTTP headers are provided.
+
+.. _api/auth/jwt:
+
+JWT Authentication
+====================
+
+.. note::
+    To use this authentication method make sure that the
+    ``{chttpd_auth, jwt_authentication_handler}`` value in added to the
+    list of the active :config:option:`chttpd/authentication_handlers`:
+
+    .. code-block:: ini
+
+        [chttpd]
+        authentication_handlers = {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, jwt_authentication_handler}, {chttpd_auth, default_authentication_handler}
+
+`JWT authentication` enables CouchDB to use externally generated JWT tokens
+instead of defining users or roles in the _users database.
+
+The JWT authentication handler requires that all JWT tokens are signed by a key that
+CouchDB has been configured to trust (there is no support for JWT's "NONE" algorithm).
+
+Additionally, CouchDB can be configured to reject JWT tokens that are missing a
+configurable set of claims (e.g, a CouchDB administrator could insist on the exp claim).
+
+All claims presented in a JWT token are validated if presented, regardless of whether they
+are required.
+
+Two new sections of config have been introduced to configure JWT authentication;
+
+.. code-block:: ini
+
+    ;[jwt_auth]
+    ; List of claims to validate
+    ; required_claims =
+
+The `required_claims` config setting is a comma-separate list of additional mandatory
+JWT claims that much be present in any presented JWT token. A 400 Bad Request is sent
+if any are missing.
+
+The `alg` claim is mandatory as it used to lookup the correct key for verifying the
+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, it is a JSON
+array of strings, as is used as the CouchDB user's roles list if the JWT token
+is valid.
+
+.. code-block:: ini
+
+    ; [jwt_keys]
+    ; Configure at least one key here if using the JWT auth handler.
+    ; If your JWT tokens do not include a "kid" attribute, use "_default"
+    ; as the config key, otherwise use the kid as the config key.
+    ; Examples
+    ; hmac:_default = aGVsbG8=
+    ; hmac:foo = aGVsbG8=
+    ; The config values can represent symmetric and asymmetrics keys.
+    ; For symmetrics keys, the value is base64 encoded;
+    ; hmac:_default = aGVsbG8= # base64-encoded form of "hello"
+    ; For asymmetric keys, the value is the PEM encoding of the public
+    ; key with newlines replaced with the escape sequence \n.
+    ; rsa:foo = -----BEGIN PUBLIC KEY-----\nMIIBIjAN...IDAQAB\n-----END PUBLIC KEY-----\n
+    ; ec:bar = -----BEGIN PUBLIC KEY-----\nMHYwEAYHK...AzztRs\n-----END PUBLIC KEY-----\n
+
+The `jwt_key` section lists all the keys that this CouchDB server trusts. You
+should ensure that all nodes of your cluster has the same list.
+
+JWT tokens that do not include a `kid` claim will be validated against the
+`$alg:_default` key.
+
+It is mandatory to specify the algorithm associated with every key for security
+reasons (notably presenting a HMAC signed token using a RSA or EC public key

Review comment:
       ```suggestion
   reasons (notably presenting a HMAC-signed token using an RSA or EC public key
   ```




----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org