Requirements and enviroment¶
Install madiadb or whatever RDBMS supported by django ORM
sudo apt install xmlsec1 mariadb-server libmariadbclient-dev python3-dev python3-pip libssl-dev libmariadb-dev-compat libsasl2-dev libldap2-dev
pip3 install virtualenv
virtualenv -ppython3 uniauth.env
source uniauth.env/bin/activate
Example project¶
git clone https://github.com/UniversitaDellaCalabria/uniAuth.git
cd uniAuth
pip3 install -r requirements.txt
pip3 install -r requirements-customizations.txt
cd example/
./manage.py migrate
./manage.py createsuperuser
./manage.py runserver
Install uniAuth as a Django app¶
pip install uniauth-saml2-idp
Configure the software¶
You have to copy and edit the following files to have your configuration. The Database and all the Django settings ca be managed in settingslocal.py. SAML2 IdP and AA configuration must be configured in idp_pysaml2.py
cd django_idp
# copy and modify as your needs
cp settingslocal.py.example settingslocal.py
# copy and modify SAML2 IDP paramenters
cp idp_pysaml2.py.example idp_pysaml2.py
djangosaml2 parameters:
- SAML_IDP_CONFIG = {}
the PySAML2 IdP configuration, see example/django_idp/idp_pysaml2.py.example and pysaml2 official documentation.
- SAML_IDP_DJANGO_USERNAME_FIELD = ‘username’
Attribute used for SAML nameid. It must be a field name, a @property or a callable of the Django User model.
- SAML_COMPUTEDID_HASHALG = ‘sha256’
Global behaviour, which algorithm should be used to produce the computedID of a user. Used only for OPAQUE, TRANSIENT and PERSISTENT nameid format.
- SAML_COMPUTEDID_SALT = b’87sdf+ybDS+FDSFsdf__7yb’
Salt used to produce the computed id. Use
b''
to disable salt. Used only for TRANSIENT and PERSISTENT nameid format.- SAML_ALLOWCREATE = True
If enabled and nameid format is persistent the nameid related to user:recipient_id will be stored in PersistentId model
Platform specific parameters, each of these can be overriden in ServiceProvider configurations:
- SAML_IDP_SHOW_USER_AGREEMENT_SCREEN = True
Global behaviour, show or not the agreement screen.
- SAML_IDP_SHOW_CONSENT_FORM = False
Global behaviour, show or not the form for the consent to transmit the attributes.
- SAML_IDP_USER_AGREEMENT_ATTR_EXCLUDE = []
Global behaviour, if for some reason some attribute should be hidden in the agreement screen (discouraged!).
- SAML_IDP_USER_AGREEMENT_VALID_FOR = 24 * 365
User agreements will be valid for 1 year unless overriden. If this attribute is not used, user agreements will not expire.
- SAML_AUTHN_SIGN_ALG and SAML_AUTHN_DIGEST_ALG
Global behaviour, which algorithms should be used for SAML signature and digest.
- SAML_FORCE_ENCRYPTED_ASSERTION = False
It will only release encryoted assertion, default = False. SP without encryption key will not works with this configuration.
- SAML_DISALLOW_UNDEFINED_SP = True
Only configured SP are allowed to do Authentication requests. If
False
all the SP available in the MetadataStore can request an authentication.- DEFAULT_SPCONFIG = {
Default configuration that will be preloaded on every ServiceProvider configurations. Put here your favourite Attribute Processor or choose another one, from one of your custom application. See examples.
To configure new Metadata stores and federate new Service Providers
you can use metadata and SP definitions in idp_pysaml2.py
for
pysaml2 compatibility, otherwise you can create and manage them via
Django Admin backend. See dedicated sections for examples.
Create Database¶
You can even use sqlite3 for test purpose. If you want to use mariadb instead, create first the database and the user with the grants, then carry these parameters in your settingslocal.py file.
# create your MysqlDB
export USER='that-user'
export PASS='that-password'
export HOST='%'
export DB='uniauth'
# tested on Debian 10
sudo mysql -u root -e "\
CREATE USER IF NOT EXISTS '${USER}'@'${HOST}' IDENTIFIED BY '${PASS}';\
CREATE DATABASE IF NOT EXISTS ${DB} CHARACTER SET = 'utf8' COLLATE = 'utf8_general_ci';\
GRANT ALL PRIVILEGES ON ${DB}.* TO '${USER}'@'${HOST}';"
LDAP connection¶
You can use LDAP data source using ldap_peoples
ldap manager or pyMultiLDAP
apps.
If you don’t need a LDAP data source remove ldap_peoples
or multildap
from settingslocal.INSTALLED_APPS
.
ldap_peoples
is a fancy app to integrate a R&S LDAP manager.
On top of it you’ll find a custom authentication backend and a custom attribute processor,
you can even write your custom auth backend and processor with your preferred LDAP library.
If you need a fully compliant LDAP configuration with ldap_peoples
please try the
dedicated playbook for it.
If you need multiple LDAP data sources following ldap_peoples
approach
you’ll have to create your own django application and use types and methods found in ldap_peoples
.
If you do not want to create other django application or develop other things to manage multiple LDAP sources, you can use pyMultiLDAP as a proxy, through slapd-sock, or as a python LDAP Client. See settingslocal.py.example to have some usage examples.
Create your own SAML certificates¶
Then copy them to certificates
folder and define them in
idp_pysaml2.py (key_file
and cert_file
, even in
encryption_keypairs
).
openssl req -nodes -new -x509 -newkey rsa:2048 -days 3650 -keyout private.key -out public.cert
Create schemas and superuser¶
./manage.py migrate
./manage.py createsuperuser
Run debug server¶
./manage.py runserver
…need a SP for a preliminar tests? see djangosaml2_sp here: https://github.com/peppelinux/Django-Identity
Admin ui could be configured in settingslocal.py, with the variable ADMIN_PATH. If it is not defined, default will be admin/.
Production Environment¶
See uwsgi_setup examples.
Remember to run collectstatic
to copy all the static files in the production static folder:
./manage.py collectstatic
If you need more debug control with the same production configuration, using uwsgi you could run the following commands (absolute paths as examples):
/etc/init.d/unicalauth stop
uwsgi --ini /opt/unicalauth/uwsgi_setup/uwsgi.ini.debug