=========================
Jupyterhub Authenticators
=========================
.. image:: https://badge.fury.io/py/jhub-authenticators.svg
:target: https://badge.fury.io/py/jhub-authenticators
An extended collection of HTTP(S) header JupyterHub Authenticators that relies on proxy authenticating.
Every mentioned authenticator should be used while following
the mentioned security recommendations at `cwaldbieser <https://github.com/cwaldbieser/jhub_remote_user_authenticator/blob/master/README.rst#architecture-and-security-recommendations>`_.
------------
Installation
------------
Installation from pypi::
pip install jhub-authenticators
Installation from local git repository::
cd jhub-authenticators
pip install .
--------------------
Dummy Authentication
--------------------
Provides an option for testing JupyterHub authentication with a dummy authenticator
that can have a global preset password for any account::
c.JupyterHub.authenticator_class = 'jhubauthenticators.DummyAuthenticator'
c.DummyAuthenticator.password = 'password'
Note! Don't use in production.
---------------------
Header Authentication
---------------------
This Header Authentication method provides multiple functionalities beyond mere authentication. It can activated by adding the following to the JupyterHub configuration::
c.JupyterHub.authenticator_class = 'jhubauthenticators.HeaderAuthenticator'
By default, it exposes the following paths::
'/login' -> is utilizied to authenticate the user, relies on the 'allowed_headers' parameter to accomplish this.
'/logout' -> clears the users authenticated session.
'/set-user-data' -> allows an authenticated user to provide data to be persisted during the authenticated session. Here the 'user_external_allow_attributes' parameter defines which user attributes are allowed to be set.
Specify Authentication Header
-----------------------------
First it provides the possibility to define a custom authentication header,
this is accomplished by overriding the default allowed_headers dict required ``auth`` key::
c.HeaderAuthenticator.allowed_headers = {'auth': 'MyAuthHeader'}
This will overrive the default ``Remote-User`` header authentication to use the ``MyAuthHeader`` instead.
Additional User Data Headers
----------------------------
Beyond the ``auth`` key, the administrator is allowed to set additional headers that the authenticator will accept requests on.
For instance, if the ``MyCustomHeader`` should be accepted as well during authentication::
c.HeaderAuthenticator.enable_auth_state = True
c.HeaderAuthenticator.allowed_headers = {'auth': 'MyAuthHeader',
'auth_data': 'MyCustomHeader'}
Any information provided via the ``MyCustomHeader`` during authentication will be added to the JupyterHub user's ``auth_state``,
dictionary as defined by `Authenticators auth_state <https://jupyterhub.readthedocs.io/en/stable/reference/authenticators.html#authentication-state>`_. The data will be added to the ``auth_state`` by utilizing the header value in the
``allowed_headers`` dictionary as the key in the 'auth_state' dictionary. For instance the above configuration, will produce the following user profile::
user = {
name: 'stored MyAuthHeader value',
'auth_state': {'MyCustomHeader': 'stored MyCustomHeader value'}
}
It's important to note here, that this information is only persisted for the life-time of the authenticated session.
Sharing auth_state data with Spawner Environement
-------------------------------------------------
If any of the defined ``auth_state`` key-value pairs should be set as Spawner environement variables before a notebook is spawned, the ``spawner_shared_headers`` parameter is available to define this, E.g if the "MyCustomHeader' should do this, it can be accomplished with the following addition to the configuration::
c.HeaderAuthenticator.spawner_shared_headers = ['MyCustomHeader']
Which during `pre_spawn_hook <https://jupyterhub.readthedocs
.io/en/stable/reference/authenticators.html>`_ will produce the following environment variable::
~>env | grep MyCustomHeader
MyCustomHeader="stored MyCustomHeader value"
Special Parsers
---------------
If the administrator requires that the defined ``allowed_headers`` should be parsed in a special way.
The administrator can use the ``header_parser_classes`` parameter to define how a request with a particular header should be parsed, E.g::
from jhubauthenticators import Parser, JSONParser
c.HeaderAuthenticator.header_parser_classes = {'auth': Parser,
'auth_data': JSONParser}
The ``auth`` header is here set to be parsed by the default Parser, which just returns the provided value unchanged.
The JSONParser, however does what it indicated, attempts to parse the data as JSON.
In addition to these, the authenticator also provides the ``RegexUsernameParser`` which can be used as an ``auth`` parser, E.g::
# RegexUsernameParser
c.HeaderAuthenticator.header_parser_classes = {'auth': RegexUsernameParser}
# Email regex
RegexUsernameParser.username_extract_regex = '([a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+)'
Which will try to expand an email from the defined ``auth`` allowed_headers Header. If this can't be accomplished, the user will not be authenticated.
Related to the ``username_extract_regex``, the ``RegexUsernameParser.replace_extract_chars`` parameter exists to accomplish post filtering of illegal characters on the extracted username, E.g::
# Replace every '@' and '.' char in the extracted username with '_'
RegexUsernameParser.replace_extract_chars = {'@': '_', '.': '_'}
It is possible to define additional parsers by extending the Parser class and implementing the required parse method, E.g::
class MyParser(Parser)
# MyAdvancedParser
def parse(self, data)
return data
Which can subsequently be activate by adding it to the ``header_parser_classes`` parameter, E.g.::
# MyAdvancedParser
c.HeaderAuthenticator.header_parser_classes = {'auth': MyParser}
Set User state after Authentication
-----------------------------------
Finally, the HeaderAuthenticator also provides the administrator the possibility to define the ``user_external_allow_attributes`` parameter.
This allows defines which user attributes an authenticated user is allowed to set a user-defined variable via the HeaderAuthenticator defined `/set-user-data` endpoint.
For instance, an authentiacated user's variable `data` could be allowed to be externally defined by defining the following configuration::
c.HeaderAuthenticator.user_external_allow_attributes = ['data']
By default the ``user_external_allow_attributes`` allows no such attributes and has to be explicitly enabled/defined.
Furthermore, this will only allow an authenticated user to externally define their own `data` instance variable.
Additional configuration examples of this can be found in the ``tests/jupyterhub_configs`` directory.
Raw data
{
"_id": null,
"home_page": "https://github.com/ucphhpc/jhub-authenticators",
"name": "jhub-authenticators",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Interactive, Interpreter, Shell, Web",
"author": "Rasmus Munk",
"author_email": "munk1@live.dk",
"download_url": "https://files.pythonhosted.org/packages/65/fe/e59006eae5afb7d810393e0de78eae9a06b35018569912e1d1ab505746c3/jhub_authenticators-0.6.1.tar.gz",
"platform": "Linux",
"description": "=========================\nJupyterhub Authenticators\n=========================\n.. image:: https://badge.fury.io/py/jhub-authenticators.svg\n :target: https://badge.fury.io/py/jhub-authenticators\n\nAn extended collection of HTTP(S) header JupyterHub Authenticators that relies on proxy authenticating.\nEvery mentioned authenticator should be used while following\nthe mentioned security recommendations at `cwaldbieser <https://github.com/cwaldbieser/jhub_remote_user_authenticator/blob/master/README.rst#architecture-and-security-recommendations>`_.\n\n------------\nInstallation\n------------\n\nInstallation from pypi::\n\n pip install jhub-authenticators\n\nInstallation from local git repository::\n\n cd jhub-authenticators\n pip install .\n\n--------------------\nDummy Authentication\n--------------------\n\nProvides an option for testing JupyterHub authentication with a dummy authenticator\nthat can have a global preset password for any account::\n\n c.JupyterHub.authenticator_class = 'jhubauthenticators.DummyAuthenticator'\n c.DummyAuthenticator.password = 'password'\n\n\nNote! Don't use in production.\n\n---------------------\nHeader Authentication\n---------------------\n\nThis Header Authentication method provides multiple functionalities beyond mere authentication. It can activated by adding the following to the JupyterHub configuration::\n\n c.JupyterHub.authenticator_class = 'jhubauthenticators.HeaderAuthenticator'\n \nBy default, it exposes the following paths::\n\n '/login' -> is utilizied to authenticate the user, relies on the 'allowed_headers' parameter to accomplish this.\n '/logout' -> clears the users authenticated session.\n '/set-user-data' -> allows an authenticated user to provide data to be persisted during the authenticated session. Here the 'user_external_allow_attributes' parameter defines which user attributes are allowed to be set.\n\nSpecify Authentication Header\n-----------------------------\n\nFirst it provides the possibility to define a custom authentication header,\nthis is accomplished by overriding the default allowed_headers dict required ``auth`` key::\n\n c.HeaderAuthenticator.allowed_headers = {'auth': 'MyAuthHeader'}\n\nThis will overrive the default ``Remote-User`` header authentication to use the ``MyAuthHeader`` instead.\n\nAdditional User Data Headers\n----------------------------\nBeyond the ``auth`` key, the administrator is allowed to set additional headers that the authenticator will accept requests on.\n\nFor instance, if the ``MyCustomHeader`` should be accepted as well during authentication::\n\n c.HeaderAuthenticator.enable_auth_state = True\n c.HeaderAuthenticator.allowed_headers = {'auth': 'MyAuthHeader',\n 'auth_data': 'MyCustomHeader'}\n\nAny information provided via the ``MyCustomHeader`` during authentication will be added to the JupyterHub user's ``auth_state``,\ndictionary as defined by `Authenticators auth_state <https://jupyterhub.readthedocs.io/en/stable/reference/authenticators.html#authentication-state>`_. The data will be added to the ``auth_state`` by utilizing the header value in the \n``allowed_headers`` dictionary as the key in the 'auth_state' dictionary. For instance the above configuration, will produce the following user profile::\n\n user = {\n name: 'stored MyAuthHeader value',\n 'auth_state': {'MyCustomHeader': 'stored MyCustomHeader value'}\n }\n\nIt's important to note here, that this information is only persisted for the life-time of the authenticated session.\n\nSharing auth_state data with Spawner Environement\n-------------------------------------------------\nIf any of the defined ``auth_state`` key-value pairs should be set as Spawner environement variables before a notebook is spawned, the ``spawner_shared_headers`` parameter is available to define this, E.g if the \"MyCustomHeader' should do this, it can be accomplished with the following addition to the configuration::\n\n c.HeaderAuthenticator.spawner_shared_headers = ['MyCustomHeader']\n\nWhich during `pre_spawn_hook <https://jupyterhub.readthedocs\n.io/en/stable/reference/authenticators.html>`_ will produce the following environment variable::\n\n ~>env | grep MyCustomHeader\n\n MyCustomHeader=\"stored MyCustomHeader value\"\n\n\nSpecial Parsers\n---------------\nIf the administrator requires that the defined ``allowed_headers`` should be parsed in a special way.\nThe administrator can use the ``header_parser_classes`` parameter to define how a request with a particular header should be parsed, E.g::\n \n from jhubauthenticators import Parser, JSONParser\n\n c.HeaderAuthenticator.header_parser_classes = {'auth': Parser,\n 'auth_data': JSONParser}\n\nThe ``auth`` header is here set to be parsed by the default Parser, which just returns the provided value unchanged.\nThe JSONParser, however does what it indicated, attempts to parse the data as JSON.\n\nIn addition to these, the authenticator also provides the ``RegexUsernameParser`` which can be used as an ``auth`` parser, E.g::\n\n # RegexUsernameParser\n c.HeaderAuthenticator.header_parser_classes = {'auth': RegexUsernameParser}\n # Email regex\n RegexUsernameParser.username_extract_regex = '([a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\.[a-zA-Z0-9-.]+)'\n\nWhich will try to expand an email from the defined ``auth`` allowed_headers Header. If this can't be accomplished, the user will not be authenticated.\n\nRelated to the ``username_extract_regex``, the ``RegexUsernameParser.replace_extract_chars`` parameter exists to accomplish post filtering of illegal characters on the extracted username, E.g::\n\n # Replace every '@' and '.' char in the extracted username with '_'\n RegexUsernameParser.replace_extract_chars = {'@': '_', '.': '_'}\n\nIt is possible to define additional parsers by extending the Parser class and implementing the required parse method, E.g::\n\n class MyParser(Parser)\n\n # MyAdvancedParser\n def parse(self, data)\n return data\n\nWhich can subsequently be activate by adding it to the ``header_parser_classes`` parameter, E.g.::\n\n # MyAdvancedParser\n c.HeaderAuthenticator.header_parser_classes = {'auth': MyParser}\n\nSet User state after Authentication\n-----------------------------------\n\nFinally, the HeaderAuthenticator also provides the administrator the possibility to define the ``user_external_allow_attributes`` parameter.\nThis allows defines which user attributes an authenticated user is allowed to set a user-defined variable via the HeaderAuthenticator defined `/set-user-data` endpoint.\nFor instance, an authentiacated user's variable `data` could be allowed to be externally defined by defining the following configuration::\n\n c.HeaderAuthenticator.user_external_allow_attributes = ['data']\n\nBy default the ``user_external_allow_attributes`` allows no such attributes and has to be explicitly enabled/defined.\nFurthermore, this will only allow an authenticated user to externally define their own `data` instance variable.\n\nAdditional configuration examples of this can be found in the ``tests/jupyterhub_configs`` directory.\n",
"bugtrack_url": null,
"license": "GNU General Public License v2 (GPLv2)",
"summary": "A collection of HTTP(s) JupyterHub Header Authenticators,including a Header, and Dummy authenticator",
"version": "0.6.1",
"project_urls": {
"Homepage": "https://github.com/ucphhpc/jhub-authenticators",
"Source Code": "https://github.com/ucphhpc/jhub-authenticators"
},
"split_keywords": [
"interactive",
" interpreter",
" shell",
" web"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f17e095a48459b504e9c348f1f80616792564ffb179e289a09815bac1423c926",
"md5": "cb4f9edcc1b69de626c78931b2735eff",
"sha256": "a827bebd55eb1c91fc9f90e6dbf0228e6b017b2baa68f74e9d8ca992e3d902ff"
},
"downloads": -1,
"filename": "jhub_authenticators-0.6.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cb4f9edcc1b69de626c78931b2735eff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 22359,
"upload_time": "2025-09-04T10:01:23",
"upload_time_iso_8601": "2025-09-04T10:01:23.720974Z",
"url": "https://files.pythonhosted.org/packages/f1/7e/095a48459b504e9c348f1f80616792564ffb179e289a09815bac1423c926/jhub_authenticators-0.6.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "65fee59006eae5afb7d810393e0de78eae9a06b35018569912e1d1ab505746c3",
"md5": "a4a085a4327c3803a4975791c7cb5dc7",
"sha256": "ae4ae75954bdfccb15720cd05775d9f47d682ba414c263b1321da75d8fa65931"
},
"downloads": -1,
"filename": "jhub_authenticators-0.6.1.tar.gz",
"has_sig": false,
"md5_digest": "a4a085a4327c3803a4975791c7cb5dc7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 25244,
"upload_time": "2025-09-04T10:01:24",
"upload_time_iso_8601": "2025-09-04T10:01:24.703719Z",
"url": "https://files.pythonhosted.org/packages/65/fe/e59006eae5afb7d810393e0de78eae9a06b35018569912e1d1ab505746c3/jhub_authenticators-0.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-04 10:01:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ucphhpc",
"github_project": "jhub-authenticators",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "jupyterhub",
"specs": [
[
">",
"5.1.0"
]
]
}
],
"lcname": "jhub-authenticators"
}
JSON
