mirror of
https://github.com/jupyterhub/the-littlest-jupyterhub.git
synced 2025-12-18 21:54:05 +08:00
updating content from zexuan's user test
This commit is contained in:
Chris Holdgraf
committed by
yuvipanda
yuvipanda
parent
258e350abc
commit
2181947f83
36
docs/howto/auth/firstuse.rst
Normal file
36
docs/howto/auth/firstuse.rst
Normal file
@@ -0,0 +1,36 @@
|
||||
.. _howto/auth/firstuse:
|
||||
|
||||
==================================================
|
||||
Let users choose a password when they first log in
|
||||
==================================================
|
||||
|
||||
The **First Use Authenticator** lets users choose their own password.
|
||||
Upon their first log-in attempt, whatever password they use will be stored
|
||||
as their password for subsequent log in attempts. This is
|
||||
the default authenticator that ships with TLJH.
|
||||
|
||||
Enabling the authenticator
|
||||
==========================
|
||||
|
||||
.. note:: the FirstUseAuthenticator is enabled by default in TLJH.
|
||||
|
||||
#. Enable the authenticator and reload config to apply the configuration:
|
||||
|
||||
sudo -E tljh-config set auth.type firstuseauthenticator.FirstUseAuthenticator
|
||||
sudo -E tljh-config reload
|
||||
|
||||
Users who are currently logged in will continue to be logged in. When they
|
||||
log out and try to log back in, they will be asked to provide a username and
|
||||
password.
|
||||
|
||||
Allowing anyone to log in to your JupyterHub
|
||||
============================================
|
||||
|
||||
By default, you need to manually create user accounts before they will be able
|
||||
to log in to your JupyterHub. If you wish to allow **any** user to access
|
||||
the JupyterHub, run the following command.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
tljh-config set auth.FirstUseAuthenticator.create_users true
|
||||
tljh-config reload
|
||||
@@ -9,52 +9,81 @@ 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::
|
||||
Step 1: Create a GitHub application
|
||||
===================================
|
||||
|
||||
http://<my-tljh-url>/hub/oauth_callback
|
||||
#. Go to the `GitHub OAuth app creation page <https://github.com/settings/applications/new>`_.
|
||||
|
||||
#. When you're done filling in the page, it should look something like this:
|
||||
* **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-ip-address>/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.
|
||||
#. Click "Register application". You'll be taken to a page with the registered application details.
|
||||
#. 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/github/client_id_secret.png
|
||||
:alt: Your client ID and secret
|
||||
.. 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::
|
||||
.. important::
|
||||
|
||||
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>'
|
||||
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 GitHub application information**
|
||||
with the new IP address.
|
||||
|
||||
#. Tell your JupyterHub to *use* the GitHub OAuthenticator for authentication::
|
||||
Configure your JupyterHub to use the GitHub Oathenticator
|
||||
=========================================================
|
||||
|
||||
sudo -E tljh-config set auth.type oauthenticator.github.GitHubOAuthenticator
|
||||
We'll use the ``tljh-config`` tool to configure your JupyterHub's authentication.
|
||||
For more information on ``tljh-config``, see :ref:`topic/tljh-config`.
|
||||
|
||||
#. Restart your JupyterHub so that new users see these changes::
|
||||
#. Log in as an administrator account to your JupyterHub.
|
||||
#. Open a terminal window.
|
||||
|
||||
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/notebook/new-terminal-button.png
|
||||
:alt: New terminal button.
|
||||
|
||||
.. image:: ../../images/auth/github/client_id_secret.png
|
||||
:alt: The GitHub authenticator login button.
|
||||
#. 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 (do not log out until you confirm
|
||||
that the new authentication method works!)
|
||||
#. Go to your JupyterHub URL.
|
||||
#. You should see a GitHub login button like below:
|
||||
|
||||
.. image:: ../../images/auth/github/login_button.png
|
||||
:alt: The GitHub authenticator login button.
|
||||
|
||||
#. After you log in with your GitHub 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`.
|
||||
|
||||
Reference in New Issue
Block a user