# CRC JupyterHub Authenticator
[](https://app.codacy.com/gh/pitt-crc/Jupyter-Authenticator/dashboard)
[](https://app.codacy.com/gh/pitt-crc/Jupyter-Authenticator/dashboard)
The `crc_jupyter_auth` package is a Jupyter authentication plugin for redirecting users based on their account status and VPN role.
The utility is based on the [jhub_remote_user_authenticator](https://github.com/cwaldbieser/jhub_remote_user_authenticator)
package originally created for more general applications.
The CRC version builds on the original utility by providing significantly improved test coverage and a refined set of configuration options.
## How It Works
The authentication plugin checks incoming authentication requests and routes users based on the associated header values.
The name of the inspected headers and the routing destination are configurable via the standard Jupyter config file.
## Installation and Setup
The `crc_jupyter_auth` package can be installable via the `pip` package manager.
```bash
pip install crc-jupyter-auth
```
After installing the package, you will need to update the `authenticator_class` option in your Jupyter configuration file.
To enable basic authentication capabilities and request routing, specify the `RemoteUserAuthenticator` class:
```bash
c.JupyterHub.authenticator_class = "crc_jupyter_auth.RemoteUserAuthenticator"
```
To enable the same functionality plus local account management, use `RemoteUserLocalAuthenticator`:
```bash
c.JupyterHub.authenticator_class = "crc_jupyter_auth.RemoteUserLocalAuthenticator"
```
The `RemoteUserLocalAuthenticator` class provides the same authentication functionality
as `RemoteUserAuthenticator` but is derived from Jupyter's built-in `LocalAuthenticator` class.
This provides extra features such as the ability to add local accounts through the admin interface.
## Package Configuration
The authenticator works by fetching the authenticated username from the HTTP header `Cn`.
If found, and not blank, the client will be logged in as that user.
Otherwise, the user is redirected.
The HTTP header names and failure redirects are configurable via the Jupyter settings file.
Setting names and default values are provided in the table below:
| Setting Name | Default | Description |
|-------------------------|----------------|-----------------------------------------------------------------------------------------------|
| `username_header` | `"Cn"` | HTTP header name to inspect for the authenticated username - |
| `vpn_header` | `"isMemberOf"` | HTTP header name to inspect for the user VPN role(s). |
| `required_vpn_role` | `""` | Required VPN role for accessing the service. Ignored if an empty string. |
| `missing_role_redirect` | `""` | Redirect URL if the user is missing the required VPN header. Defaults to 404 if empty string. |
To modify a settings value, use the `c.Authenticator` object in the configuration file.
For example:
```python
c.Authenticator.missing_role_redirect = "https://my.redirect.domain"
```
If your system assigns multiple VPN roles to users and more than a single role is reported by the header
`vpn_header`, the VPN roles should be provided in the header as a semicolon-delimited list
(e.g., `role1;role2`).
## Architecture and Security Recommendations
This authenticator relies on HTTP headers that can be spoofed by a malicious client.
To protect against this, an authenticating proxy should be placed in front
of Jupyterhub. The JupyterHub daemon should **only** be accessible from the proxy
and **never** directly accessible by a client.
The authenticating proxy should remove any HTTP headers from incoming
requests and only apply headers to proxied requests that have been properly authenticated.
Raw data
{
"_id": null,
"home_page": "https://github.com/pitt-crc/Jupyter-Authenticator",
"name": "crc-jupyter-auth",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "Pitt,CRC,Jupyter,JupyterHub,JupyterLab,Authentication",
"author": "Pitt Center for Research Computing",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/73/0a/d0f477cc7f771884a6b71a59355b8825efd508def7d5d1e20dce9052569f/crc_jupyter_auth-1.1.0.tar.gz",
"platform": null,
"description": "# CRC JupyterHub Authenticator\n[](https://app.codacy.com/gh/pitt-crc/Jupyter-Authenticator/dashboard)\n[](https://app.codacy.com/gh/pitt-crc/Jupyter-Authenticator/dashboard)\n\nThe `crc_jupyter_auth` package is a Jupyter authentication plugin for redirecting users based on their account status and VPN role.\nThe utility is based on the [jhub_remote_user_authenticator](https://github.com/cwaldbieser/jhub_remote_user_authenticator)\npackage originally created for more general applications.\nThe CRC version builds on the original utility by providing significantly improved test coverage and a refined set of configuration options.\n\n## How It Works\n\nThe authentication plugin checks incoming authentication requests and routes users based on the associated header values.\nThe name of the inspected headers and the routing destination are configurable via the standard Jupyter config file.\n\n## Installation and Setup\n\nThe `crc_jupyter_auth` package can be installable via the `pip` package manager.\n\n```bash\npip install crc-jupyter-auth\n```\n\nAfter installing the package, you will need to update the `authenticator_class` option in your Jupyter configuration file.\nTo enable basic authentication capabilities and request routing, specify the `RemoteUserAuthenticator` class:\n\n```bash\nc.JupyterHub.authenticator_class = \"crc_jupyter_auth.RemoteUserAuthenticator\"\n```\n\nTo enable the same functionality plus local account management, use `RemoteUserLocalAuthenticator`:\n\n```bash\nc.JupyterHub.authenticator_class = \"crc_jupyter_auth.RemoteUserLocalAuthenticator\"\n```\n\nThe `RemoteUserLocalAuthenticator` class provides the same authentication functionality\nas `RemoteUserAuthenticator` but is derived from Jupyter's built-in `LocalAuthenticator` class. \nThis provides extra features such as the ability to add local accounts through the admin interface.\n\n## Package Configuration\n\nThe authenticator works by fetching the authenticated username from the HTTP header `Cn`.\nIf found, and not blank, the client will be logged in as that user.\nOtherwise, the user is redirected.\n\nThe HTTP header names and failure redirects are configurable via the Jupyter settings file.\nSetting names and default values are provided in the table below:\n\n| Setting Name | Default | Description |\n|-------------------------|----------------|-----------------------------------------------------------------------------------------------|\n| `username_header` | `\"Cn\"` | HTTP header name to inspect for the authenticated username - |\n| `vpn_header` | `\"isMemberOf\"` | HTTP header name to inspect for the user VPN role(s). |\n| `required_vpn_role` | `\"\"` | Required VPN role for accessing the service. Ignored if an empty string. |\n| `missing_role_redirect` | `\"\"` | Redirect URL if the user is missing the required VPN header. Defaults to 404 if empty string. |\n\nTo modify a settings value, use the `c.Authenticator` object in the configuration file.\nFor example:\n\n```python\nc.Authenticator.missing_role_redirect = \"https://my.redirect.domain\"\n```\n\nIf your system assigns multiple VPN roles to users and more than a single role is reported by the header\n`vpn_header`, the VPN roles should be provided in the header as a semicolon-delimited list\n(e.g., `role1;role2`).\n\n## Architecture and Security Recommendations\n\nThis authenticator relies on HTTP headers that can be spoofed by a malicious client.\nTo protect against this, an authenticating proxy should be placed in front\nof Jupyterhub. The JupyterHub daemon should **only** be accessible from the proxy\nand **never** directly accessible by a client.\n\nThe authenticating proxy should remove any HTTP headers from incoming\nrequests and only apply headers to proxied requests that have been properly authenticated.\n\n",
"bugtrack_url": null,
"license": "GPL-3.0-only",
"summary": "Jupyter authentication plugin that checks for account existence and VPN roles.",
"version": "1.1.0",
"project_urls": {
"Documentation": "https://github.com/pitt-crc/Jupyter-Authenticator",
"Homepage": "https://github.com/pitt-crc/Jupyter-Authenticator",
"Repository": "https://github.com/pitt-crc/Jupyter-Authenticator"
},
"split_keywords": [
"pitt",
"crc",
"jupyter",
"jupyterhub",
"jupyterlab",
"authentication"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d3f1f4475a7e908d0a4a1ddf2eeae15e95062aa84f5eea2ba380884abf373c8d",
"md5": "15f1e83c70d17aaee71e62fabf056729",
"sha256": "c1b0b5129ae074b2deffe5eda4518bad1f91b7fffa1895a9eb71e1cba6395627"
},
"downloads": -1,
"filename": "crc_jupyter_auth-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "15f1e83c70d17aaee71e62fabf056729",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 17274,
"upload_time": "2023-10-09T17:44:50",
"upload_time_iso_8601": "2023-10-09T17:44:50.898011Z",
"url": "https://files.pythonhosted.org/packages/d3/f1/f4475a7e908d0a4a1ddf2eeae15e95062aa84f5eea2ba380884abf373c8d/crc_jupyter_auth-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "730ad0f477cc7f771884a6b71a59355b8825efd508def7d5d1e20dce9052569f",
"md5": "cedbf11ef30d1b9cabf9a04aa16f535f",
"sha256": "a84788c24de54be2a82cb3bf5b9b9f1dc1f3eb464fcf562d6cf8771891e560fb"
},
"downloads": -1,
"filename": "crc_jupyter_auth-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "cedbf11ef30d1b9cabf9a04aa16f535f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 16396,
"upload_time": "2023-10-09T17:44:52",
"upload_time_iso_8601": "2023-10-09T17:44:52.450728Z",
"url": "https://files.pythonhosted.org/packages/73/0a/d0f477cc7f771884a6b71a59355b8825efd508def7d5d1e20dce9052569f/crc_jupyter_auth-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-09 17:44:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pitt-crc",
"github_project": "Jupyter-Authenticator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "crc-jupyter-auth"
}
JSON
