jupyterhub-couchdb-authenticator

CouchDB Authenticator for JupyterHub

This is a simple authenticator for a JupyterHub that fetches user authentication information from a CouchDB over HTTPS. This authenticator is designed for events where the organizer distributes usernames and passwords to the participants, and they are not meant to be able to change them. The event is supposed to only last for a short time and the sole purpose of authentication is that the JupyterHub can tell the different users apart. This authenticator harmonizes well with a system user agnostic spawner such as dockerspawner which allow the whole JupyterHub to be torn down after the event without the need of deleting operating system users. The code of this project has been inspired by the Remote CSV Authenticator.

CouchDB Document Format

The authenticator expects that on the CouchDB server a database called users exist. Each user is expected to be a document with the fields username, password, and active. The values of username and password are plaintext, the field active is boolean. This approach does not hash the password. Each password should be randomly generated by the event organizer, and it should be sufficiently complex.

Security Notes

If you need your JupyterHub installation to be highly secure, do not use this authenticator! It trades off some security for a lot of convenience, which might or might not be the right tradeoff for your JupyterHub installation.

Logging people out

If you make any changes to JupyterHub's authentication setup that changes which group of users is allowed to log in (such as changing the CouchDB, removing access for individual users, or even just turning on a new authenticator), you have to change the JupyterHub cookie secret, or users who were previously logged in and did not log out would continue to be logged in!

You can do this by deleting the jupyterhub_cookie_secret file. Note that this will log out all users who are currently logged in.

Installation

pip install jupyterhub-couchdb-authenticator

You can then use this as your authenticator by adding the following line to your jupyterhub_config.py:

c.JupyterHub.authenticator_class = 'couchdbauthenticator.CouchDBAuthenticator'

Configuration

Don't forget the preceding c. for setting configuration parameters! JupyterHub uses traitlets for configuration, and the c represents the config object.

• CouchDBAuthenticator.couchdb_url: The url where to reach the CouchDB.
• CouchDBAuthenticator.couchdb_username: The username for log into the CouchDB so that one has read access to the users database.
• CouchDBAuthenticator.couchdb_password: The password belonging to the username above. It is advised to use environment variables and not to hardcode the credentials into the configuration.
• CouchDBAuthenticator.ssl_verification: This parameter is handed over to the requests module and interpreted by it. The value True ensures that the SSL certificate is verified. The value False disables any kind of verification. A string value is interpreted as a path pointing to the certificate you expect to see. For more information, check the docs of requests.

Adding and Deactivating Users

You can create, modify and delete users in the CouchDB Web UI manually. Furthermore, you can use any REST API tool, see the CouchDB manual for more information. In couchdbauthenticator.user_manager, the class CouchDBConnection resides. This is for pure convenience. See minimal-jupyterhub-example/seed_users_database.py and minimal-jupyterhub-example/control_users_database.py for some sample applications.

Minimal Example and Development

For running the minimal example, you need to clone the GitHub repository. Check this explanation for more insights.