SATOSA Quick Start Guide Using SAMLtest

This deploys SATOSA 8.0.0, at the end of which an interested party could perform a basic, end-to-end test of the current SATOSA release using SAMLtest (https://samltest.id/). Run all commands in a root shell.

Install Debian 11 (Bullseye). This is essentially the Docker image build process, only it uses the SATOSA release (etc.) on PyPI:

apt update
apt dist-upgrade -y
apt install -y \
    curl \
    git \
    python3-dev \
    python3-pip \
    python3-venv \
    python3-virtualenv \
    build-essential \
    libffi-dev \
    libssl-dev \
    xmlsec1 \
    libyaml-dev \
    libxml2-utils \
    jq \
    certbot \
    ;
virtualenv -p python3 /opt/satosa
/opt/satosa/bin/pip install SATOSA==8.0.0
/opt/satosa/bin/pip install yq

Copy https://github.com/IdentityPython/SATOSA/tree/v8.0.0/docker/attributemaps to /opt/satosa/attributemaps:

git clone https://github.com/IdentityPython/SATOSA /tmp/SATOSA
(cd /tmp/SATOSA && git checkout v8.0.0)
cp -a /tmp/SATOSA/docker/attributemaps /opt/satosa/attributemaps

The pysaml2 built-in attribute maps are used by default, but this lets one customize them.

Copy https://github.com/IdentityPython/SATOSA/tree/v8.0.0/example to /opt/satosa/etc:

cp -a /tmp/SATOSA/example /opt/satosa/etc

SATOSA doesn't have a default configuration, so you must provide it yourself:

cp /opt/satosa/etc/proxy_conf.yaml.example \
   /opt/satosa/etc/proxy_conf.yaml
cp /opt/satosa/etc/internal_attributes.yaml.example \
   /opt/satosa/etc/internal_attributes.yaml
cp /opt/satosa/etc/plugins/frontends/saml2_frontend.yaml.example \
   /opt/satosa/etc/plugins/frontends/saml2_frontend.yaml
cp /opt/satosa/etc/plugins/backends/saml2_backend.yaml.example \
   /opt/satosa/etc/plugins/backends/saml2_backend.yaml
cp /opt/satosa/etc/plugins/microservices/static_attributes.yaml.example \
   /opt/satosa/etc/plugins/microservices/static_attributes.yaml

You may change the proxy URL (the value of BASE in /opt/satosa/etc/proxy_conf.yaml), but it must be a method plus hostname without any trailing slash or path components, e.g., https://proxy.example.com, not https://proxy.example.com/ nor https://proxy.example.com/satosa. SATOSA must be hosted at the root of your web site:

sed -i'' -e 's/^BASE:.*/BASE: https:\/\/proxy.example.com/' \
    /opt/satosa/etc/proxy_conf.yaml

Comment out the idp_blacklist_file and disco_srv settings in /opt/satosa/etc/plugins/backends/saml2_backend.yaml:

sed -i'' -e 's/^\( *\(idp_blacklist_file\|disco_srv\)\)/#\1/g' \
    /opt/satosa/etc/plugins/backends/saml2_backend.yaml

Generate IdP, SP, metadata signing, and web site keying material:

for i in frontend backend metadata https; do
    openssl req -batch -x509 -nodes -days 3650 -newkey rsa:2048 \
        -keyout /opt/satosa/etc/$i.key -out /opt/satosa/etc/$i.crt \
        -subj /CN=proxy.example.com
done

Download the SAMLtest metadata:

curl https://samltest.id/saml/sp > /opt/satosa/etc/sp.xml
curl https://samltest.id/saml/idp > /opt/satosa/etc/idp.xml

Generate the proxy metadata documents without the <ns1:Signature> element. Otherwise, SAMLtest will be unable to load them due to an invalid signature:

. /opt/satosa/bin/activate
cd /opt/satosa/etc
satosa-saml-metadata proxy_conf.yaml metadata.key metadata.crt \
    --split-frontend --split-backend --dir /opt/satosa/etc
xmllint --format /opt/satosa/etc/Saml2IDP_0.xml \
| xq -x 'del(."ns0:EntityDescriptor"."ns1:Signature")' \
> /opt/satosa/etc/proxy-idp.xml
xmllint --format /opt/satosa/etc/Saml2_0.xml \
| xq -x 'del(."ns0:EntityDescriptor"."ns1:Signature")' \
> /opt/satosa/etc/proxy-sp.xml

This changes in future releases of SATOSA.

Upload the proxy metadata to SAMLtest (https://samltest.id/upload.php).
SAMLtest doesn't release the eduPerson Targeted ID attribute, so change /opt/satosa/etc/internal_attributes.yaml to use the email address attribute:

sed -i'' -e 's/^\(\(hash\|user_id_from_attrs\|user_id_to_attr\).*\)edupersontargetedid/\1mail/' \
    /opt/satosa/etc/internal_attributes.yaml

NEVER USE AN EMAIL ADDRESS AS AN IDENTIFIER. This is just a quick hack to get SATOSA working.

OPTIONAL: Obtain a certificate for the proxy URL (cf. step 5 above). Store the certificate in /opt/satosa/etc/https.crt and the matching private key in /opt/satosa/etc/https.key:

certbot certonly --non-interactive --agree-tos --standalone \
    --keep-until-expiring --renew-with-new-domains --cert-name satosa \
     -m [email protected] -d proxy.example.com
cp /etc/letsencrypt/live/satosa/fullchain.pem \
    /opt/satosa/etc/https.crt
cp /etc/letsencrypt/live/satosa/privkey.pem \
    /opt/satosa/etc/https.key

Start SATOSA:

. /opt/satosa/bin/activate
cd /opt/satosa/etc
gunicorn -b0.0.0.0:443 --keyfile https.key --certfile https.crt satosa.wsgi:app

At this point you should be able to perform an IdP test (https://samltest.id/start-idp-test/) by specifying the entity ID of the proxy's front end, e.g., https://example.com/Saml2IDP/proxy.xml. The SAMLtest SP will request authentication by your proxy IdP, causing your proxy SP to request authentication by the SAMLtest IdP. If everything works right, you will end up back at the SAMLtest SP. The process looks something like this:

SAMLtest SP ----AuthnRequest---> SATOSA front end (IdP)/back end (SP) ----AuthnRequest---> SAMLtest IdP
SAMLtest SP <---AuthnResponse--- SATOSA front end (IdP)/back end (SP) <---AuthnResponse--- SAMLtest IdP

xenophonf/satosa-quickstart.md