-
Notifications
You must be signed in to change notification settings - Fork 336
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #117 from jupyterhub/github_auth
adding documentation for GitHub OAuth
- Loading branch information
Showing
5 changed files
with
61 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters