Editing Shibboleth (section)

== Troubleshooting ==

=== Apache Configuration Issues ===
==== Apache 2.2 (and lower) Configuration for EPrints Shibboleth Integration ====
* Similarly to the instructions for Apache 2.4 and above, place the slightly different following configuration after the '''Include''' line for ''apache_ssl/foo.conf'', (substituting '''foo''' for your archive's name):

  Alias /shibboleth /opt/eprints3/archives/foo/shibboleth
  <Directory "/opt/eprints3/archives/foo/shibboleth">
    SetHandler perl-script
    PerlHandler ModPerl::Registry
    PerlSendHeader Off
    Options ExecCGI FollowSymLinks
  
    AuthType shibboleth
    ShibRequireSession On
    require valid-user
  </Directory>
  
  <Location /cgi/shibboleth>
    AuthType shibboleth
    ShibRequireSession On
    require valid-user
  </Location>

=== Shibboleth Configuration Issues ===
==== With attribute-map.xml ====
When authenticating using Shibboleth to login to EPrints you may see the following line in '''/var/log/shibboleth.shibd.log'''

  2015-09-09 09:26:43 INFO Shibboleth.AttributeExtractor.XML [2]: skipping unmapped SAML 2.0 Attribute with Name:  urn:mace:dir:attribute-def:department

In some cases this might not be an issue, as EPrints does not necessarily to make use of all the attributes returned by the IdP but without a mapping in attribute-map.xml.  In this case '''urn:mace:dir:attribute-def:department''' is not by default needed by EPrints to create/update a user account.  However, values like '''sn''', '''givenName''' and '''mail''' are but if you have used the attribute-map.xml provided later on the page you should not see a line like above in '''shibd.log'''.  In some cases you may still see an line like this in the log even if you think you have defined the attribute.  The line below demonstrate two known issues:

  2015-09-09 09:26:43 INFO Shibboleth.AttributeExtractor.XML [2]: skipping unmapped SAML 2.0 Attribute with Name:  givenName, Format:urn:oasis:names:tc:SAML:2.0:attrname-format:basic

# The attribute itself has no namespace it is just '''givenName''' rather than '''urn:mace:dir:attribute-def:givenName'''
# The attribute has a format that most also be defined in the attribute-map.xml attribute.

Below shows how to both include the format, which is required for the attribute to be successful mapped.  As well as define the name of the attribute without a namespace:

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

A typical Shibboleth IdP would have both a namespaced attribute name and would not apply a format to an attribute that is a simple text string.  Therefore it is worth enquiring with the IdP provider if either of these two happen to be the case.  The Shibboleth Service Provider can be [[Shibboleth Debug Logging|run in debug mode]], which may help your figure out what attributes are being mapped..

==== With idp-metadata.xml ====
If you want to be able extract scoped attributes (e.g. '''eduPersonPrincipalName''' otherwise described as '''eppn''').  Then you will need to ensure that the expected scope of this attribute, (effectively the domain part in eduPersonPrincipalName is the scope or one of the scopes in the idp-metadata.xml you downloaded from the Shibboleth IdP.  For example if the '''eduPersonPrincipalName''' is '''bar@foo.ac.uk'''.  Then the following should be defined in idp-metadata.xml ('''N.B. the namespace abbreviations (md: and shibmd:) may be different for the IdP you are working with'''):

  <md:Extensions>
    <shibmd:Scope regexp="false">foo.ac.uk</shibmd:Scope>
  </md:Extensions>

=== Login Issues ===
To be added.