shibboleth-sp-postgresql.md

COmanage Match with Shibboleth SP and PostgreSQL

Follow these steps to build and run COmanage Match using the Shibboleth SP for authentication and PostgreSQL as the relational database.

• Install Docker. These instructions require version 17.05 or higher.

• Clone this repository:

git clone https://github.internet2.edu/COmanage/docker
cd docker

• Define the shell variable COMANAGE_MATCH_VERSION to be the version of COmanage Match you want to deploy. See the COmanage Match Release History wiki page for the list of releases. We recommend using the latest release.

Here is an example (but please check the wiki page for the latest release number):

export COMANAGE_MATCH_VERSION=1.0.0

• Define the shell variable COMANAGE_MATCH_BASE_IMAGE_VERSION to be the version of the base image you are about to build:

export COMANAGE_MATCH_BASE_IMAGE_VERSION=1

• Build the base COmanage Match image:

pushd comanage-match/comanage-match-base
TAG="${COMANAGE_MATCH_VERSION}-${COMANAGE_MATCH_BASE_IMAGE_VERSION}"
docker build \
  --build-arg COMANAGE_MATCH_VERSION=${COMANAGE_MATCH_VERSION} \
  -t comanage-match-base:${TAG} .
popd

• Define the shell variable COMANAGE_SHIBBOLETH_SP_BASE_IMAGE_VERSION to be the version of the base Shibboleth SP image you are about to build:

export COMANAGE_SHIBBOLETH_SP_BASE_IMAGE_VERSION=1

• Build the base Shibboleth SP image:

pushd comanage-shibboleth-sp-base
TAG="${COMANAGE_MATCH_SHIBBOLETH_SP_BASE_IMAGE_VERSION}"
docker build \
    -t comanage-match-shibboleth-sp-base:$TAG . 
popd

• Define the shell variable COMANAGE_MATCH_SHIBBOLETH_SP_IMAGE_VERSION to be the version of the image you are about to build:

export COMANAGE_MATCH_SHIBBOLETH_SP_IMAGE_VERSION=1

• Build an image for COmanage Match that uses the Shibboleth SP for authentication:

pushd comanage-match/comanage-match-shibboleth-sp
TAG="${COMANAGE_MATCH_VERSION}-shibboleth-sp-${COMANAGE_MATCH_SHIBBOLETH_SP_IMAGE_VERSION}"
docker build \
    --build-arg COMANAGE_MATCH_VERSION=${COMANAGE_MATCH_VERSION} \
    --build-arg COMANAGE_MATCH_BASE_IMAGE_VERSION=${COMANAGE_MATCH_BASE_IMAGE_VERSION} \
    --build-arg COMANAGE_SHIBBOLETH_SP_BASE_IMAGE_VERSION=${COMANAGE_SHIBBOLETH_SP_BASE_IMAGE_VERSION} \
    -t comanage-match:$TAG .
popd

• Define the shell variable COMANAGE_MATCH_POSTGRES_IMAGE_VERSION to be the version of the image you are about to build:

export COMANAGE_MATCH_POSTGRES_IMAGE_VERSION=1

• Build an image for PostgreSQL for COmanage Registry:

pushd comanage-match/comanage-match-postgres
TAG="${COMANAGE_MATCH_POSTGRES_IMAGE_VERSION}"
docker build \
    -t comanage-match-postgres:${TAG} .
popd

• Initialize the Docker Swarm:

docker swarm init

• Create secrets for the database root password, the COmanage Match database password, the HTTPS certificate (and CA signing chain) and private key files, and the Shibboleth SP encryption certificate and private key files (be sure to choose your own values and do not use the examples below):

echo "jPkrc3TUijfmT3vi1ZKw" | docker secret create postgres_password - 

echo "ayFjKFHTre74A0k8k1mq" | docker secret create comanage_match_postgres_user_password - 

echo "ayFjKFHTre74A0k8k1mq" | docker secret create comanage_match_database_user_password - 

docker secret create https_cert_file fullchain.cert.pem

docker secret create https_privkey_file privkey.pem

docker secret create shibboleth_sp_encrypt_cert sp-encrypt-cert.pem

docker secret create shibboleth_sp_encrypt_privkey sp-encrypt-key.pem

• Create directories on the Docker engine host(s) for state files and other files including the Shibboleth SP configuration files:

sudo mkdir -p /srv/docker/var/lib/postgresql/data
sudo mkdir -p /srv/docker/srv/comanage-match/local
sudo mkdir -p /srv/docker/etc/shibboleth

• Copy Shibboleth SP configuration files into place to be mounted into the running container. Your Shibboleth SP configuration should result in the primary identifier attribute you expect to be asserted by the SAML IdP(s) to populate REMOTE_USER so that it can be read by COmanage Match. A common choice is to populate REMOTE_USER with eduPersonPrincipalName, but the details will depend on your SAML federation choices.

cp shibboleth2.xml /srv/docker/etc/shibboleth/
cp attribute-map.xml /srv/docker/etc/shibboleth/
cp saml-metadata.xml /src/docker/etc/shibboleth/

• Define a shell variable for the first COmanage Match platform administrator, for example:

export COMANAGE_MATCH_ADMIN_USERNAME=karel.novak@my.org

The username should be the value you expect to be asserted by the SAML IdP for the first platform administrator. The Shibboleth SP configuration should be such that the value is populated into REMOTE_USER where it will be read when the first platform administrator logs into COmanage Match.

• Define a shell variable with the fully-qualified domain name for the virtual host from which COmanage Match will be served. For example

export COMANAGE_MATCH_VIRTUAL_HOST_FQDN=match.my.org

• Create a Docker Swarm services stack description (compose) file in YAML format:

version: '3.1'

services:

    comanage-match-database:
        image: comanage-match-postgres:${COMANAGE_MATCH_POSTGRES_IMAGE_VERSION}
        volumes:
            - /srv/docker/var/lib/postgresql/data:/var/lib/postgresql/data
        environment:
            - POSTGRES_PASSWORD_FILE=/run/secrets/postgres_password
            - COMANAGE_MATCH_POSTGRES_USER_PASSWORD_FILE=/run/secrets/comanage_match_postgres_user_password
        secrets:
            - postgres_password
            - comanage_match_postgres_user_password
        networks:
            - default
        deploy:
            replicas: 1

    comanage-match:
        image: comanage-match:${COMANAGE_MATCH_VERSION}-shibboleth-sp-${COMANAGE_MATCH_SHIBBOLETH_SP_IMAGE_VERSION}
        volumes:
            - /srv/docker/srv/comanage-match/local:/srv/comanage-match/local
            - /srv/docker/etc/shibboleth/shibboleth2.xml:/etc/shibboleth/shibboleth2.xml
            - /srv/docker/etc/shibboleth/attribute-map.xml:/etc/shibboleth/attribute-map.xml
            - /srv/docker/etc/shibboleth/saml-metadata.xml:/etc/shibboleth/saml-metadata.xml
        environment:
            - COMANAGE_MATCH_ADMIN_USERNAME=${COMANAGE_MATCH_ADMIN_USERNAME}
            - COMANAGE_MATCH_DATASOURCE=Database/Postgres
            - COMANAGE_MATCH_DATABASE_USER_PASSWORD_FILE=/run/secrets/comanage_match_database_user_password
            - COMANAGE_MATCH_VIRTUAL_HOST_FQDN=${COMANAGE_MATCH_VIRTUAL_HOST_FQDN}
            - HTTPS_CERT_FILE=/run/secrets/https_cert_file
            - HTTPS_PRIVKEY_FILE=/run/secrets/https_privkey_file
            - SHIBBOLETH_SP_ENCRYPT_CERT=/run/secrets/shibboleth_sp_encrypt_cert
            - SHIBBOLETH_SP_ENCRYPT_PRIVKEY=/run/secrets/shibboleth_sp_encrypt_privkey
        secrets:
            - comanage_match_database_user_password
            - https_cert_file
            - https_privkey_file
            - shibboleth_sp_encrypt_cert
            - shibboleth_sp_encrypt_privkey
        networks:
            - default
        ports:
            - "80:80"
            - "443:443"
        deploy:
            replicas: 1

secrets:
    comanage_match_database_user_password:
        external: true
    comanage_match_postgres_user_password:
        external: true
    postgres_password:
        external: true
    shibboleth_sp_encrypt_cert:
        external: true
    shibboleth_sp_encrypt_privkey:
        external: true
    https_cert_file:
        external: true
    https_privkey_file:
        external: true

• Deploy the COmanage Match service stack:

docker stack deploy --compose-file comanage-match-stack.yml comanage-match

Since this is the first initialization of the containers it will take some time for the database tables to be created. The Apache HTTP Server and Shibboleth SP daemons will not be started until the entrypoint scripts detect that the database has been initialized.

You may monitor the progress of the database container using

docker service logs -f comanage-match-database

and the progress of the COmanage Match container using

docker service logs -f comanage-match

• After the Apache HTTP Server has started browse to port 443 on the host.

• Click Login to initiate a SAML authentication flow. After authenticating at the SAML IdP the Shibboleth SP should consume the SAML assertion and populate REMOTE_USER with the value for the username for the first platform administrator.

• Visit the COmanage wiki to learn how to create your first Matchgrid and begin using the platform.

• To stop the services:

docker stack rm comanage-match