# ckanext-saml
Adds an ability to login from other source (known as
[IdP](https://en.wikipedia.org/wiki/Identity_provider_(SAML))) using
[SAML2](https://en.wikipedia.org/wiki/SAML_2.0) standard. Your instance is
presented as the [SP](https://en.wikipedia.org/wiki/Service_provider_(SAML)).
#### Requirements ####
``ckanext-saml`` uses ``python3-saml`` library in order to make requests to the
IdP and return responses from it. Github repository can be found
[here](https://github.com/onelogin/python3-saml). There you can also find
examples of fields that can be used in ``settings.json`` and
``advanced_settings.json``.
#### Installation ####
To install ``ckanext-saml``:
1. Install additional packages (example is shown for CentOS):
yum install python3-devel xmlsec1-devel libtool-ltdl-devel
1. Install extension:
pip install ckanext-saml
1. Add ``saml`` to the ``ckan.plugins`` setting in your CKAN config file.
1. Initialize new table (if you previously used
[ckanext-saml2](https://github.com/datashades/ckanext-saml2), you can skip
this step or make sure that you have saml2_user table in your DB):
ckan db upgrade -p saml
If error that mentioned below appears on CentOS, you might need to install
additional packages - ``yum install libxml2-devel xmlsec1-devel
xmlsec1-openssl-devel libtool-ltdl-devel``:
import xmlsec
SystemError: null argument to internal routine
#### Configuration ####
Before start configuring, make sure that the config setting
``ckan.saml_custom_base_path`` is set if your config file is not stored at
``/etc/ckan/default`` directory.
Copy the ``saml`` folder from ``ckanext-saml`` into the directory where your
CKAN config file is placed:
cp -R saml_example/saml YOUR_CONFIG_DIRECTORY/saml
Open the ``settings.json`` file that is in your copied ``saml`` folder in order
to modify it.
**Configure main settings file**
The main sections that should be updated within the file are ``sp`` and ``idp``
In order to make it more clear lets start from configuring ``idp``:
1. Modify ``entityId`` by filling it with the ``entityID`` that should be
present in the ``idp_metadata.xml`` file (name of the file can be different)
that is been sent to you by the IdP.
2. Modify ``url`` in ``singleSignOnService``. You can find this ``url`` in
``idp_metadata.xml`` at ``SingleSignOnService`` section, it should have
``Location`` attribute where the url is specified.
3. Modify ``x509cert`` by filling it with the`` X509Certificate`` that should
be present in ``idp_metadata.xml``. Make sure the this set as a **single
line string**.
**Note**: ``singleLogoutService`` is not implemented.
Modifications for ``sp`` (CKAN):
1. Modify ``entityId`` with the domain name of your portal.
2. Modify ``url`` in ``assertionConsumerService`` with the domain name of your
portal plus adding ``/saml/`` at the end. This is the URL where IdP will
send back the reponse with User Data. Make sure the the slash is present in
the end of the URL.
``advanced_settings.json`` is used for additional configurations such as
security. It also needed to modify the ``contactPerson`` and ``organization``
sections in it if your are going to provide your SP data to your IdP.
After updating all mentioned values in ``settings.json``, at
``DOMAIN_NAME/saml/metadata URL`` you can find the ``sp.xml`` generated, which
you can provide to the IdP for configuration on their side.
The main infomation that is needed for the IdP is the
``AssertionConsumerService``(ACS) which is should be set on their APP for
SAML. ``AssertionConsumerService`` should match to what you have in your
settings.json and IdP APP, otherwise errors might appear.
#### Config settings ####
- ``ckan.saml_use_https`` - Used to send data while **https**, set ``on`` to
enable it. By **default** is set to ``off`` and uses **http**.
- ``ckan.saml_use_nameid_as_email`` - Set to ``true`` if you want to use NameID
as an email for the User in order not to claim it additionally from the
IdP. Default is set to ``false``.
- ``ckan.saml_login_button_text`` - Provides an ability to customize login
button text. By **default** set to ``SAML Login``.
- ``ckan.saml_custom_base_path`` - Provides custom path where saml
files/folders will be searched. By **default** set to
``/etc/ckan/default/saml``.
- ``ckan.saml_custom_attr_map`` - Used to modify mapper filename. By
**default** searches for ``mapper.py``.
- ``ckan.saml_use_root_path`` - This needs to be set to ``true`` if you run
your portal using the ``ckan.root_path``. By **default** set to ``false``.
- ``ckan.saml_relaystate`` - Set a custom RelayState ``path``. By **default**
set to ``/dashboard``.
#### SP Metadata file ####
As mentioned above, you can find SP metadata at ``DOMAIN_NAME/saml/metadata
URL`` after configuring ``advanced_settings.json``. This **URL** is accessible
only to ``sysadmins`` and presented in **XML** format. Additional tab on
``/ckan-admin/`` is added, that leads to this page.
#### Data encryption ####
In order to encrypt the coming data from the IdP use ``advanced_settings.json``
file. In ``security`` section, you can enable encryption for NAMEID and all
other data that will be returned to the SP.
If you enable one of
``authnRequestsSigned``,``logoutRequestSigned``,``logoutResponseSigned``,``wantAssertionsEncrypted``,
``wantNameIdEncrypted`` (you can find description of earch option
[here](https://github.com/onelogin/python3-saml#how-it-works)), you will have
to create [x509 certificate](https://en.wikipedia.org/wiki/X.509) in you
SP. Cerificate should be created in ``certs`` folder, files should be named as
``sp.crt`` and ``sp.key`` (private key). After creating it, your ``sp.xml``
will show you public key ``ds:X509Certificate`` that should be delivered to
your IdP in order to configure encryption.
#### Extras ####
ckanext-saml has interface ``ICKANSAML`` which has two hooks that can be used
for User data modificaiton and Organization memberships logic while login.
- ``after_mapping`` - Used after Users data is being mapped, but before the
User is being created.
- ``roles_and_organizations`` - Used for adding custom logic for Organization
membeship that is going to be applied to the User. There is no default logic
for this, so should be added in your custom extension using this hook.
Raw data
{
"_id": null,
"home_page": "https://github.com/DataShades/ckanext-saml",
"name": "ckanext-saml",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "CKAN",
"author": "Yan Rudendo",
"author_email": "yan.rudenko@linkdigital.com.au",
"download_url": "https://files.pythonhosted.org/packages/4a/50/ffc0cf27e8c9a0aacc5e052b53bc149b95633d21b33066d655bac4ef9575/ckanext_saml-0.3.3.tar.gz",
"platform": null,
"description": "# ckanext-saml\n\nAdds an ability to login from other source (known as\n[IdP](https://en.wikipedia.org/wiki/Identity_provider_(SAML))) using\n[SAML2](https://en.wikipedia.org/wiki/SAML_2.0) standard. Your instance is\npresented as the [SP](https://en.wikipedia.org/wiki/Service_provider_(SAML)).\n\n#### Requirements ####\n``ckanext-saml`` uses ``python3-saml`` library in order to make requests to the\nIdP and return responses from it. Github repository can be found\n[here](https://github.com/onelogin/python3-saml). There you can also find\nexamples of fields that can be used in ``settings.json`` and\n``advanced_settings.json``.\n\n#### Installation ####\n\nTo install ``ckanext-saml``:\n\n1. Install additional packages (example is shown for CentOS):\n\n\t\tyum install python3-devel xmlsec1-devel libtool-ltdl-devel\n\n1. Install extension:\n\n\t\tpip install ckanext-saml\n\n1. Add ``saml`` to the ``ckan.plugins`` setting in your CKAN config file.\n\n1. Initialize new table (if you previously used\n [ckanext-saml2](https://github.com/datashades/ckanext-saml2), you can skip\n this step or make sure that you have saml2_user table in your DB):\n\n\t\tckan db upgrade -p saml\n\nIf error that mentioned below appears on CentOS, you might need to install\nadditional packages - ``yum install libxml2-devel xmlsec1-devel\nxmlsec1-openssl-devel libtool-ltdl-devel``:\n\n\t\timport xmlsec\n\t\tSystemError: null argument to internal routine\n\n#### Configuration ####\n\nBefore start configuring, make sure that the config setting\n``ckan.saml_custom_base_path`` is set if your config file is not stored at\n``/etc/ckan/default`` directory.\n\nCopy the ``saml`` folder from ``ckanext-saml`` into the directory where your\nCKAN config file is placed:\n\n\t\tcp -R saml_example/saml YOUR_CONFIG_DIRECTORY/saml\n\nOpen the ``settings.json`` file that is in your copied ``saml`` folder in order\nto modify it.\n\n**Configure main settings file**\n\nThe main sections that should be updated within the file are ``sp`` and ``idp``\n\nIn order to make it more clear lets start from configuring ``idp``:\n\n1. Modify ``entityId`` by filling it with the ``entityID`` that should be\n present in the ``idp_metadata.xml`` file (name of the file can be different)\n that is been sent to you by the IdP.\n\n2. Modify ``url`` in ``singleSignOnService``. You can find this ``url`` in\n ``idp_metadata.xml`` at ``SingleSignOnService`` section, it should have\n ``Location`` attribute where the url is specified.\n\n3. Modify ``x509cert`` by filling it with the`` X509Certificate`` that should\n be present in ``idp_metadata.xml``. Make sure the this set as a **single\n line string**.\n\n**Note**: ``singleLogoutService`` is not implemented.\n\nModifications for ``sp`` (CKAN):\n\n1. Modify ``entityId`` with the domain name of your portal.\n\n2. Modify ``url`` in ``assertionConsumerService`` with the domain name of your\n portal plus adding ``/saml/`` at the end. This is the URL where IdP will\n send back the reponse with User Data. Make sure the the slash is present in\n the end of the URL.\n\n``advanced_settings.json`` is used for additional configurations such as\nsecurity. It also needed to modify the ``contactPerson`` and ``organization``\nsections in it if your are going to provide your SP data to your IdP.\n\nAfter updating all mentioned values in ``settings.json``, at\n``DOMAIN_NAME/saml/metadata URL`` you can find the ``sp.xml`` generated, which\nyou can provide to the IdP for configuration on their side.\n\nThe main infomation that is needed for the IdP is the\n``AssertionConsumerService``(ACS) which is should be set on their APP for\nSAML. ``AssertionConsumerService`` should match to what you have in your\nsettings.json and IdP APP, otherwise errors might appear.\n\n\n#### Config settings ####\n\n- ``ckan.saml_use_https`` - Used to send data while **https**, set ``on`` to\n enable it. By **default** is set to ``off`` and uses **http**.\n\n- ``ckan.saml_use_nameid_as_email`` - Set to ``true`` if you want to use NameID\n as an email for the User in order not to claim it additionally from the\n IdP. Default is set to ``false``.\n\n- ``ckan.saml_login_button_text`` - Provides an ability to customize login\n button text. By **default** set to ``SAML Login``.\n\n- ``ckan.saml_custom_base_path`` - Provides custom path where saml\n files/folders will be searched. By **default** set to\n ``/etc/ckan/default/saml``.\n\n- ``ckan.saml_custom_attr_map`` - Used to modify mapper filename. By\n **default** searches for ``mapper.py``.\n\n- ``ckan.saml_use_root_path`` - This needs to be set to ``true`` if you run\n your portal using the ``ckan.root_path``. By **default** set to ``false``.\n\n- ``ckan.saml_relaystate`` - Set a custom RelayState ``path``. By **default**\n set to ``/dashboard``.\n\n#### SP Metadata file ####\n\nAs mentioned above, you can find SP metadata at ``DOMAIN_NAME/saml/metadata\nURL`` after configuring ``advanced_settings.json``. This **URL** is accessible\nonly to ``sysadmins`` and presented in **XML** format. Additional tab on\n``/ckan-admin/`` is added, that leads to this page.\n\n#### Data encryption ####\n\nIn order to encrypt the coming data from the IdP use ``advanced_settings.json``\nfile. In ``security`` section, you can enable encryption for NAMEID and all\nother data that will be returned to the SP.\n\nIf you enable one of\n``authnRequestsSigned``,``logoutRequestSigned``,``logoutResponseSigned``,``wantAssertionsEncrypted``,\n``wantNameIdEncrypted`` (you can find description of earch option\n[here](https://github.com/onelogin/python3-saml#how-it-works)), you will have\nto create [x509 certificate](https://en.wikipedia.org/wiki/X.509) in you\nSP. Cerificate should be created in ``certs`` folder, files should be named as\n``sp.crt`` and ``sp.key`` (private key). After creating it, your ``sp.xml``\nwill show you public key ``ds:X509Certificate`` that should be delivered to\nyour IdP in order to configure encryption.\n\n#### Extras ####\n\nckanext-saml has interface ``ICKANSAML`` which has two hooks that can be used\nfor User data modificaiton and Organization memberships logic while login.\n\n- ``after_mapping`` - Used after Users data is being mapped, but before the\n User is being created.\n\n- ``roles_and_organizations`` - Used for adding custom logic for Organization\n membeship that is going to be applied to the User. There is no default logic\n for this, so should be added in your custom extension using this hook.\n",
"bugtrack_url": null,
"license": "AGPL",
"summary": null,
"version": "0.3.3",
"project_urls": {
"Homepage": "https://github.com/DataShades/ckanext-saml"
},
"split_keywords": [
"ckan"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "cb950b3b8054f9ea77c4d3fc825c34d0240d7fc4d44489dcf86824bc8d06d834",
"md5": "bee3a0bbf0f921dedebb691b506066cf",
"sha256": "a7ea5e0ac17f638628fa2d5fb6f871d48929b46f0e806a9362c13ec5b31cbbdb"
},
"downloads": -1,
"filename": "ckanext_saml-0.3.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bee3a0bbf0f921dedebb691b506066cf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 34101,
"upload_time": "2024-04-18T16:35:26",
"upload_time_iso_8601": "2024-04-18T16:35:26.478685Z",
"url": "https://files.pythonhosted.org/packages/cb/95/0b3b8054f9ea77c4d3fc825c34d0240d7fc4d44489dcf86824bc8d06d834/ckanext_saml-0.3.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4a50ffc0cf27e8c9a0aacc5e052b53bc149b95633d21b33066d655bac4ef9575",
"md5": "ed5626eb30efc585b24ff79f576c7dc0",
"sha256": "8cc7ba43b7a41e696fe74bc03e467b603fa6a834759e116a3950823f4317b899"
},
"downloads": -1,
"filename": "ckanext_saml-0.3.3.tar.gz",
"has_sig": false,
"md5_digest": "ed5626eb30efc585b24ff79f576c7dc0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 30892,
"upload_time": "2024-04-18T16:35:29",
"upload_time_iso_8601": "2024-04-18T16:35:29.226982Z",
"url": "https://files.pythonhosted.org/packages/4a/50/ffc0cf27e8c9a0aacc5e052b53bc149b95633d21b33066d655bac4ef9575/ckanext_saml-0.3.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-18 16:35:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DataShades",
"github_project": "ckanext-saml",
"travis_ci": true,
"coveralls": true,
"github_actions": false,
"requirements": [],
"lcname": "ckanext-saml"
}
JSON
