diff --git a/docs/howto/auth/google.rst b/docs/howto/auth/google.rst new file mode 100644 index 0000000..d3e9e60 --- /dev/null +++ b/docs/howto/auth/google.rst @@ -0,0 +1,119 @@ +.. _howto/auth/google: + +========================= +Authenticate using Google +========================= + +The **Google Authenticator** lets users log into your JupyterHub using their +Google user ID / password. To do so, you'll first need to register an +application with Google, and then provide information about this +application to your ``tljh`` configuration. +See `Google's documentation `_ +on how to create OAUth 2.0 client credentials. + + +.. note:: + + You'll need a Google account in order to complete these steps. + +Step 1: Create a Google project +=============================== + +Go to `Google Developers Console `_ +and create a new project: + + .. image:: ../../images/auth/google/create_new_project.png + :alt: Create a Google project + + +Step 2: Set up a Google OAuth client ID and secret +================================================== + +1. After creating and selecting the project: + + * Go to the credentials menu: + + .. image:: ../../images/auth/google/credentials_button.png + :alt: Credentials menu + + * Click "Create credentials" and from the dropdown menu select **"OAuth client ID"**: + + .. image:: ../../images/auth/google/create_credentials.png + :alt: Generate credentials + + * You will have to fill a form with: + * **Application type**: Choose *Web application* + * **Name**: A descriptive name for your OAuth client ID (e.g. ``tljh-client``) + * **Authorized JavaScript origins**: Use the IP address or URL of your JupyterHub. e.g. ``http(s)://``. + * **Authorized redirect URIs**: Insert text with the following form:: + + http(s):///hub/oauth_callback + + * When you're done filling in the page, it should look something like this (ideally without the red warnings): + + .. image:: ../../images/auth/google/create_oauth_client_id.png + :alt: Create a Google OAuth client ID + + +2. Click "Create". You'll be taken to a page with the registered application details. +3. Copy the **Client ID** and **Client Secret** from the application details + page. You will use these later to configure your JupyterHub authenticator. + + .. image:: ../../images/auth/google/client_id_secret.png + :alt: Your client ID and secret + +.. important:: + + If you are using a virtual machine from a cloud provider and + **stop the VM**, then when you re-start the VM, the provider will likely assign a **new public + IP address** to it. In this case, **you must update your Google application information** + with the new IP address. + +Configure your JupyterHub to use the Google Oauthenticator +========================================================== + +We'll use the ``tljh-config`` tool to configure your JupyterHub's authentication. +For more information on ``tljh-config``, see :ref:`topic/tljh-config`. + +#. Log in as an administrator account to your JupyterHub. +#. Open a terminal window. + + .. image:: ../../images/notebook/new-terminal-button.png + :alt: New terminal button. + +#. Configure the Google OAuthenticator to use your client ID, client secret and callback URL with the following commands:: + + sudo tljh-config set auth.GoogleOAuthenticator.client_id '' + + :: + + sudo tljh-config set auth.GoogleOAuthenticator.client_secret '' + + :: + + sudo tljh-config set auth.GoogleOAuthenticator.oauth_callback_url 'http(s):///hub/oauth_callback' + +#. Tell your JupyterHub to *use* the Google OAuthenticator for authentication:: + + sudo tljh-config set auth.type oauthenticator.google.GoogleOAuthenticator + +#. Restart your JupyterHub so that new users see these changes:: + + sudo tljh-config reload + +Confirm that the new authenticator works +======================================== + +#. **Open an incognito window** in your browser (do not log out until you confirm + that the new authentication method works!) +#. Go to your JupyterHub URL. +#. You should see a Google login button like below: + + .. image:: ../../images/auth/google/login_button.png + :alt: The Google authenticator login button. + +#. After you log in with your Google credentials, you should be directed to the + Jupyter interface used in this JupyterHub. + +#. **If this does not work** you can revert back to the default + JupyterHub authenticator by following the steps in :ref:`howto/auth/firstuse`. diff --git a/docs/images/auth/google/client_id_secret.png b/docs/images/auth/google/client_id_secret.png new file mode 100644 index 0000000..aacb743 Binary files /dev/null and b/docs/images/auth/google/client_id_secret.png differ diff --git a/docs/images/auth/google/create_credentials.png b/docs/images/auth/google/create_credentials.png new file mode 100644 index 0000000..5bfcf85 Binary files /dev/null and b/docs/images/auth/google/create_credentials.png differ diff --git a/docs/images/auth/google/create_new_project.png b/docs/images/auth/google/create_new_project.png new file mode 100644 index 0000000..371e084 Binary files /dev/null and b/docs/images/auth/google/create_new_project.png differ diff --git a/docs/images/auth/google/create_oauth_client_id.png b/docs/images/auth/google/create_oauth_client_id.png new file mode 100644 index 0000000..bca39e3 Binary files /dev/null and b/docs/images/auth/google/create_oauth_client_id.png differ diff --git a/docs/images/auth/google/credentials_button.png b/docs/images/auth/google/credentials_button.png new file mode 100644 index 0000000..97f70dc Binary files /dev/null and b/docs/images/auth/google/credentials_button.png differ diff --git a/docs/images/auth/google/login_button.png b/docs/images/auth/google/login_button.png new file mode 100644 index 0000000..03efe6c Binary files /dev/null and b/docs/images/auth/google/login_button.png differ diff --git a/docs/index.rst b/docs/index.rst index a5058c5..c4fa181 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -80,6 +80,7 @@ with your JupyterHub. For more information on Authentication, see howto/auth/dummy howto/auth/github + howto/auth/google howto/auth/firstuse howto/auth/nativeauth