Package: jupyterhub-couchdb-authenticator
CouchDB Authenticator for JupyterHubThis is a simple authenticator for aJupyterHubthat 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 asdockerspawnerwhich 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 theRemote CSV Authenticator.CouchDB Document FormatThe authenticator expects that on the CouchDB server a database calledusersexist.
Each user is expected to be a document with the fieldsusername,password, andactive.
The values ofusernameandpasswordare plaintext, the fieldactiveis 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 NotesIf you need your JupyterHub installation to be highly secure, donotuse 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 outIf 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),
youhaveto 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 thejupyterhub_cookie_secretfile.
Note that this will log outallusers who are currently logged in.Installationpip install jupyterhub-couchdb-authenticatorYou can then use this as your authenticator by adding the following line to
yourjupyterhub_config.py:c.JupyterHub.authenticator_class = 'couchdbauthenticator.CouchDBAuthenticator'ConfigurationDon't forget the precedingc.for setting configuration parameters!
JupyterHub usestraitletsfor
configuration, and thecrepresents theconfig 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 theusersdatabase.CouchDBAuthenticator.couchdb_password:
The password belonging to the username above.
It is advised to use environment variables andnotto
hardcode the credentials into the configuration.CouchDBAuthenticator.ssl_verification:
This parameter is handed over to the requests module and interpreted by it.
The valueTrueensures that the SSL certificate is verified.
The valueFalsedisables any kind of verification.
A string value is interpreted as a path pointing to the certificate you expect to see.
For more information, checkthe docs of requests.Adding and Deactivating UsersYou can create, modify and delete users in the CouchDB Web UI manually.
Furthermore, you can use any REST API tool, seethe CouchDB manualfor more information.
Incouchdbauthenticator.user_manager, the classCouchDBConnectionresides.
This is for pure convenience.
Seeminimal-jupyterhub-example/seed_users_database.pyandminimal-jupyterhub-example/control_users_database.pyfor some sample applications.Minimal Example and DevelopmentFor running the minimal example, you need to clone the GitHub repository.
Checkthis explanationfor more insights.