Produits Entr'ouvert » Authentic 2

Full documentation available on http://authentic2.readthedocs.org/en/stable/.

# Makefile for Sphinx documentation

#

# You can set these variables from the command line.

SPHINXOPTS    =

SPHINXBUILD   = sphinx-build

PAPER         =

BUILDDIR      = _build

# Internal variables.

PAPEROPT_a4     = -D latex_paper_size=a4

PAPEROPT_letter = -D latex_paper_size=letter

ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

# the i18n builder cannot share the environment and doctrees with the others

I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .

.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext

help:

	@echo "Please use \`make <target>' where <target> is one of"

	@echo "  html       to make standalone HTML files"

	@echo "  dirhtml    to make HTML files named index.html in directories"

	@echo "  singlehtml to make a single large HTML file"

	@echo "  pickle     to make pickle files"

	@echo "  json       to make JSON files"

	@echo "  htmlhelp   to make HTML files and a HTML help project"

	@echo "  qthelp     to make HTML files and a qthelp project"

	@echo "  devhelp    to make HTML files and a Devhelp project"

	@echo "  epub       to make an epub"

	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"

	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"

	@echo "  text       to make text files"

	@echo "  man        to make manual pages"

	@echo "  texinfo    to make Texinfo files"

	@echo "  info       to make Texinfo files and run them through makeinfo"

	@echo "  gettext    to make PO message catalogs"

	@echo "  changes    to make an overview of all changed/added/deprecated items"

	@echo "  linkcheck  to check all external links for integrity"

	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"

clean:

	-rm -rf $(BUILDDIR)/*

html:

	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html

	@echo

	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

dirhtml:

	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml

	@echo

	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."

singlehtml:

	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml

	@echo

	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."

pickle:

	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle

	@echo

	@echo "Build finished; now you can process the pickle files."

json:

	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json

	@echo

	@echo "Build finished; now you can process the JSON files."

htmlhelp:

	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp

	@echo

	@echo "Build finished; now you can run HTML Help Workshop with the" \

	      ".hhp project file in $(BUILDDIR)/htmlhelp."

qthelp:

	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp

	@echo

	@echo "Build finished; now you can run "qcollectiongenerator" with the" \

	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"

	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/Authentic2.qhcp"

	@echo "To view the help file:"

	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/Authentic2.qhc"

devhelp:

	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp

	@echo

	@echo "Build finished."

	@echo "To view the help file:"

	@echo "# mkdir -p $$HOME/.local/share/devhelp/Authentic2"

	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Authentic2"

	@echo "# devhelp"

epub:

	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub

	@echo

	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."

latex:

	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex

	@echo

	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."

	@echo "Run \`make' in that directory to run these through (pdf)latex" \

	      "(use \`make latexpdf' here to do that automatically)."

latexpdf:

	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex

	@echo "Running LaTeX files through pdflatex..."

	$(MAKE) -C $(BUILDDIR)/latex all-pdf

	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."

text:

	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text

	@echo

	@echo "Build finished. The text files are in $(BUILDDIR)/text."

man:

	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man

	@echo

	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."

texinfo:

	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo

	@echo

	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."

	@echo "Run \`make' in that directory to run these through makeinfo" \

	      "(use \`make info' here to do that automatically)."

info:

	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo

	@echo "Running Texinfo files through makeinfo..."

	make -C $(BUILDDIR)/texinfo info

	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."

gettext:

	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale

	@echo

	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."

changes:

	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes

	@echo

	@echo "The overview file is in $(BUILDDIR)/changes."

linkcheck:

	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck

	@echo

	@echo "Link check complete; look for any errors in the above output " \

	      "or in $(BUILDDIR)/linkcheck/output.txt."

doctest:

	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest

	@echo "Testing of doctests in the sources finished, look at the " \

	      "results in $(BUILDDIR)/doctest/output.txt."

.. _admin_access:

============================================

Access the grapical administration interface

============================================

The grapical administration interface is the 'Django admin' part of a Django

project. See for more information.

Just acces the admin url at http[s]://your.domain.com/admin.

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.

.. _administration_with_policies:

==================

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 'Default' and 'All':

* There is always a system default that does not correspond to the 'Default'

  policy. This is used to make Authentic 2 boot without initial

  configuration. When you add a 'Default' policy, the system default are not

  used anymore.

* A policy has always a name, 'Default' and 'All' are the names of two special

  policies with their name hardcoded. But you can create or delete them.

* If no other policy applies, the policy 'Default' applies.

* A policy can be created and attached to any related object. This policy is

  authoritative on the policy 'Default'.

* If the policy 'All' exists, it is authoritative on any other policy.

* The global policies 'All' and 'Default' are created by the administrator if

  necessary.

* A policy is taken in account only if it is enabled.

* When a regular policy is associated with an object, it is taken in account

  only if the option 'enable the following policy' is checked on the oject.

It is advised to add a 'Default' global policy when it is expected to apply a

policy to all related objects. A 'Default' global 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 'All' global policy should be used to enforce a global configuration for

all related objects or for testing purposes.

.. _advanced:

===============

Advanced topics

===============

- :ref:`attributes_in_session`

- :ref:`writing_migrations`

- :ref:`write_new_kind_policy`

.. _attributes_in_session:

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::

    request.session['multisource_attributes']

The keys of the dictionnary are the source names, i.e. 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 a same source in a same Django

session::

    request.session['multisource_attributes'] \

        [source_name] = list()

The items of this list are dictionnaries with the keys 'certificate_type' and

'attributes'.

For a saml2 assertion, all the keys are::

    a8n['certificate_type'] = 'SAML2_assertion'

    a8n['nameid'] = ...

    a8n['subject_confirmation_method'] = ...

    a8n['not_before'] = ...

    a8n['not_on_or_after'] = ...

    a8n['authn_context'] = ...

    a8n['authn_instant'] = ...

    a8n['attributes'] = attrs

a8n['attributes'] has the following structure::

    attributes = {}

    attributes[name] = (value1, value2, )

    attributes[(name, format)] = (value1, value2, )

    attributes[(name, format, nickname)] = (value1, value2, )

    a8n['attributes'] = attributes

.. _writing_migrations:

Writing migrations

==================

Migration containing reference to the user model must be rewritten manually to

refer to the user model name indirectly. The followind modifications must be applied.

1. First import the `user_model_label` from the `authentic2.compat` module:

::

    from authentic2.compat import user_model_label

Any reference to `orm['auth.User']` or `orm['authentic2.User']` must be

rewritten into `orm[user_model_label]`. For example this line:::

    ('user', self.gf('django.db.models.fields.related.ForeignKey')(to=orm['authentic2.User'])),

must be changed to:::

    ('user', self.gf('django.db.models.fields.related.ForeignKey')(to=orm[user_model_label])),

2. The user model when appearing in the `models` field like this:

::

        'auth.user': {

            'meta': {'object_name': 'User',

must be rewritten like that:::

        user_model_label: {

            'Meta': {'object_name': user_model_label.split('.')[-1]},

3. If the user model is referred inside the `to` field of a foreign key

   declaration like this:

::

        'user': ('django.db.models.fields.related.ForeignKey', [], {'to': u"orm['auth.User']"})

   must be rewritten like that:::

        'user': ('django.db.models.fields.related.ForeignKey', [], {'to': u"orm['%s']" user_model_label})

.. _write_new_kind_policy:

Add a new kind of administration policy

=======================================

See how policies works :ref:`administration_with_policies`. Then, the bahavior

should look like::

    def get_sample_policy(any_object):

        # Look for a global policy 'All'

        try:

            return SamplePolicy.objects.get(name='All', enabled=True)

        except SamplePolicy.DoesNotExist:

            pass

        # Look for a regular policy

        if any_object.enable_following_sample_policy:

            if any_object.sample_policy:

                return any_object.sample_policy

        # Look for a global policy 'Default'

        try:

            return SamplePolicy.objects.get(name='Default', enabled=True)

        except SamplePolicy.DoesNotExist:

            pass

        return None

.. _attribute_management:

===================================

Attribute Management in Authentic 2

===================================

Summary

=======

Attribute management currently allows to configure attribute policies

associated with SAML2 service providers to define 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 if Authentic 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 received from third IdP are put in

the user session.

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 to service providers can be configured per

attribute or per service provider.

By default, the namespace and format of attributes in assertion is conformant

to the SAMLV2.0 X500/LDAP Attribute profile::

    <saml:Attribute

        xmlns:x500="urn:oasis:names:tc:SAML:2.0:profiles:attribute:X500"

        NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"

        Name="urn:oid:2.5.4.42" FriendlyName="givenName">

        <saml:AttributeValue xsi:type="xs:string"

            x500:Encoding="LDAP">Mikaël</saml:AttributeValue>

    </saml:Attribute>

But the http://schemas.xmlsoap.org/ws/2005/05/identity/claims from the ISI

profile can also be used, for instance::

    <saml:Attribute

        NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri"

        Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"

        FriendlyName="First Name">

        <saml:AttributeValue>Mikaël</saml:AttributeValue>

    </saml:Attribute>

Configuration

=============

Configure local sources of attributes

-------------------------------------

The source of attributes for authentic2 are of two kinds. The LDAP sources and

the user django profile.

Declare the Django profile source

_________________________________

Add an attribute source named USER_PROFILE with namespace 'Default'.

1. Go to http[s]://your.domain.com/admin/attribute_aggregator/attributesource/add/

2. Write 'USER_PROFILE' in name field

.. image:: pictures/user_profile_source.png

   :width: 800 px

   :align: center

3. Save

.. image:: pictures/user_profile_source_saved.png

   :width: 800 px

   :align: center

Add an LDAP Source

__________________

For LDAP sources, objects of type 'LDAPSource' must be created.

**Even if the authentication is based on LDAP authentification, thus that a

server is configured in settings.py, it is

necessary to create a corresponding 'LDAPSource' to use it as a source of

attribute.**

1. Go to http[s]://your.domain.com/admin/attribute_aggregator/ldapsource/add/

2. Fill form fields

Only the field Name, Server, User, Password, Base and Port are used for now.

**The namespace of LDAP source must be kept to 'Default', since the system

namespace is based on LDAP.**

.. image:: pictures/ldapsource.png

   :width: 800 px

   :align: center

3. Save

.. image:: pictures/ldapsource_saved.png

   :width: 800 px

   :align: center

Manage user distinguished names in LDAP directories

___________________________________________________

To find the user in a LDAP directory, authentic2 must know its distinguished

name (DN). If this LDAP has been used when the user has authenticated,

Authentic 2 learn the user 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 is necessary to manually

indicate to Authentic 2 what is the user DN in the directory. For this, a

user alias in source is created for the user:

1. Go to http[s]://your.domain.com/admin/attribute_aggregator/useraliasinsource/add/

2. Fill form fields

.. image:: pictures/alias_in_source.png

   :width: 800 px

   :align: center

3. Save

.. image:: pictures/alias_in_source_saved.png

   :width: 800 px

   :align: center

Configure attributes from local sources pushed to SAML2 service providers in SSO response

-----------------------------------------------------------------------------------------

Reminder:

- The default name format in SAML2 assertions is URI

- The default namespace called 'Default' is LDAP

In summary:

1. Create attribute items indicating an attribute name, a source, the name format expected and the namespace expected 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 attribute policy.

4. Associate the policy to a service provider.

Create attribute items

______________________

1. Go to http[s]://your.domain.com/admin/idp/attributeitem/add/

2. Fill form fields

.. image:: pictures/attribute_item.png

   :width: 800 px

   :align: center

3. Save

.. image:: pictures/attribute_item_saved.png

   :width: 800 px

   :align: center

Create a named list of attribute items

______________________________________

1. Go to http[s]://your.domain.com/admin/idp/attributelist/add/

2. Name the list and add items to list

.. image:: pictures/attribute_list.png

   :width: 800 px

   :align: center

3. Save

.. image:: pictures/attribute_list_saved.png

   :width: 800 px

   :align: center

Create or modify an attribute policy

____________________________________

You can create a global policy 'All' or 'Default'. For details, see :ref:`administration_with_policies`.

Or you can create a regular policy and associate it to a service provider.

1. Go to http[s]://your.domain.com/admin/idp/attributepolicy/add/

2. Add list to the policy

.. image:: pictures/policy_pull.png

   :width: 800 px

   :align: center

3. Save

.. image:: pictures/policy_pull_saved.png

   :width: 800 px

   :align: center

Associate the policy to a service provider

__________________________________________

1. Go to http[s]://your.domain.com/admin/saml/libertyprovider/1/

2. Associate the policy to the service provider and **enable it**

.. image:: pictures/sp_policy_pull.png

   :width: 800 px

   :align: center

3. Save

.. image:: pictures/sp_policy_pull_saved.png

   :width: 800 px

   :align: center

4. The display name of the policy has changed

.. image:: pictures/policy_pull_renamed.png

   :width: 800 px

   :align: center

Handle attributes provided by other Identity providers and pushed to SAML2 service providers in SSO response (proxy attributes)

-------------------------------------------------------------------------------------------------------------------------------

To have these kind of attributes to forward, authentic must be configured as a

SAML2 service provider, see the corresponding administration page

:ref:`config_saml2_idp`.

Forward all attributes in session without any modification

__________________________________________________________

Create or modify an attribute policy activating the option 'Forward attributes from push sources' and save.

**No other option below must be used.**

.. image:: pictures/attr_policy_forward.png

   :width: 800 px

   :align: center

**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]://your.domain.com/admin/attribute_aggregator/attributesource/add/

2. Set the name (No need to change the namespace)

.. image:: pictures/attr_source_idp.png

   :width: 800 px

   :align: center

3. Save

.. image:: pictures/attr_source_idp_saved.png

   :width: 800 px

   :align: center

Then create or modify an attribute policy activating the option **'Forward attributes from push sources'**.

You then select the source you want to forward attributes through the selection box and you save.

.. image:: pictures/attr_policy_filter_source.png

   :width: 800 px

   :align: center

**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 according to the source

____________________________________________________________________________________________________________________________

The system needs to 'recognise the attributes' to perform the mapping.

For this, you need to indicate the namespace of attributes received per source

if the namespace is not the one of Authentic 2 (X500/LDAP and extensions edu*

and supann).

In other words if the source provides attributes in a different namespace, you

need to create objects corresponding to the sources of attributes and indicate

there the right namespace. By default, the only other supported namespace is

http://schemas.xmlsoap.org/ws/2005/05/identity/claims.

.. image:: pictures/attr_source_idp_claims.png

   :width: 800 px

   :align: center

Then create or modify an attribute policy activating the options 'Forward attributes from push sources',

**'Map attributes from push sources'**. You also choose the output namespace expected with the

parameters **'Output name format'** and **'Output namespace'**.

.. image:: pictures/attr_policy_map_ns.png

   :width: 800 px

   :align: center

Remind that the default namespace is X500/LDAP + edu* + supann and the only other supported namespace is

http://schemas.xmlsoap.org/ws/2005/05/identity/claims.

**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 'recognise the attributes' to filter the attributes

according to a list of attributes.

For this, you need to indicate the namespace of attributes received per source

if the namespace is not the one of Authentic 2 (X500/LDAP and extensions edu*

and supann).

In other words if the source provides attributes in a different namespace, you

need to create objects corresponding to the sources of attributes and indicate

there the right namespace. By default, the only other supported namespace is

http://schemas.xmlsoap.org/ws/2005/05/identity/claims.

.. image:: pictures/attr_source_idp_claims.png

   :width: 800 px

   :align: center

You then create an attribute list as described in section *'Create a named list of attribute items'*.

Then create or modify an attribute policy activating the option **'Forward attributes from push sources'**.

You then associate the list of attributes.

.. image:: pictures/attr_policy_filter_attributes.png

   :width: 800 px

   :align: center

If you want to also filter according to the source you can configure it as defined in section *'Filter attributes from source only'*. You can also choose to filter

with the source indicate per attribute item of the list. For this select the option **'Filter source of filtered attributes'**.

.. image:: pictures/attr_policy_filter_attributes_source.png

   :width: 800 px

   :align: center

.. image:: pictures/attribute_item.png

   :width: 800 px

   :align: center

The default name format is URI. You can however change the name format and namespace with the option **'Map attributes from push sources'** and the parameters **'Output name format'** and **'Output namespace'**.

Using the option **'Map attributes of filtered attributes'** the output name format and namespace are the ones indicated per attribute item of the list.

.. image:: pictures/attr_policy_filter_attributes_map.png

   :width: 800 px

   :align: center

.. image:: pictures/attribute_item.png

   :width: 800 px

   :align: center

Push manually (writing bits of code) attributes to SAML2 service providers in SSO response

------------------------------------------------------------------------------------------

In idp/signals.py connect to the add_attributes_to_response signal::

    add_attributes_to_response.connect(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'] = attributes

    return dic

*format* must be in (lasso.SAML2_ATTRIBUTE_NAME_FORMAT_URI,

lasso.SAML2_ATTRIBUTE_NAME_FORMAT_BASIC)

You can use the attributes form the local source and the attributes in the

session that are pushed by other identity providers.

Attributes in the session are in::

    request.session['multisource_attributes']

See the page :ref:`attributes_in_session`.

If you want to use local source of attributes and use mapping capabilities

of the UserAttributeProfile see the page :ref:`attribute_management_explained`.

Use the file idp/attributes.py as an exemple.

Modifying supported namespaces and attribute name mappings

==========================================================

The mapping is defined in the file attribute_aggregator/mapping.py

The mapping can be modified with the variables ATTRIBUTE_NAMESPACES and

ATTRIBUTE_MAPPING that can be redefined using settings.

Add new namespaces in ATTRIBUTE_NAMESPACES.

To extend the default schema add key/value in ATTRIBUTE_MAPPING, for instance::

    "displayName": {

        "oid": "2.16.840.1.113730.3.1.241",

        "display_name": _("displayName"),

        "type": "http://www.w3.org/2001/XMLSchema#string",

        "syntax": "1.3.6.1.4.1.1466.115.121.1.15",

    },

Add mapping of attribute name extending attribute entries in ATTRIBUTE_MAPPING,

for instance::

    "sn": {

        "oid": "2.5.4.4",

        "display_name": _("sn surname"),

        "alias": ['surname'],

        "profile_field_name": 'last_name',

        "type": "http://www.w3.org/2001/XMLSchema#string",

        "namespaces": {

            "http://schemas.xmlsoap.org/ws/2005/05/identity/claims": {

                "identifiers":

                    [

                "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname",

                    ],

                "friendly_names":

                    [

                "Last Name",

                    ],

            }

        }

    },

.. _auth_ldap:

==============================================

Authentication with an existing LDAP directory

==============================================

Authentic use the module django_auth_ldap to synchronize the Django user tables

with an LDAP. For complex use case, we will refer you to the django_auth_ldap

documentation, see http://packages.python.org/django-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_settings.py file for authenticating against LDAP.

The next lines must be added::

    AUTHENTICATION_BACKENDS += ( 'django_auth_ldap.backend.LDAPBackend', )

    import ldap

    from django_auth_ldap.config import LDAPSearch

    # Here put the LDAP URL of your server

    AUTH_LDAP_SERVER_URI = 'ldap://ldap.example.com'

    # Let the bind DN and bind password blank for anonymous binding

    AUTH_LDAP_BIND_DN = ""

    AUTH_LDAP_BIND_PASSWORD = ""

    # Lookup user under the branch o=base and by mathcing their uid against the

    # received login name

    AUTH_LDAP_USER_SEARCH = LDAPSearch("o=base",

        ldap.SCOPE_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 configuration for two usual classes: groupOfNames and

   groupOfUniqueNames.

2. Find the relevant groupname. We will say it is: cn=admin,o=mycompany

3. Add the following lines::

    from django_auth_ldap.config import GroupOfNamesType

    AUTH_LDAP_GROUP_TYPE = GroupOfNamesType()

    AUTH_LDAP_GROUP_SEARCH = LDAPSearch("o=mycompany",

        ldap.SCOPE_SUBTREE, "(objectClass=groupOfNames)")

    AUTH_LDAP_USER_FLAGS_BY_GROUP = {

        "is_staff": "cn=admin,o=mycompany"

    }

For an objectClass of groupOfUniqueNames you would change the string

GroupOfNamesType to GroupOfUniqueNamesType and grouOfNames to

groupOfUniqueNames. For more complex cases see the django_auth_ldap

documentation.

.. _change_db:

===============================

Specifying a different database

===============================

This is done by modifying the DATABASES dictionary in your local_settings.py

file (create it in Authentic project directory); for example::

 DATABASES['default'] = {

   'ENGINE': 'django.db.backends.postgresql',

   'NAME': 'authentic',

   'USER': 'admindb',

   'PASSWORD': 'foobar',

   'HOST': 'db.example.com',

   'PORT': '', # empty string means default value

 }

You should refer to the Django documentation on databases settings at

http://docs.djangoproject.com/en/dev/ref/settings/#databases for all

the details.

# -*- coding: utf-8 -*-

#

# Authentic2 documentation build configuration file, created by

# sphinx-quickstart on Thu Oct 13 14:38:32 2011.

#

# This file is exec()d with the current directory set to its containing dir.

#

# Note that not all possible configuration values are present in this

# autogenerated file.

#

# All configuration values have a default; values that are commented out

# serve to show the default.

# If extensions (or modules to document with autodoc) are in another directory,

# add these directories to sys.path here. If the directory is relative to the

# documentation root, use os.path.abspath to make it absolute, like shown here.

# sys.path.insert(0, os.path.abspath('.'))

# -- General configuration -----------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.

# needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be extensions

# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.

extensions = [

    'sphinx.ext.autodoc',

    'sphinx.ext.doctest',

    'sphinx.ext.intersphinx',

    'sphinx.ext.todo',

    'sphinx.ext.coverage',

    'sphinx.ext.imgmath',

    'sphinx.ext.ifconfig',

    'sphinx.ext.viewcode',

]

# Add any paths that contain templates here, relative to this directory.

templates_path = ['_templates']

# The suffix of source filenames.

source_suffix = '.rst'

# The encoding of source files.

# source_encoding = 'utf-8-sig'

# The master toctree document.

master_doc = 'index'

# General information about the project.

project = 'Authentic 2'

copyright = '2012, 2011, 2010, Entr\'ouvert'

# The version info for the project you're documenting, acts as replacement for

# |version| and |release|, also used in various other places throughout the

# built documents.

#

# The short X.Y version.

version = '2'

# The full version, including alpha/beta/rc tags.

release = '2.0.2'

# The language for content autogenerated by Sphinx. Refer to documentation

# for a list of supported languages.

# language = None

# There are two options for replacing |today|: either, you set today to some

# non-false value, then it is used:

# today = ''

# Else, today_fmt is used as the format for a strftime call.

# today_fmt = '%B %d, %Y'

# List of patterns, relative to source directory, that match files and

# directories to ignore when looking for source files.

exclude_patterns = ['_build']

# The reST default role (used for this markup: `text`) to use for all documents.

# default_role = None

# If true, '()' will be appended to :func: etc. cross-reference text.

# add_function_parentheses = True

# If true, the current module name will be prepended to all description

# unit titles (such as .. function::).

# add_module_names = True

# If true, sectionauthor and moduleauthor directives will be shown in the

# output. They are ignored by default.

# show_authors = False

# The name of the Pygments (syntax highlighting) style to use.

pygments_style = 'sphinx'

# A list of ignored prefixes for module index sorting.

# modindex_common_prefix = []

# -- Options for HTML output ---------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for

# a list of builtin themes.

html_theme = 'default'

# Theme options are theme-specific and customize the look and feel of a theme

# further.  For a list of options available for each theme, see the

# documentation.

# html_theme_options = {}

# Add any paths that contain custom themes here, relative to this directory.

# html_theme_path = []

# The name for this set of Sphinx documents.  If None, it defaults to

# "<project> v<release> documentation".

# html_title = None

# A shorter title for the navigation bar.  Default is the same as html_title.

# html_short_title = None

# The name of an image file (relative to this directory) to place at the top

# of the sidebar.

html_logo = 'pictures/eo_logo_t.png'

# The name of an image file (within the static path) to use as favicon of the

# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32

# pixels large.

# html_favicon = None

# Add any paths that contain custom static files (such as style sheets) here,

# relative to this directory. They are copied after the builtin static files,

# so a file named "default.css" will overwrite the builtin "default.css".

html_static_path = ['_static']

# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,

# using the given strftime format.

# html_last_updated_fmt = '%b %d, %Y'

# If true, SmartyPants will be used to convert quotes and dashes to

# typographically correct entities.

# html_use_smartypants = True

# Custom sidebar templates, maps document names to template names.

# html_sidebars = {}

# Additional templates that should be rendered to pages, maps page names to

# template names.

# html_additional_pages = {}

# If false, no module index is generated.

# html_domain_indices = True

# If false, no index is generated.

# html_use_index = True

# If true, the index is split into individual pages for each letter.

# html_split_index = False

# If true, links to the reST sources are added to the pages.

# html_show_sourcelink = True

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.

# html_show_sphinx = True

# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.

# html_show_copyright = True

# If true, an OpenSearch description file will be output, and all pages will

# contain a <link> tag referring to it.  The value of this option must be the

# base URL from which the finished HTML is served.

# html_use_opensearch = ''

# This is the file name suffix for HTML files (e.g. ".xhtml").

# html_file_suffix = None

# Output file base name for HTML help builder.

htmlhelp_basename = 'Authentic2doc'

# -- Options for LaTeX output --------------------------------------------------

latex_elements = {

    # The paper size ('letterpaper' or 'a4paper').

    #'papersize': 'letterpaper',

    # The font size ('10pt', '11pt' or '12pt').

    #'pointsize': '10pt',

    # Additional stuff for the LaTeX preamble.

    #'preamble': '',

}

# Grouping the document tree into LaTeX files. List of tuples

# (source start file, target name, title, author, documentclass [howto/manual]).

latex_documents = [

    ('index', 'Authentic2.tex', 'Authentic2 Documentation', 'Entr\'ouvert', 'manual'),

]

# The name of an image file (relative to this directory) to place at the top of

# the title page.

latex_logo = 'pictures/eo_logo.png'

# For "manual" documents, if this is true, then toplevel headings are parts,

# not chapters.

# latex_use_parts = False

# If true, show page references after internal links.

# latex_show_pagerefs = False

# If true, show URL addresses after external links.

# latex_show_urls = False

# Documents to append as an appendix to all manuals.

# latex_appendices = []

# If false, no module index is generated.

# latex_domain_indices = True

# -- Options for manual page output --------------------------------------------

# One entry per manual page. List of tuples

# (source start file, name, description, authors, manual section).

man_pages = [('index', 'authentic2', 'Authentic2 Documentation', [u'Mikaël Ates'], 1)]

# If true, show URL addresses after external links.

# man_show_urls = False

# -- Options for Texinfo output ------------------------------------------------

# Grouping the document tree into Texinfo files. List of tuples

# (source start file, target name, title, author,

#  dir menu entry, description, category)

texinfo_documents = [

    (

        'index',

        'Authentic2',

        'Authentic2 Documentation',

        'Mikaël Ates',

        'Authentic2',

        'One line description of project.',

        'Miscellaneous',

    ),

]

# Documents to append as an appendix to all manuals.

# texinfo_appendices = []

# If false, no module index is generated.

# texinfo_domain_indices = True

# How to display URL addresses: 'footnote', 'no', or 'inline'.

# texinfo_show_urls = 'footnote'

# Example configuration for intersphinx: refer to the Python standard library.

intersphinx_mapping = {'http://docs.python.org/': None}

.. _config_cas_sp:

=====================================

Configure Authentic 2 as a CAS server

=====================================

How to use Authentic 2 as a CAS 1.0 or CAS 2.0 identity provider ?

------------------------------------------------------------------

1. Activate CAS IdP support in settings.py::

     IDP_CAS = True

2. Then create the database table to hold CAS service tickets::

    python authentic2/manage.py syncdb --migrate

3. Also configure authentic2 to authenticate against your LDAP directory (see

   above) if your want your user attributes to be accessible from your service,

   if it is not necessary you can use the normal relational database storage

   for you users.

4. Finally configure your service to point to the CAS endpoint at:

    http[s]://your.domain.com/idp/cas/

5. If needed configure your service to resolve authenticated user with your

   LDAP directory (if user attributes are needed for your service)

.. _config_saml2_idp:

==================================================================

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 difference comes 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 service provider metadata of Authentic 2.

Go to http[s]://your.domain.com/authsaml2/metadata

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. Then, you configure it.

If your identity provider is Authentic 2, the metadata are available at:

    http[s]://your.domain.com/idp/saml2/metadata

See :ref:`where_metadata` for more information.

Create a SAML2 identity provider entry

--------------------------------------

You first need to create a new SAML2 identity provider entry. This requires

the SAML2 metadata of the identity provider.

1. Go to

    http[s]://your.domain.com/admin/saml/libertyprovider/add/

2. Fill the form fields

.. image:: pictures/new_saml2_idp_1.png

   :width: 800 px

   :align: center

.. image:: pictures/new_saml2_idp_2.png

   :width: 800 px

   :align: center

**The identity provider must be enabled.**

See below about configuring the identity provider with policies:

* options of the identity provider

3. Save

.. image:: pictures/new_saml2_idp_saved.png

   :width: 800 px

   :align: center

Apply a SAML2 identity provider options policy

----------------------------------------------

The SAML2 options of the identity provider are configured using idp options

policies. For the explanation of the options see the following section.

See the *administration with policy principle* page :ref:`administration_with_policies`.

You may create a regular policy and configure your service provider to use it.

Go to:

    http[s]://your.domain.com/admin/saml/idpoptionssppolicy/add/

Configure your policy and save:

.. image:: pictures/idp_options_regular.png

   :width: 800 px

   :align: center

.. image:: pictures/idp_options_regular_saved.png

   :width: 800 px

   :align: center

Apply the policy to the identity provider:

.. image:: pictures/idp_options_regular_modify_sp.png

   :width: 800 px

   :align: center

Example with a policy 'Default':

.. image:: pictures/idp_options_default.png

   :width: 800 px

   :align: center

Example with a policy 'All':

.. image:: pictures/idp_options_all.png

   :width: 800 px

   :align: center

If no policy is found for the configuration of the SAML2 options of an identity

provider, the following error is displayed to the users when a SSO request is

initiated.

.. image:: pictures/error_no_idp_options.png

   :width: 800 px

   :align: center

SAML2 identity provider options explained

-----------------------------------------

Behavior with persistent nameID

_______________________________

This option applies when an assertion with a persistent nameID is received and

the nameID is not recognized as an existing federation.

Two values are possible: "Create new account" and "Account linking by authentication".

The value "Create new account" makes Authentic 2 create a user account associated

to the nameID received.

The value "Account linking by authentication" makes Authentic 2 ask the user to

authenticate with an existing account to associate the nameID to this account.

Behavior with transient nameID

_______________________________

This option applies when an assertion with a transient nameID is received and

there isn't a session opened for the user yet.

Two values are possible: "Open a session" and "Ask authentication".

The value "Open a session" makes Authentic 2 open a session.

The value "Ask authentication" makes Authentic 2 ask for a user authentication,

even when a valid assertion is received. That may have sense for instance if

the SSO login is used only to receive signed attributes for users with existing

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 metadata are hosted.

To refresh them, select the provider on the list of provider, then select in

the menu 'Update metadata', then click on 'Go'.

.. image:: pictures/update_metadata.png

   :width: 800 px

   :align: center

.. image:: pictures/update_metadata_done.png

   :width: 800 px

   :align: center

How to create in bulk identity providers with the sync-metadata script?

=======================================================================

See the page explaining the use of the script sync-metadata :ref:`sync-metadata_script`.

.. _config_saml2_sp:

====================================

Configure SAML 2.0 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 identity provider metadata of Authentic 2.

Go to http[s]://your.domain.com/idp/saml2/metadata

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 service provider.

If your service provider is Authentic 2, the metadata are available at:

    http[s]://your.domain.com/authsaml2/metadata

See :ref:`where_metadata` for more information.

Create a SAML2 service provider entry

-------------------------------------

1. Go to

    http[s]://your.domain.com/admin/saml/libertyprovider/add/

2. Fill the form fields

.. image:: pictures/new_saml2_sp_1.png

   :width: 800 px

   :align: center

.. image:: pictures/new_saml2_sp_2.png

   :width: 800 px

   :align: center

**Note:** The service provider must be enabled.

See below about configuring the service provider with policies:

* options of the service provider

* protocol policy

* attribute policy

3. Save

.. image:: pictures/new_saml2_sp_saved.png

   :width: 800 px

   :align: center

Apply a SAML2 service provider options policy

---------------------------------------------

The SAML2 options of the service provider are configured using sp options

policies.

See the *administration with policy principle* page :ref:`administration_with_policies`.

You may create a regular policy and configure your service provider to use it.

Go to:

    http[s]://your.domain.com/admin/saml/spoptionsidppolicy/add/

Configure your policy and save:

.. image:: pictures/sp_options_regular.png

   :width: 800 px

   :align: center

.. image:: pictures/sp_options_regular_saved.png

   :width: 800 px

   :align: center

Apply the policy to the service provider:

.. image:: pictures/sp_options_regular_modify_sp.png

   :width: 800 px

   :align: center

Example with a policy 'Default':

.. image:: pictures/sp_options_default.png

   :width: 800 px

   :align: center

Example with a policy 'All':

.. image:: pictures/sp_options_all.png

   :width: 800 px

   :align: center

If no policy is found for the configuration of the SAML2 options of a service

provider, the following error is displayed to the users when a SSO request is

received.

.. image:: pictures/error_no_sp_options.png

   :width: 800 px

   :align: center

Configure the SAML2 service provider protocol options

-----------------------------------------------------

This kind of policy does not use the policy management using global policies.

You should use the default option except if your service provider is a

Shibboleth service provider, then you should use the option "Shibboleth SP

(AuthnRequest Signature: Does not check signatures)".

Configure the attribute policy of the service provider

------------------------------------------------------

See the attribute management page :ref:`attribute_management`.

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 metadata are hosted.

To refresh them, select the provider on the list of provider, then select in

the menu 'Update metadata', then click on 'Go'.

.. image:: pictures/update_metadata.png

   :width: 800 px

   :align: center

How to create in bulk service providers with the sync-metadata script?

======================================================================

See the page explaining the use of the script sync-metadata :ref:`sync-metadata_script`.

.. _configuration:

=============

Configuration

=============

Configuration with settings

===========================

.. toctree::

    :maxdepth: 1

    settings

    settings_listing

Configuration with the administration interface

===============================================

Basics

------

.. toctree::

    :maxdepth: 1

    admin_access

    administration_with_policies

Authentication backends

-----------------------

.. toctree::

    :maxdepth: 1

    auth_ldap

SAML2

-----

.. toctree::

    :maxdepth: 1

    where_metadata

    config_saml2_sp

    config_saml2_idp

    saml2_slo

CAS

---

.. toctree::

    :maxdepth: 1

    config_cas_sp

Attributes

----------

.. toctree::

    :maxdepth: 1

    attribute_management

User interfaces and interactions

--------------------------------

.. toctree::

    :maxdepth: 1

    consent_management

Administration

==============

.. toctree::

    :maxdepth: 1

    translation

    cronjobs

    sync-metadata_script

.. _consent_management:

=================================

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 its local 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. This signed identifier allows to

the service provider to login the user without reauthentication during the

following single sign on process.

How the consent is collected is determined by the identity provider. The

service provider receives in the authnRequest the consent attribute

indicating how the user consent was managed.