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
.
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:
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.
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 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 clonedvs
repository and save them as respective docker secrets.
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 <stack-name>_SHIB_CERT sp-signing-cert.pem
docker secret create <stack-name>_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.
docker config create idp-metadata idp-metadata-received.xml
Configure Apache ServerName used inside the
shibauth
service by modifyingAPACHE_SERVERNAME
environment variable of correspondingshibauth
service indocker-compose.<stack>.ops.yml
. This URL should resolve to the actual service URL.Configure SP and IdP EntityIDs used inside the
shibauth
service by modifyingSPEntityID
andIDPEntityID
environment variables of correspondingshibauth
service indocker-compose.<stack>.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
<service-url>/Shibboleth.sso/Metadata
.Get information about attributes provided by IdP and update
config/shibboleth/attribute-map.xml
by adding individual entries mappingname
provided by IdP toid
used by SP internally. Example configuration:
<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
andconfig/shibboleth/<stack-name>-ac-cache.xml
.
Example of external Access control rules configuration:
<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
:
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.
# Internally redirected to here. Rewrite for proper relaystate in shib
<Location /secure>
RewriteEngine On
RewriteCond %{HTTP:X-Forwarded-Uri} ^(.*)$ [NC]
RewriteRule ^.*$ %1 [PT]
</Location>
<LocationMatch "^/(admin|ows|opensearch)">
RewriteEngine On
AuthType shibboleth
ShibRequestSetting requireSession 1
Require shib-plugin /etc/shibboleth/pass-ac.xml
RewriteRule ^.*$ - [R=200]
</LocationMatch>
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:
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"