authentic2 documentation - read the docs · authentic2 documentation, release 2.0.2 authentic 2 is...
TRANSCRIPT
Authentic2 DocumentationRelease 202
Entrrsquoouvert
June 17 2016
Contents
1 Overview 3
2 Installation and quickstart tutorials 5
3 Configuration 13
4 Advanced topics 63
5 Copyright 65
i
ii
Authentic2 Documentation Release 202
Authentic 2 is a versatile identity management server aiming to address a broad range of needs from simple to complexsetups it has support for many protocols and can bridge between them
Authentic 2 supports many protocols and standards including SAML2 CAS OpenID LDAP X509 and OAUTH2
Authentic 2 is under the GNU AGPL version 3 licence
It has support for SAMLv2 thanks to Lasso a free (GNU GPL) implementation of the Liberty Alliance and OASISspecifications of SAML2
Consult current Authentic 2 activity on the project site
If you donrsquot find an explanation you donrsquot understand it or one is missing please report it on the list
Contents 1
Authentic2 Documentation Release 202
2 Contents
CHAPTER 1
Overview
Authentic 2 is a versatile identity management server aiming to address a broad range of needs from simple to complexsetups it has support for many protocols and can bridge between them
Authentic 2 supports many protocols and standards including SAML2 CAS OpenID LDAP X509 and OAUTH2
Authentic 2 is under the GNU AGPL version 3 licence
It has support for SAMLv2 thanks to Lasso a free (GNU GPL) implementation of the Liberty Alliance and OASISspecifications of SAML2
Authentic 2 requires Python 27 et Django 15
11 Features
bull SAML 20 Identity and service provider
bull OpenID 10 and 20 identity provider
bull Server CAS 10 and 20 using a plugin
bull Standards authentication mechanisms
ndash Loginpassword through internal directory or LDAP
ndash X509 certificate over SSLTLS
bull Protocol proxying for instance between OpenID and SAML
bull Support of LDAP v2 and v3 directories
bull Support of the PAM backend
bull One-time password (OATH and Google-Authenticator) using a plugin
bull Identity attribute management
bull Plugin system
12 Source and issue tracker
You can find on the project site authenticentrouvertorg mainly the issue tracker
You can find there a viewer of the git repository or clone it
3
Authentic2 Documentation Release 202
git clone httpreposentrouvertorgauthenticgit
13 Support
Authenticrsquos developpers and users hangs on the mailing list authenticlistesentrouvertcom See archives or registerat httplistesentrouvertcominfoauthentic
You can open reports or feature request on httpauthenticentrouvertorg
Entrrsquoouvert also provides a commercial support For information visit httpwwwentrouvertcom
4 Chapter 1 Overview
CHAPTER 2
Installation and quickstart tutorials
Yoursquoll find here how to start and configure very quickly Authentic 2 for its main features You just need Python 27and Django 15
First of all you can boot Authentic vwithout root privileges like this
1 Initialize a virtualenv
virtualenv authenticsource authenticbinactivatecd authentic
2 Install Authentic
pip install authentic2
3 Initialize the database migrations
authentic2-ctl syncdb --migrate
4 Run the HTTP test server
authentic2-ctl runserver
21 Quickstart guides and installation guidelines
211 Installation modes
The current version of Authentic 2 works with Python 27 and Django 15
Authentic 2 python installation script handles all the dependencies except Lasso relying on the Setuptools and thepypi repository
To run Authentic 2 with SAML2 features you need to install lasso gt= 236 see Lasso installation
The other Authentic 2 dependencies are
bull Djangolt16
bull southgt=084
bull requests
bull django-model-utils
bull django-registrationgt=1
5
Authentic2 Documentation Release 202
bull django-debug-toolbargt=12lt13
bull ndashallow-external django-admin-tools
bull ndashallow-unverified django-admin-tools
bull django-admin-toolsgt=051
bull dnspython
bull django-select2
bull django-tables2
bull gadjo
bull django-import-export
bull django-sekizai
Install Authentic 2
bull Install Authentic directly from pypi
bull Obtain the last package archive from pypi
bull Obtain the last sources from the Git repository
Lasso installation
Lasso is available in the linux debian destribution repositories If you are installing Authentic 2 on debian just execute
apt-get install python-lasso
Yoursquoll find more updated packages on httpdebentrouvertorg
We also provide rpm packages for redhat see httpsdeventrouvertorgredhatREADME
You can also install lasso from sources httplassoentrouvertorgdownload
See the Lasso website for installation details This is a quick installation example
Install the following Lasso dependencies
bull autoconf
bull automake
bull autotools-dev
bull libtool
bull gtk-doc-tools
bull zlib1g-dev
bull libglib20-dev
bull openssl-dev
bull libxml2-dev
bull libxmlsec1-dev
bull python26-dev
bull python-setuptools
Obtain Lasso
6 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
$wget httpsdeventrouvertorglassolasso-236targz$tar xzvf lasso-236targz$cd lasso-236$autogensh
Be sure that the Python bindings is selected as follows
=============Configuration=============
Main----
Compiler gccCFLAGSInstall prefix usrlocalDebugging noExperimental ID-WSF no
Optionals builds----------------
Available languages java(461) python(27) perl(5124)
Java binding yesPerl binding yesPHP 5 binding noPython binding yes
C API references yesTests suite no
Now type make install to install lasso
As indicated build and install
$make install$ldconfig
Set the lasso python binding in you python path eg
$export PYTHONPATH=$PYTHONPATHusrlocallibpython26site-packages
Test trying to import Lasso
$pythongtgtgt import lasso
Install Authentic directly from pypi
Using pip
pip install authentic2
You can now run Authentic from the installation directory
21 Quickstart guides and installation guidelines 7
Authentic2 Documentation Release 202
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last package archive from pypi
Download the archive on httppypipythonorgpypiauthentic2
Then you can install it directly from the archive using pip
pip install authentic2-xzytargz
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last sources from the Git repository
Clone the repository
git clone httpreposentrouvertorgauthenticgit
Then you can install it directly using pip
cd authenticpip install -e
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
8 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
212 Specifying a different database
This is done by modifying the DATABASES dictionary in your local_settingspy file (create it in Authentic projectdirectory) for example
DATABASES[default] = ENGINE djangodbbackendspostgresqlNAME authenticUSER admindbPASSWORD foobarHOST dbexamplecomPORT empty string means default value
You should refer to the Django documentation on databases settings athttpdocsdjangoprojectcomendevrefsettingsdatabases for all the details
213 Upgrading
Update using pip
pip install -U authentic2
Authentic store all its data in a relational database as specified in its settingspy or local_settingspy file So in order toupgrade to a new version of authentic you have to update your database schema using the migration command mdash youwill need to have installed the dependency django-south see the beginning of this README file
authentic2-ctl syncdb --migrate
214 Running Authentic 2 for real (Nginx Apache etc)
DEBUG Mode by default static files and the Django debug toolbar dependency
By default Authentic 2 is in the DEBUG mode We made this default choice because most of the Authentic 2rsquos userswill begin with Authentic 2 using the Django development server (runserver command) and we want to avoid them abad first impression because static files would not be served As a matter of fact static files are served by the Djangodevelopment server only when the project is run in the DEBUG mode
In the DEBUG mode the Django debug toolbar is used what adds a dependency
In production the Django development server should not be used to serve Authentic 2 and a dedicated server shouldalso be used to serve the static files
21 Quickstart guides and installation guidelines 9
Authentic2 Documentation Release 202
Set Authentic into the no DEBUG Mode
It is enough to edit authentic2settingspy and set
DEBUG = False
From then on the django-debug-toolbar package is not necessary anymore
Use dedicated HTTP servers and serve static files
The best is to use a server dedicated to serve the Django applications and a different server to serve the static files
You could for instance use apache with mod_wsgi to serve Authentic 2 You will find configuration file examples inthe debian directory of the Authentic 2 sources
Then you may want to use nginx to serve the static files
First you need to collect the Authentic 2 static files The static files are collected using the collectstatic command thatis configured in the settingspy
By default running collectstatic will create a static directory in the parent directory of the authentic2 directory
$python authentic2managepy collectstatic
That static directory will contain all the static files of Authentic 2
If you want to change the path of the static directory you can edit STATIC_ROOT of the settings file
See httpsdocsdjangoprojectcomendevrefcontribstaticfiles for more information about collectstatic
215 Quickstarts
Quickstart an OAuth2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6053
Quickstart an SAML2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6057
Quickstart a connection with a SAML2 Service Provider
1 Get the Identity Provider SAML2 metadata file
http[s]yourdomaincomidpsaml2metadata
2 Configure your service provider with it
3 Go to the providers admin panel on
http[s]adminsamllibertyprovideradd
There create a new provider using the service provider metadata and enable it as a service provider
10 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Quickstart a CAS Identity Provider
1 Activate CAS IdP support in your local_settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
authentic2-ctl syncdb ndashall authentic2-ctl migrate ndashfake
2 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
3 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
Quickstart to connect a LDAP Directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django for this you need python-ldap python-ldap needs python de-velopement headers to be installed but is usually packaged by most distributions
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP The next lines must be added
AUTHENTICATION_BACKENDS += ( lsquodjango_auth_ldapbackendLDAPBackendrsquo )
import ldap from django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your server AUTH_LDAP_SERVER_URI = lsquoldapldapexamplecomlsquo Let the bind DN and bind password blank for anonymous binding AUTH_LDAP_BIND_DN = ldquordquoAUTH_LDAP_BIND_PASSWORD = ldquordquo Lookup user under the branch o=base and by mathcing theiruid against the received login name AUTH_LDAP_USER_SEARCH = LDAPSearch(ldquoo=baserdquo
ldapSCOPE_SUBTREE ldquo(uid=(user)s)rdquo)
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesType AUTH_LDAP_GROUP_TYPE = GroupOf-NamesType() AUTH_LDAP_GROUP_SEARCH = LDAPSearch(ldquoo=mycompanyrdquo
ldapSCOPE_SUBTREE ldquo(objectClass=groupOfNames)rdquo)
AUTH_LDAP_USER_FLAGS_BY_GROUP = ldquois_staffrdquo ldquocn=admino=mycompanyrdquo
21 Quickstart guides and installation guidelines 11
Authentic2 Documentation Release 202
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
Quickstart for PAM Authentication
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
12 Chapter 2 Installation and quickstart tutorials
CHAPTER 3
Configuration
31 Configuration with settings
311 Works with authentic 2 settings
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6047
312 All settings
Activate or deactivate debug mode
Variable DEBUG
Values
bull False deactivate debug mode
bull True activate debug mode
Manage session cookie duration
Variable SESSION_EXPIRE_AT_BROWSER_CLOSE
Values
bull False Cookies are not removed when browser is closed
bull True Cookies are removed when browser is closed
Variable SESSION_COOKIE_AGE
Value
bull Seconds (36000 equal 10 hours)
Time zone selection
Variable TIME_ZONE
Values
13
Authentic2 Documentation Release 202
bull See httpenwikipediaorgwikiList_of_tz_zones_by_name
Activate or deactivate SSL authentication
Variable AUTH_SSL
Values
bull False deactivate SSL authentication
bull True activate SSL authentication
Activate or deactivate OpenID authentication Authentic 2 is an OpenID relying party
Variable AUTH_OPENID
Values
bull False deactivate OpenID authentication
bull True activate OpenID authentication
Activate or deactivate Authentic 2 as a SAML2 identity provider
Variable IDP_SAML2
Values
bull False deactivate SAML2 identity provider
bull True activate SAML2 identity provider
Configure SAML2 keys
bull SAML_SIGNATURE_PUBLIC_KEY Certtificate or public key for signature
bull SAML_SIGNATURE_PRIVATE_KEY Private key for signature
bull SAML_ENCRYPTION_PUBLIC_KEY Certtificate or public key for encryption
bull SAML_ENCRYPTION_PRIVATE_KEY Private key for encryption
Values are pem files of X509 certificate or key eg SAML_SIGNATURE_PRIVATE_KEY = lsquorsquolsquomdashndashBEGIN RSAPRIVATE KEYmdashndash MIIWA== mdashndashEND RSA PRIVATE KEYmdashndashlsquorsquolsquo
If SAML_ENCRYPTION_PUBLIC_KEY or SAML_ENCRYPTION_PRIVATE_KEY are not given the signaturekeys are used for encryption
Activate or deactivate Authentic 2 as an OpenID provider
Variable IDP_OPENID
Values
bull False deactivate OpenID provider
bull True activate OpenID provider
14 Chapter 3 Configuration
Authentic2 Documentation Release 202
Activate or deactivate Authentic 2 as a CAS server
Variable IDP_CAS
Values
bull False deactivate CAS server
bull True activate CAS server
32 Configuration with the administration interface
321 Basics
Access the grapical administration interface
The grapical administration interface is the lsquoDjango adminrsquo part of a Django project See for more information
Just acces the admin url at http[s]yourdomaincomadmin
At first you log with the superuser you created at the very first database initialization
Then you can configure other accesses to the admin checking the is_staff option displayed on a user in the admin
Work with policies
The policy management with global policies is nearly used for any kind of policy in Authentic 2
For each kind of these policies the system takes in account two special global policies named lsquoDefaultrsquo and lsquoAllrsquo
bull There is always a system default that does not correspond to the lsquoDefaultrsquo policy This is used to make Authentic2 boot without initial configuration When you add a lsquoDefaultrsquo policy the system default are not used anymore
bull A policy has always a name lsquoDefaultrsquo and lsquoAllrsquo are the names of two special policies with their name hardcodedBut you can create or delete them
bull If no other policy applies the policy lsquoDefaultrsquo applies
bull A policy can be created and attached to any related object This policy is authoritative on the policy lsquoDefaultrsquo
bull If the policy lsquoAllrsquo exists it is authoritative on any other policy
bull The global policies lsquoAllrsquo and lsquoDefaultrsquo are created by the administrator if necessary
bull A policy is taken in account only if it is enabled
bull When a regular policy is associated with an object it is taken in account only if the option lsquoenable the followingpolicyrsquo is checked on the oject
It is advised to add a lsquoDefaultrsquo global policy when it is expected to apply a policy to all related objects A lsquoDefaultrsquoglobal policy should be defined to avoid misonfiguration
Add a regular policy to some objects are used to handle particular configurations for a subset of related objects
An lsquoAllrsquo global policy should be used to enforce a global configuration for all related objects or for testing purposes
32 Configuration with the administration interface 15
Authentic2 Documentation Release 202
322 Authentication backends
Authentication with an existing LDAP directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP
The next lines must be added
AUTHENTICATION_BACKENDS += ( django_auth_ldapbackendLDAPBackend )
import ldapfrom django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your serverAUTH_LDAP_SERVER_URI = ldapldapexamplecom Let the bind DN and bind password blank for anonymous bindingAUTH_LDAP_BIND_DN = AUTH_LDAP_BIND_PASSWORD = Lookup user under the branch o=base and by mathcing their uid against the received login nameAUTH_LDAP_USER_SEARCH = LDAPSearch(o=base
ldapSCOPE_SUBTREE (uid=(user)s))
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesTypeAUTH_LDAP_GROUP_TYPE = GroupOfNamesType()AUTH_LDAP_GROUP_SEARCH = LDAPSearch(o=mycompany
ldapSCOPE_SUBTREE (objectClass=groupOfNames))AUTH_LDAP_USER_FLAGS_BY_GROUP =
is_staff cn=admino=mycompany
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
16 Chapter 3 Configuration
Authentic2 Documentation Release 202
Authentication on Authentic 2 with PAM
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
323 SAML2
Where do I find the Authentic 2 SAML2 metadata
The SAML2 metadata are automatically generated
Authentic 2 will infer from environment variables the host and port to generate the URLs contained in themedatada
The metadata of Authentic 2 SAML2 identity provider are available at
http[s]yourdomaincomidpsaml2metadata
The metadata of Authentic 2 SAML2 service provider are available at
http[s]yourdomaincomauthsaml2metadata
Configure SAML 20 service providers
How do I authenticate against Authentic 2 with a SAML2 service provider
1 Declare Authentic 2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identityprovider metadata of Authentic 2
Go to http[s]yourdomaincomidpsaml2metadata
2 Add and configure a SAML2 service provider in Authentic 2 using the metadata of the service provider
How do I add and configure a SAML2 service provider in Authentic 2
You first need to create a new SAML2 service provider entry This requires the SAML2 metadata of the serviceprovider
If your service provider is Authentic 2 the metadata are available at
http[s]yourdomaincomauthsaml2metadata
32 Configuration with the administration interface 17
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Contents
1 Overview 3
2 Installation and quickstart tutorials 5
3 Configuration 13
4 Advanced topics 63
5 Copyright 65
i
ii
Authentic2 Documentation Release 202
Authentic 2 is a versatile identity management server aiming to address a broad range of needs from simple to complexsetups it has support for many protocols and can bridge between them
Authentic 2 supports many protocols and standards including SAML2 CAS OpenID LDAP X509 and OAUTH2
Authentic 2 is under the GNU AGPL version 3 licence
It has support for SAMLv2 thanks to Lasso a free (GNU GPL) implementation of the Liberty Alliance and OASISspecifications of SAML2
Consult current Authentic 2 activity on the project site
If you donrsquot find an explanation you donrsquot understand it or one is missing please report it on the list
Contents 1
Authentic2 Documentation Release 202
2 Contents
CHAPTER 1
Overview
Authentic 2 is a versatile identity management server aiming to address a broad range of needs from simple to complexsetups it has support for many protocols and can bridge between them
Authentic 2 supports many protocols and standards including SAML2 CAS OpenID LDAP X509 and OAUTH2
Authentic 2 is under the GNU AGPL version 3 licence
It has support for SAMLv2 thanks to Lasso a free (GNU GPL) implementation of the Liberty Alliance and OASISspecifications of SAML2
Authentic 2 requires Python 27 et Django 15
11 Features
bull SAML 20 Identity and service provider
bull OpenID 10 and 20 identity provider
bull Server CAS 10 and 20 using a plugin
bull Standards authentication mechanisms
ndash Loginpassword through internal directory or LDAP
ndash X509 certificate over SSLTLS
bull Protocol proxying for instance between OpenID and SAML
bull Support of LDAP v2 and v3 directories
bull Support of the PAM backend
bull One-time password (OATH and Google-Authenticator) using a plugin
bull Identity attribute management
bull Plugin system
12 Source and issue tracker
You can find on the project site authenticentrouvertorg mainly the issue tracker
You can find there a viewer of the git repository or clone it
3
Authentic2 Documentation Release 202
git clone httpreposentrouvertorgauthenticgit
13 Support
Authenticrsquos developpers and users hangs on the mailing list authenticlistesentrouvertcom See archives or registerat httplistesentrouvertcominfoauthentic
You can open reports or feature request on httpauthenticentrouvertorg
Entrrsquoouvert also provides a commercial support For information visit httpwwwentrouvertcom
4 Chapter 1 Overview
CHAPTER 2
Installation and quickstart tutorials
Yoursquoll find here how to start and configure very quickly Authentic 2 for its main features You just need Python 27and Django 15
First of all you can boot Authentic vwithout root privileges like this
1 Initialize a virtualenv
virtualenv authenticsource authenticbinactivatecd authentic
2 Install Authentic
pip install authentic2
3 Initialize the database migrations
authentic2-ctl syncdb --migrate
4 Run the HTTP test server
authentic2-ctl runserver
21 Quickstart guides and installation guidelines
211 Installation modes
The current version of Authentic 2 works with Python 27 and Django 15
Authentic 2 python installation script handles all the dependencies except Lasso relying on the Setuptools and thepypi repository
To run Authentic 2 with SAML2 features you need to install lasso gt= 236 see Lasso installation
The other Authentic 2 dependencies are
bull Djangolt16
bull southgt=084
bull requests
bull django-model-utils
bull django-registrationgt=1
5
Authentic2 Documentation Release 202
bull django-debug-toolbargt=12lt13
bull ndashallow-external django-admin-tools
bull ndashallow-unverified django-admin-tools
bull django-admin-toolsgt=051
bull dnspython
bull django-select2
bull django-tables2
bull gadjo
bull django-import-export
bull django-sekizai
Install Authentic 2
bull Install Authentic directly from pypi
bull Obtain the last package archive from pypi
bull Obtain the last sources from the Git repository
Lasso installation
Lasso is available in the linux debian destribution repositories If you are installing Authentic 2 on debian just execute
apt-get install python-lasso
Yoursquoll find more updated packages on httpdebentrouvertorg
We also provide rpm packages for redhat see httpsdeventrouvertorgredhatREADME
You can also install lasso from sources httplassoentrouvertorgdownload
See the Lasso website for installation details This is a quick installation example
Install the following Lasso dependencies
bull autoconf
bull automake
bull autotools-dev
bull libtool
bull gtk-doc-tools
bull zlib1g-dev
bull libglib20-dev
bull openssl-dev
bull libxml2-dev
bull libxmlsec1-dev
bull python26-dev
bull python-setuptools
Obtain Lasso
6 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
$wget httpsdeventrouvertorglassolasso-236targz$tar xzvf lasso-236targz$cd lasso-236$autogensh
Be sure that the Python bindings is selected as follows
=============Configuration=============
Main----
Compiler gccCFLAGSInstall prefix usrlocalDebugging noExperimental ID-WSF no
Optionals builds----------------
Available languages java(461) python(27) perl(5124)
Java binding yesPerl binding yesPHP 5 binding noPython binding yes
C API references yesTests suite no
Now type make install to install lasso
As indicated build and install
$make install$ldconfig
Set the lasso python binding in you python path eg
$export PYTHONPATH=$PYTHONPATHusrlocallibpython26site-packages
Test trying to import Lasso
$pythongtgtgt import lasso
Install Authentic directly from pypi
Using pip
pip install authentic2
You can now run Authentic from the installation directory
21 Quickstart guides and installation guidelines 7
Authentic2 Documentation Release 202
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last package archive from pypi
Download the archive on httppypipythonorgpypiauthentic2
Then you can install it directly from the archive using pip
pip install authentic2-xzytargz
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last sources from the Git repository
Clone the repository
git clone httpreposentrouvertorgauthenticgit
Then you can install it directly using pip
cd authenticpip install -e
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
8 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
212 Specifying a different database
This is done by modifying the DATABASES dictionary in your local_settingspy file (create it in Authentic projectdirectory) for example
DATABASES[default] = ENGINE djangodbbackendspostgresqlNAME authenticUSER admindbPASSWORD foobarHOST dbexamplecomPORT empty string means default value
You should refer to the Django documentation on databases settings athttpdocsdjangoprojectcomendevrefsettingsdatabases for all the details
213 Upgrading
Update using pip
pip install -U authentic2
Authentic store all its data in a relational database as specified in its settingspy or local_settingspy file So in order toupgrade to a new version of authentic you have to update your database schema using the migration command mdash youwill need to have installed the dependency django-south see the beginning of this README file
authentic2-ctl syncdb --migrate
214 Running Authentic 2 for real (Nginx Apache etc)
DEBUG Mode by default static files and the Django debug toolbar dependency
By default Authentic 2 is in the DEBUG mode We made this default choice because most of the Authentic 2rsquos userswill begin with Authentic 2 using the Django development server (runserver command) and we want to avoid them abad first impression because static files would not be served As a matter of fact static files are served by the Djangodevelopment server only when the project is run in the DEBUG mode
In the DEBUG mode the Django debug toolbar is used what adds a dependency
In production the Django development server should not be used to serve Authentic 2 and a dedicated server shouldalso be used to serve the static files
21 Quickstart guides and installation guidelines 9
Authentic2 Documentation Release 202
Set Authentic into the no DEBUG Mode
It is enough to edit authentic2settingspy and set
DEBUG = False
From then on the django-debug-toolbar package is not necessary anymore
Use dedicated HTTP servers and serve static files
The best is to use a server dedicated to serve the Django applications and a different server to serve the static files
You could for instance use apache with mod_wsgi to serve Authentic 2 You will find configuration file examples inthe debian directory of the Authentic 2 sources
Then you may want to use nginx to serve the static files
First you need to collect the Authentic 2 static files The static files are collected using the collectstatic command thatis configured in the settingspy
By default running collectstatic will create a static directory in the parent directory of the authentic2 directory
$python authentic2managepy collectstatic
That static directory will contain all the static files of Authentic 2
If you want to change the path of the static directory you can edit STATIC_ROOT of the settings file
See httpsdocsdjangoprojectcomendevrefcontribstaticfiles for more information about collectstatic
215 Quickstarts
Quickstart an OAuth2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6053
Quickstart an SAML2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6057
Quickstart a connection with a SAML2 Service Provider
1 Get the Identity Provider SAML2 metadata file
http[s]yourdomaincomidpsaml2metadata
2 Configure your service provider with it
3 Go to the providers admin panel on
http[s]adminsamllibertyprovideradd
There create a new provider using the service provider metadata and enable it as a service provider
10 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Quickstart a CAS Identity Provider
1 Activate CAS IdP support in your local_settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
authentic2-ctl syncdb ndashall authentic2-ctl migrate ndashfake
2 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
3 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
Quickstart to connect a LDAP Directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django for this you need python-ldap python-ldap needs python de-velopement headers to be installed but is usually packaged by most distributions
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP The next lines must be added
AUTHENTICATION_BACKENDS += ( lsquodjango_auth_ldapbackendLDAPBackendrsquo )
import ldap from django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your server AUTH_LDAP_SERVER_URI = lsquoldapldapexamplecomlsquo Let the bind DN and bind password blank for anonymous binding AUTH_LDAP_BIND_DN = ldquordquoAUTH_LDAP_BIND_PASSWORD = ldquordquo Lookup user under the branch o=base and by mathcing theiruid against the received login name AUTH_LDAP_USER_SEARCH = LDAPSearch(ldquoo=baserdquo
ldapSCOPE_SUBTREE ldquo(uid=(user)s)rdquo)
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesType AUTH_LDAP_GROUP_TYPE = GroupOf-NamesType() AUTH_LDAP_GROUP_SEARCH = LDAPSearch(ldquoo=mycompanyrdquo
ldapSCOPE_SUBTREE ldquo(objectClass=groupOfNames)rdquo)
AUTH_LDAP_USER_FLAGS_BY_GROUP = ldquois_staffrdquo ldquocn=admino=mycompanyrdquo
21 Quickstart guides and installation guidelines 11
Authentic2 Documentation Release 202
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
Quickstart for PAM Authentication
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
12 Chapter 2 Installation and quickstart tutorials
CHAPTER 3
Configuration
31 Configuration with settings
311 Works with authentic 2 settings
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6047
312 All settings
Activate or deactivate debug mode
Variable DEBUG
Values
bull False deactivate debug mode
bull True activate debug mode
Manage session cookie duration
Variable SESSION_EXPIRE_AT_BROWSER_CLOSE
Values
bull False Cookies are not removed when browser is closed
bull True Cookies are removed when browser is closed
Variable SESSION_COOKIE_AGE
Value
bull Seconds (36000 equal 10 hours)
Time zone selection
Variable TIME_ZONE
Values
13
Authentic2 Documentation Release 202
bull See httpenwikipediaorgwikiList_of_tz_zones_by_name
Activate or deactivate SSL authentication
Variable AUTH_SSL
Values
bull False deactivate SSL authentication
bull True activate SSL authentication
Activate or deactivate OpenID authentication Authentic 2 is an OpenID relying party
Variable AUTH_OPENID
Values
bull False deactivate OpenID authentication
bull True activate OpenID authentication
Activate or deactivate Authentic 2 as a SAML2 identity provider
Variable IDP_SAML2
Values
bull False deactivate SAML2 identity provider
bull True activate SAML2 identity provider
Configure SAML2 keys
bull SAML_SIGNATURE_PUBLIC_KEY Certtificate or public key for signature
bull SAML_SIGNATURE_PRIVATE_KEY Private key for signature
bull SAML_ENCRYPTION_PUBLIC_KEY Certtificate or public key for encryption
bull SAML_ENCRYPTION_PRIVATE_KEY Private key for encryption
Values are pem files of X509 certificate or key eg SAML_SIGNATURE_PRIVATE_KEY = lsquorsquolsquomdashndashBEGIN RSAPRIVATE KEYmdashndash MIIWA== mdashndashEND RSA PRIVATE KEYmdashndashlsquorsquolsquo
If SAML_ENCRYPTION_PUBLIC_KEY or SAML_ENCRYPTION_PRIVATE_KEY are not given the signaturekeys are used for encryption
Activate or deactivate Authentic 2 as an OpenID provider
Variable IDP_OPENID
Values
bull False deactivate OpenID provider
bull True activate OpenID provider
14 Chapter 3 Configuration
Authentic2 Documentation Release 202
Activate or deactivate Authentic 2 as a CAS server
Variable IDP_CAS
Values
bull False deactivate CAS server
bull True activate CAS server
32 Configuration with the administration interface
321 Basics
Access the grapical administration interface
The grapical administration interface is the lsquoDjango adminrsquo part of a Django project See for more information
Just acces the admin url at http[s]yourdomaincomadmin
At first you log with the superuser you created at the very first database initialization
Then you can configure other accesses to the admin checking the is_staff option displayed on a user in the admin
Work with policies
The policy management with global policies is nearly used for any kind of policy in Authentic 2
For each kind of these policies the system takes in account two special global policies named lsquoDefaultrsquo and lsquoAllrsquo
bull There is always a system default that does not correspond to the lsquoDefaultrsquo policy This is used to make Authentic2 boot without initial configuration When you add a lsquoDefaultrsquo policy the system default are not used anymore
bull A policy has always a name lsquoDefaultrsquo and lsquoAllrsquo are the names of two special policies with their name hardcodedBut you can create or delete them
bull If no other policy applies the policy lsquoDefaultrsquo applies
bull A policy can be created and attached to any related object This policy is authoritative on the policy lsquoDefaultrsquo
bull If the policy lsquoAllrsquo exists it is authoritative on any other policy
bull The global policies lsquoAllrsquo and lsquoDefaultrsquo are created by the administrator if necessary
bull A policy is taken in account only if it is enabled
bull When a regular policy is associated with an object it is taken in account only if the option lsquoenable the followingpolicyrsquo is checked on the oject
It is advised to add a lsquoDefaultrsquo global policy when it is expected to apply a policy to all related objects A lsquoDefaultrsquoglobal policy should be defined to avoid misonfiguration
Add a regular policy to some objects are used to handle particular configurations for a subset of related objects
An lsquoAllrsquo global policy should be used to enforce a global configuration for all related objects or for testing purposes
32 Configuration with the administration interface 15
Authentic2 Documentation Release 202
322 Authentication backends
Authentication with an existing LDAP directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP
The next lines must be added
AUTHENTICATION_BACKENDS += ( django_auth_ldapbackendLDAPBackend )
import ldapfrom django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your serverAUTH_LDAP_SERVER_URI = ldapldapexamplecom Let the bind DN and bind password blank for anonymous bindingAUTH_LDAP_BIND_DN = AUTH_LDAP_BIND_PASSWORD = Lookup user under the branch o=base and by mathcing their uid against the received login nameAUTH_LDAP_USER_SEARCH = LDAPSearch(o=base
ldapSCOPE_SUBTREE (uid=(user)s))
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesTypeAUTH_LDAP_GROUP_TYPE = GroupOfNamesType()AUTH_LDAP_GROUP_SEARCH = LDAPSearch(o=mycompany
ldapSCOPE_SUBTREE (objectClass=groupOfNames))AUTH_LDAP_USER_FLAGS_BY_GROUP =
is_staff cn=admino=mycompany
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
16 Chapter 3 Configuration
Authentic2 Documentation Release 202
Authentication on Authentic 2 with PAM
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
323 SAML2
Where do I find the Authentic 2 SAML2 metadata
The SAML2 metadata are automatically generated
Authentic 2 will infer from environment variables the host and port to generate the URLs contained in themedatada
The metadata of Authentic 2 SAML2 identity provider are available at
http[s]yourdomaincomidpsaml2metadata
The metadata of Authentic 2 SAML2 service provider are available at
http[s]yourdomaincomauthsaml2metadata
Configure SAML 20 service providers
How do I authenticate against Authentic 2 with a SAML2 service provider
1 Declare Authentic 2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identityprovider metadata of Authentic 2
Go to http[s]yourdomaincomidpsaml2metadata
2 Add and configure a SAML2 service provider in Authentic 2 using the metadata of the service provider
How do I add and configure a SAML2 service provider in Authentic 2
You first need to create a new SAML2 service provider entry This requires the SAML2 metadata of the serviceprovider
If your service provider is Authentic 2 the metadata are available at
http[s]yourdomaincomauthsaml2metadata
32 Configuration with the administration interface 17
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
ii
Authentic2 Documentation Release 202
Authentic 2 is a versatile identity management server aiming to address a broad range of needs from simple to complexsetups it has support for many protocols and can bridge between them
Authentic 2 supports many protocols and standards including SAML2 CAS OpenID LDAP X509 and OAUTH2
Authentic 2 is under the GNU AGPL version 3 licence
It has support for SAMLv2 thanks to Lasso a free (GNU GPL) implementation of the Liberty Alliance and OASISspecifications of SAML2
Consult current Authentic 2 activity on the project site
If you donrsquot find an explanation you donrsquot understand it or one is missing please report it on the list
Contents 1
Authentic2 Documentation Release 202
2 Contents
CHAPTER 1
Overview
Authentic 2 is a versatile identity management server aiming to address a broad range of needs from simple to complexsetups it has support for many protocols and can bridge between them
Authentic 2 supports many protocols and standards including SAML2 CAS OpenID LDAP X509 and OAUTH2
Authentic 2 is under the GNU AGPL version 3 licence
It has support for SAMLv2 thanks to Lasso a free (GNU GPL) implementation of the Liberty Alliance and OASISspecifications of SAML2
Authentic 2 requires Python 27 et Django 15
11 Features
bull SAML 20 Identity and service provider
bull OpenID 10 and 20 identity provider
bull Server CAS 10 and 20 using a plugin
bull Standards authentication mechanisms
ndash Loginpassword through internal directory or LDAP
ndash X509 certificate over SSLTLS
bull Protocol proxying for instance between OpenID and SAML
bull Support of LDAP v2 and v3 directories
bull Support of the PAM backend
bull One-time password (OATH and Google-Authenticator) using a plugin
bull Identity attribute management
bull Plugin system
12 Source and issue tracker
You can find on the project site authenticentrouvertorg mainly the issue tracker
You can find there a viewer of the git repository or clone it
3
Authentic2 Documentation Release 202
git clone httpreposentrouvertorgauthenticgit
13 Support
Authenticrsquos developpers and users hangs on the mailing list authenticlistesentrouvertcom See archives or registerat httplistesentrouvertcominfoauthentic
You can open reports or feature request on httpauthenticentrouvertorg
Entrrsquoouvert also provides a commercial support For information visit httpwwwentrouvertcom
4 Chapter 1 Overview
CHAPTER 2
Installation and quickstart tutorials
Yoursquoll find here how to start and configure very quickly Authentic 2 for its main features You just need Python 27and Django 15
First of all you can boot Authentic vwithout root privileges like this
1 Initialize a virtualenv
virtualenv authenticsource authenticbinactivatecd authentic
2 Install Authentic
pip install authentic2
3 Initialize the database migrations
authentic2-ctl syncdb --migrate
4 Run the HTTP test server
authentic2-ctl runserver
21 Quickstart guides and installation guidelines
211 Installation modes
The current version of Authentic 2 works with Python 27 and Django 15
Authentic 2 python installation script handles all the dependencies except Lasso relying on the Setuptools and thepypi repository
To run Authentic 2 with SAML2 features you need to install lasso gt= 236 see Lasso installation
The other Authentic 2 dependencies are
bull Djangolt16
bull southgt=084
bull requests
bull django-model-utils
bull django-registrationgt=1
5
Authentic2 Documentation Release 202
bull django-debug-toolbargt=12lt13
bull ndashallow-external django-admin-tools
bull ndashallow-unverified django-admin-tools
bull django-admin-toolsgt=051
bull dnspython
bull django-select2
bull django-tables2
bull gadjo
bull django-import-export
bull django-sekizai
Install Authentic 2
bull Install Authentic directly from pypi
bull Obtain the last package archive from pypi
bull Obtain the last sources from the Git repository
Lasso installation
Lasso is available in the linux debian destribution repositories If you are installing Authentic 2 on debian just execute
apt-get install python-lasso
Yoursquoll find more updated packages on httpdebentrouvertorg
We also provide rpm packages for redhat see httpsdeventrouvertorgredhatREADME
You can also install lasso from sources httplassoentrouvertorgdownload
See the Lasso website for installation details This is a quick installation example
Install the following Lasso dependencies
bull autoconf
bull automake
bull autotools-dev
bull libtool
bull gtk-doc-tools
bull zlib1g-dev
bull libglib20-dev
bull openssl-dev
bull libxml2-dev
bull libxmlsec1-dev
bull python26-dev
bull python-setuptools
Obtain Lasso
6 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
$wget httpsdeventrouvertorglassolasso-236targz$tar xzvf lasso-236targz$cd lasso-236$autogensh
Be sure that the Python bindings is selected as follows
=============Configuration=============
Main----
Compiler gccCFLAGSInstall prefix usrlocalDebugging noExperimental ID-WSF no
Optionals builds----------------
Available languages java(461) python(27) perl(5124)
Java binding yesPerl binding yesPHP 5 binding noPython binding yes
C API references yesTests suite no
Now type make install to install lasso
As indicated build and install
$make install$ldconfig
Set the lasso python binding in you python path eg
$export PYTHONPATH=$PYTHONPATHusrlocallibpython26site-packages
Test trying to import Lasso
$pythongtgtgt import lasso
Install Authentic directly from pypi
Using pip
pip install authentic2
You can now run Authentic from the installation directory
21 Quickstart guides and installation guidelines 7
Authentic2 Documentation Release 202
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last package archive from pypi
Download the archive on httppypipythonorgpypiauthentic2
Then you can install it directly from the archive using pip
pip install authentic2-xzytargz
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last sources from the Git repository
Clone the repository
git clone httpreposentrouvertorgauthenticgit
Then you can install it directly using pip
cd authenticpip install -e
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
8 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
212 Specifying a different database
This is done by modifying the DATABASES dictionary in your local_settingspy file (create it in Authentic projectdirectory) for example
DATABASES[default] = ENGINE djangodbbackendspostgresqlNAME authenticUSER admindbPASSWORD foobarHOST dbexamplecomPORT empty string means default value
You should refer to the Django documentation on databases settings athttpdocsdjangoprojectcomendevrefsettingsdatabases for all the details
213 Upgrading
Update using pip
pip install -U authentic2
Authentic store all its data in a relational database as specified in its settingspy or local_settingspy file So in order toupgrade to a new version of authentic you have to update your database schema using the migration command mdash youwill need to have installed the dependency django-south see the beginning of this README file
authentic2-ctl syncdb --migrate
214 Running Authentic 2 for real (Nginx Apache etc)
DEBUG Mode by default static files and the Django debug toolbar dependency
By default Authentic 2 is in the DEBUG mode We made this default choice because most of the Authentic 2rsquos userswill begin with Authentic 2 using the Django development server (runserver command) and we want to avoid them abad first impression because static files would not be served As a matter of fact static files are served by the Djangodevelopment server only when the project is run in the DEBUG mode
In the DEBUG mode the Django debug toolbar is used what adds a dependency
In production the Django development server should not be used to serve Authentic 2 and a dedicated server shouldalso be used to serve the static files
21 Quickstart guides and installation guidelines 9
Authentic2 Documentation Release 202
Set Authentic into the no DEBUG Mode
It is enough to edit authentic2settingspy and set
DEBUG = False
From then on the django-debug-toolbar package is not necessary anymore
Use dedicated HTTP servers and serve static files
The best is to use a server dedicated to serve the Django applications and a different server to serve the static files
You could for instance use apache with mod_wsgi to serve Authentic 2 You will find configuration file examples inthe debian directory of the Authentic 2 sources
Then you may want to use nginx to serve the static files
First you need to collect the Authentic 2 static files The static files are collected using the collectstatic command thatis configured in the settingspy
By default running collectstatic will create a static directory in the parent directory of the authentic2 directory
$python authentic2managepy collectstatic
That static directory will contain all the static files of Authentic 2
If you want to change the path of the static directory you can edit STATIC_ROOT of the settings file
See httpsdocsdjangoprojectcomendevrefcontribstaticfiles for more information about collectstatic
215 Quickstarts
Quickstart an OAuth2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6053
Quickstart an SAML2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6057
Quickstart a connection with a SAML2 Service Provider
1 Get the Identity Provider SAML2 metadata file
http[s]yourdomaincomidpsaml2metadata
2 Configure your service provider with it
3 Go to the providers admin panel on
http[s]adminsamllibertyprovideradd
There create a new provider using the service provider metadata and enable it as a service provider
10 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Quickstart a CAS Identity Provider
1 Activate CAS IdP support in your local_settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
authentic2-ctl syncdb ndashall authentic2-ctl migrate ndashfake
2 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
3 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
Quickstart to connect a LDAP Directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django for this you need python-ldap python-ldap needs python de-velopement headers to be installed but is usually packaged by most distributions
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP The next lines must be added
AUTHENTICATION_BACKENDS += ( lsquodjango_auth_ldapbackendLDAPBackendrsquo )
import ldap from django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your server AUTH_LDAP_SERVER_URI = lsquoldapldapexamplecomlsquo Let the bind DN and bind password blank for anonymous binding AUTH_LDAP_BIND_DN = ldquordquoAUTH_LDAP_BIND_PASSWORD = ldquordquo Lookup user under the branch o=base and by mathcing theiruid against the received login name AUTH_LDAP_USER_SEARCH = LDAPSearch(ldquoo=baserdquo
ldapSCOPE_SUBTREE ldquo(uid=(user)s)rdquo)
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesType AUTH_LDAP_GROUP_TYPE = GroupOf-NamesType() AUTH_LDAP_GROUP_SEARCH = LDAPSearch(ldquoo=mycompanyrdquo
ldapSCOPE_SUBTREE ldquo(objectClass=groupOfNames)rdquo)
AUTH_LDAP_USER_FLAGS_BY_GROUP = ldquois_staffrdquo ldquocn=admino=mycompanyrdquo
21 Quickstart guides and installation guidelines 11
Authentic2 Documentation Release 202
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
Quickstart for PAM Authentication
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
12 Chapter 2 Installation and quickstart tutorials
CHAPTER 3
Configuration
31 Configuration with settings
311 Works with authentic 2 settings
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6047
312 All settings
Activate or deactivate debug mode
Variable DEBUG
Values
bull False deactivate debug mode
bull True activate debug mode
Manage session cookie duration
Variable SESSION_EXPIRE_AT_BROWSER_CLOSE
Values
bull False Cookies are not removed when browser is closed
bull True Cookies are removed when browser is closed
Variable SESSION_COOKIE_AGE
Value
bull Seconds (36000 equal 10 hours)
Time zone selection
Variable TIME_ZONE
Values
13
Authentic2 Documentation Release 202
bull See httpenwikipediaorgwikiList_of_tz_zones_by_name
Activate or deactivate SSL authentication
Variable AUTH_SSL
Values
bull False deactivate SSL authentication
bull True activate SSL authentication
Activate or deactivate OpenID authentication Authentic 2 is an OpenID relying party
Variable AUTH_OPENID
Values
bull False deactivate OpenID authentication
bull True activate OpenID authentication
Activate or deactivate Authentic 2 as a SAML2 identity provider
Variable IDP_SAML2
Values
bull False deactivate SAML2 identity provider
bull True activate SAML2 identity provider
Configure SAML2 keys
bull SAML_SIGNATURE_PUBLIC_KEY Certtificate or public key for signature
bull SAML_SIGNATURE_PRIVATE_KEY Private key for signature
bull SAML_ENCRYPTION_PUBLIC_KEY Certtificate or public key for encryption
bull SAML_ENCRYPTION_PRIVATE_KEY Private key for encryption
Values are pem files of X509 certificate or key eg SAML_SIGNATURE_PRIVATE_KEY = lsquorsquolsquomdashndashBEGIN RSAPRIVATE KEYmdashndash MIIWA== mdashndashEND RSA PRIVATE KEYmdashndashlsquorsquolsquo
If SAML_ENCRYPTION_PUBLIC_KEY or SAML_ENCRYPTION_PRIVATE_KEY are not given the signaturekeys are used for encryption
Activate or deactivate Authentic 2 as an OpenID provider
Variable IDP_OPENID
Values
bull False deactivate OpenID provider
bull True activate OpenID provider
14 Chapter 3 Configuration
Authentic2 Documentation Release 202
Activate or deactivate Authentic 2 as a CAS server
Variable IDP_CAS
Values
bull False deactivate CAS server
bull True activate CAS server
32 Configuration with the administration interface
321 Basics
Access the grapical administration interface
The grapical administration interface is the lsquoDjango adminrsquo part of a Django project See for more information
Just acces the admin url at http[s]yourdomaincomadmin
At first you log with the superuser you created at the very first database initialization
Then you can configure other accesses to the admin checking the is_staff option displayed on a user in the admin
Work with policies
The policy management with global policies is nearly used for any kind of policy in Authentic 2
For each kind of these policies the system takes in account two special global policies named lsquoDefaultrsquo and lsquoAllrsquo
bull There is always a system default that does not correspond to the lsquoDefaultrsquo policy This is used to make Authentic2 boot without initial configuration When you add a lsquoDefaultrsquo policy the system default are not used anymore
bull A policy has always a name lsquoDefaultrsquo and lsquoAllrsquo are the names of two special policies with their name hardcodedBut you can create or delete them
bull If no other policy applies the policy lsquoDefaultrsquo applies
bull A policy can be created and attached to any related object This policy is authoritative on the policy lsquoDefaultrsquo
bull If the policy lsquoAllrsquo exists it is authoritative on any other policy
bull The global policies lsquoAllrsquo and lsquoDefaultrsquo are created by the administrator if necessary
bull A policy is taken in account only if it is enabled
bull When a regular policy is associated with an object it is taken in account only if the option lsquoenable the followingpolicyrsquo is checked on the oject
It is advised to add a lsquoDefaultrsquo global policy when it is expected to apply a policy to all related objects A lsquoDefaultrsquoglobal policy should be defined to avoid misonfiguration
Add a regular policy to some objects are used to handle particular configurations for a subset of related objects
An lsquoAllrsquo global policy should be used to enforce a global configuration for all related objects or for testing purposes
32 Configuration with the administration interface 15
Authentic2 Documentation Release 202
322 Authentication backends
Authentication with an existing LDAP directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP
The next lines must be added
AUTHENTICATION_BACKENDS += ( django_auth_ldapbackendLDAPBackend )
import ldapfrom django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your serverAUTH_LDAP_SERVER_URI = ldapldapexamplecom Let the bind DN and bind password blank for anonymous bindingAUTH_LDAP_BIND_DN = AUTH_LDAP_BIND_PASSWORD = Lookup user under the branch o=base and by mathcing their uid against the received login nameAUTH_LDAP_USER_SEARCH = LDAPSearch(o=base
ldapSCOPE_SUBTREE (uid=(user)s))
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesTypeAUTH_LDAP_GROUP_TYPE = GroupOfNamesType()AUTH_LDAP_GROUP_SEARCH = LDAPSearch(o=mycompany
ldapSCOPE_SUBTREE (objectClass=groupOfNames))AUTH_LDAP_USER_FLAGS_BY_GROUP =
is_staff cn=admino=mycompany
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
16 Chapter 3 Configuration
Authentic2 Documentation Release 202
Authentication on Authentic 2 with PAM
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
323 SAML2
Where do I find the Authentic 2 SAML2 metadata
The SAML2 metadata are automatically generated
Authentic 2 will infer from environment variables the host and port to generate the URLs contained in themedatada
The metadata of Authentic 2 SAML2 identity provider are available at
http[s]yourdomaincomidpsaml2metadata
The metadata of Authentic 2 SAML2 service provider are available at
http[s]yourdomaincomauthsaml2metadata
Configure SAML 20 service providers
How do I authenticate against Authentic 2 with a SAML2 service provider
1 Declare Authentic 2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identityprovider metadata of Authentic 2
Go to http[s]yourdomaincomidpsaml2metadata
2 Add and configure a SAML2 service provider in Authentic 2 using the metadata of the service provider
How do I add and configure a SAML2 service provider in Authentic 2
You first need to create a new SAML2 service provider entry This requires the SAML2 metadata of the serviceprovider
If your service provider is Authentic 2 the metadata are available at
http[s]yourdomaincomauthsaml2metadata
32 Configuration with the administration interface 17
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Authentic 2 is a versatile identity management server aiming to address a broad range of needs from simple to complexsetups it has support for many protocols and can bridge between them
Authentic 2 supports many protocols and standards including SAML2 CAS OpenID LDAP X509 and OAUTH2
Authentic 2 is under the GNU AGPL version 3 licence
It has support for SAMLv2 thanks to Lasso a free (GNU GPL) implementation of the Liberty Alliance and OASISspecifications of SAML2
Consult current Authentic 2 activity on the project site
If you donrsquot find an explanation you donrsquot understand it or one is missing please report it on the list
Contents 1
Authentic2 Documentation Release 202
2 Contents
CHAPTER 1
Overview
Authentic 2 is a versatile identity management server aiming to address a broad range of needs from simple to complexsetups it has support for many protocols and can bridge between them
Authentic 2 supports many protocols and standards including SAML2 CAS OpenID LDAP X509 and OAUTH2
Authentic 2 is under the GNU AGPL version 3 licence
It has support for SAMLv2 thanks to Lasso a free (GNU GPL) implementation of the Liberty Alliance and OASISspecifications of SAML2
Authentic 2 requires Python 27 et Django 15
11 Features
bull SAML 20 Identity and service provider
bull OpenID 10 and 20 identity provider
bull Server CAS 10 and 20 using a plugin
bull Standards authentication mechanisms
ndash Loginpassword through internal directory or LDAP
ndash X509 certificate over SSLTLS
bull Protocol proxying for instance between OpenID and SAML
bull Support of LDAP v2 and v3 directories
bull Support of the PAM backend
bull One-time password (OATH and Google-Authenticator) using a plugin
bull Identity attribute management
bull Plugin system
12 Source and issue tracker
You can find on the project site authenticentrouvertorg mainly the issue tracker
You can find there a viewer of the git repository or clone it
3
Authentic2 Documentation Release 202
git clone httpreposentrouvertorgauthenticgit
13 Support
Authenticrsquos developpers and users hangs on the mailing list authenticlistesentrouvertcom See archives or registerat httplistesentrouvertcominfoauthentic
You can open reports or feature request on httpauthenticentrouvertorg
Entrrsquoouvert also provides a commercial support For information visit httpwwwentrouvertcom
4 Chapter 1 Overview
CHAPTER 2
Installation and quickstart tutorials
Yoursquoll find here how to start and configure very quickly Authentic 2 for its main features You just need Python 27and Django 15
First of all you can boot Authentic vwithout root privileges like this
1 Initialize a virtualenv
virtualenv authenticsource authenticbinactivatecd authentic
2 Install Authentic
pip install authentic2
3 Initialize the database migrations
authentic2-ctl syncdb --migrate
4 Run the HTTP test server
authentic2-ctl runserver
21 Quickstart guides and installation guidelines
211 Installation modes
The current version of Authentic 2 works with Python 27 and Django 15
Authentic 2 python installation script handles all the dependencies except Lasso relying on the Setuptools and thepypi repository
To run Authentic 2 with SAML2 features you need to install lasso gt= 236 see Lasso installation
The other Authentic 2 dependencies are
bull Djangolt16
bull southgt=084
bull requests
bull django-model-utils
bull django-registrationgt=1
5
Authentic2 Documentation Release 202
bull django-debug-toolbargt=12lt13
bull ndashallow-external django-admin-tools
bull ndashallow-unverified django-admin-tools
bull django-admin-toolsgt=051
bull dnspython
bull django-select2
bull django-tables2
bull gadjo
bull django-import-export
bull django-sekizai
Install Authentic 2
bull Install Authentic directly from pypi
bull Obtain the last package archive from pypi
bull Obtain the last sources from the Git repository
Lasso installation
Lasso is available in the linux debian destribution repositories If you are installing Authentic 2 on debian just execute
apt-get install python-lasso
Yoursquoll find more updated packages on httpdebentrouvertorg
We also provide rpm packages for redhat see httpsdeventrouvertorgredhatREADME
You can also install lasso from sources httplassoentrouvertorgdownload
See the Lasso website for installation details This is a quick installation example
Install the following Lasso dependencies
bull autoconf
bull automake
bull autotools-dev
bull libtool
bull gtk-doc-tools
bull zlib1g-dev
bull libglib20-dev
bull openssl-dev
bull libxml2-dev
bull libxmlsec1-dev
bull python26-dev
bull python-setuptools
Obtain Lasso
6 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
$wget httpsdeventrouvertorglassolasso-236targz$tar xzvf lasso-236targz$cd lasso-236$autogensh
Be sure that the Python bindings is selected as follows
=============Configuration=============
Main----
Compiler gccCFLAGSInstall prefix usrlocalDebugging noExperimental ID-WSF no
Optionals builds----------------
Available languages java(461) python(27) perl(5124)
Java binding yesPerl binding yesPHP 5 binding noPython binding yes
C API references yesTests suite no
Now type make install to install lasso
As indicated build and install
$make install$ldconfig
Set the lasso python binding in you python path eg
$export PYTHONPATH=$PYTHONPATHusrlocallibpython26site-packages
Test trying to import Lasso
$pythongtgtgt import lasso
Install Authentic directly from pypi
Using pip
pip install authentic2
You can now run Authentic from the installation directory
21 Quickstart guides and installation guidelines 7
Authentic2 Documentation Release 202
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last package archive from pypi
Download the archive on httppypipythonorgpypiauthentic2
Then you can install it directly from the archive using pip
pip install authentic2-xzytargz
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last sources from the Git repository
Clone the repository
git clone httpreposentrouvertorgauthenticgit
Then you can install it directly using pip
cd authenticpip install -e
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
8 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
212 Specifying a different database
This is done by modifying the DATABASES dictionary in your local_settingspy file (create it in Authentic projectdirectory) for example
DATABASES[default] = ENGINE djangodbbackendspostgresqlNAME authenticUSER admindbPASSWORD foobarHOST dbexamplecomPORT empty string means default value
You should refer to the Django documentation on databases settings athttpdocsdjangoprojectcomendevrefsettingsdatabases for all the details
213 Upgrading
Update using pip
pip install -U authentic2
Authentic store all its data in a relational database as specified in its settingspy or local_settingspy file So in order toupgrade to a new version of authentic you have to update your database schema using the migration command mdash youwill need to have installed the dependency django-south see the beginning of this README file
authentic2-ctl syncdb --migrate
214 Running Authentic 2 for real (Nginx Apache etc)
DEBUG Mode by default static files and the Django debug toolbar dependency
By default Authentic 2 is in the DEBUG mode We made this default choice because most of the Authentic 2rsquos userswill begin with Authentic 2 using the Django development server (runserver command) and we want to avoid them abad first impression because static files would not be served As a matter of fact static files are served by the Djangodevelopment server only when the project is run in the DEBUG mode
In the DEBUG mode the Django debug toolbar is used what adds a dependency
In production the Django development server should not be used to serve Authentic 2 and a dedicated server shouldalso be used to serve the static files
21 Quickstart guides and installation guidelines 9
Authentic2 Documentation Release 202
Set Authentic into the no DEBUG Mode
It is enough to edit authentic2settingspy and set
DEBUG = False
From then on the django-debug-toolbar package is not necessary anymore
Use dedicated HTTP servers and serve static files
The best is to use a server dedicated to serve the Django applications and a different server to serve the static files
You could for instance use apache with mod_wsgi to serve Authentic 2 You will find configuration file examples inthe debian directory of the Authentic 2 sources
Then you may want to use nginx to serve the static files
First you need to collect the Authentic 2 static files The static files are collected using the collectstatic command thatis configured in the settingspy
By default running collectstatic will create a static directory in the parent directory of the authentic2 directory
$python authentic2managepy collectstatic
That static directory will contain all the static files of Authentic 2
If you want to change the path of the static directory you can edit STATIC_ROOT of the settings file
See httpsdocsdjangoprojectcomendevrefcontribstaticfiles for more information about collectstatic
215 Quickstarts
Quickstart an OAuth2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6053
Quickstart an SAML2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6057
Quickstart a connection with a SAML2 Service Provider
1 Get the Identity Provider SAML2 metadata file
http[s]yourdomaincomidpsaml2metadata
2 Configure your service provider with it
3 Go to the providers admin panel on
http[s]adminsamllibertyprovideradd
There create a new provider using the service provider metadata and enable it as a service provider
10 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Quickstart a CAS Identity Provider
1 Activate CAS IdP support in your local_settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
authentic2-ctl syncdb ndashall authentic2-ctl migrate ndashfake
2 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
3 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
Quickstart to connect a LDAP Directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django for this you need python-ldap python-ldap needs python de-velopement headers to be installed but is usually packaged by most distributions
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP The next lines must be added
AUTHENTICATION_BACKENDS += ( lsquodjango_auth_ldapbackendLDAPBackendrsquo )
import ldap from django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your server AUTH_LDAP_SERVER_URI = lsquoldapldapexamplecomlsquo Let the bind DN and bind password blank for anonymous binding AUTH_LDAP_BIND_DN = ldquordquoAUTH_LDAP_BIND_PASSWORD = ldquordquo Lookup user under the branch o=base and by mathcing theiruid against the received login name AUTH_LDAP_USER_SEARCH = LDAPSearch(ldquoo=baserdquo
ldapSCOPE_SUBTREE ldquo(uid=(user)s)rdquo)
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesType AUTH_LDAP_GROUP_TYPE = GroupOf-NamesType() AUTH_LDAP_GROUP_SEARCH = LDAPSearch(ldquoo=mycompanyrdquo
ldapSCOPE_SUBTREE ldquo(objectClass=groupOfNames)rdquo)
AUTH_LDAP_USER_FLAGS_BY_GROUP = ldquois_staffrdquo ldquocn=admino=mycompanyrdquo
21 Quickstart guides and installation guidelines 11
Authentic2 Documentation Release 202
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
Quickstart for PAM Authentication
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
12 Chapter 2 Installation and quickstart tutorials
CHAPTER 3
Configuration
31 Configuration with settings
311 Works with authentic 2 settings
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6047
312 All settings
Activate or deactivate debug mode
Variable DEBUG
Values
bull False deactivate debug mode
bull True activate debug mode
Manage session cookie duration
Variable SESSION_EXPIRE_AT_BROWSER_CLOSE
Values
bull False Cookies are not removed when browser is closed
bull True Cookies are removed when browser is closed
Variable SESSION_COOKIE_AGE
Value
bull Seconds (36000 equal 10 hours)
Time zone selection
Variable TIME_ZONE
Values
13
Authentic2 Documentation Release 202
bull See httpenwikipediaorgwikiList_of_tz_zones_by_name
Activate or deactivate SSL authentication
Variable AUTH_SSL
Values
bull False deactivate SSL authentication
bull True activate SSL authentication
Activate or deactivate OpenID authentication Authentic 2 is an OpenID relying party
Variable AUTH_OPENID
Values
bull False deactivate OpenID authentication
bull True activate OpenID authentication
Activate or deactivate Authentic 2 as a SAML2 identity provider
Variable IDP_SAML2
Values
bull False deactivate SAML2 identity provider
bull True activate SAML2 identity provider
Configure SAML2 keys
bull SAML_SIGNATURE_PUBLIC_KEY Certtificate or public key for signature
bull SAML_SIGNATURE_PRIVATE_KEY Private key for signature
bull SAML_ENCRYPTION_PUBLIC_KEY Certtificate or public key for encryption
bull SAML_ENCRYPTION_PRIVATE_KEY Private key for encryption
Values are pem files of X509 certificate or key eg SAML_SIGNATURE_PRIVATE_KEY = lsquorsquolsquomdashndashBEGIN RSAPRIVATE KEYmdashndash MIIWA== mdashndashEND RSA PRIVATE KEYmdashndashlsquorsquolsquo
If SAML_ENCRYPTION_PUBLIC_KEY or SAML_ENCRYPTION_PRIVATE_KEY are not given the signaturekeys are used for encryption
Activate or deactivate Authentic 2 as an OpenID provider
Variable IDP_OPENID
Values
bull False deactivate OpenID provider
bull True activate OpenID provider
14 Chapter 3 Configuration
Authentic2 Documentation Release 202
Activate or deactivate Authentic 2 as a CAS server
Variable IDP_CAS
Values
bull False deactivate CAS server
bull True activate CAS server
32 Configuration with the administration interface
321 Basics
Access the grapical administration interface
The grapical administration interface is the lsquoDjango adminrsquo part of a Django project See for more information
Just acces the admin url at http[s]yourdomaincomadmin
At first you log with the superuser you created at the very first database initialization
Then you can configure other accesses to the admin checking the is_staff option displayed on a user in the admin
Work with policies
The policy management with global policies is nearly used for any kind of policy in Authentic 2
For each kind of these policies the system takes in account two special global policies named lsquoDefaultrsquo and lsquoAllrsquo
bull There is always a system default that does not correspond to the lsquoDefaultrsquo policy This is used to make Authentic2 boot without initial configuration When you add a lsquoDefaultrsquo policy the system default are not used anymore
bull A policy has always a name lsquoDefaultrsquo and lsquoAllrsquo are the names of two special policies with their name hardcodedBut you can create or delete them
bull If no other policy applies the policy lsquoDefaultrsquo applies
bull A policy can be created and attached to any related object This policy is authoritative on the policy lsquoDefaultrsquo
bull If the policy lsquoAllrsquo exists it is authoritative on any other policy
bull The global policies lsquoAllrsquo and lsquoDefaultrsquo are created by the administrator if necessary
bull A policy is taken in account only if it is enabled
bull When a regular policy is associated with an object it is taken in account only if the option lsquoenable the followingpolicyrsquo is checked on the oject
It is advised to add a lsquoDefaultrsquo global policy when it is expected to apply a policy to all related objects A lsquoDefaultrsquoglobal policy should be defined to avoid misonfiguration
Add a regular policy to some objects are used to handle particular configurations for a subset of related objects
An lsquoAllrsquo global policy should be used to enforce a global configuration for all related objects or for testing purposes
32 Configuration with the administration interface 15
Authentic2 Documentation Release 202
322 Authentication backends
Authentication with an existing LDAP directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP
The next lines must be added
AUTHENTICATION_BACKENDS += ( django_auth_ldapbackendLDAPBackend )
import ldapfrom django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your serverAUTH_LDAP_SERVER_URI = ldapldapexamplecom Let the bind DN and bind password blank for anonymous bindingAUTH_LDAP_BIND_DN = AUTH_LDAP_BIND_PASSWORD = Lookup user under the branch o=base and by mathcing their uid against the received login nameAUTH_LDAP_USER_SEARCH = LDAPSearch(o=base
ldapSCOPE_SUBTREE (uid=(user)s))
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesTypeAUTH_LDAP_GROUP_TYPE = GroupOfNamesType()AUTH_LDAP_GROUP_SEARCH = LDAPSearch(o=mycompany
ldapSCOPE_SUBTREE (objectClass=groupOfNames))AUTH_LDAP_USER_FLAGS_BY_GROUP =
is_staff cn=admino=mycompany
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
16 Chapter 3 Configuration
Authentic2 Documentation Release 202
Authentication on Authentic 2 with PAM
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
323 SAML2
Where do I find the Authentic 2 SAML2 metadata
The SAML2 metadata are automatically generated
Authentic 2 will infer from environment variables the host and port to generate the URLs contained in themedatada
The metadata of Authentic 2 SAML2 identity provider are available at
http[s]yourdomaincomidpsaml2metadata
The metadata of Authentic 2 SAML2 service provider are available at
http[s]yourdomaincomauthsaml2metadata
Configure SAML 20 service providers
How do I authenticate against Authentic 2 with a SAML2 service provider
1 Declare Authentic 2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identityprovider metadata of Authentic 2
Go to http[s]yourdomaincomidpsaml2metadata
2 Add and configure a SAML2 service provider in Authentic 2 using the metadata of the service provider
How do I add and configure a SAML2 service provider in Authentic 2
You first need to create a new SAML2 service provider entry This requires the SAML2 metadata of the serviceprovider
If your service provider is Authentic 2 the metadata are available at
http[s]yourdomaincomauthsaml2metadata
32 Configuration with the administration interface 17
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
2 Contents
CHAPTER 1
Overview
Authentic 2 is a versatile identity management server aiming to address a broad range of needs from simple to complexsetups it has support for many protocols and can bridge between them
Authentic 2 supports many protocols and standards including SAML2 CAS OpenID LDAP X509 and OAUTH2
Authentic 2 is under the GNU AGPL version 3 licence
It has support for SAMLv2 thanks to Lasso a free (GNU GPL) implementation of the Liberty Alliance and OASISspecifications of SAML2
Authentic 2 requires Python 27 et Django 15
11 Features
bull SAML 20 Identity and service provider
bull OpenID 10 and 20 identity provider
bull Server CAS 10 and 20 using a plugin
bull Standards authentication mechanisms
ndash Loginpassword through internal directory or LDAP
ndash X509 certificate over SSLTLS
bull Protocol proxying for instance between OpenID and SAML
bull Support of LDAP v2 and v3 directories
bull Support of the PAM backend
bull One-time password (OATH and Google-Authenticator) using a plugin
bull Identity attribute management
bull Plugin system
12 Source and issue tracker
You can find on the project site authenticentrouvertorg mainly the issue tracker
You can find there a viewer of the git repository or clone it
3
Authentic2 Documentation Release 202
git clone httpreposentrouvertorgauthenticgit
13 Support
Authenticrsquos developpers and users hangs on the mailing list authenticlistesentrouvertcom See archives or registerat httplistesentrouvertcominfoauthentic
You can open reports or feature request on httpauthenticentrouvertorg
Entrrsquoouvert also provides a commercial support For information visit httpwwwentrouvertcom
4 Chapter 1 Overview
CHAPTER 2
Installation and quickstart tutorials
Yoursquoll find here how to start and configure very quickly Authentic 2 for its main features You just need Python 27and Django 15
First of all you can boot Authentic vwithout root privileges like this
1 Initialize a virtualenv
virtualenv authenticsource authenticbinactivatecd authentic
2 Install Authentic
pip install authentic2
3 Initialize the database migrations
authentic2-ctl syncdb --migrate
4 Run the HTTP test server
authentic2-ctl runserver
21 Quickstart guides and installation guidelines
211 Installation modes
The current version of Authentic 2 works with Python 27 and Django 15
Authentic 2 python installation script handles all the dependencies except Lasso relying on the Setuptools and thepypi repository
To run Authentic 2 with SAML2 features you need to install lasso gt= 236 see Lasso installation
The other Authentic 2 dependencies are
bull Djangolt16
bull southgt=084
bull requests
bull django-model-utils
bull django-registrationgt=1
5
Authentic2 Documentation Release 202
bull django-debug-toolbargt=12lt13
bull ndashallow-external django-admin-tools
bull ndashallow-unverified django-admin-tools
bull django-admin-toolsgt=051
bull dnspython
bull django-select2
bull django-tables2
bull gadjo
bull django-import-export
bull django-sekizai
Install Authentic 2
bull Install Authentic directly from pypi
bull Obtain the last package archive from pypi
bull Obtain the last sources from the Git repository
Lasso installation
Lasso is available in the linux debian destribution repositories If you are installing Authentic 2 on debian just execute
apt-get install python-lasso
Yoursquoll find more updated packages on httpdebentrouvertorg
We also provide rpm packages for redhat see httpsdeventrouvertorgredhatREADME
You can also install lasso from sources httplassoentrouvertorgdownload
See the Lasso website for installation details This is a quick installation example
Install the following Lasso dependencies
bull autoconf
bull automake
bull autotools-dev
bull libtool
bull gtk-doc-tools
bull zlib1g-dev
bull libglib20-dev
bull openssl-dev
bull libxml2-dev
bull libxmlsec1-dev
bull python26-dev
bull python-setuptools
Obtain Lasso
6 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
$wget httpsdeventrouvertorglassolasso-236targz$tar xzvf lasso-236targz$cd lasso-236$autogensh
Be sure that the Python bindings is selected as follows
=============Configuration=============
Main----
Compiler gccCFLAGSInstall prefix usrlocalDebugging noExperimental ID-WSF no
Optionals builds----------------
Available languages java(461) python(27) perl(5124)
Java binding yesPerl binding yesPHP 5 binding noPython binding yes
C API references yesTests suite no
Now type make install to install lasso
As indicated build and install
$make install$ldconfig
Set the lasso python binding in you python path eg
$export PYTHONPATH=$PYTHONPATHusrlocallibpython26site-packages
Test trying to import Lasso
$pythongtgtgt import lasso
Install Authentic directly from pypi
Using pip
pip install authentic2
You can now run Authentic from the installation directory
21 Quickstart guides and installation guidelines 7
Authentic2 Documentation Release 202
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last package archive from pypi
Download the archive on httppypipythonorgpypiauthentic2
Then you can install it directly from the archive using pip
pip install authentic2-xzytargz
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last sources from the Git repository
Clone the repository
git clone httpreposentrouvertorgauthenticgit
Then you can install it directly using pip
cd authenticpip install -e
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
8 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
212 Specifying a different database
This is done by modifying the DATABASES dictionary in your local_settingspy file (create it in Authentic projectdirectory) for example
DATABASES[default] = ENGINE djangodbbackendspostgresqlNAME authenticUSER admindbPASSWORD foobarHOST dbexamplecomPORT empty string means default value
You should refer to the Django documentation on databases settings athttpdocsdjangoprojectcomendevrefsettingsdatabases for all the details
213 Upgrading
Update using pip
pip install -U authentic2
Authentic store all its data in a relational database as specified in its settingspy or local_settingspy file So in order toupgrade to a new version of authentic you have to update your database schema using the migration command mdash youwill need to have installed the dependency django-south see the beginning of this README file
authentic2-ctl syncdb --migrate
214 Running Authentic 2 for real (Nginx Apache etc)
DEBUG Mode by default static files and the Django debug toolbar dependency
By default Authentic 2 is in the DEBUG mode We made this default choice because most of the Authentic 2rsquos userswill begin with Authentic 2 using the Django development server (runserver command) and we want to avoid them abad first impression because static files would not be served As a matter of fact static files are served by the Djangodevelopment server only when the project is run in the DEBUG mode
In the DEBUG mode the Django debug toolbar is used what adds a dependency
In production the Django development server should not be used to serve Authentic 2 and a dedicated server shouldalso be used to serve the static files
21 Quickstart guides and installation guidelines 9
Authentic2 Documentation Release 202
Set Authentic into the no DEBUG Mode
It is enough to edit authentic2settingspy and set
DEBUG = False
From then on the django-debug-toolbar package is not necessary anymore
Use dedicated HTTP servers and serve static files
The best is to use a server dedicated to serve the Django applications and a different server to serve the static files
You could for instance use apache with mod_wsgi to serve Authentic 2 You will find configuration file examples inthe debian directory of the Authentic 2 sources
Then you may want to use nginx to serve the static files
First you need to collect the Authentic 2 static files The static files are collected using the collectstatic command thatis configured in the settingspy
By default running collectstatic will create a static directory in the parent directory of the authentic2 directory
$python authentic2managepy collectstatic
That static directory will contain all the static files of Authentic 2
If you want to change the path of the static directory you can edit STATIC_ROOT of the settings file
See httpsdocsdjangoprojectcomendevrefcontribstaticfiles for more information about collectstatic
215 Quickstarts
Quickstart an OAuth2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6053
Quickstart an SAML2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6057
Quickstart a connection with a SAML2 Service Provider
1 Get the Identity Provider SAML2 metadata file
http[s]yourdomaincomidpsaml2metadata
2 Configure your service provider with it
3 Go to the providers admin panel on
http[s]adminsamllibertyprovideradd
There create a new provider using the service provider metadata and enable it as a service provider
10 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Quickstart a CAS Identity Provider
1 Activate CAS IdP support in your local_settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
authentic2-ctl syncdb ndashall authentic2-ctl migrate ndashfake
2 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
3 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
Quickstart to connect a LDAP Directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django for this you need python-ldap python-ldap needs python de-velopement headers to be installed but is usually packaged by most distributions
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP The next lines must be added
AUTHENTICATION_BACKENDS += ( lsquodjango_auth_ldapbackendLDAPBackendrsquo )
import ldap from django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your server AUTH_LDAP_SERVER_URI = lsquoldapldapexamplecomlsquo Let the bind DN and bind password blank for anonymous binding AUTH_LDAP_BIND_DN = ldquordquoAUTH_LDAP_BIND_PASSWORD = ldquordquo Lookup user under the branch o=base and by mathcing theiruid against the received login name AUTH_LDAP_USER_SEARCH = LDAPSearch(ldquoo=baserdquo
ldapSCOPE_SUBTREE ldquo(uid=(user)s)rdquo)
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesType AUTH_LDAP_GROUP_TYPE = GroupOf-NamesType() AUTH_LDAP_GROUP_SEARCH = LDAPSearch(ldquoo=mycompanyrdquo
ldapSCOPE_SUBTREE ldquo(objectClass=groupOfNames)rdquo)
AUTH_LDAP_USER_FLAGS_BY_GROUP = ldquois_staffrdquo ldquocn=admino=mycompanyrdquo
21 Quickstart guides and installation guidelines 11
Authentic2 Documentation Release 202
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
Quickstart for PAM Authentication
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
12 Chapter 2 Installation and quickstart tutorials
CHAPTER 3
Configuration
31 Configuration with settings
311 Works with authentic 2 settings
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6047
312 All settings
Activate or deactivate debug mode
Variable DEBUG
Values
bull False deactivate debug mode
bull True activate debug mode
Manage session cookie duration
Variable SESSION_EXPIRE_AT_BROWSER_CLOSE
Values
bull False Cookies are not removed when browser is closed
bull True Cookies are removed when browser is closed
Variable SESSION_COOKIE_AGE
Value
bull Seconds (36000 equal 10 hours)
Time zone selection
Variable TIME_ZONE
Values
13
Authentic2 Documentation Release 202
bull See httpenwikipediaorgwikiList_of_tz_zones_by_name
Activate or deactivate SSL authentication
Variable AUTH_SSL
Values
bull False deactivate SSL authentication
bull True activate SSL authentication
Activate or deactivate OpenID authentication Authentic 2 is an OpenID relying party
Variable AUTH_OPENID
Values
bull False deactivate OpenID authentication
bull True activate OpenID authentication
Activate or deactivate Authentic 2 as a SAML2 identity provider
Variable IDP_SAML2
Values
bull False deactivate SAML2 identity provider
bull True activate SAML2 identity provider
Configure SAML2 keys
bull SAML_SIGNATURE_PUBLIC_KEY Certtificate or public key for signature
bull SAML_SIGNATURE_PRIVATE_KEY Private key for signature
bull SAML_ENCRYPTION_PUBLIC_KEY Certtificate or public key for encryption
bull SAML_ENCRYPTION_PRIVATE_KEY Private key for encryption
Values are pem files of X509 certificate or key eg SAML_SIGNATURE_PRIVATE_KEY = lsquorsquolsquomdashndashBEGIN RSAPRIVATE KEYmdashndash MIIWA== mdashndashEND RSA PRIVATE KEYmdashndashlsquorsquolsquo
If SAML_ENCRYPTION_PUBLIC_KEY or SAML_ENCRYPTION_PRIVATE_KEY are not given the signaturekeys are used for encryption
Activate or deactivate Authentic 2 as an OpenID provider
Variable IDP_OPENID
Values
bull False deactivate OpenID provider
bull True activate OpenID provider
14 Chapter 3 Configuration
Authentic2 Documentation Release 202
Activate or deactivate Authentic 2 as a CAS server
Variable IDP_CAS
Values
bull False deactivate CAS server
bull True activate CAS server
32 Configuration with the administration interface
321 Basics
Access the grapical administration interface
The grapical administration interface is the lsquoDjango adminrsquo part of a Django project See for more information
Just acces the admin url at http[s]yourdomaincomadmin
At first you log with the superuser you created at the very first database initialization
Then you can configure other accesses to the admin checking the is_staff option displayed on a user in the admin
Work with policies
The policy management with global policies is nearly used for any kind of policy in Authentic 2
For each kind of these policies the system takes in account two special global policies named lsquoDefaultrsquo and lsquoAllrsquo
bull There is always a system default that does not correspond to the lsquoDefaultrsquo policy This is used to make Authentic2 boot without initial configuration When you add a lsquoDefaultrsquo policy the system default are not used anymore
bull A policy has always a name lsquoDefaultrsquo and lsquoAllrsquo are the names of two special policies with their name hardcodedBut you can create or delete them
bull If no other policy applies the policy lsquoDefaultrsquo applies
bull A policy can be created and attached to any related object This policy is authoritative on the policy lsquoDefaultrsquo
bull If the policy lsquoAllrsquo exists it is authoritative on any other policy
bull The global policies lsquoAllrsquo and lsquoDefaultrsquo are created by the administrator if necessary
bull A policy is taken in account only if it is enabled
bull When a regular policy is associated with an object it is taken in account only if the option lsquoenable the followingpolicyrsquo is checked on the oject
It is advised to add a lsquoDefaultrsquo global policy when it is expected to apply a policy to all related objects A lsquoDefaultrsquoglobal policy should be defined to avoid misonfiguration
Add a regular policy to some objects are used to handle particular configurations for a subset of related objects
An lsquoAllrsquo global policy should be used to enforce a global configuration for all related objects or for testing purposes
32 Configuration with the administration interface 15
Authentic2 Documentation Release 202
322 Authentication backends
Authentication with an existing LDAP directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP
The next lines must be added
AUTHENTICATION_BACKENDS += ( django_auth_ldapbackendLDAPBackend )
import ldapfrom django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your serverAUTH_LDAP_SERVER_URI = ldapldapexamplecom Let the bind DN and bind password blank for anonymous bindingAUTH_LDAP_BIND_DN = AUTH_LDAP_BIND_PASSWORD = Lookup user under the branch o=base and by mathcing their uid against the received login nameAUTH_LDAP_USER_SEARCH = LDAPSearch(o=base
ldapSCOPE_SUBTREE (uid=(user)s))
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesTypeAUTH_LDAP_GROUP_TYPE = GroupOfNamesType()AUTH_LDAP_GROUP_SEARCH = LDAPSearch(o=mycompany
ldapSCOPE_SUBTREE (objectClass=groupOfNames))AUTH_LDAP_USER_FLAGS_BY_GROUP =
is_staff cn=admino=mycompany
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
16 Chapter 3 Configuration
Authentic2 Documentation Release 202
Authentication on Authentic 2 with PAM
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
323 SAML2
Where do I find the Authentic 2 SAML2 metadata
The SAML2 metadata are automatically generated
Authentic 2 will infer from environment variables the host and port to generate the URLs contained in themedatada
The metadata of Authentic 2 SAML2 identity provider are available at
http[s]yourdomaincomidpsaml2metadata
The metadata of Authentic 2 SAML2 service provider are available at
http[s]yourdomaincomauthsaml2metadata
Configure SAML 20 service providers
How do I authenticate against Authentic 2 with a SAML2 service provider
1 Declare Authentic 2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identityprovider metadata of Authentic 2
Go to http[s]yourdomaincomidpsaml2metadata
2 Add and configure a SAML2 service provider in Authentic 2 using the metadata of the service provider
How do I add and configure a SAML2 service provider in Authentic 2
You first need to create a new SAML2 service provider entry This requires the SAML2 metadata of the serviceprovider
If your service provider is Authentic 2 the metadata are available at
http[s]yourdomaincomauthsaml2metadata
32 Configuration with the administration interface 17
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
CHAPTER 1
Overview
Authentic 2 is a versatile identity management server aiming to address a broad range of needs from simple to complexsetups it has support for many protocols and can bridge between them
Authentic 2 supports many protocols and standards including SAML2 CAS OpenID LDAP X509 and OAUTH2
Authentic 2 is under the GNU AGPL version 3 licence
It has support for SAMLv2 thanks to Lasso a free (GNU GPL) implementation of the Liberty Alliance and OASISspecifications of SAML2
Authentic 2 requires Python 27 et Django 15
11 Features
bull SAML 20 Identity and service provider
bull OpenID 10 and 20 identity provider
bull Server CAS 10 and 20 using a plugin
bull Standards authentication mechanisms
ndash Loginpassword through internal directory or LDAP
ndash X509 certificate over SSLTLS
bull Protocol proxying for instance between OpenID and SAML
bull Support of LDAP v2 and v3 directories
bull Support of the PAM backend
bull One-time password (OATH and Google-Authenticator) using a plugin
bull Identity attribute management
bull Plugin system
12 Source and issue tracker
You can find on the project site authenticentrouvertorg mainly the issue tracker
You can find there a viewer of the git repository or clone it
3
Authentic2 Documentation Release 202
git clone httpreposentrouvertorgauthenticgit
13 Support
Authenticrsquos developpers and users hangs on the mailing list authenticlistesentrouvertcom See archives or registerat httplistesentrouvertcominfoauthentic
You can open reports or feature request on httpauthenticentrouvertorg
Entrrsquoouvert also provides a commercial support For information visit httpwwwentrouvertcom
4 Chapter 1 Overview
CHAPTER 2
Installation and quickstart tutorials
Yoursquoll find here how to start and configure very quickly Authentic 2 for its main features You just need Python 27and Django 15
First of all you can boot Authentic vwithout root privileges like this
1 Initialize a virtualenv
virtualenv authenticsource authenticbinactivatecd authentic
2 Install Authentic
pip install authentic2
3 Initialize the database migrations
authentic2-ctl syncdb --migrate
4 Run the HTTP test server
authentic2-ctl runserver
21 Quickstart guides and installation guidelines
211 Installation modes
The current version of Authentic 2 works with Python 27 and Django 15
Authentic 2 python installation script handles all the dependencies except Lasso relying on the Setuptools and thepypi repository
To run Authentic 2 with SAML2 features you need to install lasso gt= 236 see Lasso installation
The other Authentic 2 dependencies are
bull Djangolt16
bull southgt=084
bull requests
bull django-model-utils
bull django-registrationgt=1
5
Authentic2 Documentation Release 202
bull django-debug-toolbargt=12lt13
bull ndashallow-external django-admin-tools
bull ndashallow-unverified django-admin-tools
bull django-admin-toolsgt=051
bull dnspython
bull django-select2
bull django-tables2
bull gadjo
bull django-import-export
bull django-sekizai
Install Authentic 2
bull Install Authentic directly from pypi
bull Obtain the last package archive from pypi
bull Obtain the last sources from the Git repository
Lasso installation
Lasso is available in the linux debian destribution repositories If you are installing Authentic 2 on debian just execute
apt-get install python-lasso
Yoursquoll find more updated packages on httpdebentrouvertorg
We also provide rpm packages for redhat see httpsdeventrouvertorgredhatREADME
You can also install lasso from sources httplassoentrouvertorgdownload
See the Lasso website for installation details This is a quick installation example
Install the following Lasso dependencies
bull autoconf
bull automake
bull autotools-dev
bull libtool
bull gtk-doc-tools
bull zlib1g-dev
bull libglib20-dev
bull openssl-dev
bull libxml2-dev
bull libxmlsec1-dev
bull python26-dev
bull python-setuptools
Obtain Lasso
6 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
$wget httpsdeventrouvertorglassolasso-236targz$tar xzvf lasso-236targz$cd lasso-236$autogensh
Be sure that the Python bindings is selected as follows
=============Configuration=============
Main----
Compiler gccCFLAGSInstall prefix usrlocalDebugging noExperimental ID-WSF no
Optionals builds----------------
Available languages java(461) python(27) perl(5124)
Java binding yesPerl binding yesPHP 5 binding noPython binding yes
C API references yesTests suite no
Now type make install to install lasso
As indicated build and install
$make install$ldconfig
Set the lasso python binding in you python path eg
$export PYTHONPATH=$PYTHONPATHusrlocallibpython26site-packages
Test trying to import Lasso
$pythongtgtgt import lasso
Install Authentic directly from pypi
Using pip
pip install authentic2
You can now run Authentic from the installation directory
21 Quickstart guides and installation guidelines 7
Authentic2 Documentation Release 202
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last package archive from pypi
Download the archive on httppypipythonorgpypiauthentic2
Then you can install it directly from the archive using pip
pip install authentic2-xzytargz
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last sources from the Git repository
Clone the repository
git clone httpreposentrouvertorgauthenticgit
Then you can install it directly using pip
cd authenticpip install -e
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
8 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
212 Specifying a different database
This is done by modifying the DATABASES dictionary in your local_settingspy file (create it in Authentic projectdirectory) for example
DATABASES[default] = ENGINE djangodbbackendspostgresqlNAME authenticUSER admindbPASSWORD foobarHOST dbexamplecomPORT empty string means default value
You should refer to the Django documentation on databases settings athttpdocsdjangoprojectcomendevrefsettingsdatabases for all the details
213 Upgrading
Update using pip
pip install -U authentic2
Authentic store all its data in a relational database as specified in its settingspy or local_settingspy file So in order toupgrade to a new version of authentic you have to update your database schema using the migration command mdash youwill need to have installed the dependency django-south see the beginning of this README file
authentic2-ctl syncdb --migrate
214 Running Authentic 2 for real (Nginx Apache etc)
DEBUG Mode by default static files and the Django debug toolbar dependency
By default Authentic 2 is in the DEBUG mode We made this default choice because most of the Authentic 2rsquos userswill begin with Authentic 2 using the Django development server (runserver command) and we want to avoid them abad first impression because static files would not be served As a matter of fact static files are served by the Djangodevelopment server only when the project is run in the DEBUG mode
In the DEBUG mode the Django debug toolbar is used what adds a dependency
In production the Django development server should not be used to serve Authentic 2 and a dedicated server shouldalso be used to serve the static files
21 Quickstart guides and installation guidelines 9
Authentic2 Documentation Release 202
Set Authentic into the no DEBUG Mode
It is enough to edit authentic2settingspy and set
DEBUG = False
From then on the django-debug-toolbar package is not necessary anymore
Use dedicated HTTP servers and serve static files
The best is to use a server dedicated to serve the Django applications and a different server to serve the static files
You could for instance use apache with mod_wsgi to serve Authentic 2 You will find configuration file examples inthe debian directory of the Authentic 2 sources
Then you may want to use nginx to serve the static files
First you need to collect the Authentic 2 static files The static files are collected using the collectstatic command thatis configured in the settingspy
By default running collectstatic will create a static directory in the parent directory of the authentic2 directory
$python authentic2managepy collectstatic
That static directory will contain all the static files of Authentic 2
If you want to change the path of the static directory you can edit STATIC_ROOT of the settings file
See httpsdocsdjangoprojectcomendevrefcontribstaticfiles for more information about collectstatic
215 Quickstarts
Quickstart an OAuth2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6053
Quickstart an SAML2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6057
Quickstart a connection with a SAML2 Service Provider
1 Get the Identity Provider SAML2 metadata file
http[s]yourdomaincomidpsaml2metadata
2 Configure your service provider with it
3 Go to the providers admin panel on
http[s]adminsamllibertyprovideradd
There create a new provider using the service provider metadata and enable it as a service provider
10 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Quickstart a CAS Identity Provider
1 Activate CAS IdP support in your local_settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
authentic2-ctl syncdb ndashall authentic2-ctl migrate ndashfake
2 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
3 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
Quickstart to connect a LDAP Directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django for this you need python-ldap python-ldap needs python de-velopement headers to be installed but is usually packaged by most distributions
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP The next lines must be added
AUTHENTICATION_BACKENDS += ( lsquodjango_auth_ldapbackendLDAPBackendrsquo )
import ldap from django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your server AUTH_LDAP_SERVER_URI = lsquoldapldapexamplecomlsquo Let the bind DN and bind password blank for anonymous binding AUTH_LDAP_BIND_DN = ldquordquoAUTH_LDAP_BIND_PASSWORD = ldquordquo Lookup user under the branch o=base and by mathcing theiruid against the received login name AUTH_LDAP_USER_SEARCH = LDAPSearch(ldquoo=baserdquo
ldapSCOPE_SUBTREE ldquo(uid=(user)s)rdquo)
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesType AUTH_LDAP_GROUP_TYPE = GroupOf-NamesType() AUTH_LDAP_GROUP_SEARCH = LDAPSearch(ldquoo=mycompanyrdquo
ldapSCOPE_SUBTREE ldquo(objectClass=groupOfNames)rdquo)
AUTH_LDAP_USER_FLAGS_BY_GROUP = ldquois_staffrdquo ldquocn=admino=mycompanyrdquo
21 Quickstart guides and installation guidelines 11
Authentic2 Documentation Release 202
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
Quickstart for PAM Authentication
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
12 Chapter 2 Installation and quickstart tutorials
CHAPTER 3
Configuration
31 Configuration with settings
311 Works with authentic 2 settings
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6047
312 All settings
Activate or deactivate debug mode
Variable DEBUG
Values
bull False deactivate debug mode
bull True activate debug mode
Manage session cookie duration
Variable SESSION_EXPIRE_AT_BROWSER_CLOSE
Values
bull False Cookies are not removed when browser is closed
bull True Cookies are removed when browser is closed
Variable SESSION_COOKIE_AGE
Value
bull Seconds (36000 equal 10 hours)
Time zone selection
Variable TIME_ZONE
Values
13
Authentic2 Documentation Release 202
bull See httpenwikipediaorgwikiList_of_tz_zones_by_name
Activate or deactivate SSL authentication
Variable AUTH_SSL
Values
bull False deactivate SSL authentication
bull True activate SSL authentication
Activate or deactivate OpenID authentication Authentic 2 is an OpenID relying party
Variable AUTH_OPENID
Values
bull False deactivate OpenID authentication
bull True activate OpenID authentication
Activate or deactivate Authentic 2 as a SAML2 identity provider
Variable IDP_SAML2
Values
bull False deactivate SAML2 identity provider
bull True activate SAML2 identity provider
Configure SAML2 keys
bull SAML_SIGNATURE_PUBLIC_KEY Certtificate or public key for signature
bull SAML_SIGNATURE_PRIVATE_KEY Private key for signature
bull SAML_ENCRYPTION_PUBLIC_KEY Certtificate or public key for encryption
bull SAML_ENCRYPTION_PRIVATE_KEY Private key for encryption
Values are pem files of X509 certificate or key eg SAML_SIGNATURE_PRIVATE_KEY = lsquorsquolsquomdashndashBEGIN RSAPRIVATE KEYmdashndash MIIWA== mdashndashEND RSA PRIVATE KEYmdashndashlsquorsquolsquo
If SAML_ENCRYPTION_PUBLIC_KEY or SAML_ENCRYPTION_PRIVATE_KEY are not given the signaturekeys are used for encryption
Activate or deactivate Authentic 2 as an OpenID provider
Variable IDP_OPENID
Values
bull False deactivate OpenID provider
bull True activate OpenID provider
14 Chapter 3 Configuration
Authentic2 Documentation Release 202
Activate or deactivate Authentic 2 as a CAS server
Variable IDP_CAS
Values
bull False deactivate CAS server
bull True activate CAS server
32 Configuration with the administration interface
321 Basics
Access the grapical administration interface
The grapical administration interface is the lsquoDjango adminrsquo part of a Django project See for more information
Just acces the admin url at http[s]yourdomaincomadmin
At first you log with the superuser you created at the very first database initialization
Then you can configure other accesses to the admin checking the is_staff option displayed on a user in the admin
Work with policies
The policy management with global policies is nearly used for any kind of policy in Authentic 2
For each kind of these policies the system takes in account two special global policies named lsquoDefaultrsquo and lsquoAllrsquo
bull There is always a system default that does not correspond to the lsquoDefaultrsquo policy This is used to make Authentic2 boot without initial configuration When you add a lsquoDefaultrsquo policy the system default are not used anymore
bull A policy has always a name lsquoDefaultrsquo and lsquoAllrsquo are the names of two special policies with their name hardcodedBut you can create or delete them
bull If no other policy applies the policy lsquoDefaultrsquo applies
bull A policy can be created and attached to any related object This policy is authoritative on the policy lsquoDefaultrsquo
bull If the policy lsquoAllrsquo exists it is authoritative on any other policy
bull The global policies lsquoAllrsquo and lsquoDefaultrsquo are created by the administrator if necessary
bull A policy is taken in account only if it is enabled
bull When a regular policy is associated with an object it is taken in account only if the option lsquoenable the followingpolicyrsquo is checked on the oject
It is advised to add a lsquoDefaultrsquo global policy when it is expected to apply a policy to all related objects A lsquoDefaultrsquoglobal policy should be defined to avoid misonfiguration
Add a regular policy to some objects are used to handle particular configurations for a subset of related objects
An lsquoAllrsquo global policy should be used to enforce a global configuration for all related objects or for testing purposes
32 Configuration with the administration interface 15
Authentic2 Documentation Release 202
322 Authentication backends
Authentication with an existing LDAP directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP
The next lines must be added
AUTHENTICATION_BACKENDS += ( django_auth_ldapbackendLDAPBackend )
import ldapfrom django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your serverAUTH_LDAP_SERVER_URI = ldapldapexamplecom Let the bind DN and bind password blank for anonymous bindingAUTH_LDAP_BIND_DN = AUTH_LDAP_BIND_PASSWORD = Lookup user under the branch o=base and by mathcing their uid against the received login nameAUTH_LDAP_USER_SEARCH = LDAPSearch(o=base
ldapSCOPE_SUBTREE (uid=(user)s))
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesTypeAUTH_LDAP_GROUP_TYPE = GroupOfNamesType()AUTH_LDAP_GROUP_SEARCH = LDAPSearch(o=mycompany
ldapSCOPE_SUBTREE (objectClass=groupOfNames))AUTH_LDAP_USER_FLAGS_BY_GROUP =
is_staff cn=admino=mycompany
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
16 Chapter 3 Configuration
Authentic2 Documentation Release 202
Authentication on Authentic 2 with PAM
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
323 SAML2
Where do I find the Authentic 2 SAML2 metadata
The SAML2 metadata are automatically generated
Authentic 2 will infer from environment variables the host and port to generate the URLs contained in themedatada
The metadata of Authentic 2 SAML2 identity provider are available at
http[s]yourdomaincomidpsaml2metadata
The metadata of Authentic 2 SAML2 service provider are available at
http[s]yourdomaincomauthsaml2metadata
Configure SAML 20 service providers
How do I authenticate against Authentic 2 with a SAML2 service provider
1 Declare Authentic 2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identityprovider metadata of Authentic 2
Go to http[s]yourdomaincomidpsaml2metadata
2 Add and configure a SAML2 service provider in Authentic 2 using the metadata of the service provider
How do I add and configure a SAML2 service provider in Authentic 2
You first need to create a new SAML2 service provider entry This requires the SAML2 metadata of the serviceprovider
If your service provider is Authentic 2 the metadata are available at
http[s]yourdomaincomauthsaml2metadata
32 Configuration with the administration interface 17
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
git clone httpreposentrouvertorgauthenticgit
13 Support
Authenticrsquos developpers and users hangs on the mailing list authenticlistesentrouvertcom See archives or registerat httplistesentrouvertcominfoauthentic
You can open reports or feature request on httpauthenticentrouvertorg
Entrrsquoouvert also provides a commercial support For information visit httpwwwentrouvertcom
4 Chapter 1 Overview
CHAPTER 2
Installation and quickstart tutorials
Yoursquoll find here how to start and configure very quickly Authentic 2 for its main features You just need Python 27and Django 15
First of all you can boot Authentic vwithout root privileges like this
1 Initialize a virtualenv
virtualenv authenticsource authenticbinactivatecd authentic
2 Install Authentic
pip install authentic2
3 Initialize the database migrations
authentic2-ctl syncdb --migrate
4 Run the HTTP test server
authentic2-ctl runserver
21 Quickstart guides and installation guidelines
211 Installation modes
The current version of Authentic 2 works with Python 27 and Django 15
Authentic 2 python installation script handles all the dependencies except Lasso relying on the Setuptools and thepypi repository
To run Authentic 2 with SAML2 features you need to install lasso gt= 236 see Lasso installation
The other Authentic 2 dependencies are
bull Djangolt16
bull southgt=084
bull requests
bull django-model-utils
bull django-registrationgt=1
5
Authentic2 Documentation Release 202
bull django-debug-toolbargt=12lt13
bull ndashallow-external django-admin-tools
bull ndashallow-unverified django-admin-tools
bull django-admin-toolsgt=051
bull dnspython
bull django-select2
bull django-tables2
bull gadjo
bull django-import-export
bull django-sekizai
Install Authentic 2
bull Install Authentic directly from pypi
bull Obtain the last package archive from pypi
bull Obtain the last sources from the Git repository
Lasso installation
Lasso is available in the linux debian destribution repositories If you are installing Authentic 2 on debian just execute
apt-get install python-lasso
Yoursquoll find more updated packages on httpdebentrouvertorg
We also provide rpm packages for redhat see httpsdeventrouvertorgredhatREADME
You can also install lasso from sources httplassoentrouvertorgdownload
See the Lasso website for installation details This is a quick installation example
Install the following Lasso dependencies
bull autoconf
bull automake
bull autotools-dev
bull libtool
bull gtk-doc-tools
bull zlib1g-dev
bull libglib20-dev
bull openssl-dev
bull libxml2-dev
bull libxmlsec1-dev
bull python26-dev
bull python-setuptools
Obtain Lasso
6 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
$wget httpsdeventrouvertorglassolasso-236targz$tar xzvf lasso-236targz$cd lasso-236$autogensh
Be sure that the Python bindings is selected as follows
=============Configuration=============
Main----
Compiler gccCFLAGSInstall prefix usrlocalDebugging noExperimental ID-WSF no
Optionals builds----------------
Available languages java(461) python(27) perl(5124)
Java binding yesPerl binding yesPHP 5 binding noPython binding yes
C API references yesTests suite no
Now type make install to install lasso
As indicated build and install
$make install$ldconfig
Set the lasso python binding in you python path eg
$export PYTHONPATH=$PYTHONPATHusrlocallibpython26site-packages
Test trying to import Lasso
$pythongtgtgt import lasso
Install Authentic directly from pypi
Using pip
pip install authentic2
You can now run Authentic from the installation directory
21 Quickstart guides and installation guidelines 7
Authentic2 Documentation Release 202
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last package archive from pypi
Download the archive on httppypipythonorgpypiauthentic2
Then you can install it directly from the archive using pip
pip install authentic2-xzytargz
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last sources from the Git repository
Clone the repository
git clone httpreposentrouvertorgauthenticgit
Then you can install it directly using pip
cd authenticpip install -e
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
8 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
212 Specifying a different database
This is done by modifying the DATABASES dictionary in your local_settingspy file (create it in Authentic projectdirectory) for example
DATABASES[default] = ENGINE djangodbbackendspostgresqlNAME authenticUSER admindbPASSWORD foobarHOST dbexamplecomPORT empty string means default value
You should refer to the Django documentation on databases settings athttpdocsdjangoprojectcomendevrefsettingsdatabases for all the details
213 Upgrading
Update using pip
pip install -U authentic2
Authentic store all its data in a relational database as specified in its settingspy or local_settingspy file So in order toupgrade to a new version of authentic you have to update your database schema using the migration command mdash youwill need to have installed the dependency django-south see the beginning of this README file
authentic2-ctl syncdb --migrate
214 Running Authentic 2 for real (Nginx Apache etc)
DEBUG Mode by default static files and the Django debug toolbar dependency
By default Authentic 2 is in the DEBUG mode We made this default choice because most of the Authentic 2rsquos userswill begin with Authentic 2 using the Django development server (runserver command) and we want to avoid them abad first impression because static files would not be served As a matter of fact static files are served by the Djangodevelopment server only when the project is run in the DEBUG mode
In the DEBUG mode the Django debug toolbar is used what adds a dependency
In production the Django development server should not be used to serve Authentic 2 and a dedicated server shouldalso be used to serve the static files
21 Quickstart guides and installation guidelines 9
Authentic2 Documentation Release 202
Set Authentic into the no DEBUG Mode
It is enough to edit authentic2settingspy and set
DEBUG = False
From then on the django-debug-toolbar package is not necessary anymore
Use dedicated HTTP servers and serve static files
The best is to use a server dedicated to serve the Django applications and a different server to serve the static files
You could for instance use apache with mod_wsgi to serve Authentic 2 You will find configuration file examples inthe debian directory of the Authentic 2 sources
Then you may want to use nginx to serve the static files
First you need to collect the Authentic 2 static files The static files are collected using the collectstatic command thatis configured in the settingspy
By default running collectstatic will create a static directory in the parent directory of the authentic2 directory
$python authentic2managepy collectstatic
That static directory will contain all the static files of Authentic 2
If you want to change the path of the static directory you can edit STATIC_ROOT of the settings file
See httpsdocsdjangoprojectcomendevrefcontribstaticfiles for more information about collectstatic
215 Quickstarts
Quickstart an OAuth2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6053
Quickstart an SAML2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6057
Quickstart a connection with a SAML2 Service Provider
1 Get the Identity Provider SAML2 metadata file
http[s]yourdomaincomidpsaml2metadata
2 Configure your service provider with it
3 Go to the providers admin panel on
http[s]adminsamllibertyprovideradd
There create a new provider using the service provider metadata and enable it as a service provider
10 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Quickstart a CAS Identity Provider
1 Activate CAS IdP support in your local_settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
authentic2-ctl syncdb ndashall authentic2-ctl migrate ndashfake
2 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
3 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
Quickstart to connect a LDAP Directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django for this you need python-ldap python-ldap needs python de-velopement headers to be installed but is usually packaged by most distributions
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP The next lines must be added
AUTHENTICATION_BACKENDS += ( lsquodjango_auth_ldapbackendLDAPBackendrsquo )
import ldap from django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your server AUTH_LDAP_SERVER_URI = lsquoldapldapexamplecomlsquo Let the bind DN and bind password blank for anonymous binding AUTH_LDAP_BIND_DN = ldquordquoAUTH_LDAP_BIND_PASSWORD = ldquordquo Lookup user under the branch o=base and by mathcing theiruid against the received login name AUTH_LDAP_USER_SEARCH = LDAPSearch(ldquoo=baserdquo
ldapSCOPE_SUBTREE ldquo(uid=(user)s)rdquo)
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesType AUTH_LDAP_GROUP_TYPE = GroupOf-NamesType() AUTH_LDAP_GROUP_SEARCH = LDAPSearch(ldquoo=mycompanyrdquo
ldapSCOPE_SUBTREE ldquo(objectClass=groupOfNames)rdquo)
AUTH_LDAP_USER_FLAGS_BY_GROUP = ldquois_staffrdquo ldquocn=admino=mycompanyrdquo
21 Quickstart guides and installation guidelines 11
Authentic2 Documentation Release 202
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
Quickstart for PAM Authentication
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
12 Chapter 2 Installation and quickstart tutorials
CHAPTER 3
Configuration
31 Configuration with settings
311 Works with authentic 2 settings
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6047
312 All settings
Activate or deactivate debug mode
Variable DEBUG
Values
bull False deactivate debug mode
bull True activate debug mode
Manage session cookie duration
Variable SESSION_EXPIRE_AT_BROWSER_CLOSE
Values
bull False Cookies are not removed when browser is closed
bull True Cookies are removed when browser is closed
Variable SESSION_COOKIE_AGE
Value
bull Seconds (36000 equal 10 hours)
Time zone selection
Variable TIME_ZONE
Values
13
Authentic2 Documentation Release 202
bull See httpenwikipediaorgwikiList_of_tz_zones_by_name
Activate or deactivate SSL authentication
Variable AUTH_SSL
Values
bull False deactivate SSL authentication
bull True activate SSL authentication
Activate or deactivate OpenID authentication Authentic 2 is an OpenID relying party
Variable AUTH_OPENID
Values
bull False deactivate OpenID authentication
bull True activate OpenID authentication
Activate or deactivate Authentic 2 as a SAML2 identity provider
Variable IDP_SAML2
Values
bull False deactivate SAML2 identity provider
bull True activate SAML2 identity provider
Configure SAML2 keys
bull SAML_SIGNATURE_PUBLIC_KEY Certtificate or public key for signature
bull SAML_SIGNATURE_PRIVATE_KEY Private key for signature
bull SAML_ENCRYPTION_PUBLIC_KEY Certtificate or public key for encryption
bull SAML_ENCRYPTION_PRIVATE_KEY Private key for encryption
Values are pem files of X509 certificate or key eg SAML_SIGNATURE_PRIVATE_KEY = lsquorsquolsquomdashndashBEGIN RSAPRIVATE KEYmdashndash MIIWA== mdashndashEND RSA PRIVATE KEYmdashndashlsquorsquolsquo
If SAML_ENCRYPTION_PUBLIC_KEY or SAML_ENCRYPTION_PRIVATE_KEY are not given the signaturekeys are used for encryption
Activate or deactivate Authentic 2 as an OpenID provider
Variable IDP_OPENID
Values
bull False deactivate OpenID provider
bull True activate OpenID provider
14 Chapter 3 Configuration
Authentic2 Documentation Release 202
Activate or deactivate Authentic 2 as a CAS server
Variable IDP_CAS
Values
bull False deactivate CAS server
bull True activate CAS server
32 Configuration with the administration interface
321 Basics
Access the grapical administration interface
The grapical administration interface is the lsquoDjango adminrsquo part of a Django project See for more information
Just acces the admin url at http[s]yourdomaincomadmin
At first you log with the superuser you created at the very first database initialization
Then you can configure other accesses to the admin checking the is_staff option displayed on a user in the admin
Work with policies
The policy management with global policies is nearly used for any kind of policy in Authentic 2
For each kind of these policies the system takes in account two special global policies named lsquoDefaultrsquo and lsquoAllrsquo
bull There is always a system default that does not correspond to the lsquoDefaultrsquo policy This is used to make Authentic2 boot without initial configuration When you add a lsquoDefaultrsquo policy the system default are not used anymore
bull A policy has always a name lsquoDefaultrsquo and lsquoAllrsquo are the names of two special policies with their name hardcodedBut you can create or delete them
bull If no other policy applies the policy lsquoDefaultrsquo applies
bull A policy can be created and attached to any related object This policy is authoritative on the policy lsquoDefaultrsquo
bull If the policy lsquoAllrsquo exists it is authoritative on any other policy
bull The global policies lsquoAllrsquo and lsquoDefaultrsquo are created by the administrator if necessary
bull A policy is taken in account only if it is enabled
bull When a regular policy is associated with an object it is taken in account only if the option lsquoenable the followingpolicyrsquo is checked on the oject
It is advised to add a lsquoDefaultrsquo global policy when it is expected to apply a policy to all related objects A lsquoDefaultrsquoglobal policy should be defined to avoid misonfiguration
Add a regular policy to some objects are used to handle particular configurations for a subset of related objects
An lsquoAllrsquo global policy should be used to enforce a global configuration for all related objects or for testing purposes
32 Configuration with the administration interface 15
Authentic2 Documentation Release 202
322 Authentication backends
Authentication with an existing LDAP directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP
The next lines must be added
AUTHENTICATION_BACKENDS += ( django_auth_ldapbackendLDAPBackend )
import ldapfrom django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your serverAUTH_LDAP_SERVER_URI = ldapldapexamplecom Let the bind DN and bind password blank for anonymous bindingAUTH_LDAP_BIND_DN = AUTH_LDAP_BIND_PASSWORD = Lookup user under the branch o=base and by mathcing their uid against the received login nameAUTH_LDAP_USER_SEARCH = LDAPSearch(o=base
ldapSCOPE_SUBTREE (uid=(user)s))
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesTypeAUTH_LDAP_GROUP_TYPE = GroupOfNamesType()AUTH_LDAP_GROUP_SEARCH = LDAPSearch(o=mycompany
ldapSCOPE_SUBTREE (objectClass=groupOfNames))AUTH_LDAP_USER_FLAGS_BY_GROUP =
is_staff cn=admino=mycompany
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
16 Chapter 3 Configuration
Authentic2 Documentation Release 202
Authentication on Authentic 2 with PAM
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
323 SAML2
Where do I find the Authentic 2 SAML2 metadata
The SAML2 metadata are automatically generated
Authentic 2 will infer from environment variables the host and port to generate the URLs contained in themedatada
The metadata of Authentic 2 SAML2 identity provider are available at
http[s]yourdomaincomidpsaml2metadata
The metadata of Authentic 2 SAML2 service provider are available at
http[s]yourdomaincomauthsaml2metadata
Configure SAML 20 service providers
How do I authenticate against Authentic 2 with a SAML2 service provider
1 Declare Authentic 2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identityprovider metadata of Authentic 2
Go to http[s]yourdomaincomidpsaml2metadata
2 Add and configure a SAML2 service provider in Authentic 2 using the metadata of the service provider
How do I add and configure a SAML2 service provider in Authentic 2
You first need to create a new SAML2 service provider entry This requires the SAML2 metadata of the serviceprovider
If your service provider is Authentic 2 the metadata are available at
http[s]yourdomaincomauthsaml2metadata
32 Configuration with the administration interface 17
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
CHAPTER 2
Installation and quickstart tutorials
Yoursquoll find here how to start and configure very quickly Authentic 2 for its main features You just need Python 27and Django 15
First of all you can boot Authentic vwithout root privileges like this
1 Initialize a virtualenv
virtualenv authenticsource authenticbinactivatecd authentic
2 Install Authentic
pip install authentic2
3 Initialize the database migrations
authentic2-ctl syncdb --migrate
4 Run the HTTP test server
authentic2-ctl runserver
21 Quickstart guides and installation guidelines
211 Installation modes
The current version of Authentic 2 works with Python 27 and Django 15
Authentic 2 python installation script handles all the dependencies except Lasso relying on the Setuptools and thepypi repository
To run Authentic 2 with SAML2 features you need to install lasso gt= 236 see Lasso installation
The other Authentic 2 dependencies are
bull Djangolt16
bull southgt=084
bull requests
bull django-model-utils
bull django-registrationgt=1
5
Authentic2 Documentation Release 202
bull django-debug-toolbargt=12lt13
bull ndashallow-external django-admin-tools
bull ndashallow-unverified django-admin-tools
bull django-admin-toolsgt=051
bull dnspython
bull django-select2
bull django-tables2
bull gadjo
bull django-import-export
bull django-sekizai
Install Authentic 2
bull Install Authentic directly from pypi
bull Obtain the last package archive from pypi
bull Obtain the last sources from the Git repository
Lasso installation
Lasso is available in the linux debian destribution repositories If you are installing Authentic 2 on debian just execute
apt-get install python-lasso
Yoursquoll find more updated packages on httpdebentrouvertorg
We also provide rpm packages for redhat see httpsdeventrouvertorgredhatREADME
You can also install lasso from sources httplassoentrouvertorgdownload
See the Lasso website for installation details This is a quick installation example
Install the following Lasso dependencies
bull autoconf
bull automake
bull autotools-dev
bull libtool
bull gtk-doc-tools
bull zlib1g-dev
bull libglib20-dev
bull openssl-dev
bull libxml2-dev
bull libxmlsec1-dev
bull python26-dev
bull python-setuptools
Obtain Lasso
6 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
$wget httpsdeventrouvertorglassolasso-236targz$tar xzvf lasso-236targz$cd lasso-236$autogensh
Be sure that the Python bindings is selected as follows
=============Configuration=============
Main----
Compiler gccCFLAGSInstall prefix usrlocalDebugging noExperimental ID-WSF no
Optionals builds----------------
Available languages java(461) python(27) perl(5124)
Java binding yesPerl binding yesPHP 5 binding noPython binding yes
C API references yesTests suite no
Now type make install to install lasso
As indicated build and install
$make install$ldconfig
Set the lasso python binding in you python path eg
$export PYTHONPATH=$PYTHONPATHusrlocallibpython26site-packages
Test trying to import Lasso
$pythongtgtgt import lasso
Install Authentic directly from pypi
Using pip
pip install authentic2
You can now run Authentic from the installation directory
21 Quickstart guides and installation guidelines 7
Authentic2 Documentation Release 202
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last package archive from pypi
Download the archive on httppypipythonorgpypiauthentic2
Then you can install it directly from the archive using pip
pip install authentic2-xzytargz
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last sources from the Git repository
Clone the repository
git clone httpreposentrouvertorgauthenticgit
Then you can install it directly using pip
cd authenticpip install -e
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
8 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
212 Specifying a different database
This is done by modifying the DATABASES dictionary in your local_settingspy file (create it in Authentic projectdirectory) for example
DATABASES[default] = ENGINE djangodbbackendspostgresqlNAME authenticUSER admindbPASSWORD foobarHOST dbexamplecomPORT empty string means default value
You should refer to the Django documentation on databases settings athttpdocsdjangoprojectcomendevrefsettingsdatabases for all the details
213 Upgrading
Update using pip
pip install -U authentic2
Authentic store all its data in a relational database as specified in its settingspy or local_settingspy file So in order toupgrade to a new version of authentic you have to update your database schema using the migration command mdash youwill need to have installed the dependency django-south see the beginning of this README file
authentic2-ctl syncdb --migrate
214 Running Authentic 2 for real (Nginx Apache etc)
DEBUG Mode by default static files and the Django debug toolbar dependency
By default Authentic 2 is in the DEBUG mode We made this default choice because most of the Authentic 2rsquos userswill begin with Authentic 2 using the Django development server (runserver command) and we want to avoid them abad first impression because static files would not be served As a matter of fact static files are served by the Djangodevelopment server only when the project is run in the DEBUG mode
In the DEBUG mode the Django debug toolbar is used what adds a dependency
In production the Django development server should not be used to serve Authentic 2 and a dedicated server shouldalso be used to serve the static files
21 Quickstart guides and installation guidelines 9
Authentic2 Documentation Release 202
Set Authentic into the no DEBUG Mode
It is enough to edit authentic2settingspy and set
DEBUG = False
From then on the django-debug-toolbar package is not necessary anymore
Use dedicated HTTP servers and serve static files
The best is to use a server dedicated to serve the Django applications and a different server to serve the static files
You could for instance use apache with mod_wsgi to serve Authentic 2 You will find configuration file examples inthe debian directory of the Authentic 2 sources
Then you may want to use nginx to serve the static files
First you need to collect the Authentic 2 static files The static files are collected using the collectstatic command thatis configured in the settingspy
By default running collectstatic will create a static directory in the parent directory of the authentic2 directory
$python authentic2managepy collectstatic
That static directory will contain all the static files of Authentic 2
If you want to change the path of the static directory you can edit STATIC_ROOT of the settings file
See httpsdocsdjangoprojectcomendevrefcontribstaticfiles for more information about collectstatic
215 Quickstarts
Quickstart an OAuth2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6053
Quickstart an SAML2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6057
Quickstart a connection with a SAML2 Service Provider
1 Get the Identity Provider SAML2 metadata file
http[s]yourdomaincomidpsaml2metadata
2 Configure your service provider with it
3 Go to the providers admin panel on
http[s]adminsamllibertyprovideradd
There create a new provider using the service provider metadata and enable it as a service provider
10 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Quickstart a CAS Identity Provider
1 Activate CAS IdP support in your local_settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
authentic2-ctl syncdb ndashall authentic2-ctl migrate ndashfake
2 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
3 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
Quickstart to connect a LDAP Directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django for this you need python-ldap python-ldap needs python de-velopement headers to be installed but is usually packaged by most distributions
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP The next lines must be added
AUTHENTICATION_BACKENDS += ( lsquodjango_auth_ldapbackendLDAPBackendrsquo )
import ldap from django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your server AUTH_LDAP_SERVER_URI = lsquoldapldapexamplecomlsquo Let the bind DN and bind password blank for anonymous binding AUTH_LDAP_BIND_DN = ldquordquoAUTH_LDAP_BIND_PASSWORD = ldquordquo Lookup user under the branch o=base and by mathcing theiruid against the received login name AUTH_LDAP_USER_SEARCH = LDAPSearch(ldquoo=baserdquo
ldapSCOPE_SUBTREE ldquo(uid=(user)s)rdquo)
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesType AUTH_LDAP_GROUP_TYPE = GroupOf-NamesType() AUTH_LDAP_GROUP_SEARCH = LDAPSearch(ldquoo=mycompanyrdquo
ldapSCOPE_SUBTREE ldquo(objectClass=groupOfNames)rdquo)
AUTH_LDAP_USER_FLAGS_BY_GROUP = ldquois_staffrdquo ldquocn=admino=mycompanyrdquo
21 Quickstart guides and installation guidelines 11
Authentic2 Documentation Release 202
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
Quickstart for PAM Authentication
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
12 Chapter 2 Installation and quickstart tutorials
CHAPTER 3
Configuration
31 Configuration with settings
311 Works with authentic 2 settings
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6047
312 All settings
Activate or deactivate debug mode
Variable DEBUG
Values
bull False deactivate debug mode
bull True activate debug mode
Manage session cookie duration
Variable SESSION_EXPIRE_AT_BROWSER_CLOSE
Values
bull False Cookies are not removed when browser is closed
bull True Cookies are removed when browser is closed
Variable SESSION_COOKIE_AGE
Value
bull Seconds (36000 equal 10 hours)
Time zone selection
Variable TIME_ZONE
Values
13
Authentic2 Documentation Release 202
bull See httpenwikipediaorgwikiList_of_tz_zones_by_name
Activate or deactivate SSL authentication
Variable AUTH_SSL
Values
bull False deactivate SSL authentication
bull True activate SSL authentication
Activate or deactivate OpenID authentication Authentic 2 is an OpenID relying party
Variable AUTH_OPENID
Values
bull False deactivate OpenID authentication
bull True activate OpenID authentication
Activate or deactivate Authentic 2 as a SAML2 identity provider
Variable IDP_SAML2
Values
bull False deactivate SAML2 identity provider
bull True activate SAML2 identity provider
Configure SAML2 keys
bull SAML_SIGNATURE_PUBLIC_KEY Certtificate or public key for signature
bull SAML_SIGNATURE_PRIVATE_KEY Private key for signature
bull SAML_ENCRYPTION_PUBLIC_KEY Certtificate or public key for encryption
bull SAML_ENCRYPTION_PRIVATE_KEY Private key for encryption
Values are pem files of X509 certificate or key eg SAML_SIGNATURE_PRIVATE_KEY = lsquorsquolsquomdashndashBEGIN RSAPRIVATE KEYmdashndash MIIWA== mdashndashEND RSA PRIVATE KEYmdashndashlsquorsquolsquo
If SAML_ENCRYPTION_PUBLIC_KEY or SAML_ENCRYPTION_PRIVATE_KEY are not given the signaturekeys are used for encryption
Activate or deactivate Authentic 2 as an OpenID provider
Variable IDP_OPENID
Values
bull False deactivate OpenID provider
bull True activate OpenID provider
14 Chapter 3 Configuration
Authentic2 Documentation Release 202
Activate or deactivate Authentic 2 as a CAS server
Variable IDP_CAS
Values
bull False deactivate CAS server
bull True activate CAS server
32 Configuration with the administration interface
321 Basics
Access the grapical administration interface
The grapical administration interface is the lsquoDjango adminrsquo part of a Django project See for more information
Just acces the admin url at http[s]yourdomaincomadmin
At first you log with the superuser you created at the very first database initialization
Then you can configure other accesses to the admin checking the is_staff option displayed on a user in the admin
Work with policies
The policy management with global policies is nearly used for any kind of policy in Authentic 2
For each kind of these policies the system takes in account two special global policies named lsquoDefaultrsquo and lsquoAllrsquo
bull There is always a system default that does not correspond to the lsquoDefaultrsquo policy This is used to make Authentic2 boot without initial configuration When you add a lsquoDefaultrsquo policy the system default are not used anymore
bull A policy has always a name lsquoDefaultrsquo and lsquoAllrsquo are the names of two special policies with their name hardcodedBut you can create or delete them
bull If no other policy applies the policy lsquoDefaultrsquo applies
bull A policy can be created and attached to any related object This policy is authoritative on the policy lsquoDefaultrsquo
bull If the policy lsquoAllrsquo exists it is authoritative on any other policy
bull The global policies lsquoAllrsquo and lsquoDefaultrsquo are created by the administrator if necessary
bull A policy is taken in account only if it is enabled
bull When a regular policy is associated with an object it is taken in account only if the option lsquoenable the followingpolicyrsquo is checked on the oject
It is advised to add a lsquoDefaultrsquo global policy when it is expected to apply a policy to all related objects A lsquoDefaultrsquoglobal policy should be defined to avoid misonfiguration
Add a regular policy to some objects are used to handle particular configurations for a subset of related objects
An lsquoAllrsquo global policy should be used to enforce a global configuration for all related objects or for testing purposes
32 Configuration with the administration interface 15
Authentic2 Documentation Release 202
322 Authentication backends
Authentication with an existing LDAP directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP
The next lines must be added
AUTHENTICATION_BACKENDS += ( django_auth_ldapbackendLDAPBackend )
import ldapfrom django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your serverAUTH_LDAP_SERVER_URI = ldapldapexamplecom Let the bind DN and bind password blank for anonymous bindingAUTH_LDAP_BIND_DN = AUTH_LDAP_BIND_PASSWORD = Lookup user under the branch o=base and by mathcing their uid against the received login nameAUTH_LDAP_USER_SEARCH = LDAPSearch(o=base
ldapSCOPE_SUBTREE (uid=(user)s))
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesTypeAUTH_LDAP_GROUP_TYPE = GroupOfNamesType()AUTH_LDAP_GROUP_SEARCH = LDAPSearch(o=mycompany
ldapSCOPE_SUBTREE (objectClass=groupOfNames))AUTH_LDAP_USER_FLAGS_BY_GROUP =
is_staff cn=admino=mycompany
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
16 Chapter 3 Configuration
Authentic2 Documentation Release 202
Authentication on Authentic 2 with PAM
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
323 SAML2
Where do I find the Authentic 2 SAML2 metadata
The SAML2 metadata are automatically generated
Authentic 2 will infer from environment variables the host and port to generate the URLs contained in themedatada
The metadata of Authentic 2 SAML2 identity provider are available at
http[s]yourdomaincomidpsaml2metadata
The metadata of Authentic 2 SAML2 service provider are available at
http[s]yourdomaincomauthsaml2metadata
Configure SAML 20 service providers
How do I authenticate against Authentic 2 with a SAML2 service provider
1 Declare Authentic 2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identityprovider metadata of Authentic 2
Go to http[s]yourdomaincomidpsaml2metadata
2 Add and configure a SAML2 service provider in Authentic 2 using the metadata of the service provider
How do I add and configure a SAML2 service provider in Authentic 2
You first need to create a new SAML2 service provider entry This requires the SAML2 metadata of the serviceprovider
If your service provider is Authentic 2 the metadata are available at
http[s]yourdomaincomauthsaml2metadata
32 Configuration with the administration interface 17
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
bull django-debug-toolbargt=12lt13
bull ndashallow-external django-admin-tools
bull ndashallow-unverified django-admin-tools
bull django-admin-toolsgt=051
bull dnspython
bull django-select2
bull django-tables2
bull gadjo
bull django-import-export
bull django-sekizai
Install Authentic 2
bull Install Authentic directly from pypi
bull Obtain the last package archive from pypi
bull Obtain the last sources from the Git repository
Lasso installation
Lasso is available in the linux debian destribution repositories If you are installing Authentic 2 on debian just execute
apt-get install python-lasso
Yoursquoll find more updated packages on httpdebentrouvertorg
We also provide rpm packages for redhat see httpsdeventrouvertorgredhatREADME
You can also install lasso from sources httplassoentrouvertorgdownload
See the Lasso website for installation details This is a quick installation example
Install the following Lasso dependencies
bull autoconf
bull automake
bull autotools-dev
bull libtool
bull gtk-doc-tools
bull zlib1g-dev
bull libglib20-dev
bull openssl-dev
bull libxml2-dev
bull libxmlsec1-dev
bull python26-dev
bull python-setuptools
Obtain Lasso
6 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
$wget httpsdeventrouvertorglassolasso-236targz$tar xzvf lasso-236targz$cd lasso-236$autogensh
Be sure that the Python bindings is selected as follows
=============Configuration=============
Main----
Compiler gccCFLAGSInstall prefix usrlocalDebugging noExperimental ID-WSF no
Optionals builds----------------
Available languages java(461) python(27) perl(5124)
Java binding yesPerl binding yesPHP 5 binding noPython binding yes
C API references yesTests suite no
Now type make install to install lasso
As indicated build and install
$make install$ldconfig
Set the lasso python binding in you python path eg
$export PYTHONPATH=$PYTHONPATHusrlocallibpython26site-packages
Test trying to import Lasso
$pythongtgtgt import lasso
Install Authentic directly from pypi
Using pip
pip install authentic2
You can now run Authentic from the installation directory
21 Quickstart guides and installation guidelines 7
Authentic2 Documentation Release 202
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last package archive from pypi
Download the archive on httppypipythonorgpypiauthentic2
Then you can install it directly from the archive using pip
pip install authentic2-xzytargz
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last sources from the Git repository
Clone the repository
git clone httpreposentrouvertorgauthenticgit
Then you can install it directly using pip
cd authenticpip install -e
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
8 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
212 Specifying a different database
This is done by modifying the DATABASES dictionary in your local_settingspy file (create it in Authentic projectdirectory) for example
DATABASES[default] = ENGINE djangodbbackendspostgresqlNAME authenticUSER admindbPASSWORD foobarHOST dbexamplecomPORT empty string means default value
You should refer to the Django documentation on databases settings athttpdocsdjangoprojectcomendevrefsettingsdatabases for all the details
213 Upgrading
Update using pip
pip install -U authentic2
Authentic store all its data in a relational database as specified in its settingspy or local_settingspy file So in order toupgrade to a new version of authentic you have to update your database schema using the migration command mdash youwill need to have installed the dependency django-south see the beginning of this README file
authentic2-ctl syncdb --migrate
214 Running Authentic 2 for real (Nginx Apache etc)
DEBUG Mode by default static files and the Django debug toolbar dependency
By default Authentic 2 is in the DEBUG mode We made this default choice because most of the Authentic 2rsquos userswill begin with Authentic 2 using the Django development server (runserver command) and we want to avoid them abad first impression because static files would not be served As a matter of fact static files are served by the Djangodevelopment server only when the project is run in the DEBUG mode
In the DEBUG mode the Django debug toolbar is used what adds a dependency
In production the Django development server should not be used to serve Authentic 2 and a dedicated server shouldalso be used to serve the static files
21 Quickstart guides and installation guidelines 9
Authentic2 Documentation Release 202
Set Authentic into the no DEBUG Mode
It is enough to edit authentic2settingspy and set
DEBUG = False
From then on the django-debug-toolbar package is not necessary anymore
Use dedicated HTTP servers and serve static files
The best is to use a server dedicated to serve the Django applications and a different server to serve the static files
You could for instance use apache with mod_wsgi to serve Authentic 2 You will find configuration file examples inthe debian directory of the Authentic 2 sources
Then you may want to use nginx to serve the static files
First you need to collect the Authentic 2 static files The static files are collected using the collectstatic command thatis configured in the settingspy
By default running collectstatic will create a static directory in the parent directory of the authentic2 directory
$python authentic2managepy collectstatic
That static directory will contain all the static files of Authentic 2
If you want to change the path of the static directory you can edit STATIC_ROOT of the settings file
See httpsdocsdjangoprojectcomendevrefcontribstaticfiles for more information about collectstatic
215 Quickstarts
Quickstart an OAuth2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6053
Quickstart an SAML2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6057
Quickstart a connection with a SAML2 Service Provider
1 Get the Identity Provider SAML2 metadata file
http[s]yourdomaincomidpsaml2metadata
2 Configure your service provider with it
3 Go to the providers admin panel on
http[s]adminsamllibertyprovideradd
There create a new provider using the service provider metadata and enable it as a service provider
10 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Quickstart a CAS Identity Provider
1 Activate CAS IdP support in your local_settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
authentic2-ctl syncdb ndashall authentic2-ctl migrate ndashfake
2 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
3 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
Quickstart to connect a LDAP Directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django for this you need python-ldap python-ldap needs python de-velopement headers to be installed but is usually packaged by most distributions
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP The next lines must be added
AUTHENTICATION_BACKENDS += ( lsquodjango_auth_ldapbackendLDAPBackendrsquo )
import ldap from django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your server AUTH_LDAP_SERVER_URI = lsquoldapldapexamplecomlsquo Let the bind DN and bind password blank for anonymous binding AUTH_LDAP_BIND_DN = ldquordquoAUTH_LDAP_BIND_PASSWORD = ldquordquo Lookup user under the branch o=base and by mathcing theiruid against the received login name AUTH_LDAP_USER_SEARCH = LDAPSearch(ldquoo=baserdquo
ldapSCOPE_SUBTREE ldquo(uid=(user)s)rdquo)
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesType AUTH_LDAP_GROUP_TYPE = GroupOf-NamesType() AUTH_LDAP_GROUP_SEARCH = LDAPSearch(ldquoo=mycompanyrdquo
ldapSCOPE_SUBTREE ldquo(objectClass=groupOfNames)rdquo)
AUTH_LDAP_USER_FLAGS_BY_GROUP = ldquois_staffrdquo ldquocn=admino=mycompanyrdquo
21 Quickstart guides and installation guidelines 11
Authentic2 Documentation Release 202
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
Quickstart for PAM Authentication
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
12 Chapter 2 Installation and quickstart tutorials
CHAPTER 3
Configuration
31 Configuration with settings
311 Works with authentic 2 settings
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6047
312 All settings
Activate or deactivate debug mode
Variable DEBUG
Values
bull False deactivate debug mode
bull True activate debug mode
Manage session cookie duration
Variable SESSION_EXPIRE_AT_BROWSER_CLOSE
Values
bull False Cookies are not removed when browser is closed
bull True Cookies are removed when browser is closed
Variable SESSION_COOKIE_AGE
Value
bull Seconds (36000 equal 10 hours)
Time zone selection
Variable TIME_ZONE
Values
13
Authentic2 Documentation Release 202
bull See httpenwikipediaorgwikiList_of_tz_zones_by_name
Activate or deactivate SSL authentication
Variable AUTH_SSL
Values
bull False deactivate SSL authentication
bull True activate SSL authentication
Activate or deactivate OpenID authentication Authentic 2 is an OpenID relying party
Variable AUTH_OPENID
Values
bull False deactivate OpenID authentication
bull True activate OpenID authentication
Activate or deactivate Authentic 2 as a SAML2 identity provider
Variable IDP_SAML2
Values
bull False deactivate SAML2 identity provider
bull True activate SAML2 identity provider
Configure SAML2 keys
bull SAML_SIGNATURE_PUBLIC_KEY Certtificate or public key for signature
bull SAML_SIGNATURE_PRIVATE_KEY Private key for signature
bull SAML_ENCRYPTION_PUBLIC_KEY Certtificate or public key for encryption
bull SAML_ENCRYPTION_PRIVATE_KEY Private key for encryption
Values are pem files of X509 certificate or key eg SAML_SIGNATURE_PRIVATE_KEY = lsquorsquolsquomdashndashBEGIN RSAPRIVATE KEYmdashndash MIIWA== mdashndashEND RSA PRIVATE KEYmdashndashlsquorsquolsquo
If SAML_ENCRYPTION_PUBLIC_KEY or SAML_ENCRYPTION_PRIVATE_KEY are not given the signaturekeys are used for encryption
Activate or deactivate Authentic 2 as an OpenID provider
Variable IDP_OPENID
Values
bull False deactivate OpenID provider
bull True activate OpenID provider
14 Chapter 3 Configuration
Authentic2 Documentation Release 202
Activate or deactivate Authentic 2 as a CAS server
Variable IDP_CAS
Values
bull False deactivate CAS server
bull True activate CAS server
32 Configuration with the administration interface
321 Basics
Access the grapical administration interface
The grapical administration interface is the lsquoDjango adminrsquo part of a Django project See for more information
Just acces the admin url at http[s]yourdomaincomadmin
At first you log with the superuser you created at the very first database initialization
Then you can configure other accesses to the admin checking the is_staff option displayed on a user in the admin
Work with policies
The policy management with global policies is nearly used for any kind of policy in Authentic 2
For each kind of these policies the system takes in account two special global policies named lsquoDefaultrsquo and lsquoAllrsquo
bull There is always a system default that does not correspond to the lsquoDefaultrsquo policy This is used to make Authentic2 boot without initial configuration When you add a lsquoDefaultrsquo policy the system default are not used anymore
bull A policy has always a name lsquoDefaultrsquo and lsquoAllrsquo are the names of two special policies with their name hardcodedBut you can create or delete them
bull If no other policy applies the policy lsquoDefaultrsquo applies
bull A policy can be created and attached to any related object This policy is authoritative on the policy lsquoDefaultrsquo
bull If the policy lsquoAllrsquo exists it is authoritative on any other policy
bull The global policies lsquoAllrsquo and lsquoDefaultrsquo are created by the administrator if necessary
bull A policy is taken in account only if it is enabled
bull When a regular policy is associated with an object it is taken in account only if the option lsquoenable the followingpolicyrsquo is checked on the oject
It is advised to add a lsquoDefaultrsquo global policy when it is expected to apply a policy to all related objects A lsquoDefaultrsquoglobal policy should be defined to avoid misonfiguration
Add a regular policy to some objects are used to handle particular configurations for a subset of related objects
An lsquoAllrsquo global policy should be used to enforce a global configuration for all related objects or for testing purposes
32 Configuration with the administration interface 15
Authentic2 Documentation Release 202
322 Authentication backends
Authentication with an existing LDAP directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP
The next lines must be added
AUTHENTICATION_BACKENDS += ( django_auth_ldapbackendLDAPBackend )
import ldapfrom django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your serverAUTH_LDAP_SERVER_URI = ldapldapexamplecom Let the bind DN and bind password blank for anonymous bindingAUTH_LDAP_BIND_DN = AUTH_LDAP_BIND_PASSWORD = Lookup user under the branch o=base and by mathcing their uid against the received login nameAUTH_LDAP_USER_SEARCH = LDAPSearch(o=base
ldapSCOPE_SUBTREE (uid=(user)s))
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesTypeAUTH_LDAP_GROUP_TYPE = GroupOfNamesType()AUTH_LDAP_GROUP_SEARCH = LDAPSearch(o=mycompany
ldapSCOPE_SUBTREE (objectClass=groupOfNames))AUTH_LDAP_USER_FLAGS_BY_GROUP =
is_staff cn=admino=mycompany
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
16 Chapter 3 Configuration
Authentic2 Documentation Release 202
Authentication on Authentic 2 with PAM
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
323 SAML2
Where do I find the Authentic 2 SAML2 metadata
The SAML2 metadata are automatically generated
Authentic 2 will infer from environment variables the host and port to generate the URLs contained in themedatada
The metadata of Authentic 2 SAML2 identity provider are available at
http[s]yourdomaincomidpsaml2metadata
The metadata of Authentic 2 SAML2 service provider are available at
http[s]yourdomaincomauthsaml2metadata
Configure SAML 20 service providers
How do I authenticate against Authentic 2 with a SAML2 service provider
1 Declare Authentic 2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identityprovider metadata of Authentic 2
Go to http[s]yourdomaincomidpsaml2metadata
2 Add and configure a SAML2 service provider in Authentic 2 using the metadata of the service provider
How do I add and configure a SAML2 service provider in Authentic 2
You first need to create a new SAML2 service provider entry This requires the SAML2 metadata of the serviceprovider
If your service provider is Authentic 2 the metadata are available at
http[s]yourdomaincomauthsaml2metadata
32 Configuration with the administration interface 17
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
$wget httpsdeventrouvertorglassolasso-236targz$tar xzvf lasso-236targz$cd lasso-236$autogensh
Be sure that the Python bindings is selected as follows
=============Configuration=============
Main----
Compiler gccCFLAGSInstall prefix usrlocalDebugging noExperimental ID-WSF no
Optionals builds----------------
Available languages java(461) python(27) perl(5124)
Java binding yesPerl binding yesPHP 5 binding noPython binding yes
C API references yesTests suite no
Now type make install to install lasso
As indicated build and install
$make install$ldconfig
Set the lasso python binding in you python path eg
$export PYTHONPATH=$PYTHONPATHusrlocallibpython26site-packages
Test trying to import Lasso
$pythongtgtgt import lasso
Install Authentic directly from pypi
Using pip
pip install authentic2
You can now run Authentic from the installation directory
21 Quickstart guides and installation guidelines 7
Authentic2 Documentation Release 202
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last package archive from pypi
Download the archive on httppypipythonorgpypiauthentic2
Then you can install it directly from the archive using pip
pip install authentic2-xzytargz
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last sources from the Git repository
Clone the repository
git clone httpreposentrouvertorgauthenticgit
Then you can install it directly using pip
cd authenticpip install -e
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
8 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
212 Specifying a different database
This is done by modifying the DATABASES dictionary in your local_settingspy file (create it in Authentic projectdirectory) for example
DATABASES[default] = ENGINE djangodbbackendspostgresqlNAME authenticUSER admindbPASSWORD foobarHOST dbexamplecomPORT empty string means default value
You should refer to the Django documentation on databases settings athttpdocsdjangoprojectcomendevrefsettingsdatabases for all the details
213 Upgrading
Update using pip
pip install -U authentic2
Authentic store all its data in a relational database as specified in its settingspy or local_settingspy file So in order toupgrade to a new version of authentic you have to update your database schema using the migration command mdash youwill need to have installed the dependency django-south see the beginning of this README file
authentic2-ctl syncdb --migrate
214 Running Authentic 2 for real (Nginx Apache etc)
DEBUG Mode by default static files and the Django debug toolbar dependency
By default Authentic 2 is in the DEBUG mode We made this default choice because most of the Authentic 2rsquos userswill begin with Authentic 2 using the Django development server (runserver command) and we want to avoid them abad first impression because static files would not be served As a matter of fact static files are served by the Djangodevelopment server only when the project is run in the DEBUG mode
In the DEBUG mode the Django debug toolbar is used what adds a dependency
In production the Django development server should not be used to serve Authentic 2 and a dedicated server shouldalso be used to serve the static files
21 Quickstart guides and installation guidelines 9
Authentic2 Documentation Release 202
Set Authentic into the no DEBUG Mode
It is enough to edit authentic2settingspy and set
DEBUG = False
From then on the django-debug-toolbar package is not necessary anymore
Use dedicated HTTP servers and serve static files
The best is to use a server dedicated to serve the Django applications and a different server to serve the static files
You could for instance use apache with mod_wsgi to serve Authentic 2 You will find configuration file examples inthe debian directory of the Authentic 2 sources
Then you may want to use nginx to serve the static files
First you need to collect the Authentic 2 static files The static files are collected using the collectstatic command thatis configured in the settingspy
By default running collectstatic will create a static directory in the parent directory of the authentic2 directory
$python authentic2managepy collectstatic
That static directory will contain all the static files of Authentic 2
If you want to change the path of the static directory you can edit STATIC_ROOT of the settings file
See httpsdocsdjangoprojectcomendevrefcontribstaticfiles for more information about collectstatic
215 Quickstarts
Quickstart an OAuth2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6053
Quickstart an SAML2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6057
Quickstart a connection with a SAML2 Service Provider
1 Get the Identity Provider SAML2 metadata file
http[s]yourdomaincomidpsaml2metadata
2 Configure your service provider with it
3 Go to the providers admin panel on
http[s]adminsamllibertyprovideradd
There create a new provider using the service provider metadata and enable it as a service provider
10 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Quickstart a CAS Identity Provider
1 Activate CAS IdP support in your local_settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
authentic2-ctl syncdb ndashall authentic2-ctl migrate ndashfake
2 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
3 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
Quickstart to connect a LDAP Directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django for this you need python-ldap python-ldap needs python de-velopement headers to be installed but is usually packaged by most distributions
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP The next lines must be added
AUTHENTICATION_BACKENDS += ( lsquodjango_auth_ldapbackendLDAPBackendrsquo )
import ldap from django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your server AUTH_LDAP_SERVER_URI = lsquoldapldapexamplecomlsquo Let the bind DN and bind password blank for anonymous binding AUTH_LDAP_BIND_DN = ldquordquoAUTH_LDAP_BIND_PASSWORD = ldquordquo Lookup user under the branch o=base and by mathcing theiruid against the received login name AUTH_LDAP_USER_SEARCH = LDAPSearch(ldquoo=baserdquo
ldapSCOPE_SUBTREE ldquo(uid=(user)s)rdquo)
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesType AUTH_LDAP_GROUP_TYPE = GroupOf-NamesType() AUTH_LDAP_GROUP_SEARCH = LDAPSearch(ldquoo=mycompanyrdquo
ldapSCOPE_SUBTREE ldquo(objectClass=groupOfNames)rdquo)
AUTH_LDAP_USER_FLAGS_BY_GROUP = ldquois_staffrdquo ldquocn=admino=mycompanyrdquo
21 Quickstart guides and installation guidelines 11
Authentic2 Documentation Release 202
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
Quickstart for PAM Authentication
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
12 Chapter 2 Installation and quickstart tutorials
CHAPTER 3
Configuration
31 Configuration with settings
311 Works with authentic 2 settings
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6047
312 All settings
Activate or deactivate debug mode
Variable DEBUG
Values
bull False deactivate debug mode
bull True activate debug mode
Manage session cookie duration
Variable SESSION_EXPIRE_AT_BROWSER_CLOSE
Values
bull False Cookies are not removed when browser is closed
bull True Cookies are removed when browser is closed
Variable SESSION_COOKIE_AGE
Value
bull Seconds (36000 equal 10 hours)
Time zone selection
Variable TIME_ZONE
Values
13
Authentic2 Documentation Release 202
bull See httpenwikipediaorgwikiList_of_tz_zones_by_name
Activate or deactivate SSL authentication
Variable AUTH_SSL
Values
bull False deactivate SSL authentication
bull True activate SSL authentication
Activate or deactivate OpenID authentication Authentic 2 is an OpenID relying party
Variable AUTH_OPENID
Values
bull False deactivate OpenID authentication
bull True activate OpenID authentication
Activate or deactivate Authentic 2 as a SAML2 identity provider
Variable IDP_SAML2
Values
bull False deactivate SAML2 identity provider
bull True activate SAML2 identity provider
Configure SAML2 keys
bull SAML_SIGNATURE_PUBLIC_KEY Certtificate or public key for signature
bull SAML_SIGNATURE_PRIVATE_KEY Private key for signature
bull SAML_ENCRYPTION_PUBLIC_KEY Certtificate or public key for encryption
bull SAML_ENCRYPTION_PRIVATE_KEY Private key for encryption
Values are pem files of X509 certificate or key eg SAML_SIGNATURE_PRIVATE_KEY = lsquorsquolsquomdashndashBEGIN RSAPRIVATE KEYmdashndash MIIWA== mdashndashEND RSA PRIVATE KEYmdashndashlsquorsquolsquo
If SAML_ENCRYPTION_PUBLIC_KEY or SAML_ENCRYPTION_PRIVATE_KEY are not given the signaturekeys are used for encryption
Activate or deactivate Authentic 2 as an OpenID provider
Variable IDP_OPENID
Values
bull False deactivate OpenID provider
bull True activate OpenID provider
14 Chapter 3 Configuration
Authentic2 Documentation Release 202
Activate or deactivate Authentic 2 as a CAS server
Variable IDP_CAS
Values
bull False deactivate CAS server
bull True activate CAS server
32 Configuration with the administration interface
321 Basics
Access the grapical administration interface
The grapical administration interface is the lsquoDjango adminrsquo part of a Django project See for more information
Just acces the admin url at http[s]yourdomaincomadmin
At first you log with the superuser you created at the very first database initialization
Then you can configure other accesses to the admin checking the is_staff option displayed on a user in the admin
Work with policies
The policy management with global policies is nearly used for any kind of policy in Authentic 2
For each kind of these policies the system takes in account two special global policies named lsquoDefaultrsquo and lsquoAllrsquo
bull There is always a system default that does not correspond to the lsquoDefaultrsquo policy This is used to make Authentic2 boot without initial configuration When you add a lsquoDefaultrsquo policy the system default are not used anymore
bull A policy has always a name lsquoDefaultrsquo and lsquoAllrsquo are the names of two special policies with their name hardcodedBut you can create or delete them
bull If no other policy applies the policy lsquoDefaultrsquo applies
bull A policy can be created and attached to any related object This policy is authoritative on the policy lsquoDefaultrsquo
bull If the policy lsquoAllrsquo exists it is authoritative on any other policy
bull The global policies lsquoAllrsquo and lsquoDefaultrsquo are created by the administrator if necessary
bull A policy is taken in account only if it is enabled
bull When a regular policy is associated with an object it is taken in account only if the option lsquoenable the followingpolicyrsquo is checked on the oject
It is advised to add a lsquoDefaultrsquo global policy when it is expected to apply a policy to all related objects A lsquoDefaultrsquoglobal policy should be defined to avoid misonfiguration
Add a regular policy to some objects are used to handle particular configurations for a subset of related objects
An lsquoAllrsquo global policy should be used to enforce a global configuration for all related objects or for testing purposes
32 Configuration with the administration interface 15
Authentic2 Documentation Release 202
322 Authentication backends
Authentication with an existing LDAP directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP
The next lines must be added
AUTHENTICATION_BACKENDS += ( django_auth_ldapbackendLDAPBackend )
import ldapfrom django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your serverAUTH_LDAP_SERVER_URI = ldapldapexamplecom Let the bind DN and bind password blank for anonymous bindingAUTH_LDAP_BIND_DN = AUTH_LDAP_BIND_PASSWORD = Lookup user under the branch o=base and by mathcing their uid against the received login nameAUTH_LDAP_USER_SEARCH = LDAPSearch(o=base
ldapSCOPE_SUBTREE (uid=(user)s))
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesTypeAUTH_LDAP_GROUP_TYPE = GroupOfNamesType()AUTH_LDAP_GROUP_SEARCH = LDAPSearch(o=mycompany
ldapSCOPE_SUBTREE (objectClass=groupOfNames))AUTH_LDAP_USER_FLAGS_BY_GROUP =
is_staff cn=admino=mycompany
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
16 Chapter 3 Configuration
Authentic2 Documentation Release 202
Authentication on Authentic 2 with PAM
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
323 SAML2
Where do I find the Authentic 2 SAML2 metadata
The SAML2 metadata are automatically generated
Authentic 2 will infer from environment variables the host and port to generate the URLs contained in themedatada
The metadata of Authentic 2 SAML2 identity provider are available at
http[s]yourdomaincomidpsaml2metadata
The metadata of Authentic 2 SAML2 service provider are available at
http[s]yourdomaincomauthsaml2metadata
Configure SAML 20 service providers
How do I authenticate against Authentic 2 with a SAML2 service provider
1 Declare Authentic 2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identityprovider metadata of Authentic 2
Go to http[s]yourdomaincomidpsaml2metadata
2 Add and configure a SAML2 service provider in Authentic 2 using the metadata of the service provider
How do I add and configure a SAML2 service provider in Authentic 2
You first need to create a new SAML2 service provider entry This requires the SAML2 metadata of the serviceprovider
If your service provider is Authentic 2 the metadata are available at
http[s]yourdomaincomauthsaml2metadata
32 Configuration with the administration interface 17
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last package archive from pypi
Download the archive on httppypipythonorgpypiauthentic2
Then you can install it directly from the archive using pip
pip install authentic2-xzytargz
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
Obtain the last sources from the Git repository
Clone the repository
git clone httpreposentrouvertorgauthenticgit
Then you can install it directly using pip
cd authenticpip install -e
You can now run Authentic from the installation directory eg
authentic2-ctl syncdb --migrate
authentic2-ctl runserver
You should see the following output
8 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
212 Specifying a different database
This is done by modifying the DATABASES dictionary in your local_settingspy file (create it in Authentic projectdirectory) for example
DATABASES[default] = ENGINE djangodbbackendspostgresqlNAME authenticUSER admindbPASSWORD foobarHOST dbexamplecomPORT empty string means default value
You should refer to the Django documentation on databases settings athttpdocsdjangoprojectcomendevrefsettingsdatabases for all the details
213 Upgrading
Update using pip
pip install -U authentic2
Authentic store all its data in a relational database as specified in its settingspy or local_settingspy file So in order toupgrade to a new version of authentic you have to update your database schema using the migration command mdash youwill need to have installed the dependency django-south see the beginning of this README file
authentic2-ctl syncdb --migrate
214 Running Authentic 2 for real (Nginx Apache etc)
DEBUG Mode by default static files and the Django debug toolbar dependency
By default Authentic 2 is in the DEBUG mode We made this default choice because most of the Authentic 2rsquos userswill begin with Authentic 2 using the Django development server (runserver command) and we want to avoid them abad first impression because static files would not be served As a matter of fact static files are served by the Djangodevelopment server only when the project is run in the DEBUG mode
In the DEBUG mode the Django debug toolbar is used what adds a dependency
In production the Django development server should not be used to serve Authentic 2 and a dedicated server shouldalso be used to serve the static files
21 Quickstart guides and installation guidelines 9
Authentic2 Documentation Release 202
Set Authentic into the no DEBUG Mode
It is enough to edit authentic2settingspy and set
DEBUG = False
From then on the django-debug-toolbar package is not necessary anymore
Use dedicated HTTP servers and serve static files
The best is to use a server dedicated to serve the Django applications and a different server to serve the static files
You could for instance use apache with mod_wsgi to serve Authentic 2 You will find configuration file examples inthe debian directory of the Authentic 2 sources
Then you may want to use nginx to serve the static files
First you need to collect the Authentic 2 static files The static files are collected using the collectstatic command thatis configured in the settingspy
By default running collectstatic will create a static directory in the parent directory of the authentic2 directory
$python authentic2managepy collectstatic
That static directory will contain all the static files of Authentic 2
If you want to change the path of the static directory you can edit STATIC_ROOT of the settings file
See httpsdocsdjangoprojectcomendevrefcontribstaticfiles for more information about collectstatic
215 Quickstarts
Quickstart an OAuth2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6053
Quickstart an SAML2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6057
Quickstart a connection with a SAML2 Service Provider
1 Get the Identity Provider SAML2 metadata file
http[s]yourdomaincomidpsaml2metadata
2 Configure your service provider with it
3 Go to the providers admin panel on
http[s]adminsamllibertyprovideradd
There create a new provider using the service provider metadata and enable it as a service provider
10 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Quickstart a CAS Identity Provider
1 Activate CAS IdP support in your local_settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
authentic2-ctl syncdb ndashall authentic2-ctl migrate ndashfake
2 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
3 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
Quickstart to connect a LDAP Directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django for this you need python-ldap python-ldap needs python de-velopement headers to be installed but is usually packaged by most distributions
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP The next lines must be added
AUTHENTICATION_BACKENDS += ( lsquodjango_auth_ldapbackendLDAPBackendrsquo )
import ldap from django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your server AUTH_LDAP_SERVER_URI = lsquoldapldapexamplecomlsquo Let the bind DN and bind password blank for anonymous binding AUTH_LDAP_BIND_DN = ldquordquoAUTH_LDAP_BIND_PASSWORD = ldquordquo Lookup user under the branch o=base and by mathcing theiruid against the received login name AUTH_LDAP_USER_SEARCH = LDAPSearch(ldquoo=baserdquo
ldapSCOPE_SUBTREE ldquo(uid=(user)s)rdquo)
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesType AUTH_LDAP_GROUP_TYPE = GroupOf-NamesType() AUTH_LDAP_GROUP_SEARCH = LDAPSearch(ldquoo=mycompanyrdquo
ldapSCOPE_SUBTREE ldquo(objectClass=groupOfNames)rdquo)
AUTH_LDAP_USER_FLAGS_BY_GROUP = ldquois_staffrdquo ldquocn=admino=mycompanyrdquo
21 Quickstart guides and installation guidelines 11
Authentic2 Documentation Release 202
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
Quickstart for PAM Authentication
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
12 Chapter 2 Installation and quickstart tutorials
CHAPTER 3
Configuration
31 Configuration with settings
311 Works with authentic 2 settings
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6047
312 All settings
Activate or deactivate debug mode
Variable DEBUG
Values
bull False deactivate debug mode
bull True activate debug mode
Manage session cookie duration
Variable SESSION_EXPIRE_AT_BROWSER_CLOSE
Values
bull False Cookies are not removed when browser is closed
bull True Cookies are removed when browser is closed
Variable SESSION_COOKIE_AGE
Value
bull Seconds (36000 equal 10 hours)
Time zone selection
Variable TIME_ZONE
Values
13
Authentic2 Documentation Release 202
bull See httpenwikipediaorgwikiList_of_tz_zones_by_name
Activate or deactivate SSL authentication
Variable AUTH_SSL
Values
bull False deactivate SSL authentication
bull True activate SSL authentication
Activate or deactivate OpenID authentication Authentic 2 is an OpenID relying party
Variable AUTH_OPENID
Values
bull False deactivate OpenID authentication
bull True activate OpenID authentication
Activate or deactivate Authentic 2 as a SAML2 identity provider
Variable IDP_SAML2
Values
bull False deactivate SAML2 identity provider
bull True activate SAML2 identity provider
Configure SAML2 keys
bull SAML_SIGNATURE_PUBLIC_KEY Certtificate or public key for signature
bull SAML_SIGNATURE_PRIVATE_KEY Private key for signature
bull SAML_ENCRYPTION_PUBLIC_KEY Certtificate or public key for encryption
bull SAML_ENCRYPTION_PRIVATE_KEY Private key for encryption
Values are pem files of X509 certificate or key eg SAML_SIGNATURE_PRIVATE_KEY = lsquorsquolsquomdashndashBEGIN RSAPRIVATE KEYmdashndash MIIWA== mdashndashEND RSA PRIVATE KEYmdashndashlsquorsquolsquo
If SAML_ENCRYPTION_PUBLIC_KEY or SAML_ENCRYPTION_PRIVATE_KEY are not given the signaturekeys are used for encryption
Activate or deactivate Authentic 2 as an OpenID provider
Variable IDP_OPENID
Values
bull False deactivate OpenID provider
bull True activate OpenID provider
14 Chapter 3 Configuration
Authentic2 Documentation Release 202
Activate or deactivate Authentic 2 as a CAS server
Variable IDP_CAS
Values
bull False deactivate CAS server
bull True activate CAS server
32 Configuration with the administration interface
321 Basics
Access the grapical administration interface
The grapical administration interface is the lsquoDjango adminrsquo part of a Django project See for more information
Just acces the admin url at http[s]yourdomaincomadmin
At first you log with the superuser you created at the very first database initialization
Then you can configure other accesses to the admin checking the is_staff option displayed on a user in the admin
Work with policies
The policy management with global policies is nearly used for any kind of policy in Authentic 2
For each kind of these policies the system takes in account two special global policies named lsquoDefaultrsquo and lsquoAllrsquo
bull There is always a system default that does not correspond to the lsquoDefaultrsquo policy This is used to make Authentic2 boot without initial configuration When you add a lsquoDefaultrsquo policy the system default are not used anymore
bull A policy has always a name lsquoDefaultrsquo and lsquoAllrsquo are the names of two special policies with their name hardcodedBut you can create or delete them
bull If no other policy applies the policy lsquoDefaultrsquo applies
bull A policy can be created and attached to any related object This policy is authoritative on the policy lsquoDefaultrsquo
bull If the policy lsquoAllrsquo exists it is authoritative on any other policy
bull The global policies lsquoAllrsquo and lsquoDefaultrsquo are created by the administrator if necessary
bull A policy is taken in account only if it is enabled
bull When a regular policy is associated with an object it is taken in account only if the option lsquoenable the followingpolicyrsquo is checked on the oject
It is advised to add a lsquoDefaultrsquo global policy when it is expected to apply a policy to all related objects A lsquoDefaultrsquoglobal policy should be defined to avoid misonfiguration
Add a regular policy to some objects are used to handle particular configurations for a subset of related objects
An lsquoAllrsquo global policy should be used to enforce a global configuration for all related objects or for testing purposes
32 Configuration with the administration interface 15
Authentic2 Documentation Release 202
322 Authentication backends
Authentication with an existing LDAP directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP
The next lines must be added
AUTHENTICATION_BACKENDS += ( django_auth_ldapbackendLDAPBackend )
import ldapfrom django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your serverAUTH_LDAP_SERVER_URI = ldapldapexamplecom Let the bind DN and bind password blank for anonymous bindingAUTH_LDAP_BIND_DN = AUTH_LDAP_BIND_PASSWORD = Lookup user under the branch o=base and by mathcing their uid against the received login nameAUTH_LDAP_USER_SEARCH = LDAPSearch(o=base
ldapSCOPE_SUBTREE (uid=(user)s))
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesTypeAUTH_LDAP_GROUP_TYPE = GroupOfNamesType()AUTH_LDAP_GROUP_SEARCH = LDAPSearch(o=mycompany
ldapSCOPE_SUBTREE (objectClass=groupOfNames))AUTH_LDAP_USER_FLAGS_BY_GROUP =
is_staff cn=admino=mycompany
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
16 Chapter 3 Configuration
Authentic2 Documentation Release 202
Authentication on Authentic 2 with PAM
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
323 SAML2
Where do I find the Authentic 2 SAML2 metadata
The SAML2 metadata are automatically generated
Authentic 2 will infer from environment variables the host and port to generate the URLs contained in themedatada
The metadata of Authentic 2 SAML2 identity provider are available at
http[s]yourdomaincomidpsaml2metadata
The metadata of Authentic 2 SAML2 service provider are available at
http[s]yourdomaincomauthsaml2metadata
Configure SAML 20 service providers
How do I authenticate against Authentic 2 with a SAML2 service provider
1 Declare Authentic 2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identityprovider metadata of Authentic 2
Go to http[s]yourdomaincomidpsaml2metadata
2 Add and configure a SAML2 service provider in Authentic 2 using the metadata of the service provider
How do I add and configure a SAML2 service provider in Authentic 2
You first need to create a new SAML2 service provider entry This requires the SAML2 metadata of the serviceprovider
If your service provider is Authentic 2 the metadata are available at
http[s]yourdomaincomauthsaml2metadata
32 Configuration with the administration interface 17
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Validating models0 errors found
Django version 15 using settings authenticsettingsDevelopment server is running at http1270018000Quit the server with CONTROL-C
You can access the running application on http1270018000
212 Specifying a different database
This is done by modifying the DATABASES dictionary in your local_settingspy file (create it in Authentic projectdirectory) for example
DATABASES[default] = ENGINE djangodbbackendspostgresqlNAME authenticUSER admindbPASSWORD foobarHOST dbexamplecomPORT empty string means default value
You should refer to the Django documentation on databases settings athttpdocsdjangoprojectcomendevrefsettingsdatabases for all the details
213 Upgrading
Update using pip
pip install -U authentic2
Authentic store all its data in a relational database as specified in its settingspy or local_settingspy file So in order toupgrade to a new version of authentic you have to update your database schema using the migration command mdash youwill need to have installed the dependency django-south see the beginning of this README file
authentic2-ctl syncdb --migrate
214 Running Authentic 2 for real (Nginx Apache etc)
DEBUG Mode by default static files and the Django debug toolbar dependency
By default Authentic 2 is in the DEBUG mode We made this default choice because most of the Authentic 2rsquos userswill begin with Authentic 2 using the Django development server (runserver command) and we want to avoid them abad first impression because static files would not be served As a matter of fact static files are served by the Djangodevelopment server only when the project is run in the DEBUG mode
In the DEBUG mode the Django debug toolbar is used what adds a dependency
In production the Django development server should not be used to serve Authentic 2 and a dedicated server shouldalso be used to serve the static files
21 Quickstart guides and installation guidelines 9
Authentic2 Documentation Release 202
Set Authentic into the no DEBUG Mode
It is enough to edit authentic2settingspy and set
DEBUG = False
From then on the django-debug-toolbar package is not necessary anymore
Use dedicated HTTP servers and serve static files
The best is to use a server dedicated to serve the Django applications and a different server to serve the static files
You could for instance use apache with mod_wsgi to serve Authentic 2 You will find configuration file examples inthe debian directory of the Authentic 2 sources
Then you may want to use nginx to serve the static files
First you need to collect the Authentic 2 static files The static files are collected using the collectstatic command thatis configured in the settingspy
By default running collectstatic will create a static directory in the parent directory of the authentic2 directory
$python authentic2managepy collectstatic
That static directory will contain all the static files of Authentic 2
If you want to change the path of the static directory you can edit STATIC_ROOT of the settings file
See httpsdocsdjangoprojectcomendevrefcontribstaticfiles for more information about collectstatic
215 Quickstarts
Quickstart an OAuth2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6053
Quickstart an SAML2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6057
Quickstart a connection with a SAML2 Service Provider
1 Get the Identity Provider SAML2 metadata file
http[s]yourdomaincomidpsaml2metadata
2 Configure your service provider with it
3 Go to the providers admin panel on
http[s]adminsamllibertyprovideradd
There create a new provider using the service provider metadata and enable it as a service provider
10 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Quickstart a CAS Identity Provider
1 Activate CAS IdP support in your local_settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
authentic2-ctl syncdb ndashall authentic2-ctl migrate ndashfake
2 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
3 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
Quickstart to connect a LDAP Directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django for this you need python-ldap python-ldap needs python de-velopement headers to be installed but is usually packaged by most distributions
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP The next lines must be added
AUTHENTICATION_BACKENDS += ( lsquodjango_auth_ldapbackendLDAPBackendrsquo )
import ldap from django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your server AUTH_LDAP_SERVER_URI = lsquoldapldapexamplecomlsquo Let the bind DN and bind password blank for anonymous binding AUTH_LDAP_BIND_DN = ldquordquoAUTH_LDAP_BIND_PASSWORD = ldquordquo Lookup user under the branch o=base and by mathcing theiruid against the received login name AUTH_LDAP_USER_SEARCH = LDAPSearch(ldquoo=baserdquo
ldapSCOPE_SUBTREE ldquo(uid=(user)s)rdquo)
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesType AUTH_LDAP_GROUP_TYPE = GroupOf-NamesType() AUTH_LDAP_GROUP_SEARCH = LDAPSearch(ldquoo=mycompanyrdquo
ldapSCOPE_SUBTREE ldquo(objectClass=groupOfNames)rdquo)
AUTH_LDAP_USER_FLAGS_BY_GROUP = ldquois_staffrdquo ldquocn=admino=mycompanyrdquo
21 Quickstart guides and installation guidelines 11
Authentic2 Documentation Release 202
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
Quickstart for PAM Authentication
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
12 Chapter 2 Installation and quickstart tutorials
CHAPTER 3
Configuration
31 Configuration with settings
311 Works with authentic 2 settings
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6047
312 All settings
Activate or deactivate debug mode
Variable DEBUG
Values
bull False deactivate debug mode
bull True activate debug mode
Manage session cookie duration
Variable SESSION_EXPIRE_AT_BROWSER_CLOSE
Values
bull False Cookies are not removed when browser is closed
bull True Cookies are removed when browser is closed
Variable SESSION_COOKIE_AGE
Value
bull Seconds (36000 equal 10 hours)
Time zone selection
Variable TIME_ZONE
Values
13
Authentic2 Documentation Release 202
bull See httpenwikipediaorgwikiList_of_tz_zones_by_name
Activate or deactivate SSL authentication
Variable AUTH_SSL
Values
bull False deactivate SSL authentication
bull True activate SSL authentication
Activate or deactivate OpenID authentication Authentic 2 is an OpenID relying party
Variable AUTH_OPENID
Values
bull False deactivate OpenID authentication
bull True activate OpenID authentication
Activate or deactivate Authentic 2 as a SAML2 identity provider
Variable IDP_SAML2
Values
bull False deactivate SAML2 identity provider
bull True activate SAML2 identity provider
Configure SAML2 keys
bull SAML_SIGNATURE_PUBLIC_KEY Certtificate or public key for signature
bull SAML_SIGNATURE_PRIVATE_KEY Private key for signature
bull SAML_ENCRYPTION_PUBLIC_KEY Certtificate or public key for encryption
bull SAML_ENCRYPTION_PRIVATE_KEY Private key for encryption
Values are pem files of X509 certificate or key eg SAML_SIGNATURE_PRIVATE_KEY = lsquorsquolsquomdashndashBEGIN RSAPRIVATE KEYmdashndash MIIWA== mdashndashEND RSA PRIVATE KEYmdashndashlsquorsquolsquo
If SAML_ENCRYPTION_PUBLIC_KEY or SAML_ENCRYPTION_PRIVATE_KEY are not given the signaturekeys are used for encryption
Activate or deactivate Authentic 2 as an OpenID provider
Variable IDP_OPENID
Values
bull False deactivate OpenID provider
bull True activate OpenID provider
14 Chapter 3 Configuration
Authentic2 Documentation Release 202
Activate or deactivate Authentic 2 as a CAS server
Variable IDP_CAS
Values
bull False deactivate CAS server
bull True activate CAS server
32 Configuration with the administration interface
321 Basics
Access the grapical administration interface
The grapical administration interface is the lsquoDjango adminrsquo part of a Django project See for more information
Just acces the admin url at http[s]yourdomaincomadmin
At first you log with the superuser you created at the very first database initialization
Then you can configure other accesses to the admin checking the is_staff option displayed on a user in the admin
Work with policies
The policy management with global policies is nearly used for any kind of policy in Authentic 2
For each kind of these policies the system takes in account two special global policies named lsquoDefaultrsquo and lsquoAllrsquo
bull There is always a system default that does not correspond to the lsquoDefaultrsquo policy This is used to make Authentic2 boot without initial configuration When you add a lsquoDefaultrsquo policy the system default are not used anymore
bull A policy has always a name lsquoDefaultrsquo and lsquoAllrsquo are the names of two special policies with their name hardcodedBut you can create or delete them
bull If no other policy applies the policy lsquoDefaultrsquo applies
bull A policy can be created and attached to any related object This policy is authoritative on the policy lsquoDefaultrsquo
bull If the policy lsquoAllrsquo exists it is authoritative on any other policy
bull The global policies lsquoAllrsquo and lsquoDefaultrsquo are created by the administrator if necessary
bull A policy is taken in account only if it is enabled
bull When a regular policy is associated with an object it is taken in account only if the option lsquoenable the followingpolicyrsquo is checked on the oject
It is advised to add a lsquoDefaultrsquo global policy when it is expected to apply a policy to all related objects A lsquoDefaultrsquoglobal policy should be defined to avoid misonfiguration
Add a regular policy to some objects are used to handle particular configurations for a subset of related objects
An lsquoAllrsquo global policy should be used to enforce a global configuration for all related objects or for testing purposes
32 Configuration with the administration interface 15
Authentic2 Documentation Release 202
322 Authentication backends
Authentication with an existing LDAP directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP
The next lines must be added
AUTHENTICATION_BACKENDS += ( django_auth_ldapbackendLDAPBackend )
import ldapfrom django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your serverAUTH_LDAP_SERVER_URI = ldapldapexamplecom Let the bind DN and bind password blank for anonymous bindingAUTH_LDAP_BIND_DN = AUTH_LDAP_BIND_PASSWORD = Lookup user under the branch o=base and by mathcing their uid against the received login nameAUTH_LDAP_USER_SEARCH = LDAPSearch(o=base
ldapSCOPE_SUBTREE (uid=(user)s))
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesTypeAUTH_LDAP_GROUP_TYPE = GroupOfNamesType()AUTH_LDAP_GROUP_SEARCH = LDAPSearch(o=mycompany
ldapSCOPE_SUBTREE (objectClass=groupOfNames))AUTH_LDAP_USER_FLAGS_BY_GROUP =
is_staff cn=admino=mycompany
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
16 Chapter 3 Configuration
Authentic2 Documentation Release 202
Authentication on Authentic 2 with PAM
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
323 SAML2
Where do I find the Authentic 2 SAML2 metadata
The SAML2 metadata are automatically generated
Authentic 2 will infer from environment variables the host and port to generate the URLs contained in themedatada
The metadata of Authentic 2 SAML2 identity provider are available at
http[s]yourdomaincomidpsaml2metadata
The metadata of Authentic 2 SAML2 service provider are available at
http[s]yourdomaincomauthsaml2metadata
Configure SAML 20 service providers
How do I authenticate against Authentic 2 with a SAML2 service provider
1 Declare Authentic 2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identityprovider metadata of Authentic 2
Go to http[s]yourdomaincomidpsaml2metadata
2 Add and configure a SAML2 service provider in Authentic 2 using the metadata of the service provider
How do I add and configure a SAML2 service provider in Authentic 2
You first need to create a new SAML2 service provider entry This requires the SAML2 metadata of the serviceprovider
If your service provider is Authentic 2 the metadata are available at
http[s]yourdomaincomauthsaml2metadata
32 Configuration with the administration interface 17
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Set Authentic into the no DEBUG Mode
It is enough to edit authentic2settingspy and set
DEBUG = False
From then on the django-debug-toolbar package is not necessary anymore
Use dedicated HTTP servers and serve static files
The best is to use a server dedicated to serve the Django applications and a different server to serve the static files
You could for instance use apache with mod_wsgi to serve Authentic 2 You will find configuration file examples inthe debian directory of the Authentic 2 sources
Then you may want to use nginx to serve the static files
First you need to collect the Authentic 2 static files The static files are collected using the collectstatic command thatis configured in the settingspy
By default running collectstatic will create a static directory in the parent directory of the authentic2 directory
$python authentic2managepy collectstatic
That static directory will contain all the static files of Authentic 2
If you want to change the path of the static directory you can edit STATIC_ROOT of the settings file
See httpsdocsdjangoprojectcomendevrefcontribstaticfiles for more information about collectstatic
215 Quickstarts
Quickstart an OAuth2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6053
Quickstart an SAML2 Identity Provider
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6057
Quickstart a connection with a SAML2 Service Provider
1 Get the Identity Provider SAML2 metadata file
http[s]yourdomaincomidpsaml2metadata
2 Configure your service provider with it
3 Go to the providers admin panel on
http[s]adminsamllibertyprovideradd
There create a new provider using the service provider metadata and enable it as a service provider
10 Chapter 2 Installation and quickstart tutorials
Authentic2 Documentation Release 202
Quickstart a CAS Identity Provider
1 Activate CAS IdP support in your local_settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
authentic2-ctl syncdb ndashall authentic2-ctl migrate ndashfake
2 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
3 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
Quickstart to connect a LDAP Directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django for this you need python-ldap python-ldap needs python de-velopement headers to be installed but is usually packaged by most distributions
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP The next lines must be added
AUTHENTICATION_BACKENDS += ( lsquodjango_auth_ldapbackendLDAPBackendrsquo )
import ldap from django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your server AUTH_LDAP_SERVER_URI = lsquoldapldapexamplecomlsquo Let the bind DN and bind password blank for anonymous binding AUTH_LDAP_BIND_DN = ldquordquoAUTH_LDAP_BIND_PASSWORD = ldquordquo Lookup user under the branch o=base and by mathcing theiruid against the received login name AUTH_LDAP_USER_SEARCH = LDAPSearch(ldquoo=baserdquo
ldapSCOPE_SUBTREE ldquo(uid=(user)s)rdquo)
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesType AUTH_LDAP_GROUP_TYPE = GroupOf-NamesType() AUTH_LDAP_GROUP_SEARCH = LDAPSearch(ldquoo=mycompanyrdquo
ldapSCOPE_SUBTREE ldquo(objectClass=groupOfNames)rdquo)
AUTH_LDAP_USER_FLAGS_BY_GROUP = ldquois_staffrdquo ldquocn=admino=mycompanyrdquo
21 Quickstart guides and installation guidelines 11
Authentic2 Documentation Release 202
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
Quickstart for PAM Authentication
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
12 Chapter 2 Installation and quickstart tutorials
CHAPTER 3
Configuration
31 Configuration with settings
311 Works with authentic 2 settings
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6047
312 All settings
Activate or deactivate debug mode
Variable DEBUG
Values
bull False deactivate debug mode
bull True activate debug mode
Manage session cookie duration
Variable SESSION_EXPIRE_AT_BROWSER_CLOSE
Values
bull False Cookies are not removed when browser is closed
bull True Cookies are removed when browser is closed
Variable SESSION_COOKIE_AGE
Value
bull Seconds (36000 equal 10 hours)
Time zone selection
Variable TIME_ZONE
Values
13
Authentic2 Documentation Release 202
bull See httpenwikipediaorgwikiList_of_tz_zones_by_name
Activate or deactivate SSL authentication
Variable AUTH_SSL
Values
bull False deactivate SSL authentication
bull True activate SSL authentication
Activate or deactivate OpenID authentication Authentic 2 is an OpenID relying party
Variable AUTH_OPENID
Values
bull False deactivate OpenID authentication
bull True activate OpenID authentication
Activate or deactivate Authentic 2 as a SAML2 identity provider
Variable IDP_SAML2
Values
bull False deactivate SAML2 identity provider
bull True activate SAML2 identity provider
Configure SAML2 keys
bull SAML_SIGNATURE_PUBLIC_KEY Certtificate or public key for signature
bull SAML_SIGNATURE_PRIVATE_KEY Private key for signature
bull SAML_ENCRYPTION_PUBLIC_KEY Certtificate or public key for encryption
bull SAML_ENCRYPTION_PRIVATE_KEY Private key for encryption
Values are pem files of X509 certificate or key eg SAML_SIGNATURE_PRIVATE_KEY = lsquorsquolsquomdashndashBEGIN RSAPRIVATE KEYmdashndash MIIWA== mdashndashEND RSA PRIVATE KEYmdashndashlsquorsquolsquo
If SAML_ENCRYPTION_PUBLIC_KEY or SAML_ENCRYPTION_PRIVATE_KEY are not given the signaturekeys are used for encryption
Activate or deactivate Authentic 2 as an OpenID provider
Variable IDP_OPENID
Values
bull False deactivate OpenID provider
bull True activate OpenID provider
14 Chapter 3 Configuration
Authentic2 Documentation Release 202
Activate or deactivate Authentic 2 as a CAS server
Variable IDP_CAS
Values
bull False deactivate CAS server
bull True activate CAS server
32 Configuration with the administration interface
321 Basics
Access the grapical administration interface
The grapical administration interface is the lsquoDjango adminrsquo part of a Django project See for more information
Just acces the admin url at http[s]yourdomaincomadmin
At first you log with the superuser you created at the very first database initialization
Then you can configure other accesses to the admin checking the is_staff option displayed on a user in the admin
Work with policies
The policy management with global policies is nearly used for any kind of policy in Authentic 2
For each kind of these policies the system takes in account two special global policies named lsquoDefaultrsquo and lsquoAllrsquo
bull There is always a system default that does not correspond to the lsquoDefaultrsquo policy This is used to make Authentic2 boot without initial configuration When you add a lsquoDefaultrsquo policy the system default are not used anymore
bull A policy has always a name lsquoDefaultrsquo and lsquoAllrsquo are the names of two special policies with their name hardcodedBut you can create or delete them
bull If no other policy applies the policy lsquoDefaultrsquo applies
bull A policy can be created and attached to any related object This policy is authoritative on the policy lsquoDefaultrsquo
bull If the policy lsquoAllrsquo exists it is authoritative on any other policy
bull The global policies lsquoAllrsquo and lsquoDefaultrsquo are created by the administrator if necessary
bull A policy is taken in account only if it is enabled
bull When a regular policy is associated with an object it is taken in account only if the option lsquoenable the followingpolicyrsquo is checked on the oject
It is advised to add a lsquoDefaultrsquo global policy when it is expected to apply a policy to all related objects A lsquoDefaultrsquoglobal policy should be defined to avoid misonfiguration
Add a regular policy to some objects are used to handle particular configurations for a subset of related objects
An lsquoAllrsquo global policy should be used to enforce a global configuration for all related objects or for testing purposes
32 Configuration with the administration interface 15
Authentic2 Documentation Release 202
322 Authentication backends
Authentication with an existing LDAP directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP
The next lines must be added
AUTHENTICATION_BACKENDS += ( django_auth_ldapbackendLDAPBackend )
import ldapfrom django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your serverAUTH_LDAP_SERVER_URI = ldapldapexamplecom Let the bind DN and bind password blank for anonymous bindingAUTH_LDAP_BIND_DN = AUTH_LDAP_BIND_PASSWORD = Lookup user under the branch o=base and by mathcing their uid against the received login nameAUTH_LDAP_USER_SEARCH = LDAPSearch(o=base
ldapSCOPE_SUBTREE (uid=(user)s))
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesTypeAUTH_LDAP_GROUP_TYPE = GroupOfNamesType()AUTH_LDAP_GROUP_SEARCH = LDAPSearch(o=mycompany
ldapSCOPE_SUBTREE (objectClass=groupOfNames))AUTH_LDAP_USER_FLAGS_BY_GROUP =
is_staff cn=admino=mycompany
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
16 Chapter 3 Configuration
Authentic2 Documentation Release 202
Authentication on Authentic 2 with PAM
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
323 SAML2
Where do I find the Authentic 2 SAML2 metadata
The SAML2 metadata are automatically generated
Authentic 2 will infer from environment variables the host and port to generate the URLs contained in themedatada
The metadata of Authentic 2 SAML2 identity provider are available at
http[s]yourdomaincomidpsaml2metadata
The metadata of Authentic 2 SAML2 service provider are available at
http[s]yourdomaincomauthsaml2metadata
Configure SAML 20 service providers
How do I authenticate against Authentic 2 with a SAML2 service provider
1 Declare Authentic 2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identityprovider metadata of Authentic 2
Go to http[s]yourdomaincomidpsaml2metadata
2 Add and configure a SAML2 service provider in Authentic 2 using the metadata of the service provider
How do I add and configure a SAML2 service provider in Authentic 2
You first need to create a new SAML2 service provider entry This requires the SAML2 metadata of the serviceprovider
If your service provider is Authentic 2 the metadata are available at
http[s]yourdomaincomauthsaml2metadata
32 Configuration with the administration interface 17
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Quickstart a CAS Identity Provider
1 Activate CAS IdP support in your local_settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
authentic2-ctl syncdb ndashall authentic2-ctl migrate ndashfake
2 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
3 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
Quickstart to connect a LDAP Directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django for this you need python-ldap python-ldap needs python de-velopement headers to be installed but is usually packaged by most distributions
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP The next lines must be added
AUTHENTICATION_BACKENDS += ( lsquodjango_auth_ldapbackendLDAPBackendrsquo )
import ldap from django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your server AUTH_LDAP_SERVER_URI = lsquoldapldapexamplecomlsquo Let the bind DN and bind password blank for anonymous binding AUTH_LDAP_BIND_DN = ldquordquoAUTH_LDAP_BIND_PASSWORD = ldquordquo Lookup user under the branch o=base and by mathcing theiruid against the received login name AUTH_LDAP_USER_SEARCH = LDAPSearch(ldquoo=baserdquo
ldapSCOPE_SUBTREE ldquo(uid=(user)s)rdquo)
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesType AUTH_LDAP_GROUP_TYPE = GroupOf-NamesType() AUTH_LDAP_GROUP_SEARCH = LDAPSearch(ldquoo=mycompanyrdquo
ldapSCOPE_SUBTREE ldquo(objectClass=groupOfNames)rdquo)
AUTH_LDAP_USER_FLAGS_BY_GROUP = ldquois_staffrdquo ldquocn=admino=mycompanyrdquo
21 Quickstart guides and installation guidelines 11
Authentic2 Documentation Release 202
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
Quickstart for PAM Authentication
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
12 Chapter 2 Installation and quickstart tutorials
CHAPTER 3
Configuration
31 Configuration with settings
311 Works with authentic 2 settings
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6047
312 All settings
Activate or deactivate debug mode
Variable DEBUG
Values
bull False deactivate debug mode
bull True activate debug mode
Manage session cookie duration
Variable SESSION_EXPIRE_AT_BROWSER_CLOSE
Values
bull False Cookies are not removed when browser is closed
bull True Cookies are removed when browser is closed
Variable SESSION_COOKIE_AGE
Value
bull Seconds (36000 equal 10 hours)
Time zone selection
Variable TIME_ZONE
Values
13
Authentic2 Documentation Release 202
bull See httpenwikipediaorgwikiList_of_tz_zones_by_name
Activate or deactivate SSL authentication
Variable AUTH_SSL
Values
bull False deactivate SSL authentication
bull True activate SSL authentication
Activate or deactivate OpenID authentication Authentic 2 is an OpenID relying party
Variable AUTH_OPENID
Values
bull False deactivate OpenID authentication
bull True activate OpenID authentication
Activate or deactivate Authentic 2 as a SAML2 identity provider
Variable IDP_SAML2
Values
bull False deactivate SAML2 identity provider
bull True activate SAML2 identity provider
Configure SAML2 keys
bull SAML_SIGNATURE_PUBLIC_KEY Certtificate or public key for signature
bull SAML_SIGNATURE_PRIVATE_KEY Private key for signature
bull SAML_ENCRYPTION_PUBLIC_KEY Certtificate or public key for encryption
bull SAML_ENCRYPTION_PRIVATE_KEY Private key for encryption
Values are pem files of X509 certificate or key eg SAML_SIGNATURE_PRIVATE_KEY = lsquorsquolsquomdashndashBEGIN RSAPRIVATE KEYmdashndash MIIWA== mdashndashEND RSA PRIVATE KEYmdashndashlsquorsquolsquo
If SAML_ENCRYPTION_PUBLIC_KEY or SAML_ENCRYPTION_PRIVATE_KEY are not given the signaturekeys are used for encryption
Activate or deactivate Authentic 2 as an OpenID provider
Variable IDP_OPENID
Values
bull False deactivate OpenID provider
bull True activate OpenID provider
14 Chapter 3 Configuration
Authentic2 Documentation Release 202
Activate or deactivate Authentic 2 as a CAS server
Variable IDP_CAS
Values
bull False deactivate CAS server
bull True activate CAS server
32 Configuration with the administration interface
321 Basics
Access the grapical administration interface
The grapical administration interface is the lsquoDjango adminrsquo part of a Django project See for more information
Just acces the admin url at http[s]yourdomaincomadmin
At first you log with the superuser you created at the very first database initialization
Then you can configure other accesses to the admin checking the is_staff option displayed on a user in the admin
Work with policies
The policy management with global policies is nearly used for any kind of policy in Authentic 2
For each kind of these policies the system takes in account two special global policies named lsquoDefaultrsquo and lsquoAllrsquo
bull There is always a system default that does not correspond to the lsquoDefaultrsquo policy This is used to make Authentic2 boot without initial configuration When you add a lsquoDefaultrsquo policy the system default are not used anymore
bull A policy has always a name lsquoDefaultrsquo and lsquoAllrsquo are the names of two special policies with their name hardcodedBut you can create or delete them
bull If no other policy applies the policy lsquoDefaultrsquo applies
bull A policy can be created and attached to any related object This policy is authoritative on the policy lsquoDefaultrsquo
bull If the policy lsquoAllrsquo exists it is authoritative on any other policy
bull The global policies lsquoAllrsquo and lsquoDefaultrsquo are created by the administrator if necessary
bull A policy is taken in account only if it is enabled
bull When a regular policy is associated with an object it is taken in account only if the option lsquoenable the followingpolicyrsquo is checked on the oject
It is advised to add a lsquoDefaultrsquo global policy when it is expected to apply a policy to all related objects A lsquoDefaultrsquoglobal policy should be defined to avoid misonfiguration
Add a regular policy to some objects are used to handle particular configurations for a subset of related objects
An lsquoAllrsquo global policy should be used to enforce a global configuration for all related objects or for testing purposes
32 Configuration with the administration interface 15
Authentic2 Documentation Release 202
322 Authentication backends
Authentication with an existing LDAP directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP
The next lines must be added
AUTHENTICATION_BACKENDS += ( django_auth_ldapbackendLDAPBackend )
import ldapfrom django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your serverAUTH_LDAP_SERVER_URI = ldapldapexamplecom Let the bind DN and bind password blank for anonymous bindingAUTH_LDAP_BIND_DN = AUTH_LDAP_BIND_PASSWORD = Lookup user under the branch o=base and by mathcing their uid against the received login nameAUTH_LDAP_USER_SEARCH = LDAPSearch(o=base
ldapSCOPE_SUBTREE (uid=(user)s))
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesTypeAUTH_LDAP_GROUP_TYPE = GroupOfNamesType()AUTH_LDAP_GROUP_SEARCH = LDAPSearch(o=mycompany
ldapSCOPE_SUBTREE (objectClass=groupOfNames))AUTH_LDAP_USER_FLAGS_BY_GROUP =
is_staff cn=admino=mycompany
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
16 Chapter 3 Configuration
Authentic2 Documentation Release 202
Authentication on Authentic 2 with PAM
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
323 SAML2
Where do I find the Authentic 2 SAML2 metadata
The SAML2 metadata are automatically generated
Authentic 2 will infer from environment variables the host and port to generate the URLs contained in themedatada
The metadata of Authentic 2 SAML2 identity provider are available at
http[s]yourdomaincomidpsaml2metadata
The metadata of Authentic 2 SAML2 service provider are available at
http[s]yourdomaincomauthsaml2metadata
Configure SAML 20 service providers
How do I authenticate against Authentic 2 with a SAML2 service provider
1 Declare Authentic 2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identityprovider metadata of Authentic 2
Go to http[s]yourdomaincomidpsaml2metadata
2 Add and configure a SAML2 service provider in Authentic 2 using the metadata of the service provider
How do I add and configure a SAML2 service provider in Authentic 2
You first need to create a new SAML2 service provider entry This requires the SAML2 metadata of the serviceprovider
If your service provider is Authentic 2 the metadata are available at
http[s]yourdomaincomauthsaml2metadata
32 Configuration with the administration interface 17
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
Quickstart for PAM Authentication
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
12 Chapter 2 Installation and quickstart tutorials
CHAPTER 3
Configuration
31 Configuration with settings
311 Works with authentic 2 settings
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6047
312 All settings
Activate or deactivate debug mode
Variable DEBUG
Values
bull False deactivate debug mode
bull True activate debug mode
Manage session cookie duration
Variable SESSION_EXPIRE_AT_BROWSER_CLOSE
Values
bull False Cookies are not removed when browser is closed
bull True Cookies are removed when browser is closed
Variable SESSION_COOKIE_AGE
Value
bull Seconds (36000 equal 10 hours)
Time zone selection
Variable TIME_ZONE
Values
13
Authentic2 Documentation Release 202
bull See httpenwikipediaorgwikiList_of_tz_zones_by_name
Activate or deactivate SSL authentication
Variable AUTH_SSL
Values
bull False deactivate SSL authentication
bull True activate SSL authentication
Activate or deactivate OpenID authentication Authentic 2 is an OpenID relying party
Variable AUTH_OPENID
Values
bull False deactivate OpenID authentication
bull True activate OpenID authentication
Activate or deactivate Authentic 2 as a SAML2 identity provider
Variable IDP_SAML2
Values
bull False deactivate SAML2 identity provider
bull True activate SAML2 identity provider
Configure SAML2 keys
bull SAML_SIGNATURE_PUBLIC_KEY Certtificate or public key for signature
bull SAML_SIGNATURE_PRIVATE_KEY Private key for signature
bull SAML_ENCRYPTION_PUBLIC_KEY Certtificate or public key for encryption
bull SAML_ENCRYPTION_PRIVATE_KEY Private key for encryption
Values are pem files of X509 certificate or key eg SAML_SIGNATURE_PRIVATE_KEY = lsquorsquolsquomdashndashBEGIN RSAPRIVATE KEYmdashndash MIIWA== mdashndashEND RSA PRIVATE KEYmdashndashlsquorsquolsquo
If SAML_ENCRYPTION_PUBLIC_KEY or SAML_ENCRYPTION_PRIVATE_KEY are not given the signaturekeys are used for encryption
Activate or deactivate Authentic 2 as an OpenID provider
Variable IDP_OPENID
Values
bull False deactivate OpenID provider
bull True activate OpenID provider
14 Chapter 3 Configuration
Authentic2 Documentation Release 202
Activate or deactivate Authentic 2 as a CAS server
Variable IDP_CAS
Values
bull False deactivate CAS server
bull True activate CAS server
32 Configuration with the administration interface
321 Basics
Access the grapical administration interface
The grapical administration interface is the lsquoDjango adminrsquo part of a Django project See for more information
Just acces the admin url at http[s]yourdomaincomadmin
At first you log with the superuser you created at the very first database initialization
Then you can configure other accesses to the admin checking the is_staff option displayed on a user in the admin
Work with policies
The policy management with global policies is nearly used for any kind of policy in Authentic 2
For each kind of these policies the system takes in account two special global policies named lsquoDefaultrsquo and lsquoAllrsquo
bull There is always a system default that does not correspond to the lsquoDefaultrsquo policy This is used to make Authentic2 boot without initial configuration When you add a lsquoDefaultrsquo policy the system default are not used anymore
bull A policy has always a name lsquoDefaultrsquo and lsquoAllrsquo are the names of two special policies with their name hardcodedBut you can create or delete them
bull If no other policy applies the policy lsquoDefaultrsquo applies
bull A policy can be created and attached to any related object This policy is authoritative on the policy lsquoDefaultrsquo
bull If the policy lsquoAllrsquo exists it is authoritative on any other policy
bull The global policies lsquoAllrsquo and lsquoDefaultrsquo are created by the administrator if necessary
bull A policy is taken in account only if it is enabled
bull When a regular policy is associated with an object it is taken in account only if the option lsquoenable the followingpolicyrsquo is checked on the oject
It is advised to add a lsquoDefaultrsquo global policy when it is expected to apply a policy to all related objects A lsquoDefaultrsquoglobal policy should be defined to avoid misonfiguration
Add a regular policy to some objects are used to handle particular configurations for a subset of related objects
An lsquoAllrsquo global policy should be used to enforce a global configuration for all related objects or for testing purposes
32 Configuration with the administration interface 15
Authentic2 Documentation Release 202
322 Authentication backends
Authentication with an existing LDAP directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP
The next lines must be added
AUTHENTICATION_BACKENDS += ( django_auth_ldapbackendLDAPBackend )
import ldapfrom django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your serverAUTH_LDAP_SERVER_URI = ldapldapexamplecom Let the bind DN and bind password blank for anonymous bindingAUTH_LDAP_BIND_DN = AUTH_LDAP_BIND_PASSWORD = Lookup user under the branch o=base and by mathcing their uid against the received login nameAUTH_LDAP_USER_SEARCH = LDAPSearch(o=base
ldapSCOPE_SUBTREE (uid=(user)s))
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesTypeAUTH_LDAP_GROUP_TYPE = GroupOfNamesType()AUTH_LDAP_GROUP_SEARCH = LDAPSearch(o=mycompany
ldapSCOPE_SUBTREE (objectClass=groupOfNames))AUTH_LDAP_USER_FLAGS_BY_GROUP =
is_staff cn=admino=mycompany
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
16 Chapter 3 Configuration
Authentic2 Documentation Release 202
Authentication on Authentic 2 with PAM
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
323 SAML2
Where do I find the Authentic 2 SAML2 metadata
The SAML2 metadata are automatically generated
Authentic 2 will infer from environment variables the host and port to generate the URLs contained in themedatada
The metadata of Authentic 2 SAML2 identity provider are available at
http[s]yourdomaincomidpsaml2metadata
The metadata of Authentic 2 SAML2 service provider are available at
http[s]yourdomaincomauthsaml2metadata
Configure SAML 20 service providers
How do I authenticate against Authentic 2 with a SAML2 service provider
1 Declare Authentic 2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identityprovider metadata of Authentic 2
Go to http[s]yourdomaincomidpsaml2metadata
2 Add and configure a SAML2 service provider in Authentic 2 using the metadata of the service provider
How do I add and configure a SAML2 service provider in Authentic 2
You first need to create a new SAML2 service provider entry This requires the SAML2 metadata of the serviceprovider
If your service provider is Authentic 2 the metadata are available at
http[s]yourdomaincomauthsaml2metadata
32 Configuration with the administration interface 17
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
CHAPTER 3
Configuration
31 Configuration with settings
311 Works with authentic 2 settings
This section has to be done If you need it now say it on the issue tracker
httpsdeventrouvertorgissues6047
312 All settings
Activate or deactivate debug mode
Variable DEBUG
Values
bull False deactivate debug mode
bull True activate debug mode
Manage session cookie duration
Variable SESSION_EXPIRE_AT_BROWSER_CLOSE
Values
bull False Cookies are not removed when browser is closed
bull True Cookies are removed when browser is closed
Variable SESSION_COOKIE_AGE
Value
bull Seconds (36000 equal 10 hours)
Time zone selection
Variable TIME_ZONE
Values
13
Authentic2 Documentation Release 202
bull See httpenwikipediaorgwikiList_of_tz_zones_by_name
Activate or deactivate SSL authentication
Variable AUTH_SSL
Values
bull False deactivate SSL authentication
bull True activate SSL authentication
Activate or deactivate OpenID authentication Authentic 2 is an OpenID relying party
Variable AUTH_OPENID
Values
bull False deactivate OpenID authentication
bull True activate OpenID authentication
Activate or deactivate Authentic 2 as a SAML2 identity provider
Variable IDP_SAML2
Values
bull False deactivate SAML2 identity provider
bull True activate SAML2 identity provider
Configure SAML2 keys
bull SAML_SIGNATURE_PUBLIC_KEY Certtificate or public key for signature
bull SAML_SIGNATURE_PRIVATE_KEY Private key for signature
bull SAML_ENCRYPTION_PUBLIC_KEY Certtificate or public key for encryption
bull SAML_ENCRYPTION_PRIVATE_KEY Private key for encryption
Values are pem files of X509 certificate or key eg SAML_SIGNATURE_PRIVATE_KEY = lsquorsquolsquomdashndashBEGIN RSAPRIVATE KEYmdashndash MIIWA== mdashndashEND RSA PRIVATE KEYmdashndashlsquorsquolsquo
If SAML_ENCRYPTION_PUBLIC_KEY or SAML_ENCRYPTION_PRIVATE_KEY are not given the signaturekeys are used for encryption
Activate or deactivate Authentic 2 as an OpenID provider
Variable IDP_OPENID
Values
bull False deactivate OpenID provider
bull True activate OpenID provider
14 Chapter 3 Configuration
Authentic2 Documentation Release 202
Activate or deactivate Authentic 2 as a CAS server
Variable IDP_CAS
Values
bull False deactivate CAS server
bull True activate CAS server
32 Configuration with the administration interface
321 Basics
Access the grapical administration interface
The grapical administration interface is the lsquoDjango adminrsquo part of a Django project See for more information
Just acces the admin url at http[s]yourdomaincomadmin
At first you log with the superuser you created at the very first database initialization
Then you can configure other accesses to the admin checking the is_staff option displayed on a user in the admin
Work with policies
The policy management with global policies is nearly used for any kind of policy in Authentic 2
For each kind of these policies the system takes in account two special global policies named lsquoDefaultrsquo and lsquoAllrsquo
bull There is always a system default that does not correspond to the lsquoDefaultrsquo policy This is used to make Authentic2 boot without initial configuration When you add a lsquoDefaultrsquo policy the system default are not used anymore
bull A policy has always a name lsquoDefaultrsquo and lsquoAllrsquo are the names of two special policies with their name hardcodedBut you can create or delete them
bull If no other policy applies the policy lsquoDefaultrsquo applies
bull A policy can be created and attached to any related object This policy is authoritative on the policy lsquoDefaultrsquo
bull If the policy lsquoAllrsquo exists it is authoritative on any other policy
bull The global policies lsquoAllrsquo and lsquoDefaultrsquo are created by the administrator if necessary
bull A policy is taken in account only if it is enabled
bull When a regular policy is associated with an object it is taken in account only if the option lsquoenable the followingpolicyrsquo is checked on the oject
It is advised to add a lsquoDefaultrsquo global policy when it is expected to apply a policy to all related objects A lsquoDefaultrsquoglobal policy should be defined to avoid misonfiguration
Add a regular policy to some objects are used to handle particular configurations for a subset of related objects
An lsquoAllrsquo global policy should be used to enforce a global configuration for all related objects or for testing purposes
32 Configuration with the administration interface 15
Authentic2 Documentation Release 202
322 Authentication backends
Authentication with an existing LDAP directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP
The next lines must be added
AUTHENTICATION_BACKENDS += ( django_auth_ldapbackendLDAPBackend )
import ldapfrom django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your serverAUTH_LDAP_SERVER_URI = ldapldapexamplecom Let the bind DN and bind password blank for anonymous bindingAUTH_LDAP_BIND_DN = AUTH_LDAP_BIND_PASSWORD = Lookup user under the branch o=base and by mathcing their uid against the received login nameAUTH_LDAP_USER_SEARCH = LDAPSearch(o=base
ldapSCOPE_SUBTREE (uid=(user)s))
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesTypeAUTH_LDAP_GROUP_TYPE = GroupOfNamesType()AUTH_LDAP_GROUP_SEARCH = LDAPSearch(o=mycompany
ldapSCOPE_SUBTREE (objectClass=groupOfNames))AUTH_LDAP_USER_FLAGS_BY_GROUP =
is_staff cn=admino=mycompany
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
16 Chapter 3 Configuration
Authentic2 Documentation Release 202
Authentication on Authentic 2 with PAM
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
323 SAML2
Where do I find the Authentic 2 SAML2 metadata
The SAML2 metadata are automatically generated
Authentic 2 will infer from environment variables the host and port to generate the URLs contained in themedatada
The metadata of Authentic 2 SAML2 identity provider are available at
http[s]yourdomaincomidpsaml2metadata
The metadata of Authentic 2 SAML2 service provider are available at
http[s]yourdomaincomauthsaml2metadata
Configure SAML 20 service providers
How do I authenticate against Authentic 2 with a SAML2 service provider
1 Declare Authentic 2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identityprovider metadata of Authentic 2
Go to http[s]yourdomaincomidpsaml2metadata
2 Add and configure a SAML2 service provider in Authentic 2 using the metadata of the service provider
How do I add and configure a SAML2 service provider in Authentic 2
You first need to create a new SAML2 service provider entry This requires the SAML2 metadata of the serviceprovider
If your service provider is Authentic 2 the metadata are available at
http[s]yourdomaincomauthsaml2metadata
32 Configuration with the administration interface 17
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
bull See httpenwikipediaorgwikiList_of_tz_zones_by_name
Activate or deactivate SSL authentication
Variable AUTH_SSL
Values
bull False deactivate SSL authentication
bull True activate SSL authentication
Activate or deactivate OpenID authentication Authentic 2 is an OpenID relying party
Variable AUTH_OPENID
Values
bull False deactivate OpenID authentication
bull True activate OpenID authentication
Activate or deactivate Authentic 2 as a SAML2 identity provider
Variable IDP_SAML2
Values
bull False deactivate SAML2 identity provider
bull True activate SAML2 identity provider
Configure SAML2 keys
bull SAML_SIGNATURE_PUBLIC_KEY Certtificate or public key for signature
bull SAML_SIGNATURE_PRIVATE_KEY Private key for signature
bull SAML_ENCRYPTION_PUBLIC_KEY Certtificate or public key for encryption
bull SAML_ENCRYPTION_PRIVATE_KEY Private key for encryption
Values are pem files of X509 certificate or key eg SAML_SIGNATURE_PRIVATE_KEY = lsquorsquolsquomdashndashBEGIN RSAPRIVATE KEYmdashndash MIIWA== mdashndashEND RSA PRIVATE KEYmdashndashlsquorsquolsquo
If SAML_ENCRYPTION_PUBLIC_KEY or SAML_ENCRYPTION_PRIVATE_KEY are not given the signaturekeys are used for encryption
Activate or deactivate Authentic 2 as an OpenID provider
Variable IDP_OPENID
Values
bull False deactivate OpenID provider
bull True activate OpenID provider
14 Chapter 3 Configuration
Authentic2 Documentation Release 202
Activate or deactivate Authentic 2 as a CAS server
Variable IDP_CAS
Values
bull False deactivate CAS server
bull True activate CAS server
32 Configuration with the administration interface
321 Basics
Access the grapical administration interface
The grapical administration interface is the lsquoDjango adminrsquo part of a Django project See for more information
Just acces the admin url at http[s]yourdomaincomadmin
At first you log with the superuser you created at the very first database initialization
Then you can configure other accesses to the admin checking the is_staff option displayed on a user in the admin
Work with policies
The policy management with global policies is nearly used for any kind of policy in Authentic 2
For each kind of these policies the system takes in account two special global policies named lsquoDefaultrsquo and lsquoAllrsquo
bull There is always a system default that does not correspond to the lsquoDefaultrsquo policy This is used to make Authentic2 boot without initial configuration When you add a lsquoDefaultrsquo policy the system default are not used anymore
bull A policy has always a name lsquoDefaultrsquo and lsquoAllrsquo are the names of two special policies with their name hardcodedBut you can create or delete them
bull If no other policy applies the policy lsquoDefaultrsquo applies
bull A policy can be created and attached to any related object This policy is authoritative on the policy lsquoDefaultrsquo
bull If the policy lsquoAllrsquo exists it is authoritative on any other policy
bull The global policies lsquoAllrsquo and lsquoDefaultrsquo are created by the administrator if necessary
bull A policy is taken in account only if it is enabled
bull When a regular policy is associated with an object it is taken in account only if the option lsquoenable the followingpolicyrsquo is checked on the oject
It is advised to add a lsquoDefaultrsquo global policy when it is expected to apply a policy to all related objects A lsquoDefaultrsquoglobal policy should be defined to avoid misonfiguration
Add a regular policy to some objects are used to handle particular configurations for a subset of related objects
An lsquoAllrsquo global policy should be used to enforce a global configuration for all related objects or for testing purposes
32 Configuration with the administration interface 15
Authentic2 Documentation Release 202
322 Authentication backends
Authentication with an existing LDAP directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP
The next lines must be added
AUTHENTICATION_BACKENDS += ( django_auth_ldapbackendLDAPBackend )
import ldapfrom django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your serverAUTH_LDAP_SERVER_URI = ldapldapexamplecom Let the bind DN and bind password blank for anonymous bindingAUTH_LDAP_BIND_DN = AUTH_LDAP_BIND_PASSWORD = Lookup user under the branch o=base and by mathcing their uid against the received login nameAUTH_LDAP_USER_SEARCH = LDAPSearch(o=base
ldapSCOPE_SUBTREE (uid=(user)s))
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesTypeAUTH_LDAP_GROUP_TYPE = GroupOfNamesType()AUTH_LDAP_GROUP_SEARCH = LDAPSearch(o=mycompany
ldapSCOPE_SUBTREE (objectClass=groupOfNames))AUTH_LDAP_USER_FLAGS_BY_GROUP =
is_staff cn=admino=mycompany
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
16 Chapter 3 Configuration
Authentic2 Documentation Release 202
Authentication on Authentic 2 with PAM
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
323 SAML2
Where do I find the Authentic 2 SAML2 metadata
The SAML2 metadata are automatically generated
Authentic 2 will infer from environment variables the host and port to generate the URLs contained in themedatada
The metadata of Authentic 2 SAML2 identity provider are available at
http[s]yourdomaincomidpsaml2metadata
The metadata of Authentic 2 SAML2 service provider are available at
http[s]yourdomaincomauthsaml2metadata
Configure SAML 20 service providers
How do I authenticate against Authentic 2 with a SAML2 service provider
1 Declare Authentic 2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identityprovider metadata of Authentic 2
Go to http[s]yourdomaincomidpsaml2metadata
2 Add and configure a SAML2 service provider in Authentic 2 using the metadata of the service provider
How do I add and configure a SAML2 service provider in Authentic 2
You first need to create a new SAML2 service provider entry This requires the SAML2 metadata of the serviceprovider
If your service provider is Authentic 2 the metadata are available at
http[s]yourdomaincomauthsaml2metadata
32 Configuration with the administration interface 17
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Activate or deactivate Authentic 2 as a CAS server
Variable IDP_CAS
Values
bull False deactivate CAS server
bull True activate CAS server
32 Configuration with the administration interface
321 Basics
Access the grapical administration interface
The grapical administration interface is the lsquoDjango adminrsquo part of a Django project See for more information
Just acces the admin url at http[s]yourdomaincomadmin
At first you log with the superuser you created at the very first database initialization
Then you can configure other accesses to the admin checking the is_staff option displayed on a user in the admin
Work with policies
The policy management with global policies is nearly used for any kind of policy in Authentic 2
For each kind of these policies the system takes in account two special global policies named lsquoDefaultrsquo and lsquoAllrsquo
bull There is always a system default that does not correspond to the lsquoDefaultrsquo policy This is used to make Authentic2 boot without initial configuration When you add a lsquoDefaultrsquo policy the system default are not used anymore
bull A policy has always a name lsquoDefaultrsquo and lsquoAllrsquo are the names of two special policies with their name hardcodedBut you can create or delete them
bull If no other policy applies the policy lsquoDefaultrsquo applies
bull A policy can be created and attached to any related object This policy is authoritative on the policy lsquoDefaultrsquo
bull If the policy lsquoAllrsquo exists it is authoritative on any other policy
bull The global policies lsquoAllrsquo and lsquoDefaultrsquo are created by the administrator if necessary
bull A policy is taken in account only if it is enabled
bull When a regular policy is associated with an object it is taken in account only if the option lsquoenable the followingpolicyrsquo is checked on the oject
It is advised to add a lsquoDefaultrsquo global policy when it is expected to apply a policy to all related objects A lsquoDefaultrsquoglobal policy should be defined to avoid misonfiguration
Add a regular policy to some objects are used to handle particular configurations for a subset of related objects
An lsquoAllrsquo global policy should be used to enforce a global configuration for all related objects or for testing purposes
32 Configuration with the administration interface 15
Authentic2 Documentation Release 202
322 Authentication backends
Authentication with an existing LDAP directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP
The next lines must be added
AUTHENTICATION_BACKENDS += ( django_auth_ldapbackendLDAPBackend )
import ldapfrom django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your serverAUTH_LDAP_SERVER_URI = ldapldapexamplecom Let the bind DN and bind password blank for anonymous bindingAUTH_LDAP_BIND_DN = AUTH_LDAP_BIND_PASSWORD = Lookup user under the branch o=base and by mathcing their uid against the received login nameAUTH_LDAP_USER_SEARCH = LDAPSearch(o=base
ldapSCOPE_SUBTREE (uid=(user)s))
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesTypeAUTH_LDAP_GROUP_TYPE = GroupOfNamesType()AUTH_LDAP_GROUP_SEARCH = LDAPSearch(o=mycompany
ldapSCOPE_SUBTREE (objectClass=groupOfNames))AUTH_LDAP_USER_FLAGS_BY_GROUP =
is_staff cn=admino=mycompany
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
16 Chapter 3 Configuration
Authentic2 Documentation Release 202
Authentication on Authentic 2 with PAM
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
323 SAML2
Where do I find the Authentic 2 SAML2 metadata
The SAML2 metadata are automatically generated
Authentic 2 will infer from environment variables the host and port to generate the URLs contained in themedatada
The metadata of Authentic 2 SAML2 identity provider are available at
http[s]yourdomaincomidpsaml2metadata
The metadata of Authentic 2 SAML2 service provider are available at
http[s]yourdomaincomauthsaml2metadata
Configure SAML 20 service providers
How do I authenticate against Authentic 2 with a SAML2 service provider
1 Declare Authentic 2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identityprovider metadata of Authentic 2
Go to http[s]yourdomaincomidpsaml2metadata
2 Add and configure a SAML2 service provider in Authentic 2 using the metadata of the service provider
How do I add and configure a SAML2 service provider in Authentic 2
You first need to create a new SAML2 service provider entry This requires the SAML2 metadata of the serviceprovider
If your service provider is Authentic 2 the metadata are available at
http[s]yourdomaincomauthsaml2metadata
32 Configuration with the administration interface 17
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
322 Authentication backends
Authentication with an existing LDAP directory
Authentic use the module django_auth_ldap to synchronize the Django user tables with an LDAP For complex usecase we will refer you to the django_auth_ldap documentation see httppackagespythonorgdjango-auth-ldap
How to authenticate users against an LDAP server with anonymous binding
1 Install the django_auth_ldap module for Django
pip install django_auth_ldap
2 Configure your local_settingspy file for authenticating against LDAP
The next lines must be added
AUTHENTICATION_BACKENDS += ( django_auth_ldapbackendLDAPBackend )
import ldapfrom django_auth_ldapconfig import LDAPSearch
Here put the LDAP URL of your serverAUTH_LDAP_SERVER_URI = ldapldapexamplecom Let the bind DN and bind password blank for anonymous bindingAUTH_LDAP_BIND_DN = AUTH_LDAP_BIND_PASSWORD = Lookup user under the branch o=base and by mathcing their uid against the received login nameAUTH_LDAP_USER_SEARCH = LDAPSearch(o=base
ldapSCOPE_SUBTREE (uid=(user)s))
How to allow members of an LDAP group to manage Authentic
1 First you must know the objectClass of groups in your LDAP schema this FAQ will show you the configurationfor two usual classes groupOfNames and groupOfUniqueNames
2 Find the relevant groupname We will say it is cn=admino=mycompany
3 Add the following lines
from django_auth_ldapconfig import GroupOfNamesTypeAUTH_LDAP_GROUP_TYPE = GroupOfNamesType()AUTH_LDAP_GROUP_SEARCH = LDAPSearch(o=mycompany
ldapSCOPE_SUBTREE (objectClass=groupOfNames))AUTH_LDAP_USER_FLAGS_BY_GROUP =
is_staff cn=admino=mycompany
For an objectClass of groupOfUniqueNames you would change the string GroupOfNamesType to GroupOfUnique-NamesType and grouOfNames to groupOfUniqueNames For more complex cases see the django_auth_ldap docu-mentation
16 Chapter 3 Configuration
Authentic2 Documentation Release 202
Authentication on Authentic 2 with PAM
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
323 SAML2
Where do I find the Authentic 2 SAML2 metadata
The SAML2 metadata are automatically generated
Authentic 2 will infer from environment variables the host and port to generate the URLs contained in themedatada
The metadata of Authentic 2 SAML2 identity provider are available at
http[s]yourdomaincomidpsaml2metadata
The metadata of Authentic 2 SAML2 service provider are available at
http[s]yourdomaincomauthsaml2metadata
Configure SAML 20 service providers
How do I authenticate against Authentic 2 with a SAML2 service provider
1 Declare Authentic 2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identityprovider metadata of Authentic 2
Go to http[s]yourdomaincomidpsaml2metadata
2 Add and configure a SAML2 service provider in Authentic 2 using the metadata of the service provider
How do I add and configure a SAML2 service provider in Authentic 2
You first need to create a new SAML2 service provider entry This requires the SAML2 metadata of the serviceprovider
If your service provider is Authentic 2 the metadata are available at
http[s]yourdomaincomauthsaml2metadata
32 Configuration with the administration interface 17
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Authentication on Authentic 2 with PAM
This module is copied from httpsbitbucketorgwnielsondjango-pam by Weston Nielson and the pam ctype moduleby Chris Atlee httpatleecasoftwarepam
Add lsquoauthentic2vendordpambackendsPAMBackendrsquo to your settingspy
AUTHENTICATION_BACKENDS = (authentic2vendordpambackendsPAMBackend
)
Now you can login via the system-login credentials If the user is successfully authenticated but has never logged-inbefore a new User object is created By default this new User has both is_staff and is_superuser setto False You can change this behavior by adding PAM_IS_STAFF=True and PAM_IS_SUPERUSER in yoursettingspy file
The default PAM service used is login but you can change it by setting the PAM_SERVICE variable in yoursettingspy file
323 SAML2
Where do I find the Authentic 2 SAML2 metadata
The SAML2 metadata are automatically generated
Authentic 2 will infer from environment variables the host and port to generate the URLs contained in themedatada
The metadata of Authentic 2 SAML2 identity provider are available at
http[s]yourdomaincomidpsaml2metadata
The metadata of Authentic 2 SAML2 service provider are available at
http[s]yourdomaincomauthsaml2metadata
Configure SAML 20 service providers
How do I authenticate against Authentic 2 with a SAML2 service provider
1 Declare Authentic 2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identityprovider metadata of Authentic 2
Go to http[s]yourdomaincomidpsaml2metadata
2 Add and configure a SAML2 service provider in Authentic 2 using the metadata of the service provider
How do I add and configure a SAML2 service provider in Authentic 2
You first need to create a new SAML2 service provider entry This requires the SAML2 metadata of the serviceprovider
If your service provider is Authentic 2 the metadata are available at
http[s]yourdomaincomauthsaml2metadata
32 Configuration with the administration interface 17
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 service provider entry
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
18 Chapter 3 Configuration
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Note The service provider must be enabled
See below about configuring the service provider with policies
bull options of the service provider
bull protocol policy
bull attribute policy
3 Save
Apply a SAML2 service provider options policy The SAML2 options of the service provider are configured usingsp options policies
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
32 Configuration with the administration interface 19
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Go to
http[s]yourdomaincomadminsamlspoptionsidppolicyadd
Configure your policy and save
20 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Apply the policy to the service provider
Example with a policy lsquoDefaultrsquo
32 Configuration with the administration interface 21
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
22 Chapter 3 Configuration
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of a service provider the following error is displayedto the users when a SSO request is received
32 Configuration with the administration interface 23
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Configure the SAML2 service provider protocol options This kind of policy does not use the policy managementusing global policies
You should use the default option except if your service provider is a Shibboleth service provider then you should usethe option ldquoShibboleth SP (AuthnRequest Signature Does not check signatures)rdquo
Configure the attribute policy of the service provider See the attribute management page Attribute Managementin Authentic 2
How to refresh the metadata of a service provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
24 Chapter 3 Configuration
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
How to create in bulk service providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Configure Authentic 2 as a SAML2 service provider or a SAML2 proxy
The configuration to make Authentic 2 a SAML2 service provider or a SAML2 proxy is the same The differencecomes from that Authentic 2 is may be configured or not as a SAML2 identity provider
How do I authenticate against a third SAML2 identity provider
1 Declare Authentic 2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 serviceprovider metadata of Authentic 2
Go to http[s]yourdomaincomauthsaml2metadata
2 Add and configure a SAML2 identity provider entry in Authentic 2 using the metadata of the identity provider
How do I add and configure a SAML2 identity provider in Authentic 2
You first need to create a SAML2 identity provider entry with the SAML2 metadata of the identity provider Thenyou configure it
If your identity provider is Authentic 2 the metadata are available at
http[s]yourdomaincomidpsaml2metadata
See Where do I find the Authentic 2 SAML2 metadata for more information
Create a SAML2 identity provider entry You first need to create a new SAML2 identity provider entry Thisrequires the SAML2 metadata of the identity provider
1 Go to
http[s]yourdomaincomadminsamllibertyprovideradd
2 Fill the form fields
32 Configuration with the administration interface 25
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
The identity provider must be enabled
See below about configuring the identity provider with policies
bull options of the identity provider
3 Save
26 Chapter 3 Configuration
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Apply a SAML2 identity provider options policy The SAML2 options of the identity provider are configuredusing idp options policies For the explanation of the options see the following section
See the administration with policy principle page Work with policies
You may create a regular policy and configure your service provider to use it
Go to
http[s]yourdomaincomadminsamlidpoptionssppolicyadd
Configure your policy and save
32 Configuration with the administration interface 27
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Apply the policy to the identity provider
Example with a policy lsquoDefaultrsquo
28 Chapter 3 Configuration
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Example with a policy lsquoAllrsquo
32 Configuration with the administration interface 29
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
If no policy is found for the configuration of the SAML2 options of an identity provider the following error is displayedto the users when a SSO request is initiated
30 Chapter 3 Configuration
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
SAML2 identity provider options explained
Behavior with persistent nameID This option applies when an assertion with a persistent nameID is received andthe nameID is not recognized as an existing federation
Two values are possible ldquoCreate new accountrdquo and ldquoAccount linking by authenticationrdquo
The value ldquoCreate new accountrdquo makes Authentic 2 create a user account associated to the nameID received
The value ldquoAccount linking by authenticationrdquo makes Authentic 2 ask the user to authenticate with an existing accountto associate the nameID to this account
Behavior with transient nameID This option applies when an assertion with a transient nameID is received andthere isnrsquot a session opened for the user yet
Two values are possible ldquoOpen a sessionrdquo and ldquoAsk authenticationrdquo
The value ldquoOpen a sessionrdquo makes Authentic 2 open a session
The value ldquoAsk authenticationrdquo makes Authentic 2 ask for a user authentication even when a valid assertion is re-ceived That may have sense for instance if the SSO login is used only to receive signed attributes for users withexisting accounts
How to refresh the metadata of an identity provider hosted at a Well-Known Location
The Well-Known Location (WKL) means that the entity Id of the provider is a URL at which the provider metadataare hosted
To refresh them select the provider on the list of provider then select in the menu lsquoUpdate metadatarsquo then click onlsquoGorsquo
32 Configuration with the administration interface 31
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
How to create in bulk identity providers with the sync-metadata script
See the page explaining the use of the script sync-metadata How to createimport and delete in bulk SAML2 identityand service providers with the sync-metadata script
Single Logout Management in Authentic 2
Explanation
Authentic 2 implements the single logout profile of SAML2 (SLO) Single Logout is used to realise to close usersession on distributed applications The Single Logout is managed by the IdP However its exists many profiles allsupported by Authentic 2
bull SLO IdP initiated by SOAP
bull SLO IdP initiated by Redirect
bull SLO SP initiated by SOAP
bull SLO SP initiated by Redirect
Then Authentic 2 acting as an IdP but also as a SP (for proxying) a logout request can be received from
bull the logout button on the user interface
32 Chapter 3 Configuration
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
bull a service provider
bull a third identity provider
The configuration by policy allows to refuse SLO request coming from a SP or an IdP
The the SLO request is accepted or comes from the user interface at the end of the process the local session onAuthentic 2 will always be closed
During the process of treatment of the logout request when the logout request comes from a SP if the local sessionwas established through a third SAML2 IdP Authentic 2 sends it a logout request (SLO proxying) Then Authentic 2sends logout resuests to all service providers with an active session but the requesting service provider
During the process of treatment of the logout request when the logout request comes from an IdP Authentic 2 sendslogout resuests to all service providers with an active session
The configuration by policy allows to select which IdP and SP to logout forwarding is done
Note When a logout request comes from an IdP the logout request is always forwarded by soap to the serviceproviders
Note When a logout request comes from an SP - if done by SOAP the logout request is always forwarded by soapto the identity provider and service providers - if done by Redirect the logout request is forwarded to the identityprovider according to the idp options policy and to the service providers according to their metadata
Note When a logout request comes from the user interface the logout request is forwarded to the identity provideraccording to the idp options policy and to the service providers according to their metadata
Note To make the SLO works a policy must be found for the source or the desitnation of the logout request Bydefault when creating a sp options policy or an IdP options policy the SLO is accepted and forwarded
See the administration with policy principle page Work with policies
How to know if a service provider supports the logout request
Look for the following elements in the service provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpspmiklan8000authsaml2singleLogout ResponseLocation=httpspmiklan8000authsaml2singleLogoutReturngt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpspmiklan8000authsaml2singleLogoutSOAPgt
How to know if an identity provider supports the logout request
Look for the following elements in the identity provider metadata
bull Redirect binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsHTTP-Redirect Location=httpidpmiklan8001idpsaml2slo ResponseLocation=httpidpmiklan8001idpsaml2slo_return gt
bull SOAP binding
ltns0SingleLogoutService Binding=urnoasisnamestcSAML20bindingsSOAP Location=httpidpmiklan8001idpsaml2slosoap gt
32 Configuration with the administration interface 33
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
How activate the SLO
No activation is required However it is required a policy be found for the source or the desitnation of the logoutrequest
The sp options policy or idp options policy that applies has parameters to indicate if the sp or idp which the policyapplies is allowed to send and receive logout requests
Then create the lsquodefaultrsquo options policy and check the both options Accept to receive Single Logout requests andForward Single Logout requests as follows
34 Chapter 3 Configuration
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
How deactivate the SLO
There is no real deactivation process When it is possible and authorized Authentic 2 send logout requests when alogout request is received
If an options policy is not found for the source or the destination of the logout request the logout requests are notaccepted nor forwarded
However it is not the right way The best is to create the lsquoallrsquo options policies with the options Accept to receive SingleLogout requests and Forward Single Logout requests unchecked as follows
32 Configuration with the administration interface 35
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
36 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Take care that the lsquoallrsquo policies are authoritative To desactivate the SLO but for particular providers the best is tounchecked these options on the lsquodefaultrsquo options policies and apply regular policies to those particular providers
How refuse SLO from an identity provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that identity provider
How refuse SLO from a service provider
Uncheck the option Accept to receive Single Logout requests of the policy that applies to that service provider
32 Configuration with the administration interface 37
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
How indicate identity providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the identity providers logout requestsmust not be forwarded
How indicate service providers to not forward logout request
Uncheck the option Forward Single Logout requests of the policies that applies to the service providers logout requestsmust not be forwarded
How do manage the SLO without closing the local session
Not implemented
324 CAS
Configure Authentic 2 as a CAS server
How to use Authentic 2 as a CAS 10 or CAS 20 identity provider
1 Activate CAS IdP support in settingspy
IDP_CAS = True
2 Then create the database table to hold CAS service tickets
python authentic2managepy syncdb --migrate
3 Also configure authentic2 to authenticate against your LDAP directory (see above) if your want your user at-tributes to be accessible from your service if it is not necessary you can use the normal relational databasestorage for you users
4 Finally configure your service to point to the CAS endpoint at
http[s]yourdomaincomidpcas
5 If needed configure your service to resolve authenticated user with your LDAP directory (if user attributes areneeded for your service)
325 Attributes
Attribute Management in Authentic 2
Summary
Attribute management currently allows to configure attribute policies associated with SAML2 service providers todefine attributes that are pushed in SAML2 successful authentication response delivered by Authentic 2
User attributes can be taken from LDAP directories the user Django profile or taken from the user Django session ifAuthentic 2 is also configured as a SAML2 service provider
Indeed when Authentic 2 acts also as a SAML2 service provider attributes contained in the SAML2 assertion receivedfrom third IdP are put in the user session
38 Chapter 3 Configuration
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Attributes can thus be proxyfied during SSO with Authentic 2 configured as a SAML2 proxy
If there is no attribute policy associate with a service provider no attribute is forwarded to it
The namespace of attributes received from another SAML2 IdP and of attributes pushed in the assertion given toservice providers can be configured per attribute or per service provider
By default the namespace and format of attributes in assertion is conformant to the SAMLV20 X500LDAP Attributeprofile
ltsamlAttributexmlnsx500=urnoasisnamestcSAML20profilesattributeX500NameFormat=urnoasisnamestcSAML20attrname-formaturiName=urnoid25442 FriendlyName=givenNamegtltsamlAttributeValue xsitype=xsstring
x500Encoding=LDAPgtMikaeumllltsamlAttributeValuegtltsamlAttributegt
But the httpschemasxmlsoaporgws200505identityclaims from the ISI profile can also be used for instance
ltsamlAttributeNameFormat=urnoasisnamestcSAML20attrname-formaturiName=httpschemasxmlsoaporgws200505identityclaimsgivennameFriendlyName=First NamegtltsamlAttributeValuegtMikaeumllltsamlAttributeValuegt
ltsamlAttributegt
Configuration
Configure local sources of attributes The source of attributes for authentic2 are of two kinds The LDAP sourcesand the user django profile
Declare the Django profile source Add an attribute source named USER_PROFILE with namespace lsquoDefaultrsquo
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
2 Write lsquoUSER_PROFILErsquo in name field
3 Save
32 Configuration with the administration interface 39
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Add an LDAP Source For LDAP sources objects of type lsquoLDAPSourcersquo must be created
Even if the authentication is based on LDAP authentification thus that a server is configured in settingspy itis necessary to create a corresponding lsquoLDAPSourcersquo to use it as a source of attribute
1 Go to http[s]yourdomaincomadminattribute_aggregatorldapsourceadd
2 Fill form fields
Only the field Name Server User Password Base and Port are used for now The namespace of LDAP source mustbe kept to lsquoDefaultrsquo since the system namespace is based on LDAP
3 Save
40 Chapter 3 Configuration
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Manage user distinguished names in LDAP directories To find the user in a LDAP directory authentic2 mustknow its distinguished name (DN) If this LDAP has been used when the user has authenticated Authentic 2 learn theuser DN Nothing has to be done from this point of view
However if it is expected that user attributes be taken in a directory that is not used by the user for authentication it isnecessary to manually indicate to Authentic 2 what is the user DN in the directory For this a user alias in source iscreated for the user
1 Go to http[s]yourdomaincomadminattribute_aggregatoruseraliasinsourceadd
2 Fill form fields
3 Save
Configure attributes from local sources pushed to SAML2 service providers in SSO response Reminder
bull The default name format in SAML2 assertions is URI
bull The default namespace called lsquoDefaultrsquo is LDAP
In summary
32 Configuration with the administration interface 41
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
1 Create attribute items indicating an attribute name a source the name format expected and the namespaceexpected for the attribute name and friendly name if any
2 Create a named list of attribute items
3 Create an attribute policy and associate the previous list or associate the previous list to a existing attributepolicy
4 Associate the policy to a service provider
Create attribute items
1 Go to http[s]yourdomaincomadminidpattributeitemadd
2 Fill form fields
3 Save
Create a named list of attribute items
1 Go to http[s]yourdomaincomadminidpattributelistadd
2 Name the list and add items to list
42 Chapter 3 Configuration
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
3 Save
Create or modify an attribute policy You can create a global policy lsquoAllrsquo or lsquoDefaultrsquo For details see Work withpolicies Or you can create a regular policy and associate it to a service provider
1 Go to http[s]yourdomaincomadminidpattributepolicyadd
2 Add list to the policy
32 Configuration with the administration interface 43
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
3 Save
44 Chapter 3 Configuration
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Associate the policy to a service provider
1 Go to http[s]yourdomaincomadminsamllibertyprovider1
2 Associate the policy to the service provider and enable it
3 Save
4 The display name of the policy has changed
Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO re-sponse (proxy attributes) To have these kind of attributes to forward authentic must be configured as a SAML2service provider see the corresponding administration page Configure Authentic 2 as a SAML2 service provider or aSAML2 proxy
32 Configuration with the administration interface 45
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Forward all attributes in session without any modification Create or modify an attribute policy activating theoption lsquoForward attributes from push sourcesrsquo and save
No other option below must be used
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Filter attributes from source only Here you want to forward all attributes of selected source of attributes
First of all you need to create objects corresponding to the sources of attributes
The name of the source object must be the entity ID of the SAML2 identity provider
1 Go to http[s]yourdomaincomadminattribute_aggregatorattributesourceadd
46 Chapter 3 Configuration
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
2 Set the name (No need to change the namespace)
3 Save
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenselect the source you want to forward attributes through the selection box and you save
32 Configuration with the administration interface 47
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Attach policy to the service provider if it is not yet the case
No need to deal with namespace here
Modify namespace of attributes forwarded when attributes forwarded are not filtered or when filtered accord-ing to the source The system needs to lsquorecognise the attributesrsquo to perform the mapping For this you need toindicate the namespace of attributes received per source if the namespace is not the one of Authentic 2 (X500LDAPand extensions edu and supann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
48 Chapter 3 Configuration
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Then create or modify an attribute policy activating the options lsquoForward attributes from push sourcesrsquo lsquoMap at-tributes from push sourcesrsquo You also choose the output namespace expected with the parameters lsquoOutput nameformatrsquo and lsquoOutput namespacersquo
32 Configuration with the administration interface 49
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Remind that the default namespace is X500LDAP + edu + supann and the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
Attach policy to the service provider if it is not yet the case
Filter attributes with a list of attributes with or without choosing the source The system needs to lsquorecognisethe attributesrsquo to filter the attributes according to a list of attributes For this you need to indicate the namespace ofattributes received per source if the namespace is not the one of Authentic 2 (X500LDAP and extensions edu andsupann)
In other words if the source provides attributes in a different namespace you need to create objects corresponding tothe sources of attributes and indicate there the right namespace By default the only other supported namespace ishttpschemasxmlsoaporgws200505identityclaims
You then create an attribute list as described in section lsquoCreate a named list of attribute itemsrsquo
Then create or modify an attribute policy activating the option lsquoForward attributes from push sourcesrsquo You thenassociate the list of attributes
50 Chapter 3 Configuration
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
If you want to also filter according to the source you can configure it as defined in section lsquoFilter attributes from sourceonlyrsquo You can also choose to filter with the source indicate per attribute item of the list For this select the optionlsquoFilter source of filtered attributesrsquo
32 Configuration with the administration interface 51
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
52 Chapter 3 Configuration
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
The default name format is URI You can however change the name format and namespace with the option lsquoMapattributes from push sourcesrsquo and the parameters lsquoOutput name formatrsquo and lsquoOutput namespacersquo
Using the option lsquoMap attributes of filtered attributesrsquo the output name format and namespace are the ones indicatedper attribute item of the list
32 Configuration with the administration interface 53
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
54 Chapter 3 Configuration
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Push manually (writing bits of code) attributes to SAML2 service providers in SSO response In idpsignalspyconnect to the add_attributes_to_response signal
add_attributes_to_responseconnect(your_function)
Your function must return an attribute dictionnary as follows
dic = attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )dic[attributes] = attributesreturn dic
format must be in (lassoSAML2_ATTRIBUTE_NAME_FORMAT_URI lassoSAML2_ATTRIBUTE_NAME_FORMAT_BASIC)
You can use the attributes form the local source and the attributes in the session that are pushed by other identityproviders
Attributes in the session are in
requestsession[multisource_attributes]
See the page Attributes in session pushed by third SAML2 identity providers
If you want to use local source of attributes and use mapping capabilities of the UserAttributeProfile see the pageattribute_management_explained Use the file idpattributespy as an exemple
Modifying supported namespaces and attribute name mappings
The mapping is defined in the file attribute_aggregatoremappingpy
The manual modification of this file is necessary to extend the default schema and mappings
Add new namespaces in ATTRIBUTE_NAMESPACES
To extend the default schema add keyvalue in ATTRIBUTE_MAPPING for instance
32 Configuration with the administration interface 55
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
displayName oid 216840111373031241display_name _(displayName)type httpwwww3org2001XMLSchemastringsyntax 1361411466115121115
Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING for instance
sn oid 2544display_name _(sn surname)alias [surname]profile_field_name last_nametype httpwwww3org2001XMLSchemastringnamespaces
httpschemasxmlsoaporgws200505identityclaims identifiers
[httpschemasxmlsoaporgws200505identityclaimssurname
]friendly_names
[Last Name
]
326 User interfaces and interactions
Consent Management in Authentic 2
What is the SAML2 federation consent aka account linking consent
At the first single sign on process on the identity provider side the user may be asked if she agrees to federation itslocal account with the remote account on the service provider side
The account linking also called a federation means that the nameID is persistent and will link the two accounts Thissigned identifier allows to the service provider to login the user without reauthentication during the following singlesign on process
How the consent is collected is determined by the identity provider The service provider receives in the authnRequestthe consent attribute indicating how the user consent was managed
Account linking consent management on the identity provider side
The consent is managed per service provider according to the options policy that applies to the service provider
The parameter lsquoAsk user for consent when creating a federationrsquo determine if the user consent must be asked to theuser
56 Chapter 3 Configuration
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
Take care that is the identity provider provides the service provider with a transient nameID there is no accountlinking so there is no need for a consent
The user consent is only asked once In other words if the user already has a federation the consent wonrsquot be askedanymore
If the policy requires the user consent this can be bypassed using the signal lsquoavoid_consentrsquo
Account linking consent management on the service provider side
The service provider may refuse a valid single sign on if the user consent was not asked
The parameter lsquoRequire the user consent be given at account linkingrsquo of the identity provider options policy determinethe service provider behavior
32 Configuration with the administration interface 57
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
How manage attribute forwarding consent
If there is no attribute policy associate with a service provider no attribute is forwarded
When an attribute policy applies you can configure the consent rules per service provider
The choices are
bull Donrsquot ask the user consent
bull Ask the consent in all-or-nothing mode
bull Allow attribute selection
To ask the user consent tick the parameter lsquoAsk the user consent before forwarding attributesrsquo of the attribute policythat applies to the service provider
To allow the attribute selection on the attribute consent page tick the parameter lsquoAllow the user to select the forwardingattributesrsquo
58 Chapter 3 Configuration
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
33 Administration
331 Compiling translations
Translations must compiled to be useful to do that run the following command
33 Administration 59
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
setuppy compile_translations
332 Cronjobs and cleaning
The following cronjob must be run to clean deleted accounts and temporary objects
5 0 athentic2-ctl cleanup
Itrsquos made to run every day at 0005
333 How to createimport and delete in bulk SAML2 identity and service providerswith the sync-metadata script
This section explains hot to use the script sync-metadata
Presentation
This script allows to createimport and deleted in bulk SAML2 identity and service providers using standard SAML2metadata files containing entity descriptors
An example of such a file used in production is the global metadata file of the identity federation of French universitiesthat can be found at http
Use the following command
path_to_projectauthentic2$ python managepy sync-metadata file_name [options]
Options
bull idp
Load only identity providers of the metadata file
bull sp
Load only service providers of the metadata file
bull source
Used to tag all imported providers with a label This option is used to metadata reloading and deletionin bulk
Reloading a metadata file when a provider with same entity is found it is updated If a provider inthe metadata file does not exist it is created If a provider exists in the system but not in the metadatafile it is removed
For reloading a source can only be associated with a unique metadata file This is due to thefact that all providers of a source not found in the metadata file are removed
path_to_projectauthentic2$ python managepy sync-metadata file_name --source=french_federation
bull sp-policy
To configure the SAML2 parameters of service providers imported with the script a policy of typeSPOptionsIdPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
60 Chapter 3 Configuration
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
path_to_projectauthentic2$ python managepy sync-metadata file_name --sp-policy=sp_policy_name
bull idp-policy
To configure the SAML2 parameters of identity providers imported with the script a policy of typeIdPOptionsSPPolicy must be created in the the administration interface Either it is a global policylsquoDefaultrsquo or lsquoAllrsquo or it is a regular policy If it is a regular policy the policy name can be specified inparameter of the script with this option The policy is then associated to all service providers created
path_to_projectauthentic2$ python managepy sync-metadata file_name --idp-policy=idp_policy_name
bull delete
With no options all providers are deleted
With the source option only providers with the source name given are deleted
This option can not be combined with options idp and sp
bull ignore-errors
If loading of one EntityDescriptor fails continue loading
33 Administration 61
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
62 Chapter 3 Configuration
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
CHAPTER 4
Advanced topics
bull Attributes in session pushed by third SAML2 identity providers
bull Writing migrations
bull Add a new kind of administration policy
41 Attributes in session pushed by third SAML2 identity providers
When an assertion is received assertion data including attributes are pushed in the Django session dictionnary
It leads to the creation of the following dictionnary
requestsession[multisource_attributes]
The keys of the dictionnary are the source names ie the entity Id for SAML2 identity providers
The values are list of data extracted from assertions Indeed this is done to store multiple assertion received from asame source in a same Django session
requestsession[multisource_attributes] [source_name] = list()
The items of this list are dictionnaries with the keys lsquocertificate_typersquo and lsquoattributesrsquo
For a saml2 assertion all the keys are
a8n[certificate_type] = SAML2_assertiona8n[nameid] = a8n[subject_confirmation_method] = a8n[not_before] = a8n[not_on_or_after] = a8n[authn_context] = a8n[authn_instant] = a8n[attributes] = attrs
a8n[rsquoattributesrsquo] has the following structure
attributes = attributes[name] = (value1 value2 )attributes[(name format)] = (value1 value2 )attributes[(name format nickname)] = (value1 value2 )a8n[attributes] = attributes
63
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
Authentic2 Documentation Release 202
42 Writing migrations
Migration containing reference to the user model must be rewritten manually to refer to the user model name indirectlyThe followind modifications must be applied
1 First import the user_model_label from the authentic2compat module
from authentic2compat import user_model_label
Any reference to orm[rsquoauthUserrsquo] or orm[rsquoauthentic2Userrsquo] must be rewritten into orm[user_model_label] Forexample this line
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[authentic2User]))
must be changed to
(user selfgf(djangodbmodelsfieldsrelatedForeignKey)(to=orm[user_model_label]))
2 The user model when appearing in the models field like this
uauthuser meta object_name User
must be rewritten like that
user_model_label Meta object_name user_model_labelsplit()[-1]
3 If the user model is referred inside the to field of a foreign key declaration like this
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[authUser])
must be rewritten like that
user (djangodbmodelsfieldsrelatedForeignKey [] to uorm[s] user_model_label)
43 Add a new kind of administration policy
See how policies works Work with policies Then the bahavior should look like
def get_sample_policy(any_object) Look for a global policy Alltry
return SamplePolicyobjectsget(name=All enabled=True)except SamplePolicyDoesNotExist
pass Look for a regular policyif any_objectenable_following_sample_policy
if any_objectsample_policyreturn any_objectsample_policy
Look for a global policy Defaulttry
return SamplePolicyobjectsget(name=Default enabled=True)except SamplePolicyDoesNotExist
passreturn None
64 Chapter 4 Advanced topics
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-
CHAPTER 5
Copyright
Authentic and Authentic 2 are copyrighted by Entrrsquoouvert and are licensed through the GNU AFFERO GENERALPUBLIC LICENSE version 3 or later A copy of the whole license text is available in the COPYING file
The OpenID IdP originates in the project django_openid_provider by Roman Barczyski which is under the Apache20 licence This imply that you must distribute authentic2 under the AGPL3 licence when distributing this part of theproject which is the only AGPL licence version compatible with the Apache 20 licence
The Documentation is under the licence Creative Commons CC BY-SA 20
This documentation is under the licence Creative Commons CC BY-SA 20
65
- Overview
- Installation and quickstart tutorials
- Configuration
- Advanced topics
- Copyright
-