Package: djangosaml2-spid
SPID/CIE DjangoA SPID/CIE Service Provider based onpysaml2.IntroductionThis is a Django application that provides a SAML2 Service Provider
for a Single Sign On with SPID and CIE, the Italian Digital Identity System.This project comes with a demo on a Spid button template withspid-saml-checkIDP preconfigured.
See running the Demo project paragaph for details.Furthermore, this application integrates the checks ofSpid QAwithin its CI pipeline, throughspid-sp-test.
See github actions log for details.The technical documentation on SPID and SAML is available atDocs ItaliaThe technical documentation on CIE and SAML is available atDocs ItaliaDependenciesThese libraries are required on your operating system environment
in order to compile external modules of some dependencies:xmlsecpython3-devpython3-piplibssl-devlibsasl2-devRunning the Demo projectThe demo project is configured withinexample/subdirectory.
This project usesspid-saml-checkas demo IDP.Prepare environment:cd example/
virtualenv -ppython3 env
source env/bin/activate

pip install djangosaml2-spid⚠️ djangosaml2-spid uses amonkey-patchversion of the pysaml2 library that fixes
some limitations or small bugs that can affect SPID data. Patches are applied only
once after the app is ready to run. Take a look at moduledjangosaml2_spid._saml2for patches code and references.Your example saml2 configuration is inspid_config/spid_settings.py.
See djangosaml2 and pysaml2 official docs for clarifications.To run the demo project:python -B ./manage.py migratepython -B ./manage.py collectstatic --noinputuwsgi --https 0.0.0.0:8000,./certificates/public.cert,./certificates/private.key --module example.wsgi:application --env example.settings --chdir .or execute the run.sh script with these environment settings to enable tests IdPs:SPID_SAML_CHECK_IDP_ACTIVE=True SPID_DEMO_IDP_ACTIVE=True bash run.shIf you chose to use your own demo IdP you just have to save the
current demo metadata in the demo IdP configuration, this way:# cd into demo IdP metadata folder ...
wget https://localhost:8000/spid/metadata -O conf/sp_metadata.xmlFinally, start pid-saml-check (docker is suggested) and open 'https://localhost:8000' in your browser.Demo project with DockerTo use Docker compose environment, add to /etc/hosts this line:127.0.0.1   hostnetthen usedocker-compose --env-file docker-compose.env up(the process takes some time) and when the services are up go tohttp://hostnet:8000/spid/loginwarning: if you want to change ports of any of the docker-compose services (as, spid-saml-check) and/or the FQDN of the docker-compose default network gateway (defaults tohostnet) you need to change all the files
under./example/configs/to match the new configurations, changing only./docker-compose.envwill not suffice.Setup for an existing projectdjangosaml2_spid uses a pySAML2 fork.pip install git+https://github.com/italia/spid-djangoCopy theexample/spid_config/to your project base dir and remember to edit with your custom paramentersImport SAML2 entity configuration in your project settings file:from spid_config.spid_settings import *Add insettings.INSTALLED_APPSthe following'djangosaml2',
  'djangosaml2_spid',
  'spid_config'spid_configis your configuration, with statics and templates. Seeexampleproject.Add you custom User model, see example project:AUTH_USER_MODEL = 'custom_accounts.User'Add insettings.MIDDLEWARE:'djangosaml2.middleware.SamlSessionMiddleware'forSameSite CookieAdd insettings.AUTHENTICATION_BACKENDS:'django.contrib.auth.backends.ModelBackend',
  'djangosaml2.backends.Saml2Backend',Generate X.509 certificates and store them to a path, generally in./certificates, usingspid-compliant-certificatesRegister the SP metadata to your test Spid IDPsStart the django server for tests./manage.py runserver 0.0.0.0:8000SAML2 SPID compliant certificatesHere an example about how to do that.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 ../Minimal SPID settingsInstead of copy the whole demo project configuration you can add only the
necessary configuration entries (eg. SAML_CONFIG with 'organization' info,
and SPID_CONTACTS, other configurations that you want to be different from
defaults) directly to your project settings file. In this case don't
add'spid_config'tosettings.INSTALLED_APPS.An example of a minimal configuration for SPID is the following: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=FalseSAML_DJANGO_USER_MAIN_ATTRIBUTE='username'SAML_CREATE_UNKNOWN_USER=TrueSAML_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':'',},]⚠️ In the example project, inspid_settings.pywe founddisable_ssl_certificate_validationset to True. This is only for test/development purpose and its usage means that the "remote metadata" won't validate the https certificates. That's something not intended for production environment, remote metadata must be avoided and the tls validation must be adopted.Attribute MappingIs necessary to maps SPID attributes to Django ones.
An example that links fiscalNumber wiht username have been configured in the example project.
This is another example that achieve the same behaviour without changing the default User model.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', ),
}Download identity providers metadataTo update the list of entity providers use the custom django commandupdate_idps.
In the example project you can do it as follows:cd example/
python ./manage.py update_idpsRunning tests (only for developers)Tests are integrated into the demo project and are intended for use
only by developers.To test the application:pip install -r requirements-dev.txt
pip install -e .
python runtests.pyFor running tests using the settings of the Demo project:pip install -r requirements-dev.txt
cd example/
coverage erase
coverage run ./manage.py test djangosaml2_spid.tests
coverage report -mWarningsdebug server uses the same SAML2 certificates, please create your SAML2 certificates for production and also a real TLS one for httpd!Read djangosaml2 documentation, remember to set SESSION_COOKIE_SECURE in your project settings.pyThe SPID Button template is only for test purpose, please don't use it in production, do your customizations instead!In a production environment please don't use "remote" as metadata storage, use "local" or "mdq" instead!When using spid-saml-check via docker image, mind that the metadata download url would match tohttps://172.17.0.1:8000/spid/metadataand not to localhost!AuthorsGiuseppe De MarcoDavide Brunato