Merge pull request #2976 from holta/jupyterhub-admin

JupyterHub cleanups & clarifs

roles/jupyterhub/README.md

@@ -7,32 +7,69 @@
   * [Getting Started](https://jupyterhub.readthedocs.io/en/stable/getting-started/)
 * Students create their own accounts on first use — e.g. at http://box.lan/jupyterhub — just as if they're logging in regularly (unfortunately the login screen doesn't make that clear, but the teacher _does not_ need to be involved!)
   * A student can then sign in with their username and password, to gain access to their files (Jupyter Notebooks).
-  * The teacher should set and protect JupyterHub's overall ``Admin`` password, just in case.  As with student accounts, the login screen doesn't make that clear — so just log in with username `Admin` using any password that you want to become permanent.
-* Individual student folders are created in ``/var/lib/private/`` on the Internet-in-a-Box (IIAB) server:
+  * The teacher should set and protect JupyterHub's overall `Admin` password, just in case.  As with student accounts, the login screen doesn't make that clear — so just log in with username `Admin` using any password that you want to become permanent.
+* Individual student folders are created in `/var/lib/private/` on the Internet-in-a-Box (IIAB) server:
   * A student will only be able to see their own work — they do not have privileges outside of their own folder.
   * Students may upload Jupyter Notebooks to the IIAB server, and download the current state of their work via a normal browser.
 
 ### Settings
 
-Linux administrators please see `/opt/iiab/jupyterhub/etc/jupyterhub/jupyterhub_config.py` which originates from:
+Linux administrators may want to review `/opt/iiab/jupyterhub/etc/jupyterhub/jupyterhub_config.py` which originates from:
 
 https://github.com/iiab/iiab/blob/master/roles/jupyterhub/templates/jupyterhub_config.py
 
-Note that `/opt/iiab/jupyterhub` is a Python 3 virtual environment, that can be activated with the usual formula:
+In some rare circumstances, it may be necessary to restart JupyterHub's systemd service:
+
+```
+sudo systemctl restart jupyterhub
+```
+
+FYI `/opt/iiab/jupyterhub` is a Python 3 virtual environment, that can be activated with the usual formula:
 
 ```
 source /opt/iiab/jupyterhub/bin/activate
 ```
 
+Passwords are hashed using 4096 rounds of the latest Blowfish (bcrypt's $2b$ algorithm) and stored in:
+
+```
+/opt/iiab/jupyterhub/etc/passwords.dbm.db
+```
+
+### Users can change their own password
+
+Users can change their password by logging in, and then visiting URL: http://box.lan/jupyterhub/auth/change-password
+
+NOTE: This is the only way to change the password for user 'Admin', because Control Panel > Admin (below) does not permit deletion of this account.
+
+### Control Panel > Admin page, to manage other accounts
+
+The 'Admin' user (and any users given 'Admin' privilege) can reset user passwords by deleting the user from JupyterHub's **Admin** page (below).  This logs the user out, but does not remove any of their data or home directories.  The user can then set a new password in the usual way — simply by logging in.  Example:
+
+1. As a user with 'Admin' privilege, click **Control Panel** in the top right of your JupyterHub:
+
+   ![Control panel button in notebook, top right](control-panel-button1.png)
+
+2. In the Control Panel, open the **Admin** link in the top left:
+
+   ![Admin button in control panel, top left](admin-access-button1.png)
+
+   This opens up the JupyterHub Admin page, where you can add / delete users, start / stop peoples’ servers and see who is online.
+
+3. Delete the user whose password needs resetting.  Remember this does not delete their data or home directory:
+
+   ![Delete user button for each user](delete-user.png)
+
+   If there is a confirmation dialog, confirm the deletion.  This will also log the user out if they were currently running.
+
+4. Re-create the user whose password needs resetting, on this same screen.
+
+5. Ask the user to log in, but with a new password of their choosing.  This will be their password going forward.
+
+_WARNING: If on login users see "500 : Internal Server Error", you may need to remove ALL files of the form_ `/run/jupyter-johndoe-singleuser`
+
 ### PAWS/Jupyter Notebooks for Python Beginners
 
 While PAWS is a little bit off topic, if you have an interest in Wikipedia, please do see this 23m 42s video ["Intro to PAWS/Jupyter notebooks for Python beginners"](https://www.youtube.com/watch?v=AUZkioRI-aA&list=PLeoTcBlDanyNQXBqI1rVXUqUTSSiuSIXN&index=8) by Chico Venancio, from 2021-06-01.
 
 He explains PAWS as a "powerful Python execution environment http://paws.wmcloud.org [allowing] ordinary folks to write interactive scripts to work with Wikimedia content."
-
-### Known Issues
-
-* 2021-08-07: The page that allows you to reset/change your own password is not accessible.  Likewise Admin users cannot reset/change the password of any _individual_ user at this time.  <sub><sub>[#2918](https://github.com/iiab/iiab/pull/2918)</sub></sub>
-  * If necessary, a Linux administrator can delete the `/passwords.dbm.db` file at the very top of your Linux filesystem, allowing all JupyterHub users to (re)create new passwords.  This does work, but is very heavy-handed.  <sub><sub>[PR #2892](https://github.com/iiab/iiab/pull/2892#issuecomment-890551682)</sub></sub>
-* 2021-08-07: Teachers (i.e. Admin users) cannot currently access the very helpful "administrator's page" discussed at [JupyterHub FAQ >> "How do I manage users?"](https://jupyterhub.readthedocs.io/en/stable/getting-started/institutional-faq.html#how-do-i-manage-users) and [roles/jupyterhub/templates/jupyterhub_config.py#L1049-L1054 >> "Admin users have extra privileges"](https://github.com/iiab/iiab/blob/d0e8e048347bf46c02a2cdb0da9c5cd0c489fe40/roles/jupyterhub/templates/jupyterhub_config.py#L1049-L1054).  <sub><sub>[#2919](https://github.com/iiab/iiab/pull/2919)</sub></sub>
-* 2021-08-08: Password [dbm file](https://github.com/jupyterhub/firstuseauthenticator#firstuseauthenticatordbm_path) `/passwords.dbm.db` should be moved from the top of the filesystem to a better place — e.g. to `/opt/iiab/jupyterhub/etc/` ?  <sub><sub>[PR #2892](https://github.com/iiab/iiab/pull/2892#issuecomment-890579789)</sub></sub>

roles/jupyterhub/tasks/install.yml

@@ -51,13 +51,37 @@
 
 - name: "Install from template: {{ jupyterhub_venv }}/etc/jupyterhub/jupyterhub_config.py"
   template:
-    src: jupyterhub_config.py
-    dest: "{{ jupyterhub_venv }}/etc/jupyterhub/"
+    src: jupyterhub_config.py.j2
+    dest: "{{ jupyterhub_venv }}/etc/jupyterhub/jupyterhub_config.py"
 
 - name: "Install from template: /etc/systemd/system/jupyterhub.service"
   template:
-    src: jupyterhub.service
-    dest: /etc/systemd/system/
+    src: jupyterhub.service.j2
+    dest: /etc/systemd/system/jupyterhub.service
+
+- name: Install {{ jupyterhub_venv }}/bin/getsite.py from template, to fetch site_packages path, e.g. {{ jupyterhub_venv }}/lib/python{{ python_ver }}/site-packages
+  template:
+    src: getsite.py.j2
+    dest: "{{ jupyterhub_venv }}/bin/getsite.py"
+    mode: 0755
+
+- name: Install patch_FUA.sh from template -- to (1) fix async password-changing page, and (2) force usernames to lowercase -- patching $SITE_PACKAGES/firstuseauthenticator/firstuseauthenticator.py
+  template:
+    src: patch_FUA.sh.j2
+    dest: "{{ jupyterhub_venv }}/bin/patch_FUA.sh"
+    mode: 0755
+
+- name: "Run the above two, via: {{ jupyterhub_venv }}/bin/patch_FUA.sh"
+  command: "{{ jupyterhub_venv }}/bin/patch_FUA.sh"
+
+- name: Install patch_http-warning.sh from template, to turn off the warning about http insecurity, in {{ jupyterhub_venv }}/share/jupyterhub/templates/login.html
+  template:
+    src: patch-http-warning.sh.j2
+    dest: "{{ jupyterhub_venv }}/bin/patch_http-warning.sh"
+    mode: 0755
+
+- name: "Now run it: {{ jupyterhub_venv }}/bin/patch_http-warning.sh"
+  command: "{{ jupyterhub_venv }}/bin/patch_http-warning.sh"
 
 
 # RECORD JupyterHub AS INSTALLED

roles/jupyterhub/templates/getsite.py.j2

@@ -0,0 +1,7 @@
+#!{{ jupyterhub_venv }}/bin/python3
+
+import site
+
+for path in iter(site.getsitepackages()):
+    if path.find('site') != -1:
+        print(path)

roles/jupyterhub/templates/jupyterhub_config.py.j2

@@ -1057,7 +1057,8 @@ c.JupyterHub.spawner_class = 'systemdspawner.SystemdSpawner'
 #  
 #  Defaults to an empty set, in which case no user has admin access.
 #  Default: set()
-c.Authenticator.admin_users = set('Admin')
+c.Authenticator.admin_users = set(['admin'])
+c.Authenticator.dbm_path = "{{ jupyterhub_venv }}/etc/passwords.dbm"
 
 ## Set of usernames that are allowed to log in.
 #  

roles/jupyterhub/templates/patch-http-warning.sh.j2

@@ -0,0 +1,4 @@
+#!/bin/bash -x
+# Do not enable the warning about the insecurity of http protocol
+
+sed -i 's/if (window\.location.*/if (false) {/' {{ jupyterhub_venv }}/share/jupyterhub/templates/login.html

roles/jupyterhub/templates/patch_FUA.sh.j2

@@ -0,0 +1,16 @@
+#!/bin/bash -x
+# Apply 2 patches to firstuseauthenticator.py
+
+# SITE_PACKAGES=$({{ jupyterhub_venv }}/bin/python -m site | grep {{ jupyterhub_venv }} | grep /site-packages | cut -d\' -f2)
+SITE_PACKAGES=$({{ jupyterhub_venv }}/bin/getsite.py)
+file=$SITE_PACKAGES/firstuseauthenticator/firstuseauthenticator.py
+# e.g. /opt/iiab/jupyterhub/lib/python3.9/site-packages/firstuseauthenticator/firstuseauthenticator.py
+
+# (1) Add await to asyncio change password function:
+# https://github.com/iiab/iiab/issues/2918 == JupyterHub password-changing page shows "500 : Internal Server Error"
+# https://github.com/jupyterhub/firstuseauthenticator/issues/36 == 500 Error on path /hub/auth/change-password
+# https://github.com/jupyterhub/firstuseauthenticator/pull/37 == proposed fix to issue 36
+sed -i 's/= self\.render/= await self.render/' $file
+
+# (2) https://github.com/jupyterhub/firstuseauthenticator/pull/38 == lowercase username to lock password
+sed -i "s/data\['username'\]$/&.lower()/" $file