mit-oidc-oauthenticator

Authenticate Jupyter users with MIT OIDC OAuth (MIT's OAuth2/OpenID service).

This is based on Google OAuthenticator, which is based on Github OAuthenticator.

The class will redirect the user to the MIT OIDC server, where they can log in with a Kerberos password, ticket, or client certificates. The class verifies a mit.edu email suffix, strips it, and returns the bare username as the Jupyterhub client name.

Installation

First, install dependencies:

pip install -r requirements.txt

Then, install the package:

python setup.py install

Setup

You will need to create an OAuth 2.0 client ID in the MIT OIDC website. A client secret will be automatically generated for you. Set the callback URL to:

http[s]://[your-host]/hub/oauth2_callback

where [your-host] is your server's hostname, e.g. example.com:8000.

Then, add the following to your jupyterhub_config.py file:

c.JupyterHub.authenticator_class = 'oauthenticator.MITOAuthenticator'

You will need to provide the callback URL and the MIT OIDC OAuth client ID and client secret to JupyterHub. For example, if these values are in the environment variables $OAUTH_CALLBACK_URL, $OAUTH_CLIENT_ID and $OAUTH_CLIENT_SECRET, you should add the following to your jupyterhub_config.py:

c.MITOAuthenticator.oauth_callback_url = os.environ['OAUTH_CALLBACK_URL']
c.MITOAuthenticator.client_id = os.environ['OAUTH_CLIENT_ID']
c.MITOAuthenticator.client_secret = os.environ['OAUTH_CLIENT_SECRET']

Restricting access to a specific group

You can also use the the MITGroupOAuthenticator class to restrict access to a single group (via /etc/group membership). Add the following lines to your configuration:

c.JupyterHub.authenticator_class = 'oauthenticator.MITGroupOAuthenticator'
c.MITGroupOAuthenticator.required_group = 'YOUR_GROUP'

If you omit the required_group in your configuration, the class will behave like MITOAuthenticator and allow all users. If you give it an invalid group, or try to log in as a user not in that group, the user will be rejected with a HTTP 403 error.

Handling non-matching usernames

The authenticator uses Authenticator.normalize_username, which allows a configurable dict to remap usernames (username_map). This can be used to map MIT names to CSAIL names, in cases where they differ. Names that do not appear in the map are passed through unaltered. Note that the outer proxy server needs to be restarted when this dict is changed, but client Jupyter instances will be preserved as long as the sqlite database and per-user Docker images are left up (the c.JupyterHub.cleanup_servers option).

c.Authenticator.username_map = {"MIT_USERNAME" : "CSAIL_USERNAME"}