Debian Codegraph @

docs/source/howto/configuration/config-ghoauth.md

raw
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.