Merge pull request #11582 from camptocamp/backport/11577-to-master

[Backport master] Create a dedicated page for the authentication

doc/integrator/authentication.rst

@@ -1,19 +1,20 @@
+
+.. _integrator_authentication:
+
 Authentication
---------------
+==============
 
-~~~~~~~~~~~~~~~~~~~
 Supported standards
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 - `OpenID Connect`: as client, to be able to connect to an external OpenID Connect (OIDC) server.
 - `TOTP`: for two-factor authentication (2FA), this can be used for example with Google Authenticator.
 - `OAuth2` as server: An external application can use GeoMapFish as a single sign-on (SSO) for the
   authentication, even if it was initially implemented to be able to connect from QGIS desktop on an
   application that requires two factor authentication.
 
-~~~~~~~~~~~~~~~~~~
 The default policy
-~~~~~~~~~~~~~~~~~~
+------------------
 
 By default, ``c2cgeoportal`` applications use an *auth ticket* authentication
 policy (``AuthTktAuthenticationPolicy``). With this policy, the user name is
@@ -40,28 +41,23 @@ In the file ``env.project``, you can configure the policy with the following var
 See also `the official documentation <https://docs.pylonsproject.org/projects/pyramid/en/latest/api/authentication.html#pyramid.authentication.AuthTktAuthenticationPolicy>`_.
 
 
-~~~~~~~~~~~~~~~~~~~~
 Using another policy
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 When using ``AuthTktAuthenticationPolicy``, an "auth ticket" cookie should be
 set in the request for the user to be identified. In some applications, using
 a custom identification mechanism may be needed instead, for instance to use SSO.
-Our knowledge base has an example of how this can be achieved.
 
-~~~~~~~~~~~~~~~
 User validation
-~~~~~~~~~~~~~~~
+---------------
 
 For logging in, ``c2cgeoportal`` validates the user credentials
 (username/password) by reading the user information from the ``user`` database
 table. If a c2cgeoportal application should work with another user information
 source, like LDAP, a custom *client validation* mechanism can be set up.
-Our knowledge base has an example of how this can be achieved.
 
-~~~~~~~~~~
 Basic auth
-~~~~~~~~~~
+----------
 
 To be able to access the OGC services from your desktop GIS, you should enable the basic authentication
 by setting ``BASICAUTH`` to ``True`` in the ``env.project`` file.
@@ -73,9 +69,8 @@ in your query string.
 
    For security reasons, basic authentication and two factor authentication should not be enabled together.
 
-~~~~~~~~~~~~~~~~~~~~~~~~~~
 Two factors authentication
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 GeoMapFish support TOTP (Time-Based One-Time Password Algorithm) two factors authentication
 (`RFC 6238 <https://tools.ietf.org/html/rfc6238>`_).
@@ -96,9 +91,8 @@ should uncheck the 'The user changed his password' field on the user in the admi
    For security reasons, basic authentication and two factor authentication should not be enabled together,
    you should use :ref:`OAuth2<integrator_authentication_oauth2>` for that.
 
-~~~~~~~~~~~~~~~
 Account lockout
-~~~~~~~~~~~~~~~
+---------------
 
 To lock an account after a certain number of authentication failures, set the following settings:
 
@@ -111,9 +105,9 @@ To lock an account after a certain number of authentication failures, set the fo
 To unlock a user, the administrator should uncheck the 'Deactivated' field on the user in the
 admin interface.
 
-~~~~~~~~
+
 Intranet
-~~~~~~~~
+--------
 
 To configure the intranet networks fill in the configuration like:
 
@@ -138,19 +132,17 @@ See `Python documentation <https://docs.python.org/3.4/library/ipaddress.html#ip
 
    A user can easily manually set the `Forwarded` or `X-Forwarded-For` header to spoof his IP.
 
-~~~~~~~~~~~~~~~~~~~
 Lost admin password
-~~~~~~~~~~~~~~~~~~~
+-------------------
 
 You can generate a new admin password the following command:
 
 .. argparse::
    :ref: c2cgeoportal_geoportal.scripts.manage_users.get_argparser
    :prog: docker compose exec geoportal manage-users
 
-~~~~~~~~~~~~~~~~~~~~
 External application
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
 Some service of GeoMapFish has some host restriction if you mix the domain.
 
@@ -177,3 +169,9 @@ Admin
 We provide a view for the admin interface, to be able to clear the cache per OGC server.
 If for an unknown reason you have not the same host in the ``Host`` header and ``came_from`` parameter, you should
 add the domain of the ``came_from`` parameter in the vars in ``vars/admin_interface/allowed_hosts``.
+
+
+.. _integrator_authentication_oauth2:
+.. include:: authentication_oauth2.rst
+.. _integrator_authentication_oidc:
+.. include:: authentication_oidc.rst

doc/integrator/authentication_oauth2.rst

@@ -1,5 +1,5 @@
 OAuth2 with QGIS
-~~~~~~~~~~~~~~~~
+----------------
 
 In the admin interface create an 'OAuth2 Client' with:
 

doc/integrator/authentication_oidc.rst

@@ -1,5 +1,5 @@
 OpenID Connect
-~~~~~~~~~~~~~~
+--------------
 
 We can configure an OpenID connect service as an SSO (Single Sign-On) provider for our application. This allows users to log in to our application using their OpenID Connect credentials.
 
@@ -33,7 +33,6 @@ We use `OpenID Connect Discovery 1.0 <https://openid.net/specs/openid-connect-di
         end
         Geoportal->>-Browser: response
 
-~~~~~~~~~~~~~~~~~~~~~~~
 Authentication provider
 ~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -52,7 +51,6 @@ If we want to use OpenID Connect as an authentication provider, we need to set t
 With that the user will be create in the database at the first login, and the access right will be set in the GeoMapFish database.
 The user correspondence will be done on the email field.
 
-~~~~~~~~~~~~~~~~~~~~~~
 Authorization provider
 ~~~~~~~~~~~~~~~~~~~~~~
 
@@ -74,7 +72,6 @@ If we want to use OpenID Connect as an authorization provider, we need to set th
 
 With that the user will not be in the database only the roles will be set in the GeoMapFish database.
 
-~~~~~~~~~~~~~
 Other options
 ~~~~~~~~~~~~~
 
@@ -107,7 +104,6 @@ Other options
      display_name: name
      email: email
 
-~~~~~~~~~~~~~~~~~~~~
 Example with Zitadel
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -121,7 +117,6 @@ Example with Zitadel
          query_user_info: true
          create_user: true
 
-~~~~~
 Hooks
 ~~~~~
 
@@ -153,7 +148,6 @@ Configure the hooks in the project initialization:
         config.add_request_method(get_remember_from_user_info, name="get_remember_from_user_info")
         config.add_request_method(get_user_from_remember, name="get_user_from_remember")
 
-~~~~~~~~~~~~~~~~~
 QGIS with Zitadel
 ~~~~~~~~~~~~~~~~~
 
@@ -173,7 +167,6 @@ On QGIS:
 * Set ``Client ID`` to ``<client_id>``.
 * Set ``Scope`` to the ``openid profile email``.
 
-~~~~~~~~~~~~~~
 Implementation
 ~~~~~~~~~~~~~~
 

doc/integrator/index.rst

@@ -21,6 +21,7 @@ Content:
    database
    configuration
    customize
+   authentication
    security
    features
    docker

doc/integrator/security.rst

@@ -3,12 +3,6 @@
 Security
 ========
 
-.. _integrator_authentication:
-.. include:: authentication.rst
-.. _integrator_authentication_oidc:
-.. include:: authentication_oidc.rst
-.. _integrator_authentication_oauth2:
-.. include:: authentication_oauth2.rst
 .. include:: https.rst
 .. include:: reset_password.rst