diff --git a/docs/howto/auth/github.rst b/docs/howto/auth/github.rst new file mode 100644 index 0000000..7962657 --- /dev/null +++ b/docs/howto/auth/github.rst @@ -0,0 +1,60 @@ +.. _howto/auth/github: + +=================================== +Authenticate using GitHub Usernames +=================================== + +The **GitHub Authenticator** lets users log into your JupyterHub using their +GitHub user ID / password. To do so, you'll first need to register an +application with GitHub, and then provide information about this +application to your ``tljh`` configuration. + +Enabling the authenticator +========================== + +.. note:: + + You'll need a GitHub account in order to complete these steps. + +#. Create a GitHub application + #. Go to the `GitHub OAuth app creation page `_. + #. **Application name**: Choose a descriptive application name (e.g. ``tljh``) + #. **Homepage URL**: Use the IP address or URL of your JupyterHub. e.g. ``http://```. + #. **Application description**: Use any description that you like. + #. **Authorization callback URL**: Insert text with the following form:: + + http:///hub/oauth_callback + + #. When you're done filling in the page, it should look something like this: + + .. image:: ../../images/auth/github/create_application.png + :alt: Create a GitHub OAuth application + #. Click "Register application". + #. You'll be taken to a page with the registered application details. Note + the **Client ID** and **Client Secret**, as you will use these later. + + .. image:: ../../images/auth/github/client_id_secret.png + :alt: Your client ID and secret + +#. Configure your JupyterHub to use the GitHub Oathenticator + #. Log in as an administrator account to your JupyterHub. + #. Open a terminal on your JupyterHub. + #. Configure the GitHub OAuthenticator to use your client ID and secret with the following commands:: + + sudo -E tljh-config set auth.GitHubOAuthenticator.client_id '' + sudo -E tljh-config set auth.GitHubOAuthenticator.client_secret '' + + #. Tell your JupyterHub to *use* the GitHub OAuthenticator for authentication:: + + sudo -E tljh-config set auth.type oauthenticator.github.GitHubOAuthenticator + + #. Restart your JupyterHub so that new users see these changes:: + + sudo -E tljh-config reload +#. Confirm that the new authentactor works. + #. Open an **incognito window** in your browser. + #. Go to your JupyterHub URL. + #. You should see a GitHub login button like below: + + .. image:: ../../images/auth/github/client_id_secret.png + :alt: The GitHub authenticator login button. diff --git a/docs/images/auth/github/client_id_secret.png b/docs/images/auth/github/client_id_secret.png new file mode 100644 index 0000000..3a29056 Binary files /dev/null and b/docs/images/auth/github/client_id_secret.png differ diff --git a/docs/images/auth/github/create_application.png b/docs/images/auth/github/create_application.png new file mode 100644 index 0000000..38306e7 Binary files /dev/null and b/docs/images/auth/github/create_application.png differ diff --git a/docs/images/auth/github/login_button.png b/docs/images/auth/github/login_button.png new file mode 100644 index 0000000..6eca51d Binary files /dev/null and b/docs/images/auth/github/login_button.png differ diff --git a/docs/index.rst b/docs/index.rst index 9f68ce7..1188977 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -68,6 +68,7 @@ with your JupyterHub. :titlesonly: howto/auth/dummy + howto/auth/github Topic Guides ============