authentic2 documentation - read the docs · authentic2 documentation, release 2.0.2 authentic 2 is...

69
Authentic2 Documentation Release 2.0.2 Entr’ouvert June 17, 2016

Upload: others

Post on 25-Jun-2020

13 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 2: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 3: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 4: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 5: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 6: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 7: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 8: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 9: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 10: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 11: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 12: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 13: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 14: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 15: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 16: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 17: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 18: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 19: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 20: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 21: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 22: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 23: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 24: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 25: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 26: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 27: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 28: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 29: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 30: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 31: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 32: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 33: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 34: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 35: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 36: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 37: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 38: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 39: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 40: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 41: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 42: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 43: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 44: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 45: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 46: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 47: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 48: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 49: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 50: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 51: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 52: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 53: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 54: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 55: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 56: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 57: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 58: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 59: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 60: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 61: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 62: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 63: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 64: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 65: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 66: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 67: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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
Page 68: Authentic2 Documentation - Read the Docs · Authentic2 Documentation, Release 2.0.2 Authentic 2 is a versatile identity management server aiming to address a broad range of needs,

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