[![CI][]][1] [![Coverage][]][2] [![Gitter][]][3] [![Pypi][]][4] [![Python][]][5] [![CKAN][]][6]
# ckanext-saml2auth
A [CKAN](https://ckan.org) extension to enable Single Sign-On (SSO) for CKAN data portals via SAML2 Authentication.
## Requirements
This extension works with CKAN 2.9+.
## Installation
To install ckanext-saml2auth:
1. Install the required system packages:
sudo apt install xmlsec1
2. Activate your CKAN virtual environment, for example:
. /usr/lib/ckan/default/bin/activate
3. Install the required system packages to install the necessary python
module dependencies:
# rustc and cargo are neeeded to build cryptography if no binary wheel exists
sudo apt install rustc cargo
4. Install the ckanext-saml2auth Python package into your virtual
environment:
pip install ckanext-saml2auth
5. Add `saml2auth` to the `ckan.plugins` setting in your CKAN config
file (by default the config file is located at
`/etc/ckan/default/ckan.ini`).
6. Restart CKAN. For example if you\'ve deployed CKAN with Apache on
Ubuntu:
sudo service apache2 reload
## Config settings
Required:
# Specifies the metadata location type
# Options: local or remote
ckanext.saml2auth.idp_metadata.location = remote
# Path to a local file accessible on the server the service runs on
# Ignore this config if the idp metadata location is set to: remote
ckanext.saml2auth.idp_metadata.local_path = /opt/metadata/idp.xml
# A remote URL serving aggregate metadata
# Ignore this config if the idp metadata location is set to: local
ckanext.saml2auth.idp_metadata.remote_url = https://kalmar2.org/simplesaml/module.php/aggregator/?id=kalmarcentral2&set=saml2
# Path to a local file accessible on the server the service runs on
# Ignore this config if the idp metadata location is set to: local and metadata is public
ckanext.saml2auth.idp_metadata.remote_cert = /opt/metadata/kalmar2.cert
# Corresponding SAML user field for firstname
ckanext.saml2auth.user_firstname = firstname
# Corresponding SAML user field for lastname
ckanext.saml2auth.user_lastname = lastname
# Corresponding SAML user field for fullname
# (Optional: Can be used as an alternative to firstname + lastname)
ckanext.saml2auth.user_fullname = fullname
# Corresponding SAML user field for email
ckanext.saml2auth.user_email = email
Optional:
# URL route of the endpoint where the SAML assertion is sent, also known as Assertion Consumer Service (ACS).
# Default: /acs
ckanext.saml2auth.acs_endpoint = /sso/post
# Configuration setting that enables CKAN's internal register/login functionality as well
# Default: False
ckanext.saml2auth.enable_ckan_internal_login = True
# List of email addresses from users that should be created as sysadmins (system administrators)
# Note that this means that CKAN sysadmins will _only_ be managed based on this config option and will override existing user permissions in the CKAN database
# If not set then it is ignored and CKAN sysadmins are managed through normal means
# Default: <Not set>
ckanext.saml2auth.sysadmins_list = mail@domain.com mail2@domain.com mail3@domain.com
# Indicates that attributes that are not recognized (they are not configured in attribute-mapping),
# will not be discarded.
# Default: True
ckanext.saml2auth.allow_unknown_attributes = False
# A list of string values that will be used to set the <NameIDFormat> element of the metadata of an entity.
# Default: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
ckanext.saml2auth.sp.name_id_format = urn:oasis:names:tc:SAML:2.0:nameid-format:persistent urn:oasis:names:tc:SAML:2.0:nameid-format:transient
# A string value that will be used to set the Format attribute of the <NameIDPolicy> element of the metadata of an entity.
# Default: <Not set>
ckanext.saml2auth.sp.name_id_policy_format = urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
# Entity ID (also know as Issuer)
# Define the entity ID. Default is urn:mace:umu.se:saml:ckan:sp
ckanext.saml2auth.entity_id = urn:gov:gsa:SAML:2.0.profiles:sp:sso:gsa:catalog-dev
# Signed responses and assertions
ckanext.saml2auth.want_response_signed = True
ckanext.saml2auth.want_assertions_signed = False
ckanext.saml2auth.want_assertions_or_response_signed = False
# Cert & key files
ckanext.saml2auth.key_file_path = /path/to/mykey.pem
ckanext.saml2auth.cert_file_path = /path/to/mycert.pem
# Attribute map directory
ckanext.saml2auth.attribute_map_dir = /path/to/dir/attributemaps
# Authentication context request before redirect to login
# e.g. to ask for a PIV card with login.gov provider (https://developers.login.gov/oidc/#aal-values) use:
ckanext.saml2auth.requested_authn_context = http://idmanagement.gov/ns/assurance/aal/3?hspd12=true
# You can use multiple context separated by spaces
ckanext.saml2auth.requested_authn_context = req1 req2
# Define the comparison value for RequestedAuthnContext
# Comparison could be one of this: exact, minimum, maximum or better
ckanext.saml2auth.requested_authn_context_comparison = exact
# Indicates if this entity will sign the Logout Requests originated from it
ckanext.saml2auth.logout_requests_signed = False
# Saml logout request preferred binding settings variable
# Default: urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
ckanext.saml2auth.logout_expected_binding = urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST
# Default fallback endpoint to redirect to if no RelayState provided in the SAML Response
# Default: user.me (ie /dashboard)
# e.g. to redirect to the home page
ckanext.saml2auth.default_fallback_endpoint = home.index
## Plugin interface
This extension provides the [ISaml2Auth]{.title-ref} interface that
allows other plugins to hook into the Saml2 authorization flow. This
allows plugins to integrate custom logic like:
- Include additional attributes returned via the IdP as
[plugin_extras]{.title-ref} in the CKAN users
- Assign users to specific organizations with specific roles based on
Saml2 attributes
- Customize the flow response, to eg issue redirects or include custom
headers.
For a list of available methods and their parameters check the
[`ckanext/saml2auth/interfaces.py`](ckanext/saml2auth/interfaces.py)
file, and for a basic example see the
[`ExampleISaml2AuthPlugin`](ckanext/saml2auth/tests/test_interface.py)
class.
## Developer installation
To install ckanext-saml2auth for development, activate your CKAN
virtualenv and do:
sudo apt install xmlsec1
git clone https://github.com/duskobogdanovski/ckanext-saml2auth.git
cd ckanext-saml2auth
python setup.py develop
pip install -r dev-requirements.txt
## Tests
To run the tests, do:
pytest --ckan-ini=test.ini
To run the tests and produce a coverage report, first make sure you have
`pytest-cov` installed in your virtualenv (`pip install pytest-cov`)
then run:
pytest --ckan-ini=test.ini --cov=ckanext.saml2auth
## Releasing a new version of ckanext-saml2auth
ckanext-saml2auth should be available on PyPI as
<https://pypi.org/project/ckanext-saml2auth>. To publish a new version
to PyPI follow these steps:
1. Update the version number in the `setup.py` file. See [PEP
440](http://legacy.python.org/dev/peps/pep-0440/#public-version-identifiers)
for how to choose version numbers.
2. Make sure you have the latest version of necessary packages:
pip install --upgrade setuptools wheel twine
3. Create a source and binary distributions of the new version:
python setup.py sdist bdist_wheel && twine check dist/*
Fix any errors you get.
4. Upload the source distribution to PyPI:
twine upload dist/*
5. Commit any outstanding changes:
git commit -a
git push
6. Tag the new release of the project on GitHub with the version number
from the `setup.py` file. For example if the version number in
`setup.py` is 0.0.1 then do:
git tag 0.0.1
git push --tags
[CI]: https://github.com/keitaroinc/ckanext-saml2auth/workflows/CI/badge.svg
[1]: https://github.com/keitaroinc/ckanext-saml2auth/actions
[Coverage]: https://coveralls.io/repos/github/keitaroinc/ckanext-saml2auth/badge.svg?branch=main
[2]: https://coveralls.io/github/keitaroinc/ckanext-saml2auth?branch=main
[Gitter]: https://badges.gitter.im/keitaroinc/ckan.svg
[3]: https://gitter.im/keitaroinc/ckan?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge
[Pypi]: https://img.shields.io/pypi/v/ckanext-saml2auth
[4]: https://pypi.org/project/ckanext-saml2auth
[Python]: https://img.shields.io/badge/python-3.7%20%7C%203.8%20%7C%203.9-blue
[5]: https://www.python.org
[CKAN]: https://img.shields.io/badge/ckan-2.9-red
[6]: https://www.ckan.org
Raw data
{
"_id": null,
"home_page": "https://github.com/keitaroinc/ckanext-saml2auth",
"name": "ckanext-saml2auth",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "CKAN ckanext saml2 sso",
"author": "Keitaro Inc",
"author_email": "info@keitaro.com",
"download_url": "https://files.pythonhosted.org/packages/b4/82/45cfade3cadb93e38bfd03fa2add061c3f4196aac611cf1bb38e16acb2e9/ckanext-saml2auth-1.3.0.tar.gz",
"platform": null,
"description": "[![CI][]][1] [![Coverage][]][2] [![Gitter][]][3] [![Pypi][]][4] [![Python][]][5] [![CKAN][]][6]\n\n# ckanext-saml2auth\n\nA [CKAN](https://ckan.org) extension to enable Single Sign-On (SSO) for CKAN data portals via SAML2 Authentication.\n\n## Requirements\n\nThis extension works with CKAN 2.9+.\n\n## Installation\n\nTo install ckanext-saml2auth:\n\n1. Install the required system packages:\n\n sudo apt install xmlsec1\n\n2. Activate your CKAN virtual environment, for example:\n\n . /usr/lib/ckan/default/bin/activate\n\n3. Install the required system packages to install the necessary python\n module dependencies:\n\n # rustc and cargo are neeeded to build cryptography if no binary wheel exists\n sudo apt install rustc cargo\n\n4. Install the ckanext-saml2auth Python package into your virtual\n environment:\n\n pip install ckanext-saml2auth\n\n5. Add `saml2auth` to the `ckan.plugins` setting in your CKAN config\n file (by default the config file is located at\n `/etc/ckan/default/ckan.ini`).\n\n6. Restart CKAN. For example if you\\'ve deployed CKAN with Apache on\n Ubuntu:\n\n sudo service apache2 reload\n\n## Config settings\n\nRequired:\n\n # Specifies the metadata location type\n # Options: local or remote\n ckanext.saml2auth.idp_metadata.location = remote\n\n # Path to a local file accessible on the server the service runs on\n # Ignore this config if the idp metadata location is set to: remote\n ckanext.saml2auth.idp_metadata.local_path = /opt/metadata/idp.xml\n\n # A remote URL serving aggregate metadata\n # Ignore this config if the idp metadata location is set to: local\n ckanext.saml2auth.idp_metadata.remote_url = https://kalmar2.org/simplesaml/module.php/aggregator/?id=kalmarcentral2&set=saml2\n\n # Path to a local file accessible on the server the service runs on\n # Ignore this config if the idp metadata location is set to: local and metadata is public\n ckanext.saml2auth.idp_metadata.remote_cert = /opt/metadata/kalmar2.cert\n\n # Corresponding SAML user field for firstname\n ckanext.saml2auth.user_firstname = firstname\n\n # Corresponding SAML user field for lastname\n ckanext.saml2auth.user_lastname = lastname\n\n # Corresponding SAML user field for fullname\n # (Optional: Can be used as an alternative to firstname + lastname)\n ckanext.saml2auth.user_fullname = fullname\n\n # Corresponding SAML user field for email\n ckanext.saml2auth.user_email = email\n\n\nOptional:\n\n # URL route of the endpoint where the SAML assertion is sent, also known as Assertion Consumer Service (ACS).\n # Default: /acs\n ckanext.saml2auth.acs_endpoint = /sso/post\n\n # Configuration setting that enables CKAN's internal register/login functionality as well\n # Default: False\n ckanext.saml2auth.enable_ckan_internal_login = True\n\n # List of email addresses from users that should be created as sysadmins (system administrators)\n # Note that this means that CKAN sysadmins will _only_ be managed based on this config option and will override existing user permissions in the CKAN database\n # If not set then it is ignored and CKAN sysadmins are managed through normal means\n # Default: <Not set>\n ckanext.saml2auth.sysadmins_list = mail@domain.com mail2@domain.com mail3@domain.com\n\n # Indicates that attributes that are not recognized (they are not configured in attribute-mapping),\n # will not be discarded.\n # Default: True\n ckanext.saml2auth.allow_unknown_attributes = False\n\n # A list of string values that will be used to set the <NameIDFormat> element of the metadata of an entity.\n # Default: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent\n ckanext.saml2auth.sp.name_id_format = urn:oasis:names:tc:SAML:2.0:nameid-format:persistent urn:oasis:names:tc:SAML:2.0:nameid-format:transient\n\n # A string value that will be used to set the Format attribute of the <NameIDPolicy> element of the metadata of an entity.\n # Default: <Not set>\n ckanext.saml2auth.sp.name_id_policy_format = urn:oasis:names:tc:SAML:2.0:nameid-format:persistent\n\n # Entity ID (also know as Issuer)\n # Define the entity ID. Default is urn:mace:umu.se:saml:ckan:sp\n ckanext.saml2auth.entity_id = urn:gov:gsa:SAML:2.0.profiles:sp:sso:gsa:catalog-dev\n\n # Signed responses and assertions\n ckanext.saml2auth.want_response_signed = True\n ckanext.saml2auth.want_assertions_signed = False\n ckanext.saml2auth.want_assertions_or_response_signed = False\n\n # Cert & key files\n ckanext.saml2auth.key_file_path = /path/to/mykey.pem\n ckanext.saml2auth.cert_file_path = /path/to/mycert.pem\n\n # Attribute map directory\n ckanext.saml2auth.attribute_map_dir = /path/to/dir/attributemaps\n\n # Authentication context request before redirect to login\n # e.g. to ask for a PIV card with login.gov provider (https://developers.login.gov/oidc/#aal-values) use:\n ckanext.saml2auth.requested_authn_context = http://idmanagement.gov/ns/assurance/aal/3?hspd12=true\n # You can use multiple context separated by spaces\n ckanext.saml2auth.requested_authn_context = req1 req2\n\n # Define the comparison value for RequestedAuthnContext\n # Comparison could be one of this: exact, minimum, maximum or better\n ckanext.saml2auth.requested_authn_context_comparison = exact\n\n # Indicates if this entity will sign the Logout Requests originated from it\n ckanext.saml2auth.logout_requests_signed = False\n\n # Saml logout request preferred binding settings variable\n # Default: urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\n ckanext.saml2auth.logout_expected_binding = urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST\n\n # Default fallback endpoint to redirect to if no RelayState provided in the SAML Response\n # Default: user.me (ie /dashboard)\n # e.g. to redirect to the home page\n ckanext.saml2auth.default_fallback_endpoint = home.index\n\n## Plugin interface\n\nThis extension provides the [ISaml2Auth]{.title-ref} interface that\nallows other plugins to hook into the Saml2 authorization flow. This\nallows plugins to integrate custom logic like:\n\n- Include additional attributes returned via the IdP as\n [plugin_extras]{.title-ref} in the CKAN users\n- Assign users to specific organizations with specific roles based on\n Saml2 attributes\n- Customize the flow response, to eg issue redirects or include custom\n headers.\n\nFor a list of available methods and their parameters check the\n[`ckanext/saml2auth/interfaces.py`](ckanext/saml2auth/interfaces.py)\nfile, and for a basic example see the\n[`ExampleISaml2AuthPlugin`](ckanext/saml2auth/tests/test_interface.py)\nclass.\n\n## Developer installation\n\nTo install ckanext-saml2auth for development, activate your CKAN\nvirtualenv and do:\n\n sudo apt install xmlsec1\n git clone https://github.com/duskobogdanovski/ckanext-saml2auth.git\n cd ckanext-saml2auth\n python setup.py develop\n pip install -r dev-requirements.txt\n\n## Tests\n\nTo run the tests, do:\n\n pytest --ckan-ini=test.ini\n\nTo run the tests and produce a coverage report, first make sure you have\n`pytest-cov` installed in your virtualenv (`pip install pytest-cov`)\nthen run:\n\n pytest --ckan-ini=test.ini --cov=ckanext.saml2auth\n\n## Releasing a new version of ckanext-saml2auth\n\nckanext-saml2auth should be available on PyPI as\n<https://pypi.org/project/ckanext-saml2auth>. To publish a new version\nto PyPI follow these steps:\n\n1. Update the version number in the `setup.py` file. See [PEP\n 440](http://legacy.python.org/dev/peps/pep-0440/#public-version-identifiers)\n for how to choose version numbers.\n\n2. Make sure you have the latest version of necessary packages:\n\n pip install --upgrade setuptools wheel twine\n\n3. Create a source and binary distributions of the new version:\n\n python setup.py sdist bdist_wheel && twine check dist/*\n\n Fix any errors you get.\n\n4. Upload the source distribution to PyPI:\n\n twine upload dist/*\n\n5. Commit any outstanding changes:\n\n git commit -a\n git push\n\n6. Tag the new release of the project on GitHub with the version number\n from the `setup.py` file. For example if the version number in\n `setup.py` is 0.0.1 then do:\n\n git tag 0.0.1\n git push --tags\n \n\n [CI]: https://github.com/keitaroinc/ckanext-saml2auth/workflows/CI/badge.svg\n [1]: https://github.com/keitaroinc/ckanext-saml2auth/actions\n [Coverage]: https://coveralls.io/repos/github/keitaroinc/ckanext-saml2auth/badge.svg?branch=main\n [2]: https://coveralls.io/github/keitaroinc/ckanext-saml2auth?branch=main\n [Gitter]: https://badges.gitter.im/keitaroinc/ckan.svg\n [3]: https://gitter.im/keitaroinc/ckan?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge\n [Pypi]: https://img.shields.io/pypi/v/ckanext-saml2auth\n [4]: https://pypi.org/project/ckanext-saml2auth\n [Python]: https://img.shields.io/badge/python-3.7%20%7C%203.8%20%7C%203.9-blue\n [5]: https://www.python.org\n [CKAN]: https://img.shields.io/badge/ckan-2.9-red\n [6]: https://www.ckan.org\n",
"bugtrack_url": null,
"license": "AGPL",
"summary": "An extension to enable Single Sign On(SSO) for CKAN data portals via SAML2 Authentication.",
"version": "1.3.0",
"split_keywords": [
"ckan",
"ckanext",
"saml2",
"sso"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "9074856ab1ede4d272fcef10f306024b",
"sha256": "aae81e514b79f956a72c44ea06dcdf94db70a1a975ccae4d641f651e940ba3e5"
},
"downloads": -1,
"filename": "ckanext_saml2auth-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9074856ab1ede4d272fcef10f306024b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 44594,
"upload_time": "2022-12-14T10:50:54",
"upload_time_iso_8601": "2022-12-14T10:50:54.776095Z",
"url": "https://files.pythonhosted.org/packages/a9/9a/8b257da6dcc6d063d069115f08eb8b9c03af2aa727ada561baaab8dfac6d/ckanext_saml2auth-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "e3ed1bb60aa3680e9993571e57ce97e0",
"sha256": "1beb532a2902647ad704dd2e96a2c20829020e69cf3cd92bafd7c1d4e327e854"
},
"downloads": -1,
"filename": "ckanext-saml2auth-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "e3ed1bb60aa3680e9993571e57ce97e0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 36142,
"upload_time": "2022-12-14T10:50:56",
"upload_time_iso_8601": "2022-12-14T10:50:56.351755Z",
"url": "https://files.pythonhosted.org/packages/b4/82/45cfade3cadb93e38bfd03fa2add061c3f4196aac611cf1bb38e16acb2e9/ckanext-saml2auth-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-14 10:50:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "keitaroinc",
"github_project": "ckanext-saml2auth",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "ckanext-saml2auth"
}
JSON
