Editing Shibboleth (section)

== Configuring Shibboleth ==
* Replace '''/etc/shibboleth/shibboleth2.xml''' with the following.  Substitute '''foo.eprints.org''' for the hostname of your EPrints repository, '''https://shib.foo.example.org/idp/shibboleth''' with the entity ID for you Shibboleth IdP and '''foo''' in the pathname of files with the name or your repository (e.g. ''foo/attribute-map.xml'' becomes ''myrepo/attribute-map.xml'').  '''(This configuration is intended for Shibboleth SP version 2.x and is liable to cause deprecation warnings if  you have installed a recent version of Shibboleth from a package repository.  [[Shibboleth/3.x|Here is a default shibboleth2.xml configuration for Shibboleth 3.x]]).'''

  <SPConfig xmlns="urn:mace:shibboleth:3.0:native:sp:config"
    xmlns:conf="urn:mace:shibboleth:3.0:native:sp:config"
    clockSkew="180">
  
    <ApplicationDefaults entityID="https://foo.eprints.org/shibboleth"
                         REMOTE_USER="eppn subject-id pairwise-id persistent-id"
                         cipherSuites="DEFAULT:!EXP:!LOW:!aNULL:!eNULL:!DES:!IDEA:!SEED:!RC4:!3DES:!kRSA:!SSLv2:!SSLv3:!TLSv1:!TLSv1.1">
  
      <Sessions lifetime="28800" timeout="3600" relayState="ss:mem" 
                checkAddress="false" handlerSSL="true" cookieProps="https"
                redirectLimit="exact">
        <SSO entityID="https://shib.foo.example.org/idp/shibboleth">SAML2</SSO>
        <Logout>SAML2 Local</Logout>
        <LogoutInitiator type="Admin" Location="/Logout/Admin" acl="127.0.0.1 ::1" />
        <Handler type="Status" Location="/Status" acl="127.0.0.1 ::1"/>
        <Handler type="Session" Location="/Session" showAttributeValues="false"/>
        <Handler type="DiscoveryFeed" Location="/DiscoFeed"/>
      </Sessions>
  
      <Errors supportContact="root@localhost" helpLocation="/about.html" styleSheet="/shibboleth/main.css"/>
      <MetadataProvider type="XML" path="foo/idp-metadata.xml"/>
      <AttributeExtractor type="XML" validate="true" reloadChanges="false" path="foo/attribute-map.xml"/>
      <AttributeFilter type="XML" validate="true" path="attribute-policy.xml"/>
      <CredentialResolver type="File" use="signing" key="foo/sp-key.pem" certificate="foo/sp-cert.pem"/>
      <CredentialResolver type="File" use="encryption" key="foo/sp-key.pem" certificate="foo/sp-cert.pem"/>
 
    </ApplicationDefaults>
  
    <SecurityPolicyProvider type="XML" validate="true" path="security-policy.xml"/>
    <ProtocolProvider type="XML" validate="true" reloadChanges="false" path="protocols.xml"/>
    
  </SPConfig>

* Create the directory '''/etc/shibboleth/foo''', substituting ''foo'' for your repository name.
  root> mkdir /etc/shibboleth/foo

* Copy '''attribute-map.xml''' into this new directory.
  cp /etc/shibboleth/attribute-map.xml /etc/shibboleth/foo/

* Temporarily rename '''sp-cert.pem''' and '''sp-key.pem''' in '''/etc/shibboleth/''' to '''sp-cert.pem.old''' and '''sp-key.pem.old'''.
  root> cd /etc/shibboleth
  root> mv sp-cert.pem sp-cert.pem.old
  root> mv sp-key.pem sp-key.pem.old

* Run '''keygen.sh''' from the '''/etc/shibboleth/''' directory, as follows replacing '''foo.eprints.org''' with your EPrints repository hostname.
  root> cd /etc/shibboleth
  root> ./keygen.sh -f -h foo.eprints.org -e https://foo.eprints.org/shibboleth

* Move the new '''sp-cert.pem''' and '''sp-key.pem''' to '''/etc/shibboleth/foo/''' and move the ''.old'' files back in place:
  root> cd /etc/shibboleth
  root> mv sp-cert.pem sp-key.pem foo/
  root> mv sp-cert.pem.old sp-cert.pem
  root> mv sp-key.pem.old sp-key.pem

* Check that '''sp-cert.pem''' and '''sp-key.pem''' in '''/etc/shibboleth/foo/''' still have the owner and group '''shibd'''.
  root> ls -l /etc/shibboleth/foo/sp-*
  -rw-r--r-- 1 shibd shibd 1192 May  6 19:04 /etc/shibboleth/foo/sp-cert.pem
  -rw------- 1 shibd shibd 1708 May  6 19:04 /etc/shibboleth/foo/sp-key.pem

* Run '''metagen.sh''' from the '''/etc/shibboleth/''' directory, as follows replacing '''foo.eprints.org''' with your EPrints repository hostname.  You will ultimately need to send the output of this to the person managing the Shibboleth IdP server with which you want to register your EPrints repository as a service.
  root> cd /etc/shibboleth
  root> ./metagen.sh -ALO -c foo/sp-cert.pem -h foo.eprints.org -e https://foo.eprints.org/shibboleth > foo/sp-metadata.xml

* Modify ''' foo/sp-metadata.xml''' to add in the namepace definitions by separately changing the <code>md:EntityDescriptor</code> and <code>ds:KeyInfo</code> lines as follows from:
 <md:EntityDescriptor entityID="https://foo.eprints.org/shibboleth">
   ...
     ...
       <ds:KeyInfo>
to:
 <md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="https://foo.eprints.org/shibboleth"> 
   ...
     ...
       <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">

* Use ''wget'' to download the metadata from your Shibboleth IdP (e.g. shib.foo.example.org) to the '''/etc/shibboleth/foo/''' directory.
  root> wget -O /etc/shibboleth/foo/idp-metadata.xml https://shib.foo.example.org/idp/shibboleth

=== Using Remote IdP Metatdata ===

As IdP Metadata may expire, you may want to use the remote metadata URL rather than a local copy.  This is what you need to do to switch to using remote IdP metadata:

* Edit the '''MetadataProvider''' line to something like the following.  The reloadInterval is best set to 7200 but this can be set less frequently:

 <MetadataProvider type="XML" url="https://shib.foo.example.org/idp/metadata.xml" backingFilePath="foo/idp-metadata.xml" reloadInterval="7200"/>

* Make sure the reloadInterval is appropriate for the IdP metadata you are downloading.  If you have large metadata file,(e.g. from a federated metadata service containing metadata for other IdPs), then it may be better to set this higher than the default.  However, the configuration checker may warn you that your reload interval is too long, so you may have to choose to ignore this, if you want to avoid downloading a large federated metadata file too often.

* Make sure that the directory '''/etc/shibboleth/foo/''' and '''/etc/shibboleth/foo/idp-metadata.xml''' if it already exists) are owned by '''shibd''':

 chown shibd:shibd /etc/shibboleth/foo/
 chown shibd:shibd /etc/shibboleth/foo/idp-metadata.xml

* To test Shibboleth you will need to make sure your '''LD_LIBRARY_PATH''' is set the same as shibd would have when started using ''systemctl shibd start''.
 
 LD_LIBRARY_PATH=/opt/shibboleth/lib64:$LD_LIBRARY_PATH shibd -t
This should return the message: ''overall configuration is loadable, check console for non-fatal problems''.

* The above message is because it is now advised not to leave the MetadataGenerator enabled unnecessarily.  However, whilst you are setting up Shibboleth, it is useful to have the metadata generator, save you needing to build your own Service Provider metadata file to register with your Identity Provider.  Later on you can comment out the MetadataGenerator line to stop getting this warning message.

* Now you can restart '''shibd''' properly:

 systemctl restart shibd