| Name | ckanext-passwordless_api JSON |
| Version |
1.1.8
JSON |
| download |
| home_page | |
| Summary | Extension to allow paswordless login to the CKAN API |
| upload_time | 2023-08-23 16:54:09 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | MIT |
| keywords |
ckan
passwordless
token
auth
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# CKAN Passwordless API
<div align="center">
<em>Extension to allow paswordless login to the CKAN API.</em>
</div>
<div align="center">
<a href="https://pypi.org/project/ckanext-passwordless_api" target="_blank">
<img src="https://img.shields.io/pypi/v/ckanext-passwordless_api?color=%2334D058&label=pypi%20package" alt="Package version">
</a>
<a href="https://pypistats.org/packages/ckanext-passwordless_api" target="_blank">
<img src="https://img.shields.io/pypi/dm/ckanext-passwordless_api.svg" alt="Downloads">
</a>
<a href="https://gitlabext.wsl.ch/EnviDat/ckanext-passwordless_api/-/raw/main/LICENSE" target="_blank">
<img src="https://img.shields.io/github/license/EnviDat/ckanext-passwordless_api.svg" alt="Licence">
</a>
</div>
---
**Documentation**: <a href="https://envidat.gitlab-pages.wsl.ch/ckanext-passwordless_api/" target="_blank">https://envidat.gitlab-pages.wsl.ch/ckanext-passwordless_api/</a>
**Source Code**: <a href="https://gitlabext.wsl.ch/EnviDat/ckanext-passwordless_api" target="_blank">https://gitlabext.wsl.ch/EnviDat/ckanext-passwordless_api</a>
---
**This plugin is primarily intended for custom frontends built on the CKAN API.**
By using API tokens from CKAN core (>2.9), this plugin provides an authentication flow where:
1. Users receive a login token via email (via reset key in core).
2. API token is returned on valid login token (reset key) submission.
3. The API token should then be included in Authorization headers from the frontend --> CKAN calls.
Based on work by @espona (Lucia Espona Pernas) for ckanext-passwordless (https://github.com/EnviDat/ckanext-passwordless).
A second login flow is also supported, using Azure AD:
1. User logs in with authorization code flow in frontend (@azure/msal-browser or similar).
2. Azure token is passed to azure specific endpoint.
3. Token is validated and API token for CKAN is returned.
4. The API token should then be included in Authorization headers from the frontend --> CKAN calls.
## Install
```bash
pip install ckanext-passwordless-api
```
## Config
Optional variables can be set in your ckan.ini:
- **passwordless_api.guidelines_url**
- Description: A link to your website guidelines.
- Default: None, not included.
- **passwordless_api.policies_url**
- Description: A link to your website policies.
- Default: None, not included.
- **passwordless_api.welcome_template**
- Description: Path to welcome template to render as html email.
- Default: uses default template.
- **passwordless_api.reset_key_template**
- Description: Path to reset key template to render as html email
- Default: uses default template.
- **passwordless_api.cookie_name**
- Description: Set to place the API token in a cookie, with given name.
The cookie will default to `secure`, `httpOnly`, `samesite: Lax`.
- Default: None, no cookie used.
- **passwordless_api.cookie_domain**
- Description: The domain for samesite to respect, required if cookie set.
- Default: None.
- **passwordless_api.cookie_samesite**
- Description: To change the cookie samesite value to `Strict`.
Only enable this if you know what you are doing.
- Default: None, samesite value is set to `Lax`.
- **passwordless_api.cookie_http_only**
- Description: Use a httpOnly cookie, recommended.
- Default: true.
- **passwordless_api.cookie_path**
- Description: Set a specific path to use the cookie, e.g. `/api`.
- Default: `/` (all paths).
- **passwordless_api.anonymous_usernames**
- Description: Set to true to anonymise usernames when generated.
- Default: false.
- **passwordless_api.anonymous_domain_exceptions**
- Description: Email domain exceptions that should not be anonymised, if enabled.
- Default: None.
## Endpoints
**POST**
- **<CKAN_HOST>/api/3/action/passwordless_request_reset_key**
- Description: Request a login token for a given email.
- Creates user if they do not exist & sends welcome email.
- Param1: email (str).
- **<CKAN_HOST>/api/3/action/passwordless_request_api_token**
- Description: Request an API token, given the email and login token (reset_key).
- Param1: email (str).
- Param2: key (str).
- **<CKAN_HOST>/api/3/action/passwordless_request_api_token_azure_ad**
- Description: Request an API token, given the email and Azure AD token.
- Param1: email (str).
- Param2: token (str).
- **<CKAN_HOST>/api/3/action/passwordless_revoke_api_token**
- Description: Revoke an API token.
- Param1: token (str).
**GET**
- **<CKAN_HOST>/api/3/action/passwordless_revoke_api_token**
- Description: If logged in, revoke the current API token.
- **<CKAN_HOST>/api/3/action/passwordless_get_user**
- Description: Get user details, given their API token.
- Also resets and returns a new API token (i.e. renewal).
- Fails silently if the user is not logged in.
- Use the core `user_show` action if refresh is not required.
- **<CKAN_HOST>/api/3/action/passwordless_introspect**
- Description: Verify if the API token is valid for a user.
- This does not renew the token in the same call.
- Mostly useful for auth checking in microservice APIs.
## Using the cookie in an Authorization header
If configured, the cookie containing an API token can't do much on it's own.
It is possible to extract the cookie value using frontend JS and pass to the CKAN backend, but this makes your site vulnerable to XSS attacks.
Instead the cookie should be stored in a secure way:
- `samesite=Lax` with `domain=YOUR_DOMAIN` to help prevent CSRF.
- `samesite=Strict` is even more secure, but significantly impacts UX for your site.
- `secure` to help prevent man-in-the-middle.
- `httpOnly` to help prevent XSS.
- Setting this means the cookie can no longer be accessed from your JS code.
Then a middleware must be used to convert the cookie value into a header than CKAN can interpret:
**NGINX server example**
(nginx is the default/recommended server to reverse proxy CKAN)
(https://docs.ckan.org/en/latest/maintaining/installing/deployment.html)
```nginx
# Add the cookie-based API token to the request Authorization header
# This is passed to the CKAN backend & read automatically by CKAN
proxy_set_header 'Authorization' $cookie_${AUTH_COOKIE_NAME};
# If using caching omit the cookie
proxy_cache_bypass $cookie_${AUTH_COOKIE_NAME};
proxy_no_cache $cookie_${AUTH_COOKIE_NAME};
```
**Apache server example**
```apache
SetEnvIf Cookie "(^|;\ *)${AUTH_COOKIE_NAME}=([^;\ ]+)" ckan_cookie_value=$2
RequestHeader set Authorization "%{ckan_cookie_value}e"
```
## Notes
- It is also recommended to disable access to the API via cookie, to help prevent CSRF:
`ckan.auth.disable_cookie_auth_in_api = true`
- The configuration for API tokens can be configured in core:
```ini
api_token.nbytes = 60
api_token.jwt.decode.secret = string:YOUR_SUPER_SECRET_STRING
api_token.jwt.algorithm = HS256
# expire_api_token plugin (unit = 1 day in seconds, lifetime = 3 days)
expire_api_token.default_lifetime = 3
expire_api_token.default_unit = 86400
```
Raw data
{
"_id": null,
"home_page": "",
"name": "ckanext-passwordless_api",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "CKAN,passwordless,token,auth",
"author": "",
"author_email": "Sam Woodcock <sam.woodcock@protonmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c7/bb/736a40a3c33d3e9589952088af91d060cd9fe5d96e1a6d11c1c03eeb860e/ckanext-passwordless-api-1.1.8.tar.gz",
"platform": null,
"description": "# CKAN Passwordless API\n\n<div align=\"center\">\n <em>Extension to allow paswordless login to the CKAN API.</em>\n</div>\n<div align=\"center\">\n <a href=\"https://pypi.org/project/ckanext-passwordless_api\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/v/ckanext-passwordless_api?color=%2334D058&label=pypi%20package\" alt=\"Package version\">\n </a>\n <a href=\"https://pypistats.org/packages/ckanext-passwordless_api\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/dm/ckanext-passwordless_api.svg\" alt=\"Downloads\">\n </a>\n <a href=\"https://gitlabext.wsl.ch/EnviDat/ckanext-passwordless_api/-/raw/main/LICENSE\" target=\"_blank\">\n <img src=\"https://img.shields.io/github/license/EnviDat/ckanext-passwordless_api.svg\" alt=\"Licence\">\n </a>\n</div>\n\n---\n\n**Documentation**: <a href=\"https://envidat.gitlab-pages.wsl.ch/ckanext-passwordless_api/\" target=\"_blank\">https://envidat.gitlab-pages.wsl.ch/ckanext-passwordless_api/</a>\n\n**Source Code**: <a href=\"https://gitlabext.wsl.ch/EnviDat/ckanext-passwordless_api\" target=\"_blank\">https://gitlabext.wsl.ch/EnviDat/ckanext-passwordless_api</a>\n\n---\n\n**This plugin is primarily intended for custom frontends built on the CKAN API.**\n\nBy using API tokens from CKAN core (>2.9), this plugin provides an authentication flow where:\n\n1. Users receive a login token via email (via reset key in core).\n2. API token is returned on valid login token (reset key) submission.\n3. The API token should then be included in Authorization headers from the frontend --> CKAN calls.\n\nBased on work by @espona (Lucia Espona Pernas) for ckanext-passwordless (https://github.com/EnviDat/ckanext-passwordless).\n\nA second login flow is also supported, using Azure AD:\n\n1. User logs in with authorization code flow in frontend (@azure/msal-browser or similar).\n2. Azure token is passed to azure specific endpoint.\n3. Token is validated and API token for CKAN is returned.\n4. The API token should then be included in Authorization headers from the frontend --> CKAN calls.\n\n## Install\n\n```bash\npip install ckanext-passwordless-api\n```\n\n## Config\n\nOptional variables can be set in your ckan.ini:\n\n- **passwordless_api.guidelines_url**\n - Description: A link to your website guidelines.\n - Default: None, not included.\n- **passwordless_api.policies_url**\n - Description: A link to your website policies.\n - Default: None, not included.\n- **passwordless_api.welcome_template**\n - Description: Path to welcome template to render as html email.\n - Default: uses default template.\n- **passwordless_api.reset_key_template**\n - Description: Path to reset key template to render as html email\n - Default: uses default template.\n- **passwordless_api.cookie_name**\n - Description: Set to place the API token in a cookie, with given name.\n The cookie will default to `secure`, `httpOnly`, `samesite: Lax`.\n - Default: None, no cookie used.\n- **passwordless_api.cookie_domain**\n - Description: The domain for samesite to respect, required if cookie set.\n - Default: None.\n- **passwordless_api.cookie_samesite**\n - Description: To change the cookie samesite value to `Strict`.\n Only enable this if you know what you are doing.\n - Default: None, samesite value is set to `Lax`.\n- **passwordless_api.cookie_http_only**\n - Description: Use a httpOnly cookie, recommended.\n - Default: true.\n- **passwordless_api.cookie_path**\n - Description: Set a specific path to use the cookie, e.g. `/api`.\n - Default: `/` (all paths).\n- **passwordless_api.anonymous_usernames**\n - Description: Set to true to anonymise usernames when generated.\n - Default: false.\n- **passwordless_api.anonymous_domain_exceptions**\n - Description: Email domain exceptions that should not be anonymised, if enabled.\n - Default: None.\n\n## Endpoints\n\n**POST**\n\n- **<CKAN_HOST>/api/3/action/passwordless_request_reset_key**\n - Description: Request a login token for a given email.\n - Creates user if they do not exist & sends welcome email.\n - Param1: email (str).\n- **<CKAN_HOST>/api/3/action/passwordless_request_api_token**\n - Description: Request an API token, given the email and login token (reset_key).\n - Param1: email (str).\n - Param2: key (str).\n- **<CKAN_HOST>/api/3/action/passwordless_request_api_token_azure_ad**\n - Description: Request an API token, given the email and Azure AD token.\n - Param1: email (str).\n - Param2: token (str).\n- **<CKAN_HOST>/api/3/action/passwordless_revoke_api_token**\n - Description: Revoke an API token.\n - Param1: token (str).\n\n**GET**\n\n- **<CKAN_HOST>/api/3/action/passwordless_revoke_api_token**\n - Description: If logged in, revoke the current API token.\n- **<CKAN_HOST>/api/3/action/passwordless_get_user**\n - Description: Get user details, given their API token.\n - Also resets and returns a new API token (i.e. renewal).\n - Fails silently if the user is not logged in.\n - Use the core `user_show` action if refresh is not required.\n- **<CKAN_HOST>/api/3/action/passwordless_introspect**\n - Description: Verify if the API token is valid for a user.\n - This does not renew the token in the same call.\n - Mostly useful for auth checking in microservice APIs.\n\n## Using the cookie in an Authorization header\n\nIf configured, the cookie containing an API token can't do much on it's own.\n\nIt is possible to extract the cookie value using frontend JS and pass to the CKAN backend, but this makes your site vulnerable to XSS attacks.\n\nInstead the cookie should be stored in a secure way:\n\n- `samesite=Lax` with `domain=YOUR_DOMAIN` to help prevent CSRF.\n - `samesite=Strict` is even more secure, but significantly impacts UX for your site.\n- `secure` to help prevent man-in-the-middle.\n- `httpOnly` to help prevent XSS.\n - Setting this means the cookie can no longer be accessed from your JS code.\n\nThen a middleware must be used to convert the cookie value into a header than CKAN can interpret:\n\n**NGINX server example**\n(nginx is the default/recommended server to reverse proxy CKAN)\n(https://docs.ckan.org/en/latest/maintaining/installing/deployment.html)\n\n```nginx\n# Add the cookie-based API token to the request Authorization header\n# This is passed to the CKAN backend & read automatically by CKAN\nproxy_set_header 'Authorization' $cookie_${AUTH_COOKIE_NAME};\n\n# If using caching omit the cookie\nproxy_cache_bypass $cookie_${AUTH_COOKIE_NAME};\nproxy_no_cache $cookie_${AUTH_COOKIE_NAME};\n```\n\n**Apache server example**\n\n```apache\nSetEnvIf Cookie \"(^|;\\ *)${AUTH_COOKIE_NAME}=([^;\\ ]+)\" ckan_cookie_value=$2\nRequestHeader set Authorization \"%{ckan_cookie_value}e\"\n```\n\n## Notes\n\n- It is also recommended to disable access to the API via cookie, to help prevent CSRF:\n `ckan.auth.disable_cookie_auth_in_api = true`\n- The configuration for API tokens can be configured in core:\n\n```ini\napi_token.nbytes = 60\napi_token.jwt.decode.secret = string:YOUR_SUPER_SECRET_STRING\napi_token.jwt.algorithm = HS256\n\n# expire_api_token plugin (unit = 1 day in seconds, lifetime = 3 days)\nexpire_api_token.default_lifetime = 3\nexpire_api_token.default_unit = 86400\n```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Extension to allow paswordless login to the CKAN API",
"version": "1.1.8",
"project_urls": {
"documentation": "https://envidat.gitlab-pages.wsl.ch/ckanext-passwordless_api",
"homepage": "https://gitlabext.wsl.ch/EnviDat/ckanext-passwordless_api.git",
"repository": "https://gitlabext.wsl.ch/EnviDat/ckanext-passwordless_api.git"
},
"split_keywords": [
"ckan",
"passwordless",
"token",
"auth"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0dff4ff0051f0b553daab556733f2cbba735c9170228bb8b046bc79b4aa2277c",
"md5": "2b703d2408c697778d31fa7bce2d2019",
"sha256": "0ef9ef70c683899d75331bdb12c7f2aa62c9c0b4bd5864b31f37053cbdda299c"
},
"downloads": -1,
"filename": "ckanext_passwordless_api-1.1.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2b703d2408c697778d31fa7bce2d2019",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 15001,
"upload_time": "2023-08-23T16:54:07",
"upload_time_iso_8601": "2023-08-23T16:54:07.507117Z",
"url": "https://files.pythonhosted.org/packages/0d/ff/4ff0051f0b553daab556733f2cbba735c9170228bb8b046bc79b4aa2277c/ckanext_passwordless_api-1.1.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c7bb736a40a3c33d3e9589952088af91d060cd9fe5d96e1a6d11c1c03eeb860e",
"md5": "00d0f464bf091ddabc431209a4ff6757",
"sha256": "0fc78db268f10f410640bdd3a080c5dd540454a809ea54dc564fa107f486148a"
},
"downloads": -1,
"filename": "ckanext-passwordless-api-1.1.8.tar.gz",
"has_sig": false,
"md5_digest": "00d0f464bf091ddabc431209a4ff6757",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 15876,
"upload_time": "2023-08-23T16:54:09",
"upload_time_iso_8601": "2023-08-23T16:54:09.469616Z",
"url": "https://files.pythonhosted.org/packages/c7/bb/736a40a3c33d3e9589952088af91d060cd9fe5d96e1a6d11c1c03eeb860e/ckanext-passwordless-api-1.1.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-23 16:54:09",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ckanext-passwordless_api"
}
