Restructure docs to match the new structure

docs/howto/configure/add-hub-domains.md

@@ -0,0 +1,36 @@
+# Add additional domains to a hub
+
+Existing pilot-hubs in the two 2i2c-managed clusters, have a subdomain created and assingned to them on creation,
+that respects the following naming convention, based on which domain name and cluster they are part of:
+
+- `<name-of-the-hub>.pilot.2i2c.cloud` - for the ones in the 2i2c cluster and *pilot.2i2c.cloud* domain
+- `<name-of-the-hub>.cloudbank.2i2c.cloud` - for the ones in the cloudbank cluster and *cloudbank.2i2c.cloud* domain
+
+But other domains can be easily linked to the same hub in a cluster if needed.
+
+Assuming there is a hub named `foo` in the `2i2c` cluster and we want to add the `foo.edu` domain to it, one would:
+
+1. **Point the `foo.edu` domain to the right cluster.**
+
+    Create a [CNAME](https://en.wikipedia.org/wiki/CNAME_record) entry from the new domain, `foo.edu`, that points to the
+    existing `foo.pilot.2i2c.cloud`, where the `foo` hub already runs.
+
+    This will map the new domain name, `foo.edu`, to the default one `foo.pilot.2i2c.cloud` - *the canonical name* and will
+    make sure `foo.edu` points to the right cluster, no matter which IP address the cluster has.
+
+2. **Point the `foo.edu` domain to the right hub.**
+
+    Since all the hubs in a cluster are running at the same IP address, but are available at different subdomains,
+    we also need a way to specify which hub in this cluster we want the new domain and subsequent requests to point to.
+
+    For this to happen we need to add the new domain as an ingress domain for this hub using the `hubs.yaml` configuration file.
+    This can be done by adding the new domain to the list in `hubs.<hub-name>.domain`:
+
+      ```yaml
+      - name: foo
+        cluster: 2i2c
+        domain:
+          - foo.pilot.2i2c.cloud # default domain
+          - foo.edu # additionl domain
+        (...)
+      ```

docs/howto/configure/auth-management.md

@@ -0,0 +1,56 @@
+# Manage authentication
+
+[auth0](https://auth0.com) provides authentication for all hubs here. It can
+be configured with many different [connections](https://auth0.com/docs/identityproviders)
+that users can authenticate with - such as Google, GitHub, etc.
+
+So we want to manage authentication by:
+
+1. Explicitly listing the type of connection we want for this hub, via
+   `auth0.connection`. Currently common ones are `google-oauth2` for Google &
+   `github` for GitHub. *Users* of the hub will use this method to log in to
+   the hub.
+
+   You can set the auth0 connector for a hub with:
+
+   ```yaml
+   auth0:
+      connection: google-oauth2
+   ```
+
+   Theoretically, every provider in [this list](https://auth0.com/docs/connections/identity-providers-social)
+   is supported. However, we've currently only tested this with Google
+   (`google-oauth2`) and GitHub (`github`)
+
+2. Explicitly list *admin users* for a given hub. These admin users will be the
+   only ones allowed to log in to begin with. They can use the JupyterHub
+   admin interface (available from their hub control panel) to explicitly allow
+   more users into the hub. This way, we don't need to be involved in explicitly
+   allowing users into hubs.
+
+   In the admin interface, admin users can add users via a username appropriate
+   for the auth connector used. For GitHub, it's the username. For Google Auth,
+   it's the email address.
+
+   You can set the admin interfaces for a hub like this:
+
+   ```yaml
+   config:
+     jupyterhub:
+       auth:
+         # will be renamed allowedlist in future JupyterHub
+         whitelist:
+           users:
+             # WARNING: THESE USER LISTS MUST MATCH (for now)
+             - user1@gmail.com
+             - user2@gmail.com
+         admin:
+           users:
+             # WARNING: THESE USER LISTS MUST MATCH (for now)
+             - user1@gmail.com
+             - user2@gmail.com
+   ```
+
+```{admonition} Switching auth
+Switching authentication for a pre-existing hub will simply create new usernames. Any pre-existing users will no longer be able to access their accounts (although administrators will be able to do so). If you have pre-existing users and want to switch the hub authentication, rename the users to the new auth pattern (e.g. convert github handles to emails).
+```