Merge pull request #117 from jupyterhub/github_auth

adding documentation for GitHub OAuth

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 <https://github.com/settings/applications/new>`_.
+   #. **Application name**: Choose a descriptive application name (e.g. ``tljh``)
+   #. **Homepage URL**: Use the IP address or URL of your JupyterHub. e.g. ``http://<my-tljh-url>```.
+   #. **Application description**: Use any description that you like.
+   #. **Authorization callback URL**: Insert text with the following form::
+
+      http://<my-tljh-url>/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 '<my-tljh-client-id>'
+        sudo -E tljh-config set auth.GitHubOAuthenticator.client_secret '<my-tljh-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.

docs/index.rst

@@ -74,6 +74,7 @@ with your JupyterHub. For more information on Authentication, see
    :titlesonly:
 
    howto/auth/dummy
+   howto/auth/github
 
 Topic Guides
 ============