Add api-root tenant config object

In order to allow for authenticated read-only access to zuul-web,
we need to be able to control the authz of the API root.  Currently,
we can only specify auth info for tenants.  But if we want to control
access to the tenant list itself, we need to be able to specify auth
rules.

To that end, add a new "api-root" tenant configuration object which,
like tenants themselves, will allow attaching authz rules to it.

We don't have any admin-level API endpoints at the root, so this change
does not add "admin-rules" to the api-root object, but if we do develop
those in the future, it could be added.

A later change will add "access-rules" to the api-root in order to
allow configuration of authenticated read-only access.

This change does add an "authentication-realm" to the api-root object
since that already exists for tenants and it will make sense to have
that in the future as well.  Currently the /info endpoint uses the
system default authentication realm, but this will override it if
set.

In general, the approach here is that the "api-root" object should
mirror the "tenant" object for all attributes that make sense.

Change-Id: I4efc6fbd64f266e7a10e101db3350837adce371f

1 files changed, 49 insertions, 6 deletions

diff --git a/doc/source/tenants.rst b/doc/source/tenants.rst
index 56d0e5666..2d28603dc 100644
--- a/doc/source/tenants.rst
+++ b/doc/source/tenants.rst
@@ -417,12 +417,12 @@ configuration. Some examples of tenant definitions are:
 
       .. note::
 
-         Defining a default realm for a tenant will not invalidate access tokens
-         issued from other configured realms, especially if they match the tenant's
-         admin rules. This is intended, so that an operator can for example issue
-         an overriding access token manually. If this is an issue, it is advised
-         to add finer filtering to admin rules, for example filtering by the ``iss``
-         claim (generally equal to the issuer ID).
+         Defining a default realm for a tenant will not invalidate
+         access tokens issued from other configured realms. This is
+         intended so that an operator can issue an overriding access
+         token manually. If this is an issue, it is advised to add
+         finer filtering to admin rules, for example, filtering by the
+         ``iss`` claim (generally equal to the issuer ID).
 
    .. attr:: semaphores
 
@@ -650,3 +650,46 @@ and **tenant-two**:
      'iat': 1234556780,
      'groups': ['tenant-one', 'tenant-two'],
     }
+
+API Root
+--------
+
+Most actions in zuul-web, zuul-client, and the REST API are understood
+to be within the context of a specific tenant and therefore the
+authorization rules specified by that tenant apply.  When zuul-web is
+deployed in a multi-tenant scenario (the default), there are a few
+extra actions or API methods which are outside of the context of an
+individual tenant (for example, listing the tenants or observing the
+state of Zuul system components).  To control access to these methods,
+an `api-root` object can be used.
+
+At most one `api-root` object may appear in the tenant configuration
+file.  If more than one appears, it is an error.  If there is no
+`api-root` object, then anonymous read-only access to the tenant list
+and other root-level API methods is assumed.
+
+The ``/api/info`` endpoint is never protected by Zuul since it
+supplies the authentication information needed by the web UI.
+
+API root access is not a pre-requisite to access tenant-specific URLs.
+
+.. attr:: api-root
+
+   The following attributes are supported:
+
+   .. attr:: authentication-realm
+
+      Each authenticator defined in Zuul's configuration is associated
+      to a realm.  When authenticating through Zuul's Web User
+      Interface at the multi-tenant root, the Web UI will redirect the
+      user to this realm's authentication service. The authenticator
+      must be of the type ``OpenIDConnect``.
+
+      .. note::
+
+         Defining a default realm for the root API will not invalidate
+         access tokens issued from other configured realms.  This is
+         intended so that an operator can issue an overriding access
+         token manually. If this is an issue, it is advised to add
+         finer filtering to admin rules, for example, filtering by the
+         ``iss`` claim (generally equal to the issuer ID).