mirror of
https://github.com/jupyterhub/the-littlest-jupyterhub.git
synced 2025-12-18 21:54:05 +08:00
adopt myst
run rst2myst, with minimal manual formatting fixes
This commit is contained in:
Min RK
128
docs/howto/auth/awscognito.md
Normal file
128
docs/howto/auth/awscognito.md
Normal file
@@ -0,0 +1,128 @@
|
||||
(howto-auth-awscognito)=
|
||||
|
||||
# Authenticate using AWS Cognito
|
||||
|
||||
The **AWS Cognito Authenticator** lets users log into your JupyterHub using
|
||||
cognito user pools. To do so, you'll first need to register and configure a
|
||||
cognito user pool and app, and then provide information about this
|
||||
application to your `tljh` configuration.
|
||||
|
||||
## Create an AWS Cognito application
|
||||
|
||||
1. Create a user pool [Getting Started with User Pool](https://docs.aws.amazon.com/cognito/latest/developerguide/getting-started-with-cognito-user-pools.html).
|
||||
|
||||
When you have completed creating a user pool, app, and domain you should have the following settings available to you:
|
||||
|
||||
- **App client id**: From the App client page
|
||||
|
||||
- **App client secret** From the App client page
|
||||
|
||||
- **Callback URL** This should be the domain you are hosting you server on:
|
||||
|
||||
```
|
||||
http(s)://<my-tljh-ip-address>/hub/oauth_callback
|
||||
```
|
||||
|
||||
- **Signout URL**: This is the landing page for a user when they are not logged on:
|
||||
|
||||
```
|
||||
http(s)://<my-tljh-ip-address>
|
||||
```
|
||||
|
||||
> - **Auth Domain** Create an auth domain e.g. \<my_jupyter_hub>:
|
||||
>
|
||||
> ```
|
||||
> https://<<my_jupyter_hub>.auth.eu-west-1.amazoncognito.com
|
||||
> ```
|
||||
|
||||
## Install and configure an AWS EC2 Instance with userdata
|
||||
|
||||
By adding following script to the ec2 instance user data you should be
|
||||
able to configure the instance automatically, replace relevant placeholders:
|
||||
|
||||
```
|
||||
#!/bin/bash
|
||||
##############################################
|
||||
# Ensure tljh is up to date
|
||||
##############################################
|
||||
curl -L https://tljh.jupyter.org/bootstrap.py \
|
||||
| sudo python3 - \
|
||||
--admin insightadmin
|
||||
|
||||
##############################################
|
||||
# Setup AWS Cognito OAuthenticator
|
||||
##############################################
|
||||
echo > /opt/tljh/config/jupyterhub_config.d/awscognito.py <<EOF
|
||||
c.GenericOAuthenticator.client_id = "[your app client ID]"
|
||||
c.GenericOAuthenticator.client_secret = "[your app client secret]"
|
||||
c.GenericOAuthenticator.oauth_callback_url = "https://[your-jupyterhub-host]/hub/oauth_callback"
|
||||
|
||||
c.GenericOAuthenticator.authorize_url = "https://your-AWSCognito-domain/oauth2/authorize"
|
||||
c.GenericOAuthenticator.token_url = "https://your-AWSCognito-domain/oauth2/token"
|
||||
c.GenericOAuthenticator.userdata_url = "https://your-AWSCognito-domain/oauth2/userInfo"
|
||||
c.GenericOAuthenticator.logout_redirect_url = "https://your-AWSCognito-domain/oauth2/logout"
|
||||
|
||||
# these are always the same
|
||||
c.GenericOAuthenticator.login_service = "AWS Cognito"
|
||||
c.GenericOAuthenticator.username_key = "username"
|
||||
c.GenericOAuthenticator.userdata_method = "POST"
|
||||
EOF
|
||||
|
||||
tljh-config set auth.type oauthenticator.generic.GenericOAuthenticator
|
||||
|
||||
tljh-config reload
|
||||
```
|
||||
|
||||
## Manual configuration to use the AWS Cognito OAuthenticator
|
||||
|
||||
AWS Cognito is configured as a generic OAuth provider.
|
||||
|
||||
Using your preferred editor create the config file:
|
||||
|
||||
```
|
||||
/opt/tljh/config/jupyterhub_config.d/awscognito.py
|
||||
```
|
||||
|
||||
substituting the relevant variables:
|
||||
|
||||
```
|
||||
c.GenericOAuthenticator.client_id = "[your app ID]"
|
||||
c.GenericOAuthenticator.client_secret = "[your app Password]"
|
||||
c.GenericOAuthenticator.oauth_callback_url = "https://[your-jupyterhub-host]/hub/oauth_callback"
|
||||
|
||||
c.GenericOAuthenticator.authorize_url = "https://your-AWSCognito-domain/oauth2/authorize"
|
||||
c.GenericOAuthenticator.token_url = "https://your-AWSCognito-domain/oauth2/token"
|
||||
c.GenericOAuthenticator.userdata_url = "https://your-AWSCognito-domain/oauth2/userInfo"
|
||||
c.GenericOAuthenticator.logout_redirect_url = "https://your-AWSCognito-domain/oauth2/logout"
|
||||
|
||||
# these are always the same
|
||||
c.GenericOAuthenticator.login_service = "AWS Cognito"
|
||||
c.GenericOAuthenticator.username_key = "username"
|
||||
c.GenericOAuthenticator.userdata_method = "POST"
|
||||
```
|
||||
|
||||
We'll use the `tljh-config` tool to configure your JupyterHub's authentication.
|
||||
For more information on `tljh-config`, see {ref}`topic/tljh-config`.
|
||||
|
||||
1. Tell your JupyterHub to use the GenericOAuthenticator for authentication:
|
||||
|
||||
```
|
||||
tljh-config set auth.type oauthenticator.generic.GenericOAuthenticator
|
||||
```
|
||||
|
||||
2. Restart your JupyterHub so that new users see these changes:
|
||||
|
||||
```
|
||||
sudo tljh-config reload
|
||||
```
|
||||
|
||||
## Confirm that the new authenticator works
|
||||
|
||||
1. **Open an incognito window** in your browser (do not log out until you confirm
|
||||
that the new authentication method works!)
|
||||
2. Go to your JupyterHub URL.
|
||||
3. You should see an AWS Cognito login button:
|
||||
4. You will likely have to create a new user (sign up) and then you should be directed to the
|
||||
Jupyter interface used in this JupyterHub.
|
||||
5. **If this does not work** you can revert back to the default
|
||||
JupyterHub authenticator by following the steps in {ref}`howto/auth/firstuse`.
|
||||
@@ -1,122 +0,0 @@
|
||||
.. _howto/auth/awscognito:
|
||||
|
||||
==============================
|
||||
Authenticate using AWS Cognito
|
||||
==============================
|
||||
|
||||
The **AWS Cognito Authenticator** lets users log into your JupyterHub using
|
||||
cognito user pools. To do so, you'll first need to register and configure a
|
||||
cognito user pool and app, and then provide information about this
|
||||
application to your ``tljh`` configuration.
|
||||
|
||||
|
||||
Create an AWS Cognito application
|
||||
=========================================
|
||||
|
||||
#. Create a user pool `Getting Started with User Pool <https://docs.aws.amazon.com/cognito/latest/developerguide/getting-started-with-cognito-user-pools.html>`_.
|
||||
|
||||
When you have completed creating a user pool, app, and domain you should have the following settings available to you:
|
||||
|
||||
* **App client id**: From the App client page
|
||||
* **App client secret** From the App client page
|
||||
* **Callback URL** This should be the domain you are hosting you server on::
|
||||
|
||||
http(s)://<my-tljh-ip-address>/hub/oauth_callback
|
||||
|
||||
* **Signout URL**: This is the landing page for a user when they are not logged on::
|
||||
|
||||
http(s)://<my-tljh-ip-address>
|
||||
|
||||
* **Auth Domain** Create an auth domain e.g. <my_jupyter_hub>::
|
||||
|
||||
https://<<my_jupyter_hub>.auth.eu-west-1.amazoncognito.com
|
||||
|
||||
|
||||
Install and configure an AWS EC2 Instance with userdata
|
||||
=======================================================
|
||||
|
||||
By adding following script to the ec2 instance user data you should be
|
||||
able to configure the instance automatically, replace relevant placeholders::
|
||||
|
||||
#!/bin/bash
|
||||
##############################################
|
||||
# Ensure tljh is up to date
|
||||
##############################################
|
||||
curl -L https://tljh.jupyter.org/bootstrap.py \
|
||||
| sudo python3 - \
|
||||
--admin insightadmin
|
||||
|
||||
##############################################
|
||||
# Setup AWS Cognito OAuthenticator
|
||||
##############################################
|
||||
echo > /opt/tljh/config/jupyterhub_config.d/awscognito.py <<EOF
|
||||
c.GenericOAuthenticator.client_id = "[your app client ID]"
|
||||
c.GenericOAuthenticator.client_secret = "[your app client secret]"
|
||||
c.GenericOAuthenticator.oauth_callback_url = "https://[your-jupyterhub-host]/hub/oauth_callback"
|
||||
|
||||
c.GenericOAuthenticator.authorize_url = "https://your-AWSCognito-domain/oauth2/authorize"
|
||||
c.GenericOAuthenticator.token_url = "https://your-AWSCognito-domain/oauth2/token"
|
||||
c.GenericOAuthenticator.userdata_url = "https://your-AWSCognito-domain/oauth2/userInfo"
|
||||
c.GenericOAuthenticator.logout_redirect_url = "https://your-AWSCognito-domain/oauth2/logout"
|
||||
|
||||
# these are always the same
|
||||
c.GenericOAuthenticator.login_service = "AWS Cognito"
|
||||
c.GenericOAuthenticator.username_key = "username"
|
||||
c.GenericOAuthenticator.userdata_method = "POST"
|
||||
EOF
|
||||
|
||||
tljh-config set auth.type oauthenticator.generic.GenericOAuthenticator
|
||||
|
||||
tljh-config reload
|
||||
|
||||
Manual configuration to use the AWS Cognito OAuthenticator
|
||||
==========================================================
|
||||
|
||||
AWS Cognito is configured as a generic OAuth provider.
|
||||
|
||||
Using your preferred editor create the config file::
|
||||
|
||||
/opt/tljh/config/jupyterhub_config.d/awscognito.py
|
||||
|
||||
substituting the relevant variables::
|
||||
|
||||
c.GenericOAuthenticator.client_id = "[your app ID]"
|
||||
c.GenericOAuthenticator.client_secret = "[your app Password]"
|
||||
c.GenericOAuthenticator.oauth_callback_url = "https://[your-jupyterhub-host]/hub/oauth_callback"
|
||||
|
||||
c.GenericOAuthenticator.authorize_url = "https://your-AWSCognito-domain/oauth2/authorize"
|
||||
c.GenericOAuthenticator.token_url = "https://your-AWSCognito-domain/oauth2/token"
|
||||
c.GenericOAuthenticator.userdata_url = "https://your-AWSCognito-domain/oauth2/userInfo"
|
||||
c.GenericOAuthenticator.logout_redirect_url = "https://your-AWSCognito-domain/oauth2/logout"
|
||||
|
||||
# these are always the same
|
||||
c.GenericOAuthenticator.login_service = "AWS Cognito"
|
||||
c.GenericOAuthenticator.username_key = "username"
|
||||
c.GenericOAuthenticator.userdata_method = "POST"
|
||||
|
||||
We'll use the ``tljh-config`` tool to configure your JupyterHub's authentication.
|
||||
For more information on ``tljh-config``, see :ref:`topic/tljh-config`.
|
||||
|
||||
#. Tell your JupyterHub to use the GenericOAuthenticator for authentication::
|
||||
|
||||
tljh-config set auth.type oauthenticator.generic.GenericOAuthenticator
|
||||
|
||||
#. 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 an AWS Cognito login button:
|
||||
|
||||
#. You will likely have to create a new user (sign up) and then 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`.
|
||||
47
docs/howto/auth/dummy.md
Normal file
47
docs/howto/auth/dummy.md
Normal file
@@ -0,0 +1,47 @@
|
||||
(howto-auth-dummy)=
|
||||
|
||||
# Authenticate _any_ user with a single shared password
|
||||
|
||||
The **Dummy Authenticator** lets _any_ user log in with the given password.
|
||||
This authenticator is **extremely insecure**, so do not use it if you can
|
||||
avoid it.
|
||||
|
||||
## Enabling the authenticator
|
||||
|
||||
1. Always use DummyAuthenticator with a password. You can communicate this
|
||||
password to all your users via an out of band mechanism (like writing on
|
||||
a whiteboard). Once you have selected a password, configure TLJH to use
|
||||
the password by executing the following from an admin console.
|
||||
|
||||
```bash
|
||||
sudo tljh-config set auth.DummyAuthenticator.password <password>
|
||||
```
|
||||
|
||||
Remember to replace `<password>` with the password you choose.
|
||||
|
||||
2. Enable the authenticator and reload config to apply configuration:
|
||||
|
||||
```bash
|
||||
sudo tljh-config set auth.type dummy
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo 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.
|
||||
|
||||
## Changing the password
|
||||
|
||||
The password used by DummyAuthenticator can be changed with the following
|
||||
commands:
|
||||
|
||||
```bash
|
||||
tljh-config set auth.DummyAuthenticator.password <new-password>
|
||||
```
|
||||
|
||||
```bash
|
||||
tljh-config reload
|
||||
```
|
||||
@@ -1,51 +0,0 @@
|
||||
.. _howto/auth/dummy:
|
||||
|
||||
=====================================================
|
||||
Authenticate *any* user with a single shared password
|
||||
=====================================================
|
||||
|
||||
The **Dummy Authenticator** lets *any* user log in with the given password.
|
||||
This authenticator is **extremely insecure**, so do not use it if you can
|
||||
avoid it.
|
||||
|
||||
Enabling the authenticator
|
||||
==========================
|
||||
|
||||
1. Always use DummyAuthenticator with a password. You can communicate this
|
||||
password to all your users via an out of band mechanism (like writing on
|
||||
a whiteboard). Once you have selected a password, configure TLJH to use
|
||||
the password by executing the following from an admin console.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo tljh-config set auth.DummyAuthenticator.password <password>
|
||||
|
||||
Remember to replace ``<password>`` with the password you choose.
|
||||
|
||||
2. Enable the authenticator and reload config to apply configuration:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo tljh-config set auth.type dummy
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo 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.
|
||||
|
||||
Changing the password
|
||||
=====================
|
||||
|
||||
The password used by DummyAuthenticator can be changed with the following
|
||||
commands:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
tljh-config set auth.DummyAuthenticator.password <new-password>
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
tljh-config reload
|
||||
79
docs/howto/auth/firstuse.md
Normal file
79
docs/howto/auth/firstuse.md
Normal file
@@ -0,0 +1,79 @@
|
||||
(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.
|
||||
:::
|
||||
|
||||
1. Enable the authenticator and reload config to apply the configuration:
|
||||
|
||||
```bash
|
||||
sudo tljh-config set auth.type firstuseauthenticator.FirstUseAuthenticator
|
||||
sudo 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.
|
||||
|
||||
## Users changing their own password
|
||||
|
||||
Users can change their password by first logging into their account and then visiting
|
||||
the url `<your_server_ip>/hub/auth/change-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.
|
||||
|
||||
```bash
|
||||
tljh-config set auth.FirstUseAuthenticator.create_users true
|
||||
tljh-config reload
|
||||
```
|
||||
|
||||
## Resetting user password
|
||||
|
||||
The admin can reset user passwords by _deleting_ the user from the JupyterHub admin
|
||||
page. This logs the user out, but does **not** remove any of their data or
|
||||
home directories. The user can then set a new password by logging in again with
|
||||
their new password.
|
||||
|
||||
1. As an admin user, open the **Control Panel** by clicking the control panel
|
||||
button on the top right of your JupyterHub.
|
||||
|
||||
```{image} ../../images/control-panel-button.png
|
||||
:alt: Control panel button in notebook, top right
|
||||
```
|
||||
|
||||
2. In the control panel, open the **Admin** link in the top left.
|
||||
|
||||
```{image} ../../images/admin/admin-access-button.png
|
||||
:alt: Admin button in control panel, top left
|
||||
```
|
||||
|
||||
This opens up the JupyterHub admin page, where you can add / delete users,
|
||||
start / stop peoples' servers and see who is online.
|
||||
|
||||
3. **Delete** the user whose password needs resetting. Remember this **does not**
|
||||
delete their data or home directory.
|
||||
|
||||
```{image} ../../images/auth/firstuse/delete-user.png
|
||||
:alt: Delete user button for each user
|
||||
```
|
||||
|
||||
If there is a confirmation dialog, confirm the deletion. This will also log the
|
||||
user out if they were currently running.
|
||||
|
||||
4. Re-create the user whose password needs resetting within that same dialog.
|
||||
|
||||
5. Ask the user to log in again with their new password as usual. This will be their
|
||||
new password going forward.
|
||||
@@ -1,81 +0,0 @@
|
||||
.. _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:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo tljh-config set auth.type firstuseauthenticator.FirstUseAuthenticator
|
||||
sudo 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.
|
||||
|
||||
Users changing their own password
|
||||
=================================
|
||||
|
||||
Users can change their password by first logging into their account and then visiting
|
||||
the url ``<your_server_ip>/hub/auth/change-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
|
||||
|
||||
|
||||
Resetting user password
|
||||
=======================
|
||||
|
||||
The admin can reset user passwords by *deleting* the user from the JupyterHub admin
|
||||
page. This logs the user out, but does **not** remove any of their data or
|
||||
home directories. The user can then set a new password by logging in again with
|
||||
their new password.
|
||||
|
||||
#. As an admin user, open the **Control Panel** by clicking the control panel
|
||||
button on the top right of your JupyterHub.
|
||||
|
||||
.. image:: ../../images/control-panel-button.png
|
||||
:alt: Control panel button in notebook, top right
|
||||
|
||||
#. In the control panel, open the **Admin** link in the top left.
|
||||
|
||||
.. image:: ../../images/admin/admin-access-button.png
|
||||
:alt: Admin button in control panel, top left
|
||||
|
||||
This opens up the JupyterHub admin page, where you can add / delete users,
|
||||
start / stop peoples' servers and see who is online.
|
||||
|
||||
#. **Delete** the user whose password needs resetting. Remember this **does not**
|
||||
delete their data or home directory.
|
||||
|
||||
.. image:: ../../images/auth/firstuse/delete-user.png
|
||||
:alt: Delete user button for each user
|
||||
|
||||
If there is a confirmation dialog, confirm the deletion. This will also log the
|
||||
user out if they were currently running.
|
||||
|
||||
#. Re-create the user whose password needs resetting within that same dialog.
|
||||
|
||||
#. Ask the user to log in again with their new password as usual. This will be their
|
||||
new password going forward.
|
||||
108
docs/howto/auth/github.md
Normal file
108
docs/howto/auth/github.md
Normal file
@@ -0,0 +1,108 @@
|
||||
(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.
|
||||
|
||||
:::{note}
|
||||
You'll need a GitHub account in order to complete these steps.
|
||||
:::
|
||||
|
||||
## Step 1: Create a GitHub application
|
||||
|
||||
1. 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(s)://<my-tljh-url>` ``.
|
||||
|
||||
- **Application description**: Use any description that you like.
|
||||
|
||||
- **Authorization callback URL**: Insert text with the following form:
|
||||
|
||||
```
|
||||
http(s)://<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
|
||||
> ```
|
||||
|
||||
2. Click "Register application". 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/github/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 GitHub application information**
|
||||
with the new IP address.
|
||||
:::
|
||||
|
||||
## Configure your JupyterHub to use the GitHub 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`.
|
||||
|
||||
1. Log in as an administrator account to your JupyterHub.
|
||||
|
||||
2. Open a terminal window.
|
||||
|
||||
```{image} ../../images/notebook/new-terminal-button.png
|
||||
:alt: New terminal button.
|
||||
```
|
||||
|
||||
3. Configure the GitHub OAuthenticator to use your client ID, client secret and callback URL with the following commands:
|
||||
|
||||
```
|
||||
sudo tljh-config set auth.GitHubOAuthenticator.client_id '<my-tljh-client-id>'
|
||||
```
|
||||
|
||||
```
|
||||
sudo tljh-config set auth.GitHubOAuthenticator.client_secret '<my-tljh-client-secret>'
|
||||
```
|
||||
|
||||
```
|
||||
sudo tljh-config set auth.GitHubOAuthenticator.oauth_callback_url 'http(s)://<my-tljh-ip-address>/hub/oauth_callback'
|
||||
```
|
||||
|
||||
4. Tell your JupyterHub to _use_ the GitHub OAuthenticator for authentication:
|
||||
|
||||
```
|
||||
sudo tljh-config set auth.type oauthenticator.github.GitHubOAuthenticator
|
||||
```
|
||||
|
||||
5. Restart your JupyterHub so that new users see these changes:
|
||||
|
||||
```
|
||||
sudo tljh-config reload
|
||||
```
|
||||
|
||||
## Confirm that the new authenticator works
|
||||
|
||||
1. **Open an incognito window** in your browser (do not log out until you confirm
|
||||
that the new authentication method works!)
|
||||
|
||||
2. Go to your JupyterHub URL.
|
||||
|
||||
3. You should see a GitHub login button like below:
|
||||
|
||||
```{image} ../../images/auth/github/login_button.png
|
||||
:alt: The GitHub authenticator login button.
|
||||
```
|
||||
|
||||
4. After you log in with your GitHub credentials, you should be directed to the
|
||||
Jupyter interface used in this JupyterHub.
|
||||
|
||||
5. **If this does not work** you can revert back to the default
|
||||
JupyterHub authenticator by following the steps in {ref}`howto/auth/firstuse`.
|
||||
@@ -1,93 +0,0 @@
|
||||
.. _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.
|
||||
|
||||
.. note::
|
||||
|
||||
You'll need a GitHub account in order to complete these steps.
|
||||
|
||||
Step 1: 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(s)://<my-tljh-url>```.
|
||||
* **Application description**: Use any description that you like.
|
||||
* **Authorization callback URL**: Insert text with the following form::
|
||||
|
||||
http(s)://<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.
|
||||
#. 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
|
||||
|
||||
.. 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 GitHub application information**
|
||||
with the new IP address.
|
||||
|
||||
Configure your JupyterHub to use the GitHub 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 GitHub OAuthenticator to use your client ID, client secret and callback URL with the following commands::
|
||||
|
||||
sudo tljh-config set auth.GitHubOAuthenticator.client_id '<my-tljh-client-id>'
|
||||
|
||||
::
|
||||
|
||||
sudo tljh-config set auth.GitHubOAuthenticator.client_secret '<my-tljh-client-secret>'
|
||||
|
||||
::
|
||||
|
||||
sudo tljh-config set auth.GitHubOAuthenticator.oauth_callback_url 'http(s)://<my-tljh-ip-address>/hub/oauth_callback'
|
||||
|
||||
#. Tell your JupyterHub to *use* the GitHub OAuthenticator for authentication::
|
||||
|
||||
sudo tljh-config set auth.type oauthenticator.github.GitHubOAuthenticator
|
||||
|
||||
#. 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 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`.
|
||||
133
docs/howto/auth/google.md
Normal file
133
docs/howto/auth/google.md
Normal file
@@ -0,0 +1,133 @@
|
||||
(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](https://developers.google.com/identity/protocols/OAuth2)
|
||||
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](https://console.developers.google.com)
|
||||
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)://<my-tljh-url>`.
|
||||
|
||||
- **Authorized redirect URIs**: Insert text with the following form:
|
||||
|
||||
```
|
||||
http(s)://<my-tljh-ip-address>/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`.
|
||||
|
||||
1. Log in as an administrator account to your JupyterHub.
|
||||
|
||||
2. Open a terminal window.
|
||||
|
||||
```{image} ../../images/notebook/new-terminal-button.png
|
||||
:alt: New terminal button.
|
||||
```
|
||||
|
||||
3. 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 '<my-tljh-client-id>'
|
||||
```
|
||||
|
||||
```
|
||||
sudo tljh-config set auth.GoogleOAuthenticator.client_secret '<my-tljh-client-secret>'
|
||||
```
|
||||
|
||||
```
|
||||
sudo tljh-config set auth.GoogleOAuthenticator.oauth_callback_url 'http(s)://<my-tljh-ip-address>/hub/oauth_callback'
|
||||
```
|
||||
|
||||
4. Tell your JupyterHub to _use_ the Google OAuthenticator for authentication:
|
||||
|
||||
```
|
||||
sudo tljh-config set auth.type oauthenticator.google.GoogleOAuthenticator
|
||||
```
|
||||
|
||||
5. Restart your JupyterHub so that new users see these changes:
|
||||
|
||||
```
|
||||
sudo tljh-config reload
|
||||
```
|
||||
|
||||
## Confirm that the new authenticator works
|
||||
|
||||
1. **Open an incognito window** in your browser (do not log out until you confirm
|
||||
that the new authentication method works!)
|
||||
|
||||
2. Go to your JupyterHub URL.
|
||||
|
||||
3. You should see a Google login button like below:
|
||||
|
||||
```{image} ../../images/auth/google/login_button.png
|
||||
:alt: The Google authenticator login button.
|
||||
```
|
||||
|
||||
4. After you log in with your Google credentials, you should be directed to the
|
||||
Jupyter interface used in this JupyterHub.
|
||||
|
||||
5. **If this does not work** you can revert back to the default
|
||||
JupyterHub authenticator by following the steps in {ref}`howto/auth/firstuse`.
|
||||
@@ -1,119 +0,0 @@
|
||||
.. _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 <https://developers.google.com/identity/protocols/OAuth2>`_
|
||||
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 <https://console.developers.google.com>`_
|
||||
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)://<my-tljh-url>``.
|
||||
* **Authorized redirect URIs**: Insert text with the following form::
|
||||
|
||||
http(s)://<my-tljh-ip-address>/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 '<my-tljh-client-id>'
|
||||
|
||||
::
|
||||
|
||||
sudo tljh-config set auth.GoogleOAuthenticator.client_secret '<my-tljh-client-secret>'
|
||||
|
||||
::
|
||||
|
||||
sudo tljh-config set auth.GoogleOAuthenticator.oauth_callback_url 'http(s)://<my-tljh-ip-address>/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`.
|
||||
33
docs/howto/auth/nativeauth.md
Normal file
33
docs/howto/auth/nativeauth.md
Normal file
@@ -0,0 +1,33 @@
|
||||
(howto-auth-nativeauth)=
|
||||
|
||||
# Let users sign up with a username and password
|
||||
|
||||
The **Native Authenticator** lets users signup for creating a new username
|
||||
and password.
|
||||
When they signup, they won't be able to login until they are authorized by an
|
||||
admin. Users that are characterized as admin have to signup as well, but they
|
||||
will be authorized automatically.
|
||||
|
||||
## Enabling the authenticator
|
||||
|
||||
Enable the authenticator and reload config to apply the configuration:
|
||||
|
||||
```bash
|
||||
sudo tljh-config set auth.type nativeauthenticator.NativeAuthenticator
|
||||
sudo tljh-config reload
|
||||
```
|
||||
|
||||
## Allowing all users to be authorized after signup
|
||||
|
||||
By default, all users created on signup don't have authorization to login.
|
||||
If you wish to allow **any** user to access
|
||||
the JupyterHub just after the signup, run the following command:
|
||||
|
||||
```bash
|
||||
tljh-config set auth.NativeAuthenticator.open_signup true
|
||||
tljh-config reload
|
||||
```
|
||||
|
||||
## Optional features
|
||||
|
||||
More optional features are available on the `authenticator documentation <https://native-authenticator.readthedocs.io/en/latest/>`
|
||||
@@ -1,40 +0,0 @@
|
||||
.. _howto/auth/nativeauth:
|
||||
|
||||
==============================================
|
||||
Let users sign up with a username and password
|
||||
==============================================
|
||||
|
||||
The **Native Authenticator** lets users signup for creating a new username
|
||||
and password.
|
||||
When they signup, they won't be able to login until they are authorized by an
|
||||
admin. Users that are characterized as admin have to signup as well, but they
|
||||
will be authorized automatically.
|
||||
|
||||
|
||||
Enabling the authenticator
|
||||
==========================
|
||||
|
||||
Enable the authenticator and reload config to apply the configuration:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
sudo tljh-config set auth.type nativeauthenticator.NativeAuthenticator
|
||||
sudo tljh-config reload
|
||||
|
||||
|
||||
Allowing all users to be authorized after signup
|
||||
================================================
|
||||
|
||||
By default, all users created on signup don't have authorization to login.
|
||||
If you wish to allow **any** user to access
|
||||
the JupyterHub just after the signup, run the following command:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
tljh-config set auth.NativeAuthenticator.open_signup true
|
||||
tljh-config reload
|
||||
|
||||
Optional features
|
||||
=================
|
||||
|
||||
More optional features are available on the `authenticator documentation <https://native-authenticator.readthedocs.io/en/latest/>`
|
||||
Reference in New Issue
Block a user