Testing Evergreen Shibboleth feature with Docker

shibboleth_eg_notes.txt

# For the purposes of these instructions, I will
# use the following metadata:
# Evergreen Entity ID: http://eg.sso_eg

# Make sure that docker is working properly before embarking
# on this adventure


##################################################
# 1. Add two hosts entries to your host computer #
##################################################

# This step is probably optional, but it sure simplifies things to have
# the same hosts entries as your docker containers

127.0.0.1 eg.sso_eg
127.0.0.1 idp.sso_eg


###########################################################
# 2. Install an IdP                                       #
#                                                         #
# Primary docs:                                           #
# https://simplesamlphp.org/docs/stable/simplesamlphp-idp #
###########################################################

# Create a docker network for your testing
docker network create evergreen_sso

# Create the IdP server
docker run -p 8080:8080 -p 8443:8443 \
-e SIMPLESAMLPHP_SP_ENTITY_ID=http://eg.sso_eg \
-e SIMPLESAMLPHP_SP_ASSERTION_CONSUMER_SERVICE=http://eg.sso_eg/Shibboleth.sso/SAML2/POST \
-e SIMPLESAMLPHP_SP_SINGLE_LOGOUT_SERVICE=http://eg.sso_eg/Shibboleth.sso/SLO/POST \
--name idp.sso_eg --network evergreen_sso \
-d kristophjunge/test-saml-idp


#################################
# 3. Create an Evergreen server #
#################################

# Make sure you don't have anything running on any
# of the ports referenced below, then
# create an Evergreen server
docker run -it -p 80:80 -p 210:210 -p 443:443 \
-p 32:22 -p 7680:7680 -p 7682:7682 -p 6001:6001 \
--name eg.sso_eg --network evergreen_sso \
mobiusoffice/evergreen-ils:3.5.0

#########################
# 4. Install shibboleth #
#########################


# Install shibboleth
docker exec -it eg.sso_eg apt-get update
docker exec -it eg.sso_eg apt-get install -y libapache2-mod-shib2

# Enable the correct apache mods, if they aren't already
docker exec -it eg.sso_eg a2enmod auth_basic shib2

# Set the shibboleth cert
docker exec -it eg.sso_eg shib-keygen -h localhost
docker exec -it eg.sso_eg openssl x509 -text -noout -in /etc/shibboleth/sp-cert.pem

#######################################
# 5. Initial shibboleth configuration #
#######################################


# Get a text editor you like, and start editing
docker exec -it eg.sso_eg apt-get install -y vim
docker exec -it eg.sso_eg vim /etc/shibboleth/shibboleth2.xml

# Find the line that defines Evergreen's entityID.  Change it to
# the entity ID you want (does not have to be an actual hostname or
# domain name
   <ApplicationDefaults entityID="http://eg.sso_eg"
   
# Find the <SSO> segment.  Replace it with: (this means
# that the IdP will be identified in the metadata and based on
# library settings in Evergreen, rather than hard-coded into this
# config file.
            <SSO>
              SAML2 SAML1
            </SSO>
            
# Find the Example of locally maintained metadata.  Uncomment it.

# Get the metadata from the IdP

docker exec -it eg.sso_eg \
wget http://idp.sso_eg:8080/simplesaml/saml2/idp/metadata.php -O /etc/shibboleth/partner-metadata.xml

# Now, add an attribute to attribute-map.xml, which will allow us to match the patron's Evergreen
# username against their Shibboleth UID

docker exec -it eg.sso_eg vim /etc/shibboleth/attribute-map.xml

    <Attribute name="uid" id="uid" nameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"/>


# Add a special security policy

docker exec -it eg.sso_eg vim /etc/shibboleth/security-policy.xml

    <Policy id="unsigned-slo">
        <PolicyRule type="NullSecurity"/>
    </Policy>


# Restart shibd and make sure it is happy
docker exec eg.sso_eg service shibd restart

###############################################
# 6. Install the correct Evergreen git branch #
###############################################

# Get a bash shell on the EG server
docker exec -it eg.sso_eg bash

# Check out the correct branch
su opensrf
cd ~/repos/Evergreen/ && git fetch working && git checkout working/user/miker/lp-1871211-Shib-patron-SSO # (as opensrf)

# Install it
make && exit # (as opensrf)
cd /home/opensrf/repos/Evergreen && make install && apache2ctl restart # (as root)

# Fiddle with the new migration and run it (commands not included)
# Apply the changes to the eg_vhost configuration and restart Apache (commands not included)

exit


##########################
# 7. Configure Evergreen #
##########################

# In your browser, go to
https://eg.sso_eg/eg/staff/admin/local/asset/org_unit_settings

Apply the following library settings:
Enable Shibboleth SSO for the OPAC: CONS: True
Shibboleth SSO Entity ID: CONS: http://idp.sso_eg:8080/simplesaml/saml2/idp/metadata.php

Open a patron record and change its username to 1

Open the OPAC and click on My Account.


########################
# Troubleshooting tips #
########################

The shibboleth logs are super helpful.  Be on the lookout for any attributes that you expected to be mapped, but which were not.


Also helpful is retrieving your Metadata xml files:
* From the SP (Evergreen): http://eg.sso_eg/Shibboleth.sso/Metadata
* From the IdP (SimpleSamlPhp): http://idp.sso_eg:8080/simplesaml/saml2/idp/metadata.php