Installation Procedure for ShARPE

Assumptions

1. you have JDK 1.5 installed, ShARPE code uses JDK 1.5 features
2. you have fully configured IdP (tested on IdP 1.3c), otherwise install IdP prior proceeding to ShARPE installation. manual installation/configuration steps for IdP available from federation website.
3. you also need Ant installed, installations tested on Ant 1.6.2 and above

Modified Files in SHIB_SRC

SHIB_SRC is wherever you put the original IdP installation source, i.e. in /usr/src/shibboleth-1.3.2-install.

There are a number of files in SHIB_SRC replaced (and backed up) during installation, in webApplication/WEB-INF/lib :commons-digester.jar, commons-beanutils.jar, struts.jar

Installation Steps:

1. stop your tomcat (otherwise you have to redo the steps)
2. remove /usr/local/tomcat/webapps/shibboleth-idp (sometimes tomcat will not replace the webapp)
3. download ShARPE
4. extract it into a folder somewhere (called "ShARPE" here)
5. make sure JDK 1.5 and Ant are installed
6. go to your SHIB_SRC (where shibboleth source files are located)
   • edit build.xml, change all javac compilation from "1.4" to "1.5"
   • edit custom/extension-build.xml, change all javac compilation from "1.4" to "1.5"
   • optionally, modify custom/extension-build.properties and set "gen.ext.docs=false". This will not generate javadoc documentation for Shib
7. go to ShARPE folder
8. run "ant" to install ShARPE
   expect to see "Build Successful" message on each execution. You will be prompted with original Shib installation process, just press enter or use the exact inputs you had when you installed Shib previously (no configurations are modified). Note that you will see lots of warnings, this is due to limitation on Shib extension mechanism in which javadoc could not find classpath for the library -- ignore this as it will be fixed later
9. configure ShARPE (continue reading below)

Enabling Attribute Mapping

ShARPE is equipped with Attribute Mapping which is disabled by default in installation. During installation process you will have the chance to enable or disable it. Once enabled, admin would be able to map attributes from one schema to another (i.e. if SP uses different schema than IdP) through ShARPE.

Attribute Mapping modifies resolver configuration file to register new attributes. Installation of ShARPE will perform full backup of your resolver (and other important files) to IDP_HOME/etc/sharpe-backup

ShARPE Configuration

Changes in idp.xml

1. edit your idp configuration xml (idp.xml). Make sure the parameters refer to correct entries (i.e. change resolver.ldap.xml to resolver.xml for example, if you use ldap version)

   replace (assuming your IDP_HOME is /usr/local/shibboleth-idp):

   <ReleasePolicyEngine>
      <ArpRepository implementation="edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository">
         <Path>/usr/local/shibboleth-idp/etc/arps/</Path>
      </ArpRepository>
   </ReleasePolicyEngine>

   to:

   <ReleasePolicyEngine>
      <ArpRepository implementation="au.edu.mq.melcoe.mams.sharpe.shib.aa.arp.provider.MAMSFileSystemArpRepository">
         <Path>/usr/local/shibboleth-idp/etc/arps/</Path>
         <GroupLookup implementation="au.edu.mq.melcoe.mams.sharpe.shib.aa.arp.group.provider.AttributeResolverGroupLookup">
            <!-- usage of MAMSAttributeResolver is optional,
                  when not used the default AttributeResolver will be instantiated instead
            -->
            <ResolverConfig implementation="edu.internet2.middleware.shibboleth.aa.attrresolv.MAMSAttributeResolver">/usr/local/shibboleth-idp/etc/resolver.ldap.xml</ResolverConfig>
            <UserGroup>urn:mace:dir:attribute-def:eduPersonAffiliation</UserGroup>
         </GroupLookup>

         <GroupLookup implementation="au.edu.mq.melcoe.mams.sharpe.shib.aa.arp.group.provider.PropertyFileGroupLookup"
            separator="%PRINCIPAL%.">
            <PropertyFile>/usr/local/shibboleth-idp/etc/sample.grouplookup.properties</PropertyFile>
            <GroupListing>institutionalGroupList</GroupListing>
            <GroupListing>groupList</GroupListing>
         </GroupLookup>
      </ArpRepository>
   </ReleasePolicyEngine>

• The above uses sample of GroupLookup with the following scenario:
  • user's group membership is supplied by AttributeResolverGroupLookup^?, which means it will use AttributeResolver^?. This is indicated by its <UserGroup>
  • list of all groups in the system is provided by PropertyFileGroupLookup^?, which is using sample.group.properties file. In particular, it queries institutionalGroupList and groupList for its purpose.
• The above points to resolver.ldap.xml, make sure this value is the same as your resolverConfig's value as registered at the top of your idp.xml

Changes in Apache config

It is important to protect access to ShARPE to limited to users who are known by Shibboleth IdP (the host of ShARPE). For this purpose, you will need to configure appropriate section of Apache for it.

1. Find the section on Apache where you protect Shibboleth's SSO (refer to manual Shibboleth IdP configuration; usually 00X-ssl-vhost )

   Find:
   
   <Location /shibboleth-idp/SSO>
     ...
   </Location>
   
   Add:
   
   <Location /ShARPE >
   #copy whatever the content of shibboleth-idp/SSO above
   </Location>
   

Additional Changes for mod_jk or mod_jk2

Redirecting ShARPE and SPDescription to Apache front-end by mean of mod_jk is recommended.

if you use mod_jk, add the following entries to your vhost files (000-default and 00X-ssl-vhost):

   JkMount /ShARPE* shibboleth
   JkMount /SPDescription* shibboleth

if you have mod_jk2, make sure you add the following entries to workers2.properties:

   [uri:/shibboleth-idp*]
   group=lb

   [uri:/ShARPE*]
   group=lb

   [uri:/SPDescription*]
   group=lb

Testing

1. restart apache & tomcat
2. access ShARPE through https://whatever.com/ShARPE
3. access SPDescription through https://whatever.com/SPDescription

Resources

• ShARPE user's manual
• ShARPE quick test
• Advanced configuration for ShARPE
• Generating eduPersonTargetedID using ShARPE
• Uninstall ShARPE
• ShARPE Mailing List

-- BrucLiong - 24 Apr 2006
to top