Skip to end of metadata
Go to start of metadata

One method to get a shiny new Shibboleth IDP v3 as replacement for your old, unsupported IDPv2 is this:

  • Build a new server using a current OS and current software, ideally following this guide (but alternatives exist, get in contact!)
  • Put it into the same VLAN/network segment as your current production IDP (to ease creation of firewall rules to access e.g. LDAP from the new machine).
  • Don't create a DNS A RR for the new IP address, instead (temporarily) modify your local workstation's/PC's hosts file to map the existing IDP server's name to the new IP address. I.e., when your local web browser accesses the production IDP hostname it will actually talk to the new machine instead.
  • If your IDP terminated HTTPS/TLS itself (not some external load balancer / TLS offloader) copy over the TLS key pair to the new server, potentially converting it into a PKCS#12 file as documented here. Or just get a new TLS cert issued from the ACOnet TCS and convert that into a PKCS#12 file just the same.
  • Using the steps so far (and the documentation provided in this wiki) you should be able to configure and verify a fully functional TLS-enabled web server, accessible (only from your local machine!) with the name and correct TLS cert (and certificate chain) of the existing/old production IDP.
  • When installing the IDPv3 from scratch on the new server give it the entityID and scope of your existing production IDP. (This list has both for all IDPs). Actually the installer asks for a hostname, so give it the hostname portion of your existing entityID, the installer will prefix that with https:// and suffix it with /idp/shibboleth and present it to you as entityID to use, which will likely match your existing entityID. Otherwise don't worry and fix it in conf/ after the install completes. Confirm with Enter or correct as needed.
  • Copy over the existing IDP's key pair from /opt/shibboleth-idp/credentials/idp.{key,crt} on the old server and replace the newly generated (by the installer) key pair called idp-signing.{key,crt} in the same directory on the new server.
  • If you're deployment supports backchannel/SOAP requests (port 8443) and you intend to continue doing so, also convert the same old, existing IDP's key pair (the one from the previous step) into a PKCS#12 file for Tomcat to use. This requires setting a passphrase on the PKCS#12 file, so first generate a random one:

    openssl rand -hex 12

    and write it into /etc/tomcat9/server.xml as keystorePass of the Connector for port 8443 (only the one where keystoreFile="/opt/shibboleth-idp/credentials/idp-backchannel.p12"). Then provide it to the following openssl command, when prompted to set a new passphrase on the PKCS#12 file to be generated:

    openssl pkcs12 -export -in idp.crt -inkey idp.key -name "backchannel key pair" -out idp-backchannel.p12

    Copy the resulting file idp-backchannel.p12 over the installer-generated one in /opt/shibboleth-idp/credentials/ on the new server. Maybe remove the installer-generated idp-backchannel.crt, too, to avoid confusion. Leave the rest of the keys untouched for now on the new server (sealer.*, idp-encryption.*). Finally make sure to get all file system permissions right for the copied/converted credentials, by re-running the chown/chgrp/chmod commands from section "Adjust Tomcat configuration" on the page IDP 3 - Step 2 - Shibboleth installation.

  • Configure the IDP with Metadata (copy/paste the MetadataProvider from this documentation, which also ensures validation of the metadata against the published Metadata Signing Key), then configure Authentication by adjusting the new file as needed.
  • After a Tomcat restart you should now be able to access the Demo SP, though no (real/correct) attributes will be sent/recieved yet. To the SP your new test IDPv3 is the old production IDP, as hostname and keys and endpoints all match perfectly, at least as seen from your own workstation with the hosts file adjusted as expained above.
  • Don't continue unless/until you have Tomcat with TLS working!
  • Don't continue unless/until authentication at the IDP and logins to the Demo SP, are working!
  • For the attribute-resolver.xml configuration we have extensively documented examples using the newer, cleaner IDP3 syntax.
    • Alternatively, copying over the old file verbatim should also work, though you'll have to redo that for IDP v4 anyway.
  • If you previously had configured support for persistent NameIDs within the attribute resolver use the new conf/saml-nameid.* method instead.
  • For the attribute-filter.xml it is strongly recommended you start with the recommended best practices from the IDP 3 Attribute release page and only add your own existing rules to those where needed.
    • Service Categories should be supported.
    • Using the "registered by ACOnet" method should get you all of the Service Providers registered into by the ACOnet team.
    • The policies from Library Services can also be copied into your filter verbatim, if your institiution is making use of at least one of the services specified there. (It won't do any harm to have other services in the filter, these SPs will only give you access if you pay license fees.)
  • Ask questions on the community mailing list – it exists for this very reason!
  • No labels