finish access part of op guide

documentation/operator-guide/access.rst

@@ -68,7 +68,7 @@ Currently setting individual authorization rules on a ``Collection`` and ``Servi
 
 Configuration
 ~~~~~~~~~~~~~
-For correct configuration of Shibboleth SP3 on a new stack, several steps need to be done.
+For correct configuration of Shibboleth SP3 on a new stack, several steps need to be done. Most of these configurations are usually done in the :ref:`_initialization` step using ``pvs_starter`` tool. Still, it is advised to check following steps, understand them and change if necessary.
 Briefly summarized, SP and IdP need to exchange metadata and certificates to trust each other, SP needs to know which attributes the IdP will be sending about the logged-in user and respective access-control rules are configured based on those attributes. Most of the configurations are done via docker configs defined in the docker compose 
 
 - Create a pair of key, certificate using attached Shibboleth ``config/shibboleth/keygen.sh`` in the cloned vs repository and save them as respective docker secrets.
@@ -98,8 +98,80 @@ Briefly summarized, SP and IdP need to exchange metadata and certificates to tru
 
 - Deploy your shibauth service and exchange your SP metadata with the IdP provider and have them recognize your SP. Necessary metadata needs to be downloaded from url ``<service-url>/Shibboleth.sso/Metadata``.
 
-- Get information about attributes provided by IdP and update ``config/shibboleth/attribute-map.xml`` by adding individual entries mapping ``name`` provided by IdP to ``id`` used by SP internally.
+- Get information about attributes provided by IdP and update ``config/shibboleth/attribute-map.xml`` by adding individual entries mapping ``name`` provided by IdP to ``id`` used by SP internally. Example configuration:
 
-- Create access-rules based on these attributes in <stack_pass-ac/xml
-- review apache endpoints vs access rules and traefik
-- mention possibility of basic auth on shib endpoint too (if request header has 'Authorization')
+.. code-block:: xml
+ 
+ <Attributes xmlns="urn:mace:shibboleth:2.0:attribute-map" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
+   <Attribute name="urn:mace:dir:attribute-def:signed-terms" id="signed_terms_and_conditions"/>
+   <Attribute name="urn:mace:dir:attribute-def:primary-group" id="user_group_primary"/>
+ </Attributes>
+
+- Create custom access rules based on these attributes and map these access controls to different internal apache routes to which Traefik ForwardAuth middleware will point. Access rules are created in ``config/shibboleth/<stack-name>-ac.xml``.
+Example of external Access control rules configuration:
+
+.. code-block:: xml
+ 
+ <AccessControl type="edu.internet2.middleware.shibboleth.sp.provider.XMLAccessControl">
+   <AND>
+     <RuleRegex require="signed_terms_and_conditions">.+</RuleRegex>
+     <Rule require="user_group_primary">
+      Privileged_Access Public_Access
+     </Rule>
+   </AND>
+ </AccessControl>
+ 
+- Check configured link between Apache configuration for ``shibauth`` service, access rules, Traefik ForwardAuth middleware and per-service Traefik labels. Following simplified examples show the links in more detail:
+
+``APACHE_SERVERNAME`` environment variable needs to be set and same as the hostname, that Traefik will be serving as main entry point. Part of docker compose of shibauth service in ``docker-compose.emg.ops.yml``:
+
+.. code-block:: yaml
+
+ services:
+   shibauth:
+     environment:
+       APACHE_SERVERNAME: "https://emg.pass.copernicus.eu:443"
+     deploy:
+       labels:
+         - "traefik.http.routers.shibauth.rule=Host(`emg.pass.copernicus.eu`) && PathPrefix(`/secure`, `/Shibboleth.sso`)"
+         ...
+
+Relevant Apache configuration in ``config/shibboleth/shib-apache.conf``, enabling Shibboleth authentication and authorization of the ``/secure`` endpoint.
+
+.. code-block:: apacheconf
+
+ <Location />
+   SetHandler shib
+ </Location>
+ <VirtualHost *:80>
+   PassEnv APACHE_SERVERNAME
+   ServerName "${APACHE_SERVERNAME}"
+   <Location /secure>
+     AuthType shibboleth
+     ShibRequestSetting requireSession 1
+     Require shib-plugin /etc/shibboleth/pass-ac.xml
+   </Location>
+   ...
+
+Part of Traefik ForwardAuth middleware configuration from ``traefik-dynamic.yml``, defining the internal address pointing to the ``shibauth`` service and ``/secure`` endpoint in it:
+
+.. code-block:: yaml
+
+ http:
+   middlewares:
+     shibAuth:
+       forwardAuth:
+         address: http://shibauth/secure
+         trustForwardHeader: true
+
+Part of renderer service Traefik labels from ``docker-compose.emg.ops.yml``, where access through the middleware is configured.
+
+.. code-block:: yaml
+
+ services:
+   renderer:
+     deploy:
+       labels:
+         # router for shib auth based access (https)
+         - "traefik.http.routers.emg-renderer-shib.rule=Host(`emg.pass.copernicus.eu`) && PathPrefix(`/ows`, `/opensearch`, `/admin`)"
+         - "traefik.http.routers.emg-renderer-shib.middlewares=shibAuth@file"