Merge branch 'main' into krassowski-manage_roles

2025-10-18 07:23:00 +00:00 · 2024-04-15 10:58:46 +02:00
parent ce74fdf0a3 b06a0f29ed
commit 528c7faf92
39 changed files with 2207 additions and 319 deletions
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -70,6 +70,8 @@ myst_enable_extensions = [
 myst_substitutions = {
    # date example: Dev 07, 2022
    "date": datetime.date.today().strftime("%b %d, %Y").title(),
+    "node_min": "12",
+    "python_min": "3.8",
    "version": jupyterhub.__version__,
 }

@@ -289,6 +291,8 @@ linkcheck_ignore = [
    "https://github.com/jupyterhub/jupyterhub/compare/",  # too many comparisons in changelog
    r"https?://(localhost|127.0.0.1).*",  # ignore localhost references in auto-links
    r"https://linux.die.net/.*",  # linux.die.net seems to block requests from CI with 403 sometimes
+    # don't check links to unpublished advisories
+    r"https://github.com/jupyterhub/jupyterhub/security/advisories/.*",
 ]
 linkcheck_anchors_ignore = [
    "/#!",
--- a/docs/source/contributing/setup.md
+++ b/docs/source/contributing/setup.md
@@ -12,18 +12,18 @@ development.
 ### Install Python

 JupyterHub is written in the [Python](https://python.org) programming language and
-requires you have at least version 3.6 installed locally. If you haven’t
+requires you have at least version {{python_min}} installed locally. If you haven’t
 installed Python before, the recommended way to install it is to use
 [Miniforge](https://github.com/conda-forge/miniforge#download).

 ### Install nodejs

-[NodeJS 12+](https://nodejs.org/en/) is required for building some JavaScript components.
+[NodeJS {{node_min}}+](https://nodejs.org/en/) is required for building some JavaScript components.
 `configurable-http-proxy`, the default proxy implementation for JupyterHub, is written in Javascript.
 If you have not installed NodeJS before, we recommend installing it in the `miniconda` environment you set up for Python.
 You can do so with `conda install nodejs`.

-Many in the Jupyter community use \[`nvm`\](<https://github.com/nvm-sh/nvm>) to
+Many in the Jupyter community use [`nvm`](https://github.com/nvm-sh/nvm) to
 managing node dependencies.

 ### Install git
@@ -59,7 +59,7 @@ a more detailed discussion.
   python -V
   ```

-   This should return a version number greater than or equal to 3.6.
+   This should return a version number greater than or equal to {{python_min}}.

   ```bash
   npm -v
--- a/docs/source/explanation/websecurity.md
+++ b/docs/source/explanation/websecurity.md
@@ -16,7 +16,8 @@ works.

 JupyterHub is designed to be a _simple multi-user server for modestly sized
 groups_ of **semi-trusted** users. While the design reflects serving
-semi-trusted users, JupyterHub can also be suitable for serving **untrusted** users.
+semi-trusted users, JupyterHub can also be suitable for serving **untrusted** users,
+but **is not suitable for untrusted users** in its default configuration.

 As a result, using JupyterHub with **untrusted** users means more work by the
 administrator, since much care is required to secure a Hub, with extra caution on
@@ -56,30 +57,63 @@ ensure that:

 If any additional services are run on the same domain as the Hub, the services
 **must never** display user-authored HTML that is neither _sanitized_ nor _sandboxed_
-(e.g. IFramed) to any user that lacks authentication as the author of a file.
+to any user that lacks authentication as the author of a file.
+
+### Sharing access to servers
+
+Because sharing access to servers (via `access:servers` scopes or the sharing feature in JupyterHub 5) by definition means users can serve each other files, enabling sharing is not suitable for untrusted users without also enabling per-user domains.
+
+JupyterHub does not enable any sharing by default.

 ## Mitigate security issues

 The several approaches to mitigating security issues with configuration
 options provided by JupyterHub include:

-### Enable subdomains
+### Enable user subdomains

 JupyterHub provides the ability to run single-user servers on their own
-subdomains. This means the cross-origin protections between servers has the
-desired effect, and user servers and the Hub are protected from each other. A
-user's single-user server will be at `username.jupyter.mydomain.com`. This also
-requires all user subdomains to point to the same address, which is most easily
-accomplished with wildcard DNS. Since this spreads the service across multiple
-domains, you will need wildcard SSL as well. Unfortunately, for many
-institutional domains, wildcard DNS and SSL are not available. **If you do plan
-to serve untrusted users, enabling subdomains is highly encouraged**, as it
-resolves the cross-site issues.
+domains. This means the cross-origin protections between servers has the
+desired effect, and user servers and the Hub are protected from each other.
+
+**Subdomains are the only way to reliably isolate user servers from each other.**
+
+To enable subdomains, set:
+
+```python
+c.JupyterHub.subdomain_host = "https://jupyter.example.org"
+```
+
+When subdomains are enabled, each user's single-user server will be at e.g. `https://username.jupyter.example.org`.
+This also requires all user subdomains to point to the same address,
+which is most easily accomplished with wildcard DNS, where a single A record points to your server and a wildcard CNAME record points to your A record:
+
+```
+A        jupyter.example.org  192.168.1.123
+CNAME  *.jupyter.example.org  jupyter.example.org
+```
+
+Since this spreads the service across multiple domains, you will likely need wildcard SSL as well,
+matching `*.jupyter.example.org`.
+
+Unfortunately, for many institutional domains, wildcard DNS and SSL may not be available.
+
+We also **strongly encourage** serving JupyterHub and user content on a domain that is _not_ a subdomain of any sensitive content.
+For reasoning, see [GitHub's discussion of moving user content to github.io from \*.github.com](https://github.blog/2013-04-09-yummy-cookies-across-domains/).
+
+**If you do plan to serve untrusted users, enabling subdomains is highly encouraged**,
+as it resolves many security issues, which are difficult to unavoidable when JupyterHub is on a single-domain.
+
+:::{important}
+JupyterHub makes no guarantees about protecting users from each other unless subdomains are enabled.
+
+If you want to protect users from each other, you **_must_** enable per-user domains.
+:::

 ### Disable user config

 If subdomains are unavailable or undesirable, JupyterHub provides a
-configuration option `Spawner.disable_user_config`, which can be set to prevent
+configuration option `Spawner.disable_user_config = True`, which can be set to prevent
 the user-owned configuration files from being loaded. After implementing this
 option, `PATH`s and package installation are the other things that the
 admin must enforce.
@@ -89,23 +123,24 @@ admin must enforce.
 For most Spawners, `PATH` is not something users can influence, but it's important that
 the Spawner should _not_ evaluate shell configuration files prior to launching the server.

-### Isolate packages using virtualenv
+### Isolate packages in a read-only environment

-Package isolation is most easily handled by running the single-user server in
-a virtualenv with disabled system-site-packages. The user should not have
-permission to install packages into this environment.
+The user must not have permission to install packages into the environment where the singleuser-server runs.
+On a shared system, package isolation is most easily handled by running the single-user server in
+a root-owned virtualenv with disabled system-site-packages.
+The user must not have permission to install packages into this environment.
 The same principle extends to the images used by container-based deployments.
-If users can select the images in which their servers run, they can disable all security.
+If users can select the images in which their servers run, they can disable all security for their own servers.

-It is important to note that the control over the environment only affects the
-single-user server, and not the environment(s) in which the user's kernel(s)
+It is important to note that the control over the environment is only required for the
+single-user server, and not the environment(s) in which the users' kernel(s)
 may run. Installing additional packages in the kernel environment does not
 pose additional risk to the web application's security.

 ### Encrypt internal connections with SSL/TLS

-By default, all communications on the server, between the proxy, hub, and single
-user notebooks are performed unencrypted. Setting the `internal_ssl` flag in
+By default, all communications within JupyterHub—between the proxy, hub, and single
+-user notebooks—are performed unencrypted. Setting the `internal_ssl` flag in
 `jupyterhub_config.py` secures the aforementioned routes. Turning this
 feature on does require that the enabled `Spawner` can use the certificates
 generated by the `Hub` (the default `LocalProcessSpawner` can, for instance).
@@ -119,6 +154,104 @@ Unix permissions to the communication sockets thereby restricting
 communication to the socket owner. The `internal_ssl` option will eventually
 extend to securing the `tcp` sockets as well.

+### Mitigating same-origin deployments
+
+While per-user domains are **required** for robust protection of users from each other,
+you can mitigate many (but not all) cross-user issues.
+First, it is critical that users cannot modify their server environments, as described above.
+Second, it is important that users do not have `access:servers` permission to any server other than their own.
+
+If users can access each others' servers, additional security measures must be enabled, some of which come with distinct user-experience costs.
+
+Without the [Same-Origin Policy] (SOP) protecting user servers from each other,
+each user server is considered a trusted origin for requests to each other user server (and the Hub itself).
+Servers _cannot_ meaningfully distinguish requests originating from other user servers,
+because SOP implies a great deal of trust, losing many restrictions applied to cross-origin requests.
+
+That means pages served from each user server can:
+
+1. arbitrarily modify the path in the Referer
+2. make fully authorized requests with cookies
+3. access full page contents served from the hub or other servers via popups
+
+JupyterHub uses distinct xsrf tokens stored in cookies on each server path to attempt to limit requests across.
+This has limitations because not all requests are protected by these XSRF tokens,
+and unless additional measures are taken, the XSRF tokens from other user prefixes may be retrieved.
+
+[Same-Origin Policy]: https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy
+
+For example:
+
+- `Content-Security-Policy` header must prohibit popups and iframes from the same origin.
+  The following Content-Security-Policy rules are _insecure_ and readily enable users to access each others' servers:
+
+  - `frame-ancestors: 'self'`
+  - `frame-ancestors: '*'`
+  - `sandbox allow-popups`
+
+- Ideally, pages should use the strictest `Content-Security-Policy: sandbox` available,
+  but this is not feasible in general for JupyterLab pages, which need at least `sandbox allow-same-origin allow-scripts` to work.
+
+The default Content-Security-Policy for single-user servers is
+
+```
+frame-ancestors: 'none'
+```
+
+which prohibits iframe embedding, but not pop-ups.
+
+A more secure Content-Security-Policy that has some costs to user experience is:
+
+```
+frame-ancestors: 'none'; sandbox allow-same-origin allow-scripts
+```
+
+`allow-popups` is not disabled by default because disabling it breaks legitimate functionality, like "Open this in a new tab", and the "JupyterHub Control Panel" menu item.
+To reiterate, the right way to avoid these issues is to enable per-user domains, where none of these concerns come up.
+
+Note: even this level of protection requires administrators maintaining full control over the user server environment.
+If users can modify their server environment, these methods are ineffective, as users can readily disable them.
+
+### Cookie tossing
+
+Cookie tossing is a technique where another server on a subdomain or peer subdomain can set a cookie
+which will be read on another domain.
+This is not relevant unless there are other user-controlled servers on a peer domain.
+
+"Domain-locked" cookies avoid this issue, but have their own restrictions:
+
+- JupyterHub must be served over HTTPS
+- All secure cookies must be set on `/`, not on sub-paths, which means they are shared by all JupyterHub components in a single-domain deployment.
+
+As a result, this option is only recommended when per-user subdomains are enabled,
+to prevent sending all jupyterhub cookies to all user servers.
+
+To enable domain-locked cookies, set:
+
+```python
+c.JupyterHub.cookie_host_prefix_enabled = True
+```
+
+```{versionadded} 4.1
+
+```
+
+### Forced-login
+
+Jupyter servers can share links with `?token=...`.
+JupyterHub prior to 5.0 will accept this request and persist the token for future requests.
+This is useful for enabling admins to create 'fully authenticated' links bypassing login.
+However, it also means users can share their own links that will log other users into their own servers,
+enabling them to serve each other notebooks and other arbitrary HTML, depending on server configuration.
+
+```{versionadded} 4.1
+Setting environment variable `JUPYTERHUB_ALLOW_TOKEN_IN_URL=0` in the single-user environment can opt out of accepting token auth in URL parameters.
+```
+
+```{versionadded} 5.0
+Accepting tokens in URLs is disabled by default, and `JUPYTERHUB_ALLOW_TOKEN_IN_URL=1` environment variable must be set to _allow_ token auth in URL parameters.
+```
+
 ## Security audits

 We recommend that you do periodic reviews of your deployment's security. It's
--- a/docs/source/reference/authenticators.md
+++ b/docs/source/reference/authenticators.md
@@ -37,14 +37,19 @@ A [generic implementation](https://github.com/jupyterhub/oauthenticator/blob/mas
 ## The Dummy Authenticator

 When testing, it may be helpful to use the
-{class}`jupyterhub.auth.DummyAuthenticator`. This allows for any username and
-password unless if a global password has been set. Once set, any username will
+{class}`~.jupyterhub.auth.DummyAuthenticator`. This allows for any username and
+password unless a global password has been set. Once set, any username will
 still be accepted but the correct password will need to be provided.

+:::{versionadded} 5.0
+The DummyAuthenticator's default `allow_all` is True,
+unlike most other Authenticators.
+:::
+
 ## Additional Authenticators

-A partial list of other authenticators is available on the
-[JupyterHub wiki](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators).
+Additional authenticators can be found on GitHub
+by searching for [topic:jupyterhub topic:authenticator](https://github.com/search?q=topic%3Ajupyterhub%20topic%3Aauthenticator&type=repositories).

 ## Technical Overview of Authentication

@@ -54,9 +59,9 @@ The base authenticator uses simple username and password authentication.

 The base Authenticator has one central method:

-#### Authenticator.authenticate method
+#### Authenticator.authenticate

-    Authenticator.authenticate(handler, data)
+{meth}`.Authenticator.authenticate`

 This method is passed the Tornado `RequestHandler` and the `POST data`
 from JupyterHub's login form. Unless the login form has been customized,
@@ -81,7 +86,8 @@ Writing an Authenticator that looks up passwords in a dictionary
 requires only overriding this one method:

 ```python
-from IPython.utils.traitlets import Dict
+from secrets import compare_digest
+from traitlets import Dict
 from jupyterhub.auth import Authenticator

 class DictionaryAuthenticator(Authenticator):
@@ -91,8 +97,14 @@ class DictionaryAuthenticator(Authenticator):
    )

    async def authenticate(self, handler, data):
-        if self.passwords.get(data['username']) == data['password']:
-            return data['username']
+        username = data["username"]
+        password = data["password"]
+        check_password = self.passwords.get(username, "")
+        # always call compare_digest, for timing attacks
+        if compare_digest(check_password, password) and username in self.passwords:
+            return username
+        else:
+            return None
 ```

 #### Normalize usernames
@@ -136,7 +148,7 @@ To only allow usernames that start with 'w':
 c.Authenticator.username_pattern = r'w.*'
 ```

-### How to write a custom authenticator
+## How to write a custom authenticator

 You can use custom Authenticator subclasses to enable authentication
 via other mechanisms. One such example is using [GitHub OAuth][].
@@ -148,11 +160,6 @@ and {meth}`.Authenticator.post_spawn_stop`, are hooks that can be used to do
 auth-related startup (e.g. opening PAM sessions) and cleanup
 (e.g. closing PAM sessions).

-See a list of custom Authenticators [on the wiki](https://github.com/jupyterhub/jupyterhub/wiki/Authenticators).
-
-If you are interested in writing a custom authenticator, you can read
-[this tutorial](http://jupyterhub-tutorial.readthedocs.io/en/latest/authenticators.html).
-
 ### Registering custom Authenticators via entry points

 As of JupyterHub 1.0, custom authenticators can register themselves via
@@ -188,6 +195,166 @@ Additionally, configurable attributes for your authenticator will
 appear in jupyterhub help output and auto-generated configuration files
 via `jupyterhub --generate-config`.

+(authenticator-allow)=
+
+### Allowing access
+
+When dealing with logging in, there are generally two _separate_ steps:
+
+authentication
+: identifying who is trying to log in, and
+
+authorization
+: deciding whether an authenticated user is allowed to access your JupyterHub
+
+{meth}`Authenticator.authenticate` is responsible for authenticating users.
+It is perfectly fine in the simplest cases for `Authenticator.authenticate` to be responsible for authentication _and_ authorization,
+in which case `authenticate` may return `None` if the user is not authorized.
+
+However, Authenticators also have two methods, {meth}`~.Authenticator.check_allowed` and {meth}`~.Authenticator.check_blocked_users`, which are called after successful authentication to further check if the user is allowed.
+
+If `check_blocked_users()` returns False, authorization stops and the user is not allowed.
+
+If `Authenticator.allow_all` is True OR `check_allowed()` returns True, authorization proceeds.
+
+:::{versionadded} 5.0
+{attr}`.Authenticator.allow_all` and {attr}`.Authenticator.allow_existing_users` are new in JupyterHub 5.0.
+
+By default, `allow_all` is False,
+which is a change from pre-5.0, where `allow_all` was implicitly True if `allowed_users` was empty.
+:::
+
+### Overriding `check_allowed`
+
+:::{versionchanged} 5.0
+`check_allowed()` is **not called** if `allow_all` is True.
+:::
+
+:::{versionchanged} 5.0
+Starting with 5.0, `check_allowed()` should **NOT** return True if no allow config
+is specified (`allow_all` should be used instead).
+
+:::
+
+The base implementation of {meth}`~.Authenticator.check_allowed` checks:
+
+- if username is in the `allowed_users` set, return True
+- else return False
+
+:::{versionchanged} 5.0
+Prior to 5.0, this would also return True if `allowed_users` was empty.
+
+For clarity, this is no longer the case. A new `allow_all` property (default False) has been added which is checked _before_ calling `check_allowed`.
+If `allow_all` is True, this takes priority over `check_allowed`, which will be ignored.
+
+If your Authenticator subclass similarly returns True when no allow config is defined,
+this is fully backward compatible for your users, but means `allow_all = False` has no real effect.
+
+You can make your Authenticator forward-compatible with JupyterHub 5 by defining `allow_all` as a boolean config trait on your class:
+
+```python
+class MyAuthenticator(Authenticator):
+
+    # backport allow_all from JupyterHub 5
+    allow_all = Bool(False, config=True)
+
+    def check_allowed(self, username, authentication):
+        if self.allow_all:
+            # replaces previous "if no auth config"
+            return True
+        ...
+```
+
+:::
+
+If an Authenticator defines additional sources of `allow` configuration,
+such as membership in a group or other information,
+it should override `check_allowed` to account for this.
+
+:::{note}
+`allow_` configuration should generally be _additive_,
+i.e. if access is granted by _any_ allow configuration,
+a user should be authorized.
+
+JupyterHub recommends that Authenticators applying _restrictive_ configuration should use names like `block_` or `require_`,
+and check this during `check_blocked_users` or `authenticate`, not `check_allowed`.
+:::
+
+In general, an Authenticator's skeleton should look like:
+
+```python
+class MyAuthenticator(Authenticator):
+    # backport allow_all for compatibility with JupyterHub < 5
+    allow_all = Bool(False, config=True)
+    require_something = List(config=True)
+    allowed_something = Set()
+
+    def authenticate(self, data, handler):
+        ...
+        if success:
+            return {"username": username, "auth_state": {...}}
+        else:
+            return None
+
+    def check_blocked_users(self, username, authentication=None):
+        """Apply _restrictive_ configuration"""
+
+        if self.require_something and not has_something(username, self.request_):
+            return False
+        # repeat for each restriction
+        if restriction_defined and restriction_not_met:
+            return False
+        return super().check_blocked_users(self, username, authentication)
+
+    def check_allowed(self, username, authentication=None):
+        """Apply _permissive_ configuration
+
+        Only called if check_blocked_users returns True
+        AND allow_all is False
+        """
+        if self.allow_all:
+            # check here to backport allow_all behavior
+            # from JupyterHub 5
+            # this branch will never be taken with jupyterhub >=5
+            return True
+        if self.allowed_something and user_has_something(username):
+            return True
+        # repeat for each allow
+        if allow_config and allow_met:
+            return True
+        # should always have this at the end
+        if self.allowed_users and username in self.allowed_users:
+            return True
+        # do not call super!
+        # super().check_allowed is not safe with JupyterHub < 5.0,
+        # as it will return True if allowed_users is empty
+        return False
+```
+
+Key points:
+
+- `allow_all` is backported from JupyterHub 5, for consistent behavior in all versions of JupyterHub (optional)
+- restrictive configuration is checked in `check_blocked_users`
+- if any restriction is not met, `check_blocked_users` returns False
+- permissive configuration is checked in `check_allowed`
+- if any `allow` condition is met, `check_allowed` returns True
+
+So the logical expression for a user being authorized should look like:
+
+> if ALL restrictions are met AND ANY admissions are met: user is authorized
+
+#### Custom error messages
+
+Any of these authentication and authorization methods may raise a `web.HTTPError` Exception
+
+```python
+from tornado import web
+
+raise web.HTTPError(403, "informative message")
+```
+
+if you want to show a more informative login failure message rather than the generic one.
+
 (authenticator-auth-state)=

 ### Authentication state
--- a/docs/source/reference/changelog.md
+++ b/docs/source/reference/changelog.md
@@ -6,8 +6,161 @@ For detailed changes from the prior release, click on the version number, and
 its link will bring up a GitHub listing of changes. Use `git log` on the
 command line for details.

+## Versioning
+
+JupyterHub follows Intended Effort Versioning ([EffVer](https://jacobtomlinson.dev/effver/)) for versioning,
+where the version number is meant to indicate the amount of effort required to upgrade to the new version.
+
+Contributors to major version bumps in JupyterHub include:
+
+- Database schema changes that require migrations and are hard to roll back
+- Increasing the minimum required Python version
+- Large new features
+- Breaking changes likely to affect users
+
 ## [Unreleased]

+## 4.1
+
+### 4.1.5 - 2024-04-04
+
+([full changelog](https://github.com/jupyterhub/jupyterhub/compare/4.1.4...4.1.5))
+
+#### Bugs fixed
+
+- singleuser mixin: include check_xsrf_cookie in overrides [#4771](https://github.com/jupyterhub/jupyterhub/pull/4771) ([@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio))
+
+#### Contributors to this release
+
+The following people contributed discussions, new ideas, code and documentation contributions, and review.
+See [our definition of contributors](https://github-activity.readthedocs.io/en/latest/#how-does-this-tool-define-contributions-in-the-reports).
+
+([GitHub contributors page for this release](https://github.com/jupyterhub/jupyterhub/graphs/contributors?from=2024-03-30&to=2024-04-04&type=c))
+
+@consideRatio ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3AconsideRatio+updated%3A2024-03-30..2024-04-04&type=Issues)) | @manics ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Amanics+updated%3A2024-03-30..2024-04-04&type=Issues)) | @minrk ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aminrk+updated%3A2024-03-30..2024-04-04&type=Issues))
+
+### 4.1.4 - 2024-03-30
+
+([full changelog](https://github.com/jupyterhub/jupyterhub/compare/4.1.3...4.1.4))
+
+#### Bugs fixed
+
+- avoid xsrf check on navigate GET requests [#4759](https://github.com/jupyterhub/jupyterhub/pull/4759) ([@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio))
+
+#### Contributors to this release
+
+The following people contributed discussions, new ideas, code and documentation contributions, and review.
+See [our definition of contributors](https://github-activity.readthedocs.io/en/latest/#how-does-this-tool-define-contributions-in-the-reports).
+
+([GitHub contributors page for this release](https://github.com/jupyterhub/jupyterhub/graphs/contributors?from=2024-03-26&to=2024-03-30&type=c))
+
+@consideRatio ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3AconsideRatio+updated%3A2024-03-26..2024-03-30&type=Issues)) | @minrk ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aminrk+updated%3A2024-03-26..2024-03-30&type=Issues))
+
+### 4.1.3 - 2024-03-26
+
+([full changelog](https://github.com/jupyterhub/jupyterhub/compare/4.1.2...4.1.3))
+
+#### Bugs fixed
+
+- respect jupyter-server disable_check_xsrf setting [#4753](https://github.com/jupyterhub/jupyterhub/pull/4753) ([@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio))
+
+#### Contributors to this release
+
+The following people contributed discussions, new ideas, code and documentation contributions, and review.
+See [our definition of contributors](https://github-activity.readthedocs.io/en/latest/#how-does-this-tool-define-contributions-in-the-reports).
+
+([GitHub contributors page for this release](https://github.com/jupyterhub/jupyterhub/graphs/contributors?from=2024-03-25&to=2024-03-26&type=c))
+
+@consideRatio ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3AconsideRatio+updated%3A2024-03-25..2024-03-26&type=Issues)) | @minrk ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aminrk+updated%3A2024-03-25..2024-03-26&type=Issues))
+
+### 4.1.2 - 2024-03-25
+
+4.1.2 fixes a regression in 4.1.0 affecting named servers.
+
+([full changelog](https://github.com/jupyterhub/jupyterhub/compare/4.1.1...4.1.2))
+
+#### Bugs fixed
+
+- rework handling of multiple xsrf tokens [#4750](https://github.com/jupyterhub/jupyterhub/pull/4750) ([@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio))
+
+#### Contributors to this release
+
+The following people contributed discussions, new ideas, code and documentation contributions, and review.
+See [our definition of contributors](https://github-activity.readthedocs.io/en/latest/#how-does-this-tool-define-contributions-in-the-reports).
+
+([GitHub contributors page for this release](https://github.com/jupyterhub/jupyterhub/graphs/contributors?from=2024-03-23&to=2024-03-25&type=c))
+
+@consideRatio ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3AconsideRatio+updated%3A2024-03-23..2024-03-25&type=Issues)) | @minrk ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aminrk+updated%3A2024-03-23..2024-03-25&type=Issues))
+
+### 4.1.1 - 2024-03-23
+
+4.1.1 fixes a compatibility regression in 4.1.0 for some extensions,
+particularly jupyter-server-proxy.
+
+([full changelog](https://github.com/jupyterhub/jupyterhub/compare/4.1.0...4.1.1))
+
+#### Bugs fixed
+
+- allow subclasses to override xsrf check [#4745](https://github.com/jupyterhub/jupyterhub/pull/4745) ([@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio))
+
+#### Contributors to this release
+
+The following people contributed discussions, new ideas, code and documentation contributions, and review.
+See [our definition of contributors](https://github-activity.readthedocs.io/en/latest/#how-does-this-tool-define-contributions-in-the-reports).
+
+([GitHub contributors page for this release](https://github.com/jupyterhub/jupyterhub/graphs/contributors?from=2024-03-20&to=2024-03-23&type=c))
+
+@consideRatio ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3AconsideRatio+updated%3A2024-03-20..2024-03-23&type=Issues)) | @minrk ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aminrk+updated%3A2024-03-20..2024-03-23&type=Issues))
+
+### 4.1.0 - 2024-03-20
+
+JupyterHub 4.1 is a security release, fixing [CVE-2024-28233].
+All JupyterHub deployments are encouraged to upgrade,
+especially those with other user content on peer domains to JupyterHub.
+
+As always, JupyterHub deployments are especially encouraged to enable per-user domains if protecting users from each other is a concern.
+
+For more information on securely deploying JupyterHub, see the [web security documentation](web-security).
+
+[CVE-2024-28233]: https://github.com/jupyterhub/jupyterhub/security/advisories/GHSA-7r3h-4ph8-w38g
+
+([full changelog](https://github.com/jupyterhub/jupyterhub/compare/4.0.2...4.1.0))
+
+#### Enhancements made
+
+- Backport PR #4628 on branch 4.x (Include LDAP groups in local spawner gids) [#4735](https://github.com/jupyterhub/jupyterhub/pull/4735) ([@minrk](https://github.com/minrk))
+- Backport PR #4561 on branch 4.x (Improve debugging when waiting for servers) [#4714](https://github.com/jupyterhub/jupyterhub/pull/4714) ([@minrk](https://github.com/minrk))
+- Backport PR #4563 on branch 4.x (only set 'domain' field on session-id cookie) [#4707](https://github.com/jupyterhub/jupyterhub/pull/4707) ([@minrk](https://github.com/minrk))
+
+#### Bugs fixed
+
+- Backport PR #4733 on branch 4.x (Catch ValueError while waiting for server to be reachable) [#4734](https://github.com/jupyterhub/jupyterhub/pull/4734) ([@minrk](https://github.com/minrk))
+- Backport PR #4679 on branch 4.x (Unescape jinja username) [#4705](https://github.com/jupyterhub/jupyterhub/pull/4705) ([@minrk](https://github.com/minrk))
+- Backport PR #4630: avoid setting unused oauth state cookies on API requests [#4697](https://github.com/jupyterhub/jupyterhub/pull/4697) ([@minrk](https://github.com/minrk))
+- Backport PR #4632: simplify, avoid errors in parsing accept headers [#4696](https://github.com/jupyterhub/jupyterhub/pull/4696) ([@minrk](https://github.com/minrk))
+- Backport PR #4677 on branch 4.x (Improve validation, docs for token.expires_in) [#4692](https://github.com/jupyterhub/jupyterhub/pull/4692) ([@minrk](https://github.com/minrk))
+- Backport PR #4570 on branch 4.x (fix mutation of frozenset in scope intersection) [#4691](https://github.com/jupyterhub/jupyterhub/pull/4691) ([@minrk](https://github.com/minrk))
+- Backport PR #4562 on branch 4.x (Use `user.stop` to cleanup spawners that stopped while Hub was down) [#4690](https://github.com/jupyterhub/jupyterhub/pull/4690) ([@minrk](https://github.com/minrk))
+- Backport PR #4542 on branch 4.x (Fix include_stopped_servers in paginated next_url) [#4689](https://github.com/jupyterhub/jupyterhub/pull/4689) ([@minrk](https://github.com/minrk))
+- Backport PR #4651 on branch 4.x (avoid attempting to patch removed IPythonHandler with notebook v7) [#4688](https://github.com/jupyterhub/jupyterhub/pull/4688) ([@minrk](https://github.com/minrk))
+- Backport PR #4560 on branch 4.x (singleuser extension: persist token from ?token=... url in cookie) [#4687](https://github.com/jupyterhub/jupyterhub/pull/4687) ([@minrk](https://github.com/minrk))
+
+#### Maintenance and upkeep improvements
+
+- Backport quay.io publishing [#4698](https://github.com/jupyterhub/jupyterhub/pull/4698) ([@minrk](https://github.com/minrk))
+- Backport PR #4617: try to improve reliability of test_external_proxy [#4695](https://github.com/jupyterhub/jupyterhub/pull/4695) ([@minrk](https://github.com/minrk))
+- Backport PR #4618 on branch 4.x (browser test: wait for token request to finish before reloading) [#4694](https://github.com/jupyterhub/jupyterhub/pull/4694) ([@minrk](https://github.com/minrk))
+- preparing 4.x branch [#4685](https://github.com/jupyterhub/jupyterhub/pull/4685) ([@minrk](https://github.com/minrk), [@consideRatio](https://github.com/consideRatio))
+
+#### Contributors to this release
+
+The following people contributed discussions, new ideas, code and documentation contributions, and review.
+See [our definition of contributors](https://github-activity.readthedocs.io/en/latest/#how-does-this-tool-define-contributions-in-the-reports).
+
+([GitHub contributors page for this release](https://github.com/jupyterhub/jupyterhub/graphs/contributors?from=2023-08-10&to=2024-03-19&type=c))
+
+@Achele ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3AAchele+updated%3A2023-08-10..2024-03-19&type=Issues)) | @akashthedeveloper ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aakashthedeveloper+updated%3A2023-08-10..2024-03-19&type=Issues)) | @balajialg ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Abalajialg+updated%3A2023-08-10..2024-03-19&type=Issues)) | @BhavyaT-135 ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3ABhavyaT-135+updated%3A2023-08-10..2024-03-19&type=Issues)) | @blink1073 ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Ablink1073+updated%3A2023-08-10..2024-03-19&type=Issues)) | @consideRatio ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3AconsideRatio+updated%3A2023-08-10..2024-03-19&type=Issues)) | @fcollonval ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Afcollonval+updated%3A2023-08-10..2024-03-19&type=Issues)) | @I-Am-D-B ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3AI-Am-D-B+updated%3A2023-08-10..2024-03-19&type=Issues)) | @jakirkham ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Ajakirkham+updated%3A2023-08-10..2024-03-19&type=Issues)) | @ktaletsk ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aktaletsk+updated%3A2023-08-10..2024-03-19&type=Issues)) | @kzgrzendek ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Akzgrzendek+updated%3A2023-08-10..2024-03-19&type=Issues)) | @lumberbot-app ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Alumberbot-app+updated%3A2023-08-10..2024-03-19&type=Issues)) | @manics ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Amanics+updated%3A2023-08-10..2024-03-19&type=Issues)) | @mbiette ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Ambiette+updated%3A2023-08-10..2024-03-19&type=Issues)) | @minrk ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aminrk+updated%3A2023-08-10..2024-03-19&type=Issues)) | @rcthomas ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Arcthomas+updated%3A2023-08-10..2024-03-19&type=Issues)) | @ryanlovett ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Aryanlovett+updated%3A2023-08-10..2024-03-19&type=Issues)) | @sgaist ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Asgaist+updated%3A2023-08-10..2024-03-19&type=Issues)) | @shubham0473 ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Ashubham0473+updated%3A2023-08-10..2024-03-19&type=Issues)) | @Temidayo32 ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3ATemidayo32+updated%3A2023-08-10..2024-03-19&type=Issues)) | @willingc ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Awillingc+updated%3A2023-08-10..2024-03-19&type=Issues)) | @yuvipanda ([activity](https://github.com/search?q=repo%3Ajupyterhub%2Fjupyterhub+involves%3Ayuvipanda+updated%3A2023-08-10..2024-03-19&type=Issues))
+
 ## 4.0

 ### 4.0.2 - 2023-08-10
--- a/docs/source/tutorial/getting-started/authenticators-users-basics.md
+++ b/docs/source/tutorial/getting-started/authenticators-users-basics.md
@@ -6,21 +6,58 @@ The default Authenticator uses [PAM][] (Pluggable Authentication Module) to auth
 their usernames and passwords. With the default Authenticator, any user
 with an account and password on the system will be allowed to login.

-## Create a set of allowed users (`allowed_users`)
+## Deciding who is allowed
+
+In the base Authenticator, there are 3 configuration options for granting users access to your Hub:
+
+1. `allow_all` grants any user who can successfully authenticate access to the Hub
+2. `allowed_users` defines a set of users who can access the Hub
+3. `allow_existing_users` enables managing users via the JupyterHub API or admin page
+
+These options should apply to all Authenticators.
+Your chosen Authenticator may add additional configuration options to admit users, such as team membership, course enrollment, etc.
+
+:::{important}
+You should always specify at least one allow configuration if you want people to be able to access your Hub!
+In most cases, this looks like:
+
+```python
+c.Authenticator.allow_all = True
+# or
+c.Authenticator.allowed_users = {"name", ...}
+```
+
+:::
+
+:::{versionchanged} 5.0
+If no allow config is specified, then by default **nobody will have access to your Hub**.
+Prior to 5.0, the opposite was true; effectively `allow_all = True` if no other allow config was specified.
+:::

 You can restrict which users are allowed to login with a set,
 `Authenticator.allowed_users`:

 ```python
 c.Authenticator.allowed_users = {'mal', 'zoe', 'inara', 'kaylee'}
+# c.Authenticator.allow_all = False
+c.Authenticator.allow_existing_users = False
 ```

-Users in the `allowed_users` set are added to the Hub database when the Hub is
-started.
+Users in the `allowed_users` set are added to the Hub database when the Hub is started.

-```{warning}
-If this configuration value is not set, then **all authenticated users will be allowed into your hub**.
-```
+:::{versionchanged} 5.0
+{attr}`.Authenticator.allow_all` and {attr}`.Authenticator.allow_existing_users` are new in JupyterHub 5.0
+to enable explicit configuration of previously implicit behavior.
+
+Prior to 5.0, `allow_all` was implicitly True if `allowed_users` was empty.
+Starting with 5.0, to allow all authenticated users by default,
+`allow_all` must be explicitly set to True.
+
+By default, `allow_existing_users` is True when `allowed_users` is not empty,
+to ensure backward-compatibility.
+To make the `allowed_users` set _restrictive_,
+set `allow_existing_users = False`.
+:::

 ## One Time Passwords ( request_otp )

@@ -42,7 +79,7 @@ c.Authenticator.otp_prompt = 'Google Authenticator:'
 ```{note}
 As of JupyterHub 2.0, the full permissions of `admin_users`
 should not be required.
-Instead, you can assign [roles](define-role-target) to users or groups
+Instead, it is best to assign [roles](define-role-target) to users or groups
 with only the scopes they require.
 ```

@@ -68,26 +105,55 @@ group. For example, we can let any user in the `wheel` group be an admin:
 c.PAMAuthenticator.admin_groups = {'wheel'}
 ```

-## Give admin access to other users' notebook servers (`admin_access`)
+## Give some users access to other users' notebook servers

-Since the default `JupyterHub.admin_access` setting is `False`, the admins
-do not have permission to log in to the single user notebook servers
-owned by _other users_. If `JupyterHub.admin_access` is set to `True`,
-then admins have permission to log in _as other users_ on their
-respective machines for debugging. **As a courtesy, you should make
-sure your users know if admin_access is enabled.**
+The `access:servers` scope can be granted to users to give them permission to visit other users' servers.
+For example, to give members of the `teachers` group access to the servers of members of the `students` group:
+
+```python
+c.JupyterHub.load_roles = [
+  {
+    "name": "teachers",
+    "scopes": [
+      "admin-ui",
+      "list:users",
+      "access:servers!group=students",
+    ],
+    "groups": ["teachers"],
+  }
+]
+```
+
+By default, only the deprecated `admin` role has global `access` permissions.
+**As a courtesy, you should make sure your users know if admin access is enabled.**

 ## Add or remove users from the Hub

+:::{versionadded} 5.0
+`c.Authenticator.allow_existing_users` is added in 5.0 and True by default _if_ any `allowed_users` are specified.
+
+Prior to 5.0, this behavior was not optional.
+:::
+
 Users can be added to and removed from the Hub via the admin
-panel or the REST API. When a user is **added**, the user will be
-automatically added to the `allowed_users` set and database. Restarting the Hub
-will not require manually updating the `allowed_users` set in your config file,
+panel or the REST API.
+
+To enable this behavior, set:
+
+```python
+c.Authenticator.allow_existing_users = True
+```
+
+When a user is **added**, the user will be
+automatically added to the `allowed_users` set and database.
+If `allow_existing_users` is True, restarting the Hub will not require manually updating the `allowed_users` set in your config file,
 as the users will be loaded from the database.
+If `allow_existing_users` is False, users not granted access by configuration such as `allowed_users` will not be permitted to login,
+even if they are present in the database.

 After starting the Hub once, it is not sufficient to **remove** a user
 from the allowed users set in your config file. You must also remove the user
-from the Hub's database, either by deleting the user from JupyterHub's
+from the Hub's database, either by deleting the user via JupyterHub's
 admin page, or you can clear the `jupyterhub.sqlite` database and start
 fresh.

--- a/docs/source/tutorial/quickstart.md
+++ b/docs/source/tutorial/quickstart.md
@@ -5,11 +5,11 @@
 Before installing JupyterHub, you will need:

 - a Linux/Unix-based system
- [Python](https://www.python.org/downloads/) 3.6 or greater. An understanding
+- [Python {{python_min}}](https://www.python.org/downloads/) or greater. An understanding
  of using [`pip`](https://pip.pypa.io) or
  [`conda`](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html) for
  installing Python packages is helpful.
- [nodejs/npm](https://www.npmjs.com/). [Install nodejs/npm](https://docs.npmjs.com/getting-started/installing-node),
+- [Node.js {{node_min}}](https://www.npmjs.com/) or greater, along with npm. [Install Node.js/npm](https://docs.npmjs.com/getting-started/installing-node),
  using your operating system's package manager.

  - If you are using **`conda`**, the nodejs and npm dependencies will be installed for
@@ -24,7 +24,7 @@ Before installing JupyterHub, you will need:
    ```

    [nodesource][] is a great resource to get more recent versions of the nodejs runtime,
-    if your system package manager only has an old version of Node.js (e.g. 10 or older).
+    if your system package manager only has an old version of Node.js.

 - A [pluggable authentication module (PAM)](https://en.wikipedia.org/wiki/Pluggable_authentication_module)
  to use the [default Authenticator](authenticators).