[lxc-devel] [lxd/master] doc/server: Cover listen + authentication

[stgraber on Github]

A non-text attachment was scrubbed...
Name: not available
Type: text/x-mailbox
Size: 487 bytes
Desc: not available
URL: <http://lists.linuxcontainers.org/pipermail/lxc-devel/attachments/20200701/b9472de3/attachment.bin>
-------------- next part --------------
From ddef51658c66d46191f45fab9ac81a2d8288450d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?St=C3=A9phane=20Graber?= <stgraber at ubuntu.com>
Date: Wed, 1 Jul 2020 16:37:16 -0400
Subject: [PATCH] doc/server: Cover listen + authentication
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This adds a few more pointers to what's needed for listening on network
and the external auth and RBAC features.

Closes #7591

Signed-off-by: Stéphane Graber <stgraber at ubuntu.com>
---
 doc/server.md | 37 +++++++++++++++++++++++++++++++++++--
 1 file changed, 35 insertions(+), 2 deletions(-)

diff --git a/doc/server.md b/doc/server.md
index 3b80618611..ee0fb0d5d8 100644
--- a/doc/server.md
+++ b/doc/server.md
@@ -5,12 +5,12 @@ The key/value configuration is namespaced with the following namespaces
 currently supported:
 
  - `backups` (backups configuration)
- - `candid` (Candid authentication integration)
+ - `candid` (External user authentication through Candid)
  - `cluster` (cluster configuration)
  - `core` (core daemon configuration)
  - `images` (image configuration)
  - `maas` (MAAS integration)
- - `rbac` (Role Based Access Control integration)
+ - `rbac` (Role Based Access Control through external Candid + Canonical RBAC)
 
 Key                                 | Type      | Scope     | Default   | API extension                     | Description
 :--                                 | :---      | :----     | :------   | :------------                     | :----------
@@ -62,3 +62,36 @@ When operating as part of a cluster, the keys marked with a `global`
 scope will immediately be applied to all the cluster members. Those keys
 with a `local` scope must be set on a per member basis using the
 `--target` option of the command line tool.
+
+## Exposing LXD to the network
+By default, LXD can only be used by local users through a UNIX socket.
+
+To expose LXD to the network, you'll need to set `core.https_address`.
+All remote clients can then connect to LXD and access any image which
+was marked for public use.
+
+Trusted clients can be manually added to the trust store on the server
+with `lxc config trust add` or the `core.trust_password` key can be set
+allowing for clients to self-enroll into the trust store at connection
+time by providing the confgiured password.
+
+More details about authentication can be found [here](security.md).
+
+## External authentication
+LXD when accessed over the network can be configured to use external
+authentication through [Candid](https://github.com/canonical/candid).
+
+Setting the `candid.*` configuration keys above to the values matching
+your Candid deployment will allow users to authenticate through their
+web browsers and then get trusted by LXD.
+
+For those that have a Canonical RBAC server in front of their Candid
+server, they can instead set the `rbac.*` configuration keys which are a
+superset of the `candid.*` ones and allow for LXD to integrate with the
+RBAC service.
+
+When integrated with RBAC, individual users and groups can be granted
+various level of access on a per-project basis. All of this is driven
+externally through the RBAC service.
+
+More details about authentication can be found [here](security.md).