diff --git a/doc/admin_access.rst b/doc/admin_access.rst new file mode 100644 index 000000000..8fcdb1ff6 --- /dev/null +++ b/doc/admin_access.rst @@ -0,0 +1,16 @@ +.. _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. diff --git a/doc/administration_with_policies.rst b/doc/administration_with_policies.rst index e5b732386..e0080324e 100644 --- a/doc/administration_with_policies.rst +++ b/doc/administration_with_policies.rst @@ -1,8 +1,8 @@ .. _administration_with_policies: -========================================================== -How global policies are used in Authentic 2 administration -========================================================== +================== +Work with policies +================== The policy management with global policies is nearly used for any kind of policy in Authentic 2. @@ -10,43 +10,28 @@ policy in Authentic 2. For each kind of these policies, the system takes in account two special global policies named 'Default' and 'All': - * If no other policy applies, the policy 'Default' will apply. +* 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. - * A policy can be created and attached to any related object. This policy is authoritative on policy 'Default'. +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. - * If the policy 'All' exists, it is authoritative on any other policy. +Add a regular policy to some objects are used to handle particular +configurations for a subset of related objects. - * The global policies must be 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.** - -:: - - 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 - -*It is advised to add a 'Default' global policy when it is expected to apply a -policy to all related objects. Add e regular policy to some objects are then -used to handle particular configurations.* - -*A 'Default' global policy should be defined to avoid misonfiguration.* - -*A 'All' global policy should be used to enforce a global configuration for -all related objects or for testing purposes.* +An 'All' global policy should be used to enforce a global configuration for +all related objects or for testing purposes. diff --git a/doc/advanced.rst b/doc/advanced.rst new file mode 100644 index 000000000..75c740091 --- /dev/null +++ b/doc/advanced.rst @@ -0,0 +1,125 @@ +.. _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: + +:: + + u'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 diff --git a/doc/config_saml2_sp.rst b/doc/config_saml2_sp.rst index 7abed2cbc..ee8729d3a 100644 --- a/doc/config_saml2_sp.rst +++ b/doc/config_saml2_sp.rst @@ -36,11 +36,13 @@ Create a SAML2 service provider entry .. image:: pictures/new_saml2_sp_1.png :width: 800 px + :align: center .. image:: pictures/new_saml2_sp_2.png :width: 800 px + :align: center -**The service provider must be enabled.** +**Note:** The service provider must be enabled. See below about configuring the service provider with policies: diff --git a/doc/configuration.rst b/doc/configuration.rst new file mode 100644 index 000000000..91d162718 --- /dev/null +++ b/doc/configuration.rst @@ -0,0 +1,88 @@ +.. _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 + + auth_pam + +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 diff --git a/doc/copyright.rst b/doc/copyright.rst new file mode 100644 index 000000000..507ac623a --- /dev/null +++ b/doc/copyright.rst @@ -0,0 +1,18 @@ +.. _copyright: + +========= +Copyright +========= + +Authentic and Authentic 2 are copyrighted by Entr'ouvert and are licensed +through the GNU AFFERO GENERAL PUBLIC 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 Apache 2.0 licence. This imply that you must +distribute authentic2 under the AGPL3 licence when distributing this part of the +project which is the only AGPL licence version compatible with the Apache 2.0 +licence. + +The Documentation is under the licence Creative Commons +`CC BY-SA 2.0 `_. diff --git a/doc/cronjobs.rst b/doc/cronjobs.rst new file mode 100644 index 000000000..534ce15b4 --- /dev/null +++ b/doc/cronjobs.rst @@ -0,0 +1,11 @@ +.. _cronjobs: + + +Cronjobs and cleaning +===================== + +The following cronjob must be run to clean deleted accounts and temporary objects:: + + 5 0 * * * athentic2-ctl cleanup + +It's made to run every day at 00:05. diff --git a/doc/deployment.rst b/doc/deployment.rst new file mode 100644 index 000000000..ffcfe12af --- /dev/null +++ b/doc/deployment.rst @@ -0,0 +1,60 @@ +.. _deployment: + +================================================== +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 2's users will begin with Authentic 2 using +the Django development server (runserver command) and we want to avoid them +a bad first impression because static files would not be served. As a matter +of fact, static files are served by the Django development 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 should also be used to serve the static +files. + +Set Authentic into the no DEBUG Mode +------------------------------------ + +It is enough to edit authentic2/settings.py 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 in the 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 that is configured in the +settings.py. + +By default, running collectstatic will create a static directory in the parent +directory of the authentic2 directory:: + + $python authentic2/manage.py 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 https://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/ for more +information about collectstatic. diff --git a/doc/index.rst b/doc/index.rst index 4cba58383..d9786bf2a 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -7,83 +7,38 @@ Authentic 2's documentation =========================== -Authentic 2 is a versatile identity provider addressing a broad -range of needs, from simple to advanced setups, around web authentication, -attribute sharing and namespace mapping. +Authentic 2 is a versatile identity management server aiming to address a +broad range of needs, from simple to complex setups; it has support for many +protocols and can bridge between them. Authentic 2 supports many protocols and standards, including SAML2, CAS, OpenID, -LDAP, X509, OATH, and can bridge between them. +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 OASIS -specifications of SAML2, ID-FF1.2 and ID-WSF2. +specifications of SAML2. -The Documentation is under the licence Creative Commons `CC BY-SA 2.0 `_. +Consult current Authentic 2 activity on the `project site `_ -- `Authentic 2 project site `_ -- `Authentic 2 roadmap `_ - -Documentation content -===================== +If you don't find an explanation, you don't understand it or one is missing, +please report it on the list. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 - features + overview - installation + installation - production + configuration - upgrading + advanced - change_db + copyright - settings - - auth_ldap - - auth_pam - - administration_with_policies - - where_metadata - - config_saml2_sp - - config_saml2_idp - - saml2_slo - - sync-metadata_script - - config_cas_sp - - attribute_management - - attribute_management_explained - - attributes_in_session - - consent_management - -Copyright -========= - -Authentic and Authentic 2 are copyrighted by Entr'ouvert and are licensed -through the GNU AFFERO GENERAL PUBLIC 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 Apache 2.0 licence. This imply that you must -distribute authentic2 under the AGPL3 licence when distributing this part of the -project which is the only AGPL licence version compatible with the Apache 2.0 -licence. - -The Documentation is under the licence Creative Commons -`CC BY-SA 2.0 `_. +This documentation is under the licence Creative Commons `CC BY-SA 2.0 `_. .. Indices and tables .. ================== diff --git a/doc/installation.rst b/doc/installation.rst index 9dcd20132..d13e23a06 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -1,261 +1,54 @@ .. _installation: -============ -Installation -============ +===================================== +Installation and quickstart tutorials +===================================== -Authentic 2 installation script handles all the dependencies, except Lasso, -relying on the Setuptools and the pypi repository. +You'll find here how to start and configure very quickly Authentic 2 for its +main features. You just need Python 2.7 and Django 1.5. -To run Authentic 2 you need to install Lasso >=2.3.6. You can obtain Lasso -from: +First of all, you can boot Authentic vwithout root +privileges like this: -- From sources: http://lasso.entrouvert.org/download -- Debian based distribution: http://deb.entrouvert.org/ +1. Initialize a virtualenv:: -The other Authentic 2 dependencies are: + virtualenv authentic + source ./authentic/bin/activate + cd authentic -- django >= 1.3 -- django-profiles >= 0.2 -- south >= 0.7.3 -- django-authopenid >= 0.9.6 -- django-debug-toolbar >= 0.9.0 +2. Install Authentic:: -Their management depends on how you install Authentic 2: + pip install authentic2 -- You can :ref:`install-pypi-ref` -- You can :ref:`obtain-pypi-ref` -- You can :ref:`obtain-git-ref` +3. Initialize the database migrations:: -Lasso installation mock-up --------------------------- + authentic2-ctl syncdb --migrate -Please see the Lasso website for installation details. This is a quick -installation example. +4. Run the HTTP test server:: -Install the following Lasso dependencies: + authentic2-ctl runserver -- autoconf -- automake -- autotools-dev -- libtool -- gtk-doc-tools -- zlib1g-dev -- libglib2.0-dev -- openssl-dev -- libxml2-dev -- libxmlsec1-dev -- python2.6-dev -- python-setuptools +Quickstart guides and installation guidelines +--------------------------------------------- -Obtain Lasso:: +.. toctree:: + :maxdepth: 1 - $wget https://dev.entrouvert.org/lasso/lasso-2.3.6.tar.gz - $tar xzvf lasso-2.3.6.tar.gz - $cd lasso-2.3.6 - $./autogen.sh -Be sure that the Python bindings is selected as follows:: + installation_modes + change_db + upgrading + deployment - ============= - Configuration - ============= +Quickstarts +___________ - Main - ---- +.. toctree:: + :maxdepth: 1 - Compiler: gcc - CFLAGS: - Install prefix: /usr/local - Debugging: no - Experimental ID-WSF: no - - Optionals builds - ---------------- - - Available languages: java(4.6.1) python(2.7) perl(5.12.4) - - Java binding: yes - Perl binding: yes - PHP 5 binding: no - Python binding: yes - - C API references: yes - Tests 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, e.g.:: - - $export PYTHONPATH="$PYTHONPATH:/usr/local/lib/python2.6/site-packages" - -Test trying to import Lasso:: - - $python - >>> import lasso - -.. _install-pypi-ref: - -Install Authentic directly from pypi ------------------------------------- - -Using pip:: - - pip install authentic2 - -or easy_install:: - - easy_install authentic2 - -You can now run Authentic from the installation directory, e.g.:: - - python /usr/local/lib/python2.6/site-packages/authentic2-x.y.z-py2.6.egg/authentic2/manage.py syncdb --migrate - python /usr/local/lib/python2.6/site-packages/authentic2-x.y.z-py2.6.egg/authentic2/manage.py runserver - -You should see the following output:: - - Validating models... - 0 errors found - - Django version 1.4, using settings 'authentic.settings' - Development server is running at http://127.0.0.1:8000/ - Quit the server with CONTROL-C. - - You can access the running application on http://127.0.0.1:8000/ - -.. _obtain-pypi-ref: - -Obtain the last package archive from pypi ------------------------------------------ - -Download the archive on http://pypi.python.org/pypi/authentic2/. - -Then, you can install it directly from the archive using pip:: - - pip install authentic2-x.z.y.tar.gz - -or easy_install:: - - easy_install authentic2-x.z.y.tar.gz - -You can now run Authentic from the installation directory, e.g.:: - - python /usr/local/lib/python2.6/site-packages/authentic2-x.y.z-py2.6.egg/authentic2/manage.py syncdb --migrate - python /usr/local/lib/python2.6/site-packages/authentic2-x.y.z-py2.6.egg/authentic2/manage.py runserver - -You should see the following output:: - - Validating models... - 0 errors found - - Django version 1.4, using settings 'authentic.settings' - Development server is running at http://127.0.0.1:8000/ - Quit the server with CONTROL-C. - - You can access the running application on http://127.0.0.1:8000/ - -You may not want to install the authentic2 package or you may want to manage the dependencies -_____________________________________________________________________________________________ - -Then, extract the archive:: - - tar xzvf authentic2-x.z.y.tar.gz - cd authentic2-x.z.y - -You can now install the dependencies by hands or use pypi to install them as -follows, either:: - - pip install django django-profiles south django-authopenid django-debug-toolbar - -or using the dependencies version requirements:: - - python setup.py egg_info - pip install -r authentic2.egg-info/requires.txt - -Then run Authentic from the extracted directory:: - - python authentic2/manage.py syncdb --migrate - python authentic2/manage.py runserver - -You should see the following output:: - - Validating models... - 0 errors found - - Django version 1.4, using settings 'authentic.settings' - Development server is running at http://127.0.0.1:8000/ - Quit the server with CONTROL-C. - - You can access the running application on http://127.0.0.1:8000/ - -.. _obtain-git-ref: - -Obtain the last sources from the Git repository ------------------------------------------------ - -Clone the repository:: - - git clone http://repos.entrouvert.org/authentic.git - -Then, you can install it directly using pip:: - - pip install ./authentic - -or easy_install:: - - easy_install ./authentic - -You can now run Authentic from the installation directory, e.g.:: - - python /usr/local/lib/python2.6/site-packages/authentic2-x.y.z-py2.6.egg/authentic2/manage.py syncdb --migrate - python /usr/local/lib/python2.6/site-packages/authentic2-x.y.z-py2.6.egg/authentic2/manage.py runserver - -You should see the following output:: - - Validating models... - 0 errors found - - Django version 1.4, using settings 'authentic.settings' - Development server is running at http://127.0.0.1:8000/ - Quit the server with CONTROL-C. - - You can access the running application on http://127.0.0.1:8000/ - -You may not want to install the authentic2 package or you may want to manage the dependencies -_____________________________________________________________________________________________ - -Then, extract the archive:: - - cd authentic - -You can now install the dependencies by hands or use pypi to install them as -follows, either:: - - pip install django django-profiles south django-authopenid django-debug-toolbar - -or using the dependencies version requirements:: - - python setup.py egg_info - pip install -r authentic2.egg-info/requires.txt - -Then run Authentic:: - - python authentic2/manage.py syncdb --migrate - python authentic2/manage.py runserver - -You should see the following output:: - - Validating models... - 0 errors found - - Django version 1.4, using settings 'authentic.settings' - Development server is running at http://127.0.0.1:8000/ - Quit the server with CONTROL-C. - - You can access the running application on http://127.0.0.1:8000/ + quick_oauth2_idp + quick_saml2_idp + quick_saml2_sp + quick_cas_idp + quick_ldap_backend + quick_pam diff --git a/doc/installation_modes.rst b/doc/installation_modes.rst new file mode 100644 index 000000000..d19d457d2 --- /dev/null +++ b/doc/installation_modes.rst @@ -0,0 +1,205 @@ +.. _installation_modes: + +================== +Installation modes +================== + +The current version of Authentic 2 works with Python 2.7 and Django 1.5. + +Authentic 2 python installation script handles all the dependencies, +except Lasso, relying on the Setuptools and the pypi repository. + +To run Authentic 2 with SAML2 features, you need to install lasso >= 2.3.6, +see :ref:`install-lasso-ref`. + +The other Authentic 2 dependencies are: + +- Django<1.6 +- south>=0.8.4 +- requests +- django-model-utils +- django-registration>=1 +- django-debug-toolbar>=1.2,<1.3 +- --allow-external django-admin-tools +- --allow-unverified django-admin-tools +- django-admin-tools>=0.5.1 +- dnspython +- django-select2 +- django-tables2 +- gadjo +- django-import-export +- django-sekizai + +Install Authentic 2: + +- :ref:`install-pypi-ref` +- :ref:`obtain-pypi-ref` +- :ref:`obtain-git-ref` + +.. _install-lasso-ref: + +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 + +You'll find more updated packages on http://deb.entrouvert.org/. + +We also provide rpm packages for redhat, see https://dev.entrouvert.org/redhat/README. + +You can also install lasso from sources http://lasso.entrouvert.org/download + +See the `Lasso website `_ for installation details. +This is a quick installation example. + +Install the following Lasso dependencies: + +- autoconf +- automake +- autotools-dev +- libtool +- gtk-doc-tools +- zlib1g-dev +- libglib2.0-dev +- openssl-dev +- libxml2-dev +- libxmlsec1-dev +- python2.6-dev +- python-setuptools + +Obtain Lasso:: + + $wget https://dev.entrouvert.org/lasso/lasso-2.3.6.tar.gz + $tar xzvf lasso-2.3.6.tar.gz + $cd lasso-2.3.6 + $./autogen.sh + +Be sure that the Python bindings is selected as follows:: + + ============= + Configuration + ============= + + Main + ---- + + Compiler: gcc + CFLAGS: + Install prefix: /usr/local + Debugging: no + Experimental ID-WSF: no + + Optionals builds + ---------------- + + Available languages: java(4.6.1) python(2.7) perl(5.12.4) + + Java binding: yes + Perl binding: yes + PHP 5 binding: no + Python binding: yes + + C API references: yes + Tests 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, e.g.:: + + $export PYTHONPATH="$PYTHONPATH:/usr/local/lib/python2.6/site-packages" + +Test trying to import Lasso:: + + $python + >>> import lasso + +.. _install-pypi-ref: + +Install Authentic directly from pypi +------------------------------------ + +Using pip:: + + pip install authentic2 + +You can now run Authentic from the installation directory:: + + ./authentic2-ctl syncdb --migrate + ./authentic2-ctl runserver + +You should see the following output:: + + Validating models... + 0 errors found + + Django version 1.5, using settings 'authentic.settings' + Development server is running at http://127.0.0.1:8000/ + Quit the server with CONTROL-C. + + You can access the running application on http://127.0.0.1:8000/ + +.. _obtain-pypi-ref: + +Obtain the last package archive from pypi +----------------------------------------- + +Download the archive on http://pypi.python.org/pypi/authentic2/. + +Then, you can install it directly from the archive using pip:: + + pip install authentic2-x.z.y.tar.gz + +You can now run Authentic from the installation directory, e.g.:: + + ./authentic2-ctl syncdb --migrate + ./authentic2-ctl runserver + +You should see the following output:: + + Validating models... + 0 errors found + + Django version 1.5, using settings 'authentic.settings' + Development server is running at http://127.0.0.1:8000/ + Quit the server with CONTROL-C. + + You can access the running application on http://127.0.0.1:8000/ + +.. _obtain-git-ref: + +Obtain the last sources from the Git repository +----------------------------------------------- + +Clone the repository:: + + git clone http://repos.entrouvert.org/authentic.git + +Then, you can install it directly using pip:: + + cd authentic + pip install -e . + +You can now run Authentic from the installation directory, e.g.:: + + ./authentic2-ctl syncdb --migrate + ./authentic2-ctl runserver + +You should see the following output:: + + Validating models... + 0 errors found + + Django version 1.5, using settings 'authentic.settings' + Development server is running at http://127.0.0.1:8000/ + Quit the server with CONTROL-C. + + You can access the running application on http://127.0.0.1:8000/ diff --git a/doc/overview.rst b/doc/overview.rst new file mode 100644 index 000000000..e95e89402 --- /dev/null +++ b/doc/overview.rst @@ -0,0 +1,58 @@ +.. _overview: + +======== +Overview +======== + +Authentic 2 is a versatile identity management server aiming to address a +broad range of needs, from simple to complex setups; 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 OASIS +specifications of SAML2. + +Authentic 2 requires Python 2.7 et Django 1.5. + +Features +-------- + +* SAML 2.0 Identity and service provider +* OpenID 1.0 and 2.0 identity provider +* Server CAS 1.0 and 2.0 using a plugin +* Standards authentication mechanisms: + + * Login/password through internal directory or LDAP + * X509 certificate over SSL/TLS + +* Protocol proxying, for instance between OpenID and SAML +* Support of LDAP v2 and v3 directories +* Support of the PAM backend +* One-time password (OATH and Google-Authenticator) using a plugin +* Identity attribute management +* Plugin system + + +Source and issue tracker +------------------------ + +You can find on the project site authentic.entrouvert.org mainly the issue +tracker. + +You can find there a viewer of the git repository or clone it:: + + git clone http://repos.entrouvert.org/authentic.git + +Support +------- +Authentic's developpers and users hangs on the mailing list authentic@listes.entrouvert.com. +See archives or register at http://listes.entrouvert.com/info/authentic. + +You can open reports or feature request on http://authentic.entrouvert.org. + +Entr'ouvert also provides a commercial support. For information, visit http://www.entrouvert.com. diff --git a/doc/quick_cas_idp.rst b/doc/quick_cas_idp.rst new file mode 100644 index 000000000..d5b74b036 --- /dev/null +++ b/doc/quick_cas_idp.rst @@ -0,0 +1,23 @@ +.. _quick_cas_idp: + +================================== +Quickstart a CAS Identity Provider +================================== + +1. Activate CAS IdP support in your local_settings.py:: + + IDP_CAS = True + +2. Then create the database table to hold CAS service tickets:: + + authentic2-ctl syncdb --all + authentic2-ctl migrate --fake + +2. 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. + +3. Finally configure your service to point to the CAS endpoint at:: + + http[s]://your.domain.com/idp/cas/ diff --git a/doc/quick_ldap_backend.rst b/doc/quick_ldap_backend.rst new file mode 100644 index 000000000..a96b3fa2b --- /dev/null +++ b/doc/quick_ldap_backend.rst @@ -0,0 +1,61 @@ +.. _quick_ldap_backend: + +====================================== +Quickstart to connect a 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, for this you need + python-ldap, python-ldap needs python developement headers to be installed + but is usually packaged by most distributions:: + + 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. diff --git a/doc/quick_oauth2_idp.rst b/doc/quick_oauth2_idp.rst new file mode 100644 index 000000000..c93c41f19 --- /dev/null +++ b/doc/quick_oauth2_idp.rst @@ -0,0 +1,9 @@ +.. _quick_oauth2_idp: + +====================================== +Quickstart an OAuth2 Identity Provider +====================================== + +This section has to be done. If you need it now, say it on the issue tracker : + +https://dev.entrouvert.org/issues/6053 diff --git a/doc/quick_pam.rst b/doc/quick_pam.rst new file mode 100644 index 000000000..5352088f6 --- /dev/null +++ b/doc/quick_pam.rst @@ -0,0 +1,26 @@ +.. _quick_pam: + +================================= +Quickstart for PAM Authentication +================================= + +This module is copied from https://bitbucket.org/wnielson/django-pam/ by Weston +Nielson and the pam ctype module by Chris Atlee http://atlee.ca/software/pam/. + +Add 'authentic2.vendor.dpam.backends.PAMBackend' to your +``settings.py``:: + + AUTHENTICATION_BACKENDS = ( + ... + 'authentic2.vendor.dpam.backends.PAMBackend', + ... + ) + +Now you can login via the system-login credentials. If the user is +successfully authenticated but has never logged-in before, a new ``User`` +object is created. By default this new ``User`` has both ``is_staff`` and +``is_superuser`` set to ``False``. You can change this behavior by adding +``PAM_IS_STAFF=True`` and ``PAM_IS_SUPERUSER`` in your ``settings.py`` file. + +The default PAM service used is ``login`` but you can change it by setting the +``PAM_SERVICE`` variable in your ``settings.py`` file. diff --git a/doc/quick_saml2_idp.rst b/doc/quick_saml2_idp.rst new file mode 100644 index 000000000..63c709416 --- /dev/null +++ b/doc/quick_saml2_idp.rst @@ -0,0 +1,9 @@ +.. _quick_saml2_idp: + +===================================== +Quickstart an SAML2 Identity Provider +===================================== + +This section has to be done. If you need it now, say it on the issue tracker : + +https://dev.entrouvert.org/issues/6057 diff --git a/doc/quick_saml2_sp.rst b/doc/quick_saml2_sp.rst new file mode 100644 index 000000000..fbe47495f --- /dev/null +++ b/doc/quick_saml2_sp.rst @@ -0,0 +1,22 @@ +.. _quick_saml2_sp: + +===================================================== +Quickstart a connection with a SAML2 Service Provider +===================================================== + +1. Get the Identity Provider SAML2 metadata file + +:: + + http[s]://your.domain.com/idp/saml2/metadata + +2. Configure your service provider with it. + +3. Go to the providers admin panel on + +:: + + http[s]://admin/saml/libertyprovider/add/ + +There create a new provider using the service provider metadata and enable it +as a service provider. diff --git a/doc/settings.rst b/doc/settings.rst index b30522179..7a17d3a64 100644 --- a/doc/settings.rst +++ b/doc/settings.rst @@ -1,119 +1,9 @@ .. _settings: -================ -General settings -================ +=============================== +Works with authentic 2 settings +=============================== -How do I configure the general settings ? -========================================= +This section has to be done. If you need it now, say it on the issue tracker : -Edit the file settings.py in the project directory authentic2. - -A settings file is a Python module with module-level variables. So configure -general settings is done by modifying those variables and reloading your -application server. - -See the django documentation for more details about the settings files -management. - -Activate or deactivate debug mode -================================= - -Variable: DEBUG - -Values: - -* False: deactivate debug mode -* True: activate debug mode - -Manage session cookie duration -============================== - -Variable: SESSION_EXPIRE_AT_BROWSER_CLOSE - -Values: - -* False: Cookies are not removed when browser is closed. -* True: Cookies are removed when browser is closed. - -Variable: SESSION_COOKIE_AGE - -Value: - -* Seconds (36000 equal 10 hours) - -Time zone selection -=================== - -Variable: TIME_ZONE - -Values: - -* See http://en.wikipedia.org/wiki/List_of_tz_zones_by_name - -Activate or deactivate SSL authentication -========================================= - -Variable: AUTH_SSL - -Values: - -* False: deactivate SSL authentication -* True: activate SSL authentication - -Activate or deactivate OpenID authentication, Authentic 2 is an OpenID relying party -==================================================================================== - -Variable: AUTH_OPENID - -Values: - -* False: deactivate OpenID authentication -* True: activate OpenID authentication - -Activate or deactivate Authentic 2 as a SAML2 identity provider -=============================================================== - -Variable: IDP_SAML2 - -Values: - -* False: deactivate SAML2 identity provider -* True: activate SAML2 identity provider - -Configure SAML2 keys -==================== - -* SAML_SIGNATURE_PUBLIC_KEY: Certtificate or public key for signature -* SAML_SIGNATURE_PRIVATE_KEY: Private key for signature -* SAML_ENCRYPTION_PUBLIC_KEY: Certtificate or public key for encryption -* SAML_ENCRYPTION_PRIVATE_KEY: Private key for encryption - -Values are pem files of X509 certificate or key, e.g.: -SAML_SIGNATURE_PRIVATE_KEY = '''-----BEGIN RSA PRIVATE KEY----- -MII...WA== ------END RSA PRIVATE KEY-----''' - -If SAML_ENCRYPTION_PUBLIC_KEY or SAML_ENCRYPTION_PRIVATE_KEY are not given, -the signature keys are used for encryption. - - -Activate or deactivate Authentic 2 as an OpenID provider -======================================================== - -Variable: IDP_OPENID - -Values: - -* False: deactivate OpenID provider -* True: activate OpenID provider - -Activate or deactivate Authentic 2 as a CAS server -================================================== - -Variable: IDP_CAS - -Values: - -* False: deactivate CAS server -* True: activate CAS server +https://dev.entrouvert.org/issues/6047 diff --git a/doc/settings_listing.rst b/doc/settings_listing.rst new file mode 100644 index 000000000..1ad751944 --- /dev/null +++ b/doc/settings_listing.rst @@ -0,0 +1,107 @@ +.. _settings_listing: + +============ +All settings +============ + +Activate or deactivate debug mode +================================= + +Variable: DEBUG + +Values: + +* False: deactivate debug mode +* True: activate debug mode + +Manage session cookie duration +============================== + +Variable: SESSION_EXPIRE_AT_BROWSER_CLOSE + +Values: + +* False: Cookies are not removed when browser is closed. +* True: Cookies are removed when browser is closed. + +Variable: SESSION_COOKIE_AGE + +Value: + +* Seconds (36000 equal 10 hours) + +Time zone selection +=================== + +Variable: TIME_ZONE + +Values: + +* See http://en.wikipedia.org/wiki/List_of_tz_zones_by_name + +Activate or deactivate SSL authentication +========================================= + +Variable: AUTH_SSL + +Values: + +* False: deactivate SSL authentication +* True: activate SSL authentication + +Activate or deactivate OpenID authentication, Authentic 2 is an OpenID relying party +==================================================================================== + +Variable: AUTH_OPENID + +Values: + +* False: deactivate OpenID authentication +* True: activate OpenID authentication + +Activate or deactivate Authentic 2 as a SAML2 identity provider +=============================================================== + +Variable: IDP_SAML2 + +Values: + +* False: deactivate SAML2 identity provider +* True: activate SAML2 identity provider + +Configure SAML2 keys +==================== + +* SAML_SIGNATURE_PUBLIC_KEY: Certtificate or public key for signature +* SAML_SIGNATURE_PRIVATE_KEY: Private key for signature +* SAML_ENCRYPTION_PUBLIC_KEY: Certtificate or public key for encryption +* SAML_ENCRYPTION_PRIVATE_KEY: Private key for encryption + +Values are pem files of X509 certificate or key, e.g.: +SAML_SIGNATURE_PRIVATE_KEY = '''-----BEGIN RSA PRIVATE KEY----- +MII...WA== +-----END RSA PRIVATE KEY-----''' + +If SAML_ENCRYPTION_PUBLIC_KEY or SAML_ENCRYPTION_PRIVATE_KEY are not given, +the signature keys are used for encryption. + + +Activate or deactivate Authentic 2 as an OpenID provider +======================================================== + +Variable: IDP_OPENID + +Values: + +* False: deactivate OpenID provider +* True: activate OpenID provider + +Activate or deactivate Authentic 2 as a CAS server +================================================== + +Variable: IDP_CAS + +Values: + +* False: deactivate CAS server +* True: activate CAS server diff --git a/doc/translation.rst b/doc/translation.rst new file mode 100644 index 000000000..eae86578c --- /dev/null +++ b/doc/translation.rst @@ -0,0 +1,9 @@ +.. _translation: + + +Compiling translations +====================== + +Translations must compiled to be useful, to do that run the following command:: + + ./setup.py compile_translations diff --git a/doc/upgrading.rst b/doc/upgrading.rst index 1be444d5e..301553777 100644 --- a/doc/upgrading.rst +++ b/doc/upgrading.rst @@ -4,17 +4,14 @@ Upgrading ========= -How to upgrade to a new version of authentic ? ----------------------------------------------- +Update using pip:: -Authentic stores all its data in a relational database as specified in its + pip install -U authentic2 + +Authentic store all its data in a relational database as specified in its settings.py or local_settings.py file. So in order to upgrade to a new version of authentic you have to update your database schema using the -migration command — you will need to have installed the dependency -django-south, see the beginning of this README file.:: +migration command — you will need to have installed the dependency django-south, +see the beginning of this README file.:: - python ./manage.py migrate - -Then you will need to create new tables if there are.:: - - python ./manage.py syncdb + authentic2-ctl syncdb --migrate