| 1 |
(howto:config:gh-oauth)= |
| 2 |
|
| 3 |
# Configure GitHub OAuth |
| 4 |
|
| 5 |
In this example, we show a configuration file for a fairly standard JupyterHub |
| 6 |
deployment with the following assumptions: |
| 7 |
|
| 8 |
- Running JupyterHub on a single cloud server |
| 9 |
- Using SSL on the standard HTTPS port 443 |
| 10 |
- Using GitHub OAuth (using [OAuthenticator](https://oauthenticator.readthedocs.io/en/latest)) for login |
| 11 |
- Using the default spawner (to configure other spawners, uncomment and edit |
| 12 |
`spawner_class` as well as follow the instructions for your desired spawner) |
| 13 |
- Users exist locally on the server |
| 14 |
- Users' notebooks to be served from `~/assignments` to allow users to browse |
| 15 |
for notebooks within other users' home directories |
| 16 |
- You want the landing page for each user to be a `Welcome.ipynb` notebook in |
| 17 |
their assignments directory |
| 18 |
- All runtime files are put into `/srv/jupyterhub` and log files in `/var/log` |
| 19 |
|
| 20 |
The `jupyterhub_config.py` file would have these settings: |
| 21 |
|
| 22 |
```python |
| 23 |
# jupyterhub_config.py file |
| 24 |
c = get_config() |
| 25 |
|
| 26 |
import os |
| 27 |
pjoin = os.path.join |
| 28 |
|
| 29 |
runtime_dir = os.path.join('/srv/jupyterhub') |
| 30 |
ssl_dir = pjoin(runtime_dir, 'ssl') |
| 31 |
if not os.path.exists(ssl_dir): |
| 32 |
os.makedirs(ssl_dir) |
| 33 |
|
| 34 |
# Allows multiple single-server per user |
| 35 |
c.JupyterHub.allow_named_servers = True |
| 36 |
|
| 37 |
# https on :443 |
| 38 |
c.JupyterHub.port = 443 |
| 39 |
c.JupyterHub.ssl_key = pjoin(ssl_dir, 'ssl.key') |
| 40 |
c.JupyterHub.ssl_cert = pjoin(ssl_dir, 'ssl.cert') |
| 41 |
|
| 42 |
# put the JupyterHub cookie secret and state db |
| 43 |
# in /var/run/jupyterhub |
| 44 |
c.JupyterHub.cookie_secret_file = pjoin(runtime_dir, 'cookie_secret') |
| 45 |
c.JupyterHub.db_url = pjoin(runtime_dir, 'jupyterhub.sqlite') |
| 46 |
# or `--db=/path/to/jupyterhub.sqlite` on the command-line |
| 47 |
|
| 48 |
# use GitHub OAuthenticator for local users |
| 49 |
c.JupyterHub.authenticator_class = 'oauthenticator.LocalGitHubOAuthenticator' |
| 50 |
c.GitHubOAuthenticator.oauth_callback_url = os.environ['OAUTH_CALLBACK_URL'] |
| 51 |
|
| 52 |
# create system users that don't exist yet |
| 53 |
c.LocalAuthenticator.create_system_users = True |
| 54 |
|
| 55 |
# specify users and admin |
| 56 |
c.Authenticator.allowed_users = {'rgbkrk', 'minrk', 'jhamrick'} |
| 57 |
c.Authenticator.admin_users = {'jhamrick', 'rgbkrk'} |
| 58 |
|
| 59 |
# uses the default spawner |
| 60 |
# To use a different spawner, uncomment `spawner_class` and set to desired |
| 61 |
# spawner (e.g. SudoSpawner). Follow instructions for desired spawner |
| 62 |
# configuration. |
| 63 |
# c.JupyterHub.spawner_class = 'sudospawner.SudoSpawner' |
| 64 |
|
| 65 |
# start single-user notebook servers in ~/assignments, |
| 66 |
# with ~/assignments/Welcome.ipynb as the default landing page |
| 67 |
# this config could also be put in |
| 68 |
# /etc/jupyter/jupyter_notebook_config.py |
| 69 |
c.Spawner.notebook_dir = '~/assignments' |
| 70 |
c.Spawner.args = ['--NotebookApp.default_url=/notebooks/Welcome.ipynb'] |
| 71 |
``` |
| 72 |
|
| 73 |
Using the GitHub Authenticator requires a few additional |
| 74 |
environment variables to be set prior to launching JupyterHub: |
| 75 |
|
| 76 |
```bash |
| 77 |
export GITHUB_CLIENT_ID=github_id |
| 78 |
export GITHUB_CLIENT_SECRET=github_secret |
| 79 |
export OAUTH_CALLBACK_URL=https://example.com/hub/oauth_callback |
| 80 |
export CONFIGPROXY_AUTH_TOKEN=super-secret |
| 81 |
# append log output to log file /var/log/jupyterhub.log |
| 82 |
jupyterhub -f /etc/jupyterhub/jupyterhub_config.py &>> /var/log/jupyterhub.log |
| 83 |
``` |
| 84 |
|
| 85 |
Visit the [Github OAuthenticator reference](https://oauthenticator.readthedocs.io/en/latest/api/gen/oauthenticator.github.html) to see the full list of options for configuring Github OAuth with JupyterHub. |