DOCS: Document logging out of CILogon

docs/conf.py

@@ -13,6 +13,7 @@
 extensions = [
     "myst_parser",
     "sphinx.ext.intersphinx",
+    "sphinx_copybutton",
     "sphinx_panels",
 ]
 

docs/howto/configure/auth-management.md

@@ -169,16 +169,41 @@ Presently, this involves a few more manual steps than the `auth0` setup describe
 
 ## CILogon
 
-[CILogon](https://www.cilogon.org) allows us to authenticate users against their campus identity providers. It is managed through [auth0](https://auth0.com), similar to Google and GitHub authentication.
+[CILogon](https://www.cilogon.org) is a service provider that allows users to login against various identity providers, including campus identity providers. 2i2c manages CILogon through [auth0](https://auth0.com), similar to Google and GitHub authentication.
 
 ```{seealso}
 See the [CILogon documentation on `Auth0`](https://www.cilogon.org/auth0) for more configuration information.
 ```
-```{note}
-The JupyterHub username will be the email address that users provide when authenticating in CILogon connection. It will not be the CILogon `user_id`! This is because the `USERNAME_KEY` used for the CILogon login is the email address.
-```
 
-To enable CILogon authentication:
+### Key terms
+
+Some key terms about CILogon authentication worth mentioning:
+
+Identity Provider
+: The authentication service available through the CILogon connection.
+
+  When a user logs in via CILogon, they are first presented with a list of various institutions and organizations that they may choose from (e.g. `UC Berkeley` or `Australia National University`).
+
+  The available identity providers are members of [InCommon](https://www.incommon.org/federation/), a federation of universities and other organizations that provide single sign-on access to various resources.
+
+  Example:
+
+  ```{figure} ../../images/cilogon-ipd-list.png
+  A list of Identity Providers the user may select from.
+  ```
+
+User account
+: Within an institution, each user is expected to have their own user account (e.g. `[email protected]`). This is the account that is used to give somebody an ID on their JupyterHub. This is entered on an Identity Provider's login screen. For example:
+
+  ```{figure} ../../images/cilogon-berkley-login-page.png
+  The Berkeley authentication screen.
+  ```
+
+  ```{note}
+  The JupyterHub usernames will be the **email address** that users provide when authenticating with an institutional identity provider. It will not be the CILogon `user_id`! This is because the `USERNAME_KEY` used for the CILogon login is the email address.
+  ```
+
+### Steps to enable CILogon authentication
 
 1. List CILogon as the type of connection we want for a hub, via `auth0.connection`:
 
@@ -193,21 +218,22 @@ To enable CILogon authentication:
   Don't forget to allow login to the test user (`deployment-service-check`), otherwise the hub health check performed during deployment will fail.
   ```
 
-
 ### Example config for CILogon
 
+The CILogon connection works by providing users the option to login into a hub using any CILogon Identity Provider of their choice, as long as the email address of the user or the entire organization (e.g. `*@berkeley.edu`) has been provided access into the hub.
+
 The following configuration example shows off how to configure hub admins and allowed users:
 
 1. **Hub admins** are these explicit emails:
-  - one `@campus.edu` user
-  - one `@gmail.com` user
-  - the 2i2c staff (identified through their 2i2c email address)
+   - one `@campus.edu` user
+   - one `@gmail.com` user
+   - the 2i2c staff (identified through their 2i2c email address)
 
 2. **Allowed users** are matched against a pattern, with a few specific addresses added in as well
-  - all `@2i2c.org` email adresses
-  - all `@campus.edu` email addresses
-  - `[email protected]`
-  - the test username, `deployment-service-check`
+   - all `@2i2c.org` email adresses
+   - all `@campus.edu` email addresses
+   - `[email protected]`
+   - the test username, `deployment-service-check`
 
 ```yaml
 config:
@@ -223,7 +249,52 @@ config:
           username_pattern: '^(.+@2i2c\.org|.+@campus\.edu|user2@gmail\.com|deployment-service-check)$'
 ```
 
-
 ```{note}
 All the users listed under `admin_users` need to match the `username_pattern` expression otherwise they won't be allowed to login!
 ```
+
+### Switch Identity Providers or user accounts
+
+By default, logging in with a particular user account will persist your credentials in future sessions.
+This means that you'll automatically re-use the same institutional and user account when you access the hub's home page.
+
+#### Switch Identity Providers
+
+1. **Logout of the Hub** using the logout button or by going to `https://{hub-name}/hub/logout`.
+2. **Clear browser cookies** (optional). If the user asked CILogon to re-use the same Identity Provider connection when they logged in, they'll need to [clear browser cookies](https://www.lifewire.com/how-to-delete-cookies-2617981) for https://cilogon.org.
+
+   ```{figure} ../../images/cilogon-remember-this-selection.png
+   The dialog box that allows you to re-use the same Identity Provider.
+   ```
+
+   Firefox example:
+   ```{figure} ../../images/cilogon-clear-cookies.png
+   An example of clearing cookies with Firefox.
+   ```
+
+3. The next time the user goes to the hub's landing page, they'll be asked to re-authenticate and will be presented with the list of available Identity Providers after choosing the CILogon connection.
+4. They can now choose **another Identity Provider** via CILogon.
+
+```{note}
+If the user choses the same Identity Provider, then they will be automatically logged in with the same user account they've used before. To change the user account, see [](auth:cilogon:switch-user-accounts).
+```
+
+(auth:cilogon:switch-user-accounts)=
+#### Switch user account
+
+1. Logout of the Hub using the logout button or by going to `https://{hub-name}/hub/logout`.
+2. Logout of CILogon by going to the [CILogon logout page](https://cilogon.org/logout).
+3. The next time the user goes to the hub's landing page, they'll be asked to re-authenticate and will be presented with the list of available Identity Providers after choosing the CILogon connection.
+4. Choose the **same Identity Provider** to login.
+5. The user can now choose **another user account** to login with.
+
+#### 403 - Unauthorized errors
+
+If you see a 403 error page, this means that the account you were using to login hasn't been allowed by the hub administrator.
+
+```{figure} ../../images/403-forbidden.png
+```
+
+If you think this is an error, and the account should have been allowed, then contact the hub adminstrator/s.
+
+If you used the wrong user account, you can log in using another account by following the steps in [](auth:cilogon:switch-user-accounts).

docs/requirements.txt

@@ -3,5 +3,6 @@ pandas
 pyyaml
 requests
 sphinx-autobuild
+sphinx-copybutton
 sphinx-panels
 git+https://github.com/2i2c-org/sphinx-2i2c-theme