From 8f0b3fd7578d7e337ae658c7dad985e6f055a0b1 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Mon, 3 Jul 2023 19:27:48 +0200 Subject: [PATCH 1/7] docs: relocate breaking change descriptions to changelog --- .../source/how-to/migrations/upgrade-to-16.md | 19 ------------------- docs/source/reference/changelog.md | 9 +++++++++ 2 files changed, 9 insertions(+), 19 deletions(-) diff --git a/docs/source/how-to/migrations/upgrade-to-16.md b/docs/source/how-to/migrations/upgrade-to-16.md index 4eded689..fd42139b 100644 --- a/docs/source/how-to/migrations/upgrade-to-16.md +++ b/docs/source/how-to/migrations/upgrade-to-16.md @@ -4,25 +4,6 @@ The following section describes what to pay attention to when upgrading to OAuthenticator 16.0. -## Breaking changes - -1. `username_key` replaced by `username_claim` in _all oauthenticators_ - - - {attr}`.GenericOAuthenticator.username_key` is deprecated and replaced by {attr}`.OAuthenticator.username_claim`. - - - {attr}`.Auth0OAuthenticator.username_key` is deprecated and replaced by {attr}`.OAuthenticator.username_claim`. - - ```{note} - The `username_claim` and the deprecated `username_key` refers to the field in the `userdata` response from which to get the JupyterHub username. Examples include: email, username, nickname. What keys are available depend on the scopes requested and the authenticator used. - ``` - -2. {attr}`.GenericOAuthenticator.extra_params` is deprecated and replaced by {attr}`.OAuthenticator.token_params`. - -3. The following public functions were removed: - - - `OkpyOAuthenticator.get_auth_request(self, code)` - - `OkpyOAuthenticator.get_user_info_request(self, access_token)` - ## New 1. The name of the user key expected to be present in `auth_state` is now configurable through {attr}`.OAuthenticator.user_auth_state_key` for _all oauthenticators_, and it defaults to their prior specific values. diff --git a/docs/source/reference/changelog.md b/docs/source/reference/changelog.md index 3801fbe4..547a7931 100644 --- a/docs/source/reference/changelog.md +++ b/docs/source/reference/changelog.md @@ -31,6 +31,15 @@ command line for details. - [CILogon] {attr}`.CILogonOAuthenticator.allowed_idps` is now required config, and `shown_idps`, `username_claim`, `additional_username_claims` must no longer be configured. +- [Okpy] The public functions `OkpyOAuthenticator.get_auth_request` and + `OkpyOAuthenticator.get_user_info_request` was removed. + +### Deprecations + +- [Generic, Auth0] `username_key` is deprecated and is being replaced by + {attr}`.OAuthenticator.username_claim`. +- [Generic] {attr}`.GenericOAuthenticator.extra_params` is deprecated and is + being replaced by {attr}`.OAuthenticator.token_params`. (changelog:version-15)= From ac90d2d9126e8a93fe32eb8fce9b80ded480fe15 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Mon, 3 Jul 2023 20:35:33 +0200 Subject: [PATCH 2/7] docs: update helpstrings for oauth urls etc --- oauthenticator/oauth2.py | 33 ++++++++++++++++++++++++++++----- 1 file changed, 28 insertions(+), 5 deletions(-) diff --git a/oauthenticator/oauth2.py b/oauthenticator/oauth2.py index 39a5b42d..faffecbf 100644 --- a/oauthenticator/oauth2.py +++ b/oauthenticator/oauth2.py @@ -302,7 +302,16 @@ class OAuthenticator(Authenticator): authorize_url = Unicode( config=True, help=""" - The authenticate url for initiating oauth + The URL to where the user is to be redirected initially based on the + OAuth2 protocol. The user is supposed to be redirected back with a + `authorization grant code`_ after interacting successfully with the + identity provider. + + .. _authorization grant code: https://www.rfc-editor.org/rfc/rfc6749#section-1.3.1 + + For more context, see the `Protocol Flow section + `_ in the OAuth2 + standard document, specifically steps A-B. """, ) @@ -313,7 +322,15 @@ def _authorize_url_default(self): token_url = Unicode( config=True, help=""" - The url retrieving an access token at the completion of oauth + The URL to where this authenticator makes a request to acquire an + `access token`_ based on the authorization code received by the user + returning from the :attr:`authorize_url`. + + .. _access token: https://www.rfc-editor.org/rfc/rfc6749#section-1.4 + + For more context, see the `Protocol Flow section + `_ in the OAuth2 + standard document, specifically steps C-D. """, ) @@ -324,7 +341,13 @@ def _token_url_default(self): userdata_url = Unicode( config=True, help=""" - The url for retrieving user data with a completed access token + The URL to where this authenticator makes a request to acquire user + details with an access token received via a request to the + :attr:`token_url`. + + For more context, see the `Protocol Flow section + `_ in the OAuth2 + standard document, specifically steps E-F. """, ) @@ -336,8 +359,8 @@ def _userdata_url_default(self): "username", config=True, help=""" - Field in userdata reply to use for username The field in the userdata - response from which to get the JupyterHub username. + The key to get the JupyterHub username from in the data response to the + request made to :attr:`userdata_url`. Examples include: email, username, nickname From f8559da2d78da89e9ec5a09bb36010a965ac3c1c Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Mon, 3 Jul 2023 20:52:40 +0200 Subject: [PATCH 3/7] docs: remove outdated note about now a constant would be configurable --- docs/source/how-to/migrations/upgrade-to-16.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/source/how-to/migrations/upgrade-to-16.md b/docs/source/how-to/migrations/upgrade-to-16.md index fd42139b..cb69c6ad 100644 --- a/docs/source/how-to/migrations/upgrade-to-16.md +++ b/docs/source/how-to/migrations/upgrade-to-16.md @@ -6,8 +6,6 @@ The following section describes what to pay attention to when upgrading to OAuth ## New -1. The name of the user key expected to be present in `auth_state` is now configurable through {attr}`.OAuthenticator.user_auth_state_key` for _all oauthenticators_, and it defaults to their prior specific values. - 2. The [`Authenticator.refresh_pre_spawn`](https://jupyterhub.readthedocs.io/en/stable/reference/api/auth.html#jupyterhub.auth.Authenticator.refresh_pre_spawn) option is enabled by default if {attr}`.OAuthenticator.enable_auth_state` is set. 3. The userdata query parameters {attr}`.OAuthenticator.userdata_params` to be added to the request sent to {attr}`.OAuthenticator.userdata_url` to get user data login information is now a configurable feature of _all the oauthenticators_. From e7645d530cbf09eecbbe5cba38cf4b2a3e64bd4d Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Mon, 3 Jul 2023 22:11:44 +0200 Subject: [PATCH 4/7] docs: coalesce v16 upgrade notes to changelog --- docs/source/conf.py | 1 + .../source/how-to/migrations/upgrade-to-16.md | 46 ------------------- docs/source/index.md | 3 +- docs/source/reference/changelog.md | 18 ++++++++ 4 files changed, 20 insertions(+), 48 deletions(-) delete mode 100644 docs/source/how-to/migrations/upgrade-to-16.md diff --git a/docs/source/conf.py b/docs/source/conf.py index 50e33daf..5cc7dff7 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -208,4 +208,5 @@ def setup(app): # 2023-06-29 docs refresh "topic/cilogon": "tutorials/provider-specific-setup/providers/cilogon", "tutorials/provider-specific-setup/providers/awscognito": "tutorials/provider-specific-setup/providers/generic", + "how-to/migrations/upgrade-to-16": "reference/changelog", } diff --git a/docs/source/how-to/migrations/upgrade-to-16.md b/docs/source/how-to/migrations/upgrade-to-16.md deleted file mode 100644 index cb69c6ad..00000000 --- a/docs/source/how-to/migrations/upgrade-to-16.md +++ /dev/null @@ -1,46 +0,0 @@ -(migrations:upgrade-to-16)= - -# Upgrading your OAuthenticator to version 16.0 - -The following section describes what to pay attention to when upgrading to OAuthenticator 16.0. - -## New - -2. The [`Authenticator.refresh_pre_spawn`](https://jupyterhub.readthedocs.io/en/stable/reference/api/auth.html#jupyterhub.auth.Authenticator.refresh_pre_spawn) option is enabled by default if {attr}`.OAuthenticator.enable_auth_state` is set. - -3. The userdata query parameters {attr}`.OAuthenticator.userdata_params` to be added to the request sent to {attr}`.OAuthenticator.userdata_url` to get user data login information is now a configurable feature of _all the oauthenticators_. - - ```{note} - Previously, a GenericOAuthenticator only trait. - ``` - -4. The method used for sending the `access token` in the userdata request[^userdata_request], called {attr}`.OAuthenticator.userdata_token_method`, is now a configurable feature of _all the oauthenticators_. - - ```{note} - Previously, a GenericOAuthenticator only trait. - ``` - -5. It is now possible to pass extra parameters to the token request[^token_request], using {attr}`.OAuthenticator.token_params` for _all of the oauthenticators_. - - ```{note} - Previously, a GenericOAuthenticator only trait. - ``` - -6. It is now possible to set whether or not to use basic authentication for the access token request[^token_request] using {attr}`.OAuthenticator.basic_auth` for _all of the oauthenticators_. - Currently it defaults to `False`. - - ```{note} - Previously, a GenericOAuthenticator only trait. - ``` - -[^token_request]: **The token request.** - - Whenever _token request_ is used, it refers to the HTTP request exchanging the [oauth code](https://www.rfc-editor.org/rfc/rfc6749#section-1.3.1) for the [access token](https://www.rfc-editor.org/rfc/rfc6749#section-1.4). - - This request is sent to the {attr}`.OAuthenticator.token_url` in {meth}`.OAuthenticator.get_token_info` method. - -[^userdata_request]: **The userdata request.** - - Whenever _userdata request_ is used, it refers to the HTTP request that's exchanging the the `access token` to get the `userdata`. - - This request is sent to {attr}`.OAuthenticator.userdata_url` in {meth}`.OAuthenticator.token_to_user` method. diff --git a/docs/source/index.md b/docs/source/index.md index aba21f8c..e3663520 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -34,10 +34,9 @@ Things like how to write your own `oauthenticator` or how to migrate to a newer :maxdepth: 1 :caption: How-to guides -how-to/migrations/upgrade-to-15 -how-to/migrations/upgrade-to-16 how-to/custom-403 how-to/writing-an-oauthenticator +how-to/migrations/upgrade-to-15 ``` ## Topic guides diff --git a/docs/source/reference/changelog.md b/docs/source/reference/changelog.md index 547a7931..653009bd 100644 --- a/docs/source/reference/changelog.md +++ b/docs/source/reference/changelog.md @@ -8,6 +8,7 @@ command line for details. ### Breaking changes +- Support for Python 3.7 has been dropped, Python 3.8+ is now required. - [All] Users are now authorized based on _either_ being part of {attr}`.OAuthenticator.admin_users`, {attr}`.OAuthenticator.allowed_users`, an Authenticator specific allowed group/team/organization, or if by being part of @@ -41,6 +42,23 @@ command line for details. - [Generic] {attr}`.GenericOAuthenticator.extra_params` is deprecated and is being replaced by {attr}`.OAuthenticator.token_params`. +### Highlights + +- [All] The project has been refactored greatly to make it easier to use, + understand, and maintain code and documentation. + +- [All] {attr}`.OAuthenticator.refresh_pre_spawn` is now by default enabled if + {attr}`.OAuthenticator.enable_auth_state` is enabled. + +- [All] Low level configurations in `GenericOAuthenticator` has been moved to + the common base class `OAuthenticator` and is therefore available to all + authenticators. + + - {attr}`.OAuthenticator.basic_auth` + - {attr}`.OAuthenticator.token_params` + - {attr}`.OAuthenticator.userdata_params` + - {attr}`.OAuthenticator.userdata_token_method` + (changelog:version-15)= ## 15.0 From b477adf059fac62ecc74463c5c225d405e085d37 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Tue, 4 Jul 2023 08:41:21 +0200 Subject: [PATCH 5/7] docs: update another helpstring --- oauthenticator/openshift.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/oauthenticator/openshift.py b/oauthenticator/openshift.py index 7b6ad34e..37f49dcc 100644 --- a/oauthenticator/openshift.py +++ b/oauthenticator/openshift.py @@ -86,6 +86,14 @@ def _ca_certs_default(self): help=""" Used to determine the default values for `authorize_url` and `token_url`. + + By default, this is determined on startup by a request to the + `openshift_url` appended with "/.well-known/oauth-authorization-server", + where "issuer" is extracted from the response. + + For more context, see the `Obtaining Authorization Server Metadata + section `_ in + an OAuth2 standard document. """, ) From 8c801d991ad77edbbbfdd0942f0c52383589a1e8 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Tue, 4 Jul 2023 10:41:52 +0200 Subject: [PATCH 6/7] docs: configure intersphinx and update another helpstring --- docs/source/conf.py | 25 ++++++++++++++++++++++++- oauthenticator/oauth2.py | 24 ++++++++++++++++-------- 2 files changed, 40 insertions(+), 9 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 5cc7dff7..130e2df0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -107,7 +107,7 @@ def setup(app): app.add_directive("versionremoved", VersionChange) -# -- General Sphinx configuration --------------------------------------------------- +# -- General Sphinx configuration -------------------------------------------- # ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration # extensions = [ @@ -134,6 +134,29 @@ def setup(app): autosummary_generate = False +# -- Options for intersphinx extension --------------------------------------- +# ref: https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration +# +# The extension makes us able to link like to other projects like below. +# +# rST - :external:py:class:`tornado.httpclient.AsyncHTTPClient` +# MyST - {external:py:class}`tornado.httpclient.AsyncHTTPClient` +# +# To see what we can link to, do the following where "objects.inv" is appended +# to the sphinx based website: +# +# python -m sphinx.ext.intersphinx https://www.tornadoweb.org/en/stable/objects.inv +# +intersphinx_mapping = { + "tornado": ("https://www.tornadoweb.org/en/stable/", None), + "jupyterhub": ("https://jupyterhub.readthedocs.io/en/stable/", None), +} + +# intersphinx_disabled_reftypes set based on recommendation in +# https://docs.readthedocs.io/en/stable/guides/intersphinx.html#using-intersphinx +intersphinx_disabled_reftypes = ["*"] + + # -- Options for HTML output ------------------------------------------------- # ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output # diff --git a/oauthenticator/oauth2.py b/oauthenticator/oauth2.py index faffecbf..14179747 100644 --- a/oauthenticator/oauth2.py +++ b/oauthenticator/oauth2.py @@ -517,14 +517,22 @@ def _validate_server_cert_default(self): help=""" Extra default kwargs passed to all HTTPRequests. - For example, to use a HTTP proxy for all requests: - - `c.OAuthenticator.http_request_kwargs = {"proxy_host": "proxy.example.com", "proxy_port": 8080}` - - See the `tornado.httpclient.HTTPRequest` documentation for all options and limitations: - https://www.tornadoweb.org/en/stable/httpclient.html#tornado.httpclient.HTTPRequest - - Note that some of these are dependent on the httpclient implementation. + .. code-block:: python + + # Example: send requests through a proxy + c.OAuthenticator.http_request_kwargs = { + "proxy_host": "proxy.example.com", + "proxy_port": 8080, + } + + # Example: validate against certain root certificates + c.OAuthenticator.http_request_kwargs = { + "ca_certs": "/run/secrets/kubernetes.io/serviceaccount/ca.crt", + } + + See :external:py:class:`tornado.httpclient.HTTPRequest` for all kwargs + options you can pass. Note that the HTTP client making these requests is + :external:py:class:`tornado.httpclient.AsyncHTTPClient`. """, ) From b3f66a7ed6747d06a78bb4acad64367506efbbc6 Mon Sep 17 00:00:00 2001 From: Erik Sundell Date: Tue, 4 Jul 2023 23:22:51 +0200 Subject: [PATCH 7/7] Apply suggestions from code review Co-authored-by: Simon Li --- docs/source/conf.py | 1 - docs/source/reference/changelog.md | 8 ++++---- oauthenticator/oauth2.py | 6 +++--- 3 files changed, 7 insertions(+), 8 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 130e2df0..f5002690 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -231,5 +231,4 @@ def setup(app): # 2023-06-29 docs refresh "topic/cilogon": "tutorials/provider-specific-setup/providers/cilogon", "tutorials/provider-specific-setup/providers/awscognito": "tutorials/provider-specific-setup/providers/generic", - "how-to/migrations/upgrade-to-16": "reference/changelog", } diff --git a/docs/source/reference/changelog.md b/docs/source/reference/changelog.md index 653009bd..32b8d326 100644 --- a/docs/source/reference/changelog.md +++ b/docs/source/reference/changelog.md @@ -33,14 +33,14 @@ command line for details. and `shown_idps`, `username_claim`, `additional_username_claims` must no longer be configured. - [Okpy] The public functions `OkpyOAuthenticator.get_auth_request` and - `OkpyOAuthenticator.get_user_info_request` was removed. + `OkpyOAuthenticator.get_user_info_request` were removed. ### Deprecations -- [Generic, Auth0] `username_key` is deprecated and is being replaced by +- [Generic, Auth0] `username_key` is deprecated and is replaced by {attr}`.OAuthenticator.username_claim`. - [Generic] {attr}`.GenericOAuthenticator.extra_params` is deprecated and is - being replaced by {attr}`.OAuthenticator.token_params`. + replaced by {attr}`.OAuthenticator.token_params`. ### Highlights @@ -50,7 +50,7 @@ command line for details. - [All] {attr}`.OAuthenticator.refresh_pre_spawn` is now by default enabled if {attr}`.OAuthenticator.enable_auth_state` is enabled. -- [All] Low level configurations in `GenericOAuthenticator` has been moved to +- [All] Low level configuration in `GenericOAuthenticator` has been moved to the common base class `OAuthenticator` and is therefore available to all authenticators. diff --git a/oauthenticator/oauth2.py b/oauthenticator/oauth2.py index 14179747..fa243b25 100644 --- a/oauthenticator/oauth2.py +++ b/oauthenticator/oauth2.py @@ -303,8 +303,8 @@ class OAuthenticator(Authenticator): config=True, help=""" The URL to where the user is to be redirected initially based on the - OAuth2 protocol. The user is supposed to be redirected back with a - `authorization grant code`_ after interacting successfully with the + OAuth2 protocol. The user will be redirected back with an + `authorization grant code`_ after authenticating successfully with the identity provider. .. _authorization grant code: https://www.rfc-editor.org/rfc/rfc6749#section-1.3.1 @@ -527,7 +527,7 @@ def _validate_server_cert_default(self): # Example: validate against certain root certificates c.OAuthenticator.http_request_kwargs = { - "ca_certs": "/run/secrets/kubernetes.io/serviceaccount/ca.crt", + "ca_certs": "/path/to/a.crt", } See :external:py:class:`tornado.httpclient.HTTPRequest` for all kwargs