[doc] New bits of documentation.

doc/administration_with_policies.rst

@@ -0,0 +1,46 @@
+.. _administration_with_policies:
+
+=========================================================
+How global policies are used in Authentic2 administration
+=========================================================
+
+The policy management with global policies is nearly used for any kind of
+policy in Authentic2.
+
+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.**
+
+::
+
+    def get_sample_policy(any_object):
+        try:
+            return SamplePolicy.objects.get(name='All', enabled=True)
+        except SamplePolicy.DoesNotExist:
+            pass
+        if any_object.enable_following_sample_policy:
+            if any_object.sample_policy:
+                return any_object.sample_policy
+        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.*

doc/attribute_management.rst

@@ -61,7 +61,17 @@ _________________________________
 
 Add an attribute source named USER_PROFILE with namespace 'Default'.
 
-Then, it is necessary that users create their profile.
+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
+
+3. Save
+
+.. image:: pictures/user_profile_source_saved.png
+   :width: 800 px
 
 Add an LDAP Source
 __________________

doc/config_saml2_idp.rst

@@ -4,9 +4,115 @@
 Configure Authentic2 as a SAML2 service provider or a SAML2 proxy
 =================================================================
 
-1. Create instance of SP settings
+**The configuration to make Authentic2 a SAML2 service provider or a SAML2
+proxy is the same. The difference comes from that Authentic2 is may be
+configured or not as a SAML2 identity provider.**
 
-2. Declare IdP
+How do I authenticate against a third SAML2 identity provider?
+==============================================================
 
-3. Get authsaml2 md
+1. Declare Authentic2 as a SAML2 service provider on your SAML2 identity provider using the SAML2 service provider metadata of Authentic2.
 
+Go to http[s]://your.domain.com/authsaml2/metadata
+
+2. Add and configure a SAML2 identity provider entry in Authentic2 using the metadata of the identity provider.
+
+How do I add and configure a SAML2 identity provider in Authentic2?
+===================================================================
+
+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 Authentic2, 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
+
+.. image:: pictures/new_saml2_idp_2.png
+   :width: 800 px
+
+**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
+
+Configure the SAML2 identity provider options
+---------------------------------------------
+
+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/idpoptionssppolicy/add/
+
+.. image:: pictures/sp_options_regular.png
+   :width: 800 px
+
+.. image:: pictures/sp_options_regular_saved.png
+   :width: 800 px
+
+.. image:: pictures/sp_options_regular_modify_sp.png
+   :width: 800 px
+
+Exemple with a policy 'Default':
+
+.. image:: pictures/sp_options_default.png
+   :width: 800 px
+
+Exemple with a policy 'All':
+
+.. image:: pictures/sp_options_all.png
+   :width: 800 px
+
+If no policy is found for the configuration of the SAML2 options of an identity
+provider, the following error is displayed when a SSO request is initiated.
+
+.. image:: pictures/error_no_idp_options.png
+   :width: 800 px
+
+How to refresh 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
+
+.. image:: pictures/update_metadata_done.png
+   :width: 800 px
+
+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`.

doc/config_saml2_sp.rst

@@ -4,20 +4,123 @@
 Configure SAML 2.0 service providers
 ====================================
 
-How to I authenticate against Authentic2 with a SAMLv2 service provider ?
--------------------------------------------------------------------------
+How do I authenticate against Authentic2 with a SAML2 service provider?
+=======================================================================
 
-1. Grab the SAML2 IdP metadata:
+1. Declare Authentic2 as a SAML2 identity provider on your SAML2 service provider using the SAML2 identity provider metadata of Authentic2.
 
-    http[s]://your.domain.com/idp/saml2/metadata
+Go to http[s]://your.domain.com/idp/saml2/metadata
 
-2. And configure your service provider with it.
+2. Add and configure a SAML2 service provider in Authentic2 using the metadata of the service provider.
 
-3. Go to the providers admin panel on:
+How do I add and configure a SAML2 service provider in Authentic2?
+==================================================================
+
+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 Authentic2, 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/
 
-There create a new provider using the service provider metadata and enable it
-as a service provider, you can customize some behaviours like the preferred
-assertion consumer or encryption for the NameID or the Assertion element.
+2. Fill the form fields
 
+.. image:: pictures/new_saml2_sp_1.png
+   :width: 800 px
+
+.. image:: pictures/new_saml2_sp_2.png
+   :width: 800 px
+
+**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
+
+Configure the SAML2 service provider options
+--------------------------------------------
+
+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/
+
+.. image:: pictures/sp_options_regular.png
+   :width: 800 px
+
+.. image:: pictures/sp_options_regular_modify_sp.png
+   :width: 800 px
+
+Exemple with a policy 'Default':
+
+.. image:: pictures/sp_options_default.png
+   :width: 800 px
+
+.. image:: pictures/sp_options_default_saved.png
+   :width: 800 px
+
+Exemple with a policy 'All':
+
+.. image:: pictures/sp_options_all.png
+   :width: 800 px
+
+If no policy is found for the configuration of the SAML2 options of a service
+provider, the following error is displayed when a SSO request is received.
+
+.. image:: pictures/error_no_sp_options.png
+   :width: 800 px
+
+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.
+
+Configure the attribute policy of the service provider
+------------------------------------------------------
+
+See the attribute management page :ref:`attribute_management`.
+
+How to refresh 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
+
+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`.

doc/index.rst

@@ -39,10 +39,16 @@ Documentation content
 
    auth_pam
 
+   administration_with_policies
+
+   where_metadata
+
    config_saml2_sp
 
    config_saml2_idp
 
+   sync-metadata_script
+
    config_cas_sp
 
    config_cas_idp
@@ -52,9 +58,8 @@ Documentation content
 Copyright
 =========
 
-Authentic is copyrighted by Entr'ouvert and is licensed through the GNU General
-Public Licence, version 2 or later. A copy of the whole license text is
-available in the COPYING file.
+Authentic and Authentic2 are copyrighted by Entr'ouvert and are licensed through the GNU General
+Public Licence, version 2 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
 Barczy¿ski, which is under the Apache 2.0 licence. This imply that you must
@@ -68,4 +73,3 @@ licence.
 .. * :ref:`genindex`
 .. * :ref:`modindex`
 .. * :ref:`search`
-

doc/sync-metadata_script.rst

@@ -0,0 +1,90 @@
+.. _sync-metadata_script:
+
+===========================================================================================================
+How to create/import and delete in bulk SAML2 identity and service providers with the sync-metadata script?
+===========================================================================================================
+
+This section explains hot to use the script sync-metadata.
+
+Presentation
+============
+
+This script allows to create/import and deleted in bulk SAML2 identity and
+service providers using standard SAML2 metadata files containing entity
+descriptors.
+
+An example of such a file used in production is the global metadata file of
+the identity federation of French universities that can be found at http://...
+
+Use the following command::
+
+    path_to_project/authentic2$ python manage.py sync-metadata file_name [options]
+
+Options
+=======
+
+* idp
+
+    Load only identity providers of the metadata file.
+
+* sp
+
+    Load only service providers of the metadata file.
+
+* source
+
+    Used to tag all imported providers with a label. This option is used to
+    metadata reloading and deletion in bulk.
+
+    Reloading a metadata file, when a provider with same entity is found, it is
+    updated. If a provider in the metadata file does not exist it is created.
+    If a provider exists in the system but not in the metadata file, it is
+    removed.
+
+    **For reloading, a source can only be associated with a unique metadata
+    file. This is due to the fact that all providers of a source not found in
+    the metadata file are removed.**
+
+::
+
+    path_to_project/authentic2$ python manage.py sync-metadata file_name --source=french_federation
+
+* sp-policy
+
+    To configure the SAML2 parameters of service providers imported with the
+    script, a policy of type SPOptionsIdPPolicy must be created in the
+    the administration interface.
+    Either it is a global policy 'Default' or 'All' or it is a regular policy.
+    If it is a regular policy, the policy name can be specified in parameter
+    of the script with this option.
+    The policy is then associated to all service providers created.
+
+::
+
+    path_to_project/authentic2$ python manage.py sync-metadata file_name --sp-policy=sp_policy_name
+
+* idp-policy
+
+    To configure the SAML2 parameters of identity providers imported with the
+    script, a policy of type IdPOptionsSPPolicy must be created in the
+    the administration interface.
+    Either it is a global policy 'Default' or 'All' or it is a regular policy.
+    If it is a regular policy, the policy name can be specified in parameter
+    of the script with this option.
+    The policy is then associated to all service providers created.
+
+::
+
+    path_to_project/authentic2$ python manage.py sync-metadata file_name --idp-policy=idp_policy_name
+
+* delete
+
+    With no options, all providers are deleted.
+
+    With the source option, only providers with the source name given are deleted.
+
+    **This option can not be combined with options idp and sp.**
+
+* ignore-errors
+
+    If loading of one EntityDescriptor fails, continue loading

doc/where_metadata.rst

@@ -0,0 +1,18 @@
+.. _where_metadata:
+
+==============================================
+Where do I find the Authentic2 SAML2 metadata?
+==============================================
+
+The SAML2 metadata are automatically generated.
+
+**Authentic2 will infer from environment variables the host and port to
+generate the URLs contained in the medatada.**
+
+The metadata of Authentic2 SAML2 identity provider are available at:
+
+    http[s]://your.domain.com/idp/saml2/metadata
+
+The metadata of Authentic2 SAML2 service provider are available at:
+
+    http[s]://your.domain.com/authsaml2/metadata