.. _access: Access ====== This chapter describes general concepts of how external access to each component is provided and how authentication and authorization layer based on `Shibboleth SP3 `_. is configured. General overview ~~~~~~~~~~~~~~~~ Each individual docker **stack** has its own internal network ``intnet`` where services can communicate between each other. This network is not exposed to the public and provides most of the necessary communication. Additionally external user access to some services (client, renderer, cache) is provided via external network ``extnet`` and reverse-proxy (traefik) with load balancer. These services can have a set of authentication and authorization rules applied both on traefik level and Shibboleth SP level. Kibana and Traefik dashboard are also accessible externally, but through a different set of default credentials. Routing with traefik ~~~~~~~~~~~~~~~~~~~~ ``Reverse-proxy`` service in base stack provides central access endpoint to the VS. It exposes ports 80 and 443 for HTTP and HTTPS access in the host mode. Configuration of the reverse-proxy is done on three places. First two are static and dynamic configuration files ``traefik.yml`` and ``traefik-dynamic.yml``. Static configuration sets up connections to providers and define the entrypoints that Traefik will listen to. Dynamic configuration defines how the requests are handled. This configuration can change and is seamlessly hot-reloaded, without any request interruption or connection loss. Third part are docker ``labels`` on individual services which Traefik provides access to, for which an update requires removing and re-creating the stack. For example following configuration snippet enables access to certain paths of ``renderer`` service under a given hostname. It also sets externally set basic authentication and other rules via ``@file`` identifier, which references global configurations from ``traefik-dynamic.yml``. .. code-block:: yaml renderer: deploy: labels: # router for basic auth based access (https) - "traefik.http.routers.vhr18-renderer.rule=Host(`vhr18.pdas.prism.eox.at`) && PathPrefix(`/ows`, `/opensearch`, `/admin`)" - "traefik.http.routers.vhr18-renderer.middlewares=auth@file,compress@file,cors@file" - "traefik.http.routers.vhr18-renderer.tls=true" - "traefik.http.routers.vhr18-renderer.tls.certresolver=default" - "traefik.http.routers.vhr18-renderer.entrypoints=https" # general rules - "traefik.http.services.vhr18-renderer.loadbalancer.sticky=false" - "traefik.http.services.vhr18-renderer.loadbalancer.server.port=80" - "traefik.docker.network=vhr18-extnet" - "traefik.docker.lbswarm=true" - "traefik.enable=true" An example of such auth@file configuration from ``traefik-dynamic.yml`` would be following snippet, where ``BASIC_AUTH_USERS_AUTH`` is referencing a docker secret configured earlier: .. code-block:: yaml http: middlewares: auth: basicAuth: realm: "PRISM View Server (PVS)" usersFile: "/run/secrets/BASIC_AUTH_USERS_AUTH" Updating of `usersFile` content needs a restart of reverse-proxy service afterwards. Unsecured HTTP access is configured to be redirected to the HTTPS endpoint. Inside the swarm among the services, only HTTP is used internally. Authentication and Authorization ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Authentication of access to external parts of VS is made up of two options: - Traefik provided basic authentication - configured as ``file@auth`` and ``file@apiAuth`` Here, access on such endpoint requires basic authentication credentials (username, password) to be inserted, while web browsers are usually prompted for input. After inserting valid credentials, access is granted. - Shibboleth Service Provider 3 + Apache 2 instance, to which requests are forwarded by `Traefik ForwardAuth middleware `_. Middleware delegates the authentication to Shibboleth. If Shibboleth response code is 2XX, access is granted and the original request is performed. Otherwise, the error response from Shibboleth is returned. In order to authenticate with Shibboleth, a user must log in with valid credentials on the side of Identity Provider (IdP), if doing so, the IdP informs the SP about successful login, accompanied by relevant user attributes and a session is created for the user. SP then saves the information about a created session into a cookie and based on user attributes can authorize access to the services. If the user was already logged in, he is automatically offered the requested resource. Currently setting individual authorization rules on a ``Collection`` (docker stack) and ``Service`` (docker service) level is possible. It is yet not clearly possible to separate viewing and download functionality, as both of these parts are handled by ``renderer`` service. Configuration ~~~~~~~~~~~~~ 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 files. - Create a pair of key, certificate using attached Shibboleth utility ``config/shibboleth/keygen.sh`` in the cloned ``vs`` repository and save them as respective docker secrets. .. code-block:: bash SP_URL="https://emg.pass.copernicus.eu" # service initial access point made accessible by traefik ./config/shibboleth/keygen.sh -h $SPURL -y 20 -e https://$SP_URL/shibboleth -n sp-signing -f docker secret create _SHIB_CERT sp-signing-cert.pem docker secret create _SHIB_KEY sp-signing-key.pem - Get IDP metadata and save it as a docker config. Also save the entityID of the IdP for further use in filling the ``shibboleth2.xml`` template. .. code-block:: bash docker config create idp-metadata idp-metadata-received.xml - Configure Apache ServerName used inside the ``shibauth`` service by modifying ``APACHE_SERVERNAME`` environment variable of corresponding ``shibauth`` service in ``docker-compose..ops.yml``. This URL should resolve to the actual service URL. - Configure SP and IdP EntityIDs used inside the ``shibauth`` service by modifying ``SPEntityID`` and ``IDPEntityID`` environment variables of corresponding ``shibauth`` service in ``docker-compose..ops.yml``. ``SPEntityID`` can be chosen in any way, IDPEntityID should be extracted from received IDP metadata. - Deploy your shibauth service and exchange your SP metadata with the IdP provider and have them register your SP. Necessary metadata can be downloaded from 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. Example configuration: .. code-block:: xml - 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/-ac.xml`` and ``config/shibboleth/-ac-cache.xml``. Example of external Access control rules configuration: .. code-block:: xml .+ Privileged_Access Public_Access - 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(`/Shibboleth.sso`)" ... Relevant Apache configuration in ``config/shibboleth/shib-apache.conf``, enabling Shibboleth authentication and authorization of the renderer service on the ``/secure`` endpoint. .. code-block:: apacheconf # Internally redirected to here. Rewrite for proper relaystate in shib RewriteEngine On RewriteCond %{HTTP:X-Forwarded-Uri} ^(.*)$ [NC] RewriteRule ^.*$ %1 [PT] RewriteEngine On AuthType shibboleth ShibRequestSetting requireSession 1 Require shib-plugin /etc/shibboleth/pass-ac.xml RewriteRule ^.*$ - [R=200] Part of Traefik ForwardAuth middleware configuration from ``docker-compose.emg.ops.yml``, defining the internal address pointing to the ``shibauth-emg`` service and ``/secure`` endpoint in it: .. code-block:: yaml renderer: deploy: labels: - "traefik.http.middlewares.emg-renderer-shib-fa.forwardauth.address=http://shibauth-emg/secure" - "traefik.http.routers.emg-renderer-shib.middlewares=emg-renderer-shib-fa,compress@file,cors@file"