summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorMikaël Ates <mates@entrouvert.com>2014-12-03 16:10:45 (GMT)
committerMikaël Ates <mates@entrouvert.com>2014-12-03 16:24:38 (GMT)
commite5ebc6621525ed4f8f08eb0feb0e7bfc2c544721 (patch)
tree865ccc149f43594d71f7afaebdc68371dd6ce33c /doc
parent19d8120b920e39ce4438cccc9f14a00d40fe8eb9 (diff)
downloadauthentic-e5ebc6621525ed4f8f08eb0feb0e7bfc2c544721.zip
authentic-e5ebc6621525ed4f8f08eb0feb0e7bfc2c544721.tar.gz
authentic-e5ebc6621525ed4f8f08eb0feb0e7bfc2c544721.tar.bz2
documentation: refactor documentation (refs #5455).
Diffstat (limited to 'doc')
-rw-r--r--doc/admin_access.rst16
-rw-r--r--doc/administration_with_policies.rst71
-rw-r--r--doc/advanced.rst125
-rw-r--r--doc/config_saml2_sp.rst4
-rw-r--r--doc/configuration.rst88
-rw-r--r--doc/copyright.rst18
-rw-r--r--doc/cronjobs.rst11
-rw-r--r--doc/deployment.rst60
-rw-r--r--doc/index.rst75
-rw-r--r--doc/installation.rst277
-rw-r--r--doc/installation_modes.rst205
-rw-r--r--doc/overview.rst58
-rw-r--r--doc/quick_cas_idp.rst23
-rw-r--r--doc/quick_ldap_backend.rst61
-rw-r--r--doc/quick_oauth2_idp.rst9
-rw-r--r--doc/quick_pam.rst26
-rw-r--r--doc/quick_saml2_idp.rst9
-rw-r--r--doc/quick_saml2_sp.rst22
-rw-r--r--doc/settings.rst120
-rw-r--r--doc/settings_listing.rst107
-rw-r--r--doc/translation.rst9
-rw-r--r--doc/upgrading.rst17
22 files changed, 940 insertions, 471 deletions
diff --git a/doc/admin_access.rst b/doc/admin_access.rst
new file mode 100644
index 0000000..8fcdb1f
--- /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 e5b7323..e008032 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.
-
- * A policy can be created and attached to any related object. This policy is authoritative on policy 'Default'.
-
- * If the policy 'All' exists, it is authoritative on any other policy.
-
- * 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.*
+* 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.
diff --git a/doc/advanced.rst b/doc/advanced.rst
new file mode 100644
index 0000000..75c7400
--- /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 7abed2c..ee8729d 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 0000000..91d1627
--- /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 0000000..507ac62
--- /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 <http://creativecommons.org/licenses/by-sa/2.0/>`_.
diff --git a/doc/cronjobs.rst b/doc/cronjobs.rst
new file mode 100644
index 0000000..534ce15
--- /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 0000000..ffcfe12
--- /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 4cba583..d9786bf 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 <http://lasso.entrouvert.org>`_,
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 <http://creativecommons.org/licenses/by-sa/2.0/>`_.
+Consult current Authentic 2 activity on the `project site <http://dev.entrouvert.org/projects/authentic>`_
-- `Authentic 2 project site <http://dev.entrouvert.org/projects/authentic>`_
-- `Authentic 2 roadmap <http://dev.entrouvert.org/projects/authentic/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
-
- features
-
- installation
-
- production
-
- upgrading
-
- change_db
-
- 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
+ :maxdepth: 1
- attributes_in_session
+ overview
- consent_management
+ installation
-Copyright
-=========
+ configuration
-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.
+ advanced
-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.
+ copyright
-The Documentation is under the licence Creative Commons
-`CC BY-SA 2.0 <http://creativecommons.org/licenses/by-sa/2.0/>`_.
+This documentation is under the licence Creative Commons `CC BY-SA 2.0 <http://creativecommons.org/licenses/by-sa/2.0/>`_.
.. Indices and tables
.. ==================
diff --git a/doc/installation.rst b/doc/installation.rst
index 9dcd201..d13e23a 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 0000000..d19d457
--- /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 <http://lasso.entrouvert.org>`_ 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 0000000..e95e894
--- /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 <http://lasso.entrouvert.org>`_,
+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 0000000..d5b74b0
--- /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 0000000..a96b3fa
--- /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 0000000..c93c41f
--- /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 0000000..5352088
--- /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 0000000..63c7094
--- /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 0000000..fbe4749
--- /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 b305221..7a17d3a 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 0000000..1ad7519
--- /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 0000000..eae8657
--- /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 1be444d..3015537 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.::
-
- python ./manage.py migrate
-
-Then you will need to create new tables if there are.::
+migration command — you will need to have installed the dependency django-south,
+see the beginning of this README file.::
- python ./manage.py syncdb
+ authentic2-ctl syncdb --migrate