djangosaml2-spid 1.1.4

SPID/CIE Django

基于pysaml2的SPID/CIE服务提供商。

简介

这是一个Django应用，为与SPID和CIE的单点登录提供SAML2服务提供商，这是意大利数字身份系统。

该项目包含一个Spid按钮模板的演示，预配置了spid-saml-check IDP。有关详细信息，请参阅运行演示项目段落。

此外，此应用程序通过spid-sp-test将其CI管道中的Spid QA检查集成，并通过Spid QA。有关详细信息，请参阅github actions日志。

有关SPID和SAML的技术文档可在Docs Italia找到。有关CIE和SAML的技术文档可在Docs Italia找到。

依赖项

为了编译某些依赖项的外部模块，这些库需要在您的操作系统环境中使用。

• xmlsec
• python3-dev
• python3-pip
• libssl-dev
• libsasl2-dev

运行演示项目

演示项目配置在example/子目录中。此项目使用spid-saml-check作为演示IDP。

准备环境

cd example/
virtualenv -ppython3 env
source env/bin/activate

pip install djangosaml2-spid

⚠️ djangosaml2-spid 使用了一个 猴子补丁 版本的 pysaml2 库，该库修复了一些可能影响 SPID 数据的限制或小错误。补丁仅在应用准备就绪后应用一次。查看模块 djangosaml2_spid._saml2 中的补丁代码和参考。

您的 saml2 配置示例位于 spid_config/spid_settings.py。有关说明，请参阅 djangosaml2 和 pysaml2 的官方文档。

要运行演示项目

• python -B ./manage.py migrate
• python -B ./manage.py collectstatic --noinput
• uwsgi --https 0.0.0.0:8000,./certificates/public.cert,./certificates/private.key --module example.wsgi:application --env example.settings --chdir .

或使用以下环境设置执行 run.sh 脚本来启用测试 IdP

SPID_SAML_CHECK_IDP_ACTIVE=True SPID_DEMO_IDP_ACTIVE=True bash run.sh

如果您选择使用自己的演示 IdP，只需将当前演示元数据保存到演示 IdP 配置中即可，方法如下

# cd into demo IdP metadata folder ...
wget https://localhost:8000/spid/metadata -O conf/sp_metadata.xml

最后，启动 pid-saml-check（建议使用 docker）并在您的浏览器中打开 'https://localhost:8000'。

使用 Docker 的演示项目

要使用 Docker Compose 环境，请将以下行添加到 /etc/hosts

127.0.0.1   hostnet

然后使用 docker-compose --env-file docker-compose.env up（此过程需要一些时间）并当服务启动后，访问 http://hostnet:8000/spid/login

警告：如果您想更改 docker-compose 服务的端口（如 spid-saml-check）和/或 docker-compose 默认网络网关的 FQDN（默认为 hostnet），您需要更改 ./example/configs/ 下的所有文件以匹配新的配置，仅更改 ./docker-compose.env 是不够的。

现有项目的设置

djangosaml2_spid 使用 pySAML2 分支。

• pip install git+https://github.com/italia/spid-django
• 将 example/spid_config/ 复制到您的项目基本目录，并记得使用自定义参数进行编辑
• 将 SAML2 实体配置导入到您的项目设置文件中：from spid_config.spid_settings import *
• 在 settings.INSTALLED_APPS 中添加以下内容

    'djangosaml2',
    'djangosaml2_spid',
    'spid_config'
  

  spid_config 是您的配置，包含静态文件和模板。参见 example 项目。
• 添加您自定义的用户模型，参见示例项目：AUTH_USER_MODEL = 'custom_accounts.User'
• 在 settings.MIDDLEWARE 中添加：'djangosaml2.middleware.SamlSessionMiddleware' 用于 SameSite Cookie
• 在 settings.AUTHENTICATION_BACKENDS 中添加

    'django.contrib.auth.backends.ModelBackend',
    'djangosaml2.backends.Saml2Backend',
  

• 使用 spid-compliant-certificates 生成 X.509 证书并将它们存储在路径中，通常在 ./certificates，使用
• 将 SP 元数据注册到您的测试 Spid IDP
• 启动 django 服务器进行测试 ./manage.py runserver 0.0.0.0:8000

SAML2 SPID 兼容证书

以下是如何做到这一点的示例。

mkdir certificates && cd "$_"

spid-compliant-certificates generator \
    --key-size 3072 \
    --common-name "A.C.M.E" \
    --days 365 \
    --entity-id https://spid.acme.it \
    --locality-name Roma \
    --org-id "PA:IT-c_h501" \
    --org-name "A Company Making Everything" \
    --sector public \
    --key-out private.key \
    --crt-out public.cert

cd ../

SPID 设置的最小值

您不需要复制整个演示项目配置，只需将必要的配置条目（例如，带有 'organization' 信息的 SAML_CONFIG，以及 SPID_CONTACTS，您想要与默认设置不同的其他配置）直接添加到您的项目设置文件中。在这种情况下，不要将 'spid_config' 添加到 settings.INSTALLED_APPS。

SPID 的最小配置示例如下

SAML_CONFIG = {
    'entityid': 'https://your.spid.url/metadata',
    'organization': {
        'name': [('Example', 'it'), ('Example', 'en')],
        'display_name': [('Example', 'it'), ('Example', 'en')],
        'url': [('http://www.example.it', 'it'), ('http://www.example.it', 'en')],
    },
}

SAML_USE_NAME_ID_AS_USERNAME = False
SAML_DJANGO_USER_MAIN_ATTRIBUTE = 'username'
SAML_CREATE_UNKNOWN_USER = True
SAML_DJANGO_USER_MAIN_ATTRIBUTE_LOOKUP = '__iexact'
SAML_ATTRIBUTE_MAPPING = {
    'spidCode': ('username', ),
    'email': ('email', ),
    'name': ('first_name', ),
    'familyName': ('last_name', ),
}

SPID_CONTACTS = [
    {
        'contact_type': 'other',
        'telephone_number': '+39 8475634785',
        'email_address': 'tech-info@example.org',
        'VATNumber': 'IT12345678901',
        'FiscalCode': 'XYZABCAAMGGJ000W',
        'Private': '',
    },
]

⚠️ 在示例项目中，在 spid_settings.py 中，我们发现 disable_ssl_certificate_validation 设置为 True。这仅适用于测试/开发目的，并且其使用意味着 "远程元数据" 不会验证 https 证书。这不是生产环境所期望的，应避免使用远程元数据，并采用 tls 验证。

属性映射

需要将 SPID 属性映射到 Django 上。示例项目中已配置了一个将 fiscalNumber 与用户名链接的示例。这是另一个不更改默认用户模型而实现相同行为的示例。

SAML_USE_NAME_ID_AS_USERNAME = False
SAML_DJANGO_USER_MAIN_ATTRIBUTE = 'username'
SAML_CREATE_UNKNOWN_USER = True
SAML_DJANGO_USER_MAIN_ATTRIBUTE_LOOKUP = '__iexact'

SAML_ATTRIBUTE_MAPPING = {
'fiscalNumber': ('username', ),
}

下载身份提供者的元数据

要更新实体提供者列表，请使用自定义 Django 命令 update_idps。在示例项目中，您可以这样做：

cd example/
python ./manage.py update_idps

运行测试（仅限开发者）

测试已集成到演示项目中，仅供开发者使用。

要测试应用程序

pip install -r requirements-dev.txt
pip install -e .
python runtests.py

使用演示项目的设置运行测试

pip install -r requirements-dev.txt
cd example/
coverage erase
coverage run ./manage.py test djangosaml2_spid.tests
coverage report -m

警告

• 调试服务器使用相同的 SAML2 证书，请为生产环境创建 SAML2 证书，并为 httpd 创建一个真实的 TLS 证书！
• 阅读 djangosaml2 文档，请记住在您的项目 settings.py 中设置 SESSION_COOKIE_SECURE
• SPID 按钮模板仅供测试目的，请在生产环境中不要使用它，而是进行自定义！
• 在生产环境中，请勿使用“远程”作为元数据存储，请使用“本地”或“mdq”代替！
• 当使用通过 Docker 镜像的 spid-saml-check 时，请注意元数据下载 URL 将匹配到 https://172.17.0.1:8000/spid/metadata 而不是 localhost！

作者

• Giuseppe De Marco
• Davide Brunato