Server Admin Access Via JWT Claims vs Explicit Configuration

# Introduction

I have implemented [JWT authentication](https://docs.couchdb.org/en/stable/api/server/authn.html#jwt-authentication). I noticed that:

(1) Users configured as server administrators are not granted server administrator privileges when authenticating via JWT unless `"_admin"` is included in the JWT payload `roles` parameter.

(2) JWT authenticated users having `"_admin"` included in the JWT payload `roles` parameter are allowed server admin privileges even though this user, or `sub` in JWT parlance, is not configured as a server admin.

When I say "configured as a server admin" I mean that the user will be listed in CouchDB's response to the `/_node/{node-name}/_config/admins` endpoint.

## Abstract

Server admin privileges should be subject to highest security measures. Double checking a JWT _claim_ of a users `_admin` role against the actual configured system admins seems worth consideration. Perhaps an even better solution is to ignore JWT claims of `_admin` altogether.

## Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in
[RFC 2119](https://www.rfc-editor.org/rfc/rfc2119.txt).

## Terminology

**JWT**, JSON Web Token
**Server admin**, user is listed in response to the `_node/_local/_config/admins/` endpoint

---

# Detailed Description

I can think of two possible enhancements:

1. CouchDB SHALL validate any JWT claim of `sub` having `role` including `_admin` against _configured_ system administrators.
2. CouchDB SHALL ignore JWT claims of `role:["_admin"]` but grant server administrator privileges if the user, `sub`, is a configured server administrator. This solution seems best since JWT payloads can be viewed by anyone and tokens including admin access are particularly interesting to attackers.

# Advantages and Disadvantages

The advantage of this additional security check is that a compromised JWT, while not probable, would disallow an attacker server admin status.

# Key Changes

This existing behavior of trusting `_admin` role claims is not explicitly documented therefore users may not notice the change. A meaningful HTTP error message such as `User is not configured as a server admin.` would enable adoption.

## Applications and Modules affected

`[chttpd]`
`[admins]`

## HTTP API additions

A meaningful HTTP error message such as `User is not configured as a server admin.`

## HTTP API deprecations

None.

# Security Considerations

CouchDB security would be enhanced by implementing this additional validation of `_admin` claims, or even better by ignoring (and perhaps discouraging via documentation) this JWT role claim altogether.

# References

https://docs.couchdb.org/en/stable/api/server/authn.html#jwt-authentication
https://docs.couchdb.org/en/stable/intro/security.html#creating-a-new-admin-user

# Acknowledgements

Thanks to the CouchDB team for creating a great product!

Start with the JWT authentication documentation and the [chttpd] and [admins] areas named in the issue. Resolve whether _admin claims should be validated against configured administrators or ignored, then define the expected HTTP error behavior and security tests. Done means one policy is implemented and documented consistently.

Written by the indexing model from the issue text.