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

@@ -175,31 +175,33 @@ Presently, this involves a few more manual steps than the `auth0` setup describe
 See the [CILogon documentation on `Auth0`](https://www.cilogon.org/auth0) for more configuration information.
 ```
 
-Some notions about CILogon authentication worth mentioning:
+### Key terms
 
-1. **Identity Provider**.
-   This is the authentication service available through the CILogon connection.
+Some key terms about CILogon authentication worth mentioning:
 
-   When a user logs in via CILogon, they are first presented with a list of various institutions and organization that they may choose from (e.g. `UC Berkeley` or `Australia National University`).
+Identity Provider
+: The authentication service available through the CILogon connection.
 
-   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.
+  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`).
 
-   Example:
+  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.
 
-   ```{figure} ../../images/cilogon-ipd-list.png
-   ```
+  Example:
 
-2. **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.
+  ```{figure} ../../images/cilogon-ipd-list.png
+  A list of Identity Providers the user may select from.
+  ```
 
-   Example:
+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
-   ```
+  ```{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.
-   ```
+  ```{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
 
@@ -251,49 +253,48 @@ config:
 All the users listed under `admin_users` need to match the `username_pattern` expression otherwise they won't be allowed to login!
 ```
 
-### Switching user accounts or Identity Providers
+### 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 Identity Provider and user account when you access the hub's home page.
+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. The next time you will go to the hub's landing page, you'll be asked to re-authenticate. After choosing the CILogon connection, you will be presented with the list of available Identity Providers.
-  3. You can now choose **another Identity Provider** to login against.
 
-  ```{note}
-  If you choose the same Identity Provider, then you will be automatically logged in with the same user account you've used beore. To change the user account, checkout **option 2**.
-  ```
+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.
 
-  **Exception**
-  You've selected for CILogon to remember a certain Identity Provider connection.
+   ```{figure} ../../images/cilogon-remember-this-selection.png
+   The dialog box that allows you to re-use the same Identity Provider.
+   ```
 
-  ```{figure} ../../images/cilogon-remember-this-selection.png
-  ```
+   Firefox example:
+   ```{figure} ../../images/cilogon-clear-cookies.png
+   An example of clearing cookies with Firefox.
+   ```
 
-  Then you'll need to [clear the cookies](https://www.lifewire.com/how-to-delete-cookies-2617981) for https://cilogon.org, to be able to choose another Identity Provider.
+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.
 
-  Firefox example:
-  ```{figure} ../../images/cilogon-clear-cookies.png
-  ```
+```{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 you will go to the hub's landing page, you'll be asked to re-authenticate. After choosing the CILogon connection, you will be presented with the list of available Identity Providers.
-  4. Choose the **same Identity Provider** to login.
-  5. You can now choose **another user account** to login with.
 
-#### Try another account after 403 error
-  If you've been shown a 403 error page, then this means that the account you were using to login with, hasn't been allowed by the hub administrator/s.
+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.
 
-  ```{figure} ../../images/403-forbidden.png
-  ```
+#### 403 - Unauthorized errors
 
-  If you think this is an error, and the account should have been allowed, then contact the hub adminstrator/s.
+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 however you made a mistake and used the wrong user account, here is what you can do to try logging in using another account:
+If you think this is an error, and the account should have been allowed, then contact the hub adminstrator/s.
 
-  1. Logout of the Hub using the `Tap to try another account` 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. Go to hub home page and follow the login process using the correct user account.
+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