Sharpe Installation Guide

The following will guide through the installation of WebSharpe (and SharpeCore) into a pre-existing IdP.

Assumptions

1. IdP is fully functional
2. IdP uses APACHE pop up window for authentication (i.e. not form authentication as provided by Tomcat)
3. tomcat 5.5 preferred
4. WebSharpe.war on http://www.federation.org.au/software/WebSharpe.war is ready
5. Java 1.5.x preferred
6. Apache 2 available with mod_jk2 to redirect requests from tomcat to apache end
7. This installation is *NIX-based. Minor adjustment requires if you are installing it into Windows environment.

Note

1. Installation of WebSharpe on tomcat webapps folder is called WEBSHARPE_TOMCAT. Typically this will be /usr/local/tomcat5/webapps/WebSharpe
2. Location of IdP configuration (as per Shib 1.3) is called SHIB_HOME. Typically this will be /usr/local/shibboleth-idp
3. Location of IdP installation on tomcat is called SHIB_TOMCAT. Typically this will be /usr/local/tomcat5/webapps/shibboleth-idp
4. Change the file location appropriately with reference to the above 3 locations. For example, if SHIB_HOME is installed at /usr/local/shibboleth-idp, then the entry file:SHIB_HOME would translate to file:/usr/local/shibboleth-idp. Configuration here shows Shib1.3 version, adjust the entry if you are using Shib1.2
5. If you are installing WebSharpe into Windows based, please make sure that ALL path specified in the configuration as follows are URL-friendly (i.e. encoded: all spaces are converted to %20, etc). For example: file:///C:/Program%20Files/Apache%20Software%20Foundation/Tomcat%205.5

Installation Steps

1. deploy WebSharpe.war into tomcat (alternatively extract it on tomcat's webapps folder)
2. go SHIB_HOME/etc and create the following folders:
   • mapper
   • services
3. Copy WEBSHARPE_TOMCAT/WEB-INF/classes/conf/crosswalk.properties to SHIB_HOME/etc/crosswalk.properties
4. Copy WEBSHARPE_TOMCAT/WEB-INF/classes/conf/services.xml to SHIB_HOME/etc/services.xml
5. modify SHIB_HOME/etc/services.xml as follow:
   • make sure the points to the location of SHIB_HOME/etc/services/ folder (as created on step 2):

     <ServiceDescriptorEngine>
         <ServiceDescriptorRepository 
            implementation="au.edu.mq.melcoe.mams.sharpe.core.service.provider.ServiceRepository">
            <Path>file:/usr/local/shibboleth-idp/etc/services/</Path>
         </ServiceDescriptorRepository>
     </ServiceDescriptorEngine>
     

6. modify WEBSHARPE_TOMCAT/WEB-INF/web.xml as follow
   • This should point to the location of SHIB_HOME where idp.xml is located:

     <context-param>
        <param-name>IdPConfigFile</param-name>
        <param-value>file:/usr/local/shibboleth-idp/etc/idp.xml</param-value>
     </context-param>
     

   • This is the IdP identifier (i.e. in this example, our IdP is known as urn:mace:federation.org.au:testfed:level-1:MY_IDP_DNS), change this according to the IdP identifier

     <context-param>
        <param-name>Shib-Identity-Provider</param-name>
        <param-value>.*:MY_IDP_DNS</param-value>
     </context-param>
     

   • This is the location crosswalk.properties as done on step 3:

     <context-param>
        <param-name>CrosswalkConfigFile</param-name>
        <param-value>file:/usr/local/shibboleth-idp/etc/crosswalk.properties</param-value>
     </context-param>
     

   • This specifies the location of folder as created on step 2:

     <context-param>
        <param-name>CrosswalkPath</param-name>
        <param-value>file:/usr/local/shibboleth-idp/etc/mapper/</param-value>
     </context-param>
     

   • This specifies location of services.xml as done on step 4:

     <context-param>
        <param-name>ServiceDescriptorConfigFile</param-name>
        <param-value>file:/usr/local/shibboleth-idp/etc/services.xml</param-value>
     </context-param>
     

7. modify apache + JK2 to redirect WebSharpe to apache end:
   • Modification on workers2.properties (usually at /etc/apache2 folder):

     #add the following info
     [uri:/WebSharpe/*]
     info=WebSharpe
     

   • modification on apache conf (003-vhost.conf or wherever shibboleth/SSO is declared): make sure the AuthName of these 2 blocks are the same and change other linkages (AuthLDAP*) accordingly. This also assumes that SHIB_TOMCAT's SSO is called "/shibboleth-idp/SSO". NOTE that we will use idp-ldap for the AUTHLDAPURL during the workshop

     <Location /WebSharpe/* >
       AuthType Basic
       AuthName "Shibboleth IdP Authentication"
       AuthLDAPBindDN uid=binduser,ou=demo,dc=mams,dc=org,dc=au
       AuthLDAPBindPassword "test"
       AuthLDAPURL "ldap://idp-ldap.mams.org.au:389/ou=demo,dc=mams,dc=org,dc=au?uid?sub?(objectClass=*)"
       require valid-user
     </Location>
     <Location /shibboleth-idp/SSO>
       AuthType Basic
       AuthName "Shibboleth IdP Authentication"
       AuthLDAPBindDN uid=binduser,ou=demo,dc=mams,dc=org,dc=au
       AuthLDAPBindPassword "test"
       AuthLDAPURL "ldap://idp-ldap.mams.org.au:389/ou=demo,dc=mams,dc=org,dc=au?uid?sub?(objectClass=*)"
       require valid-user
     </Location>
     

8. Copy WEBSHARPE_TOMCAT/WEB-INF/lib/SharpeCore.jar into SHIB_TOMCAT/WEB-INF/lib
9. Copy WEBSHARPE_TOMCAT/WEB-INF/lib/base64.jar to SHIB_TOMCAT/WEB-INF/lib
10. Copy WEBSHARPE_TOMCAT/WEB-INF/lib/xercesImpl.jar to SHIB_TOMCAT/WEB-INF/lib (if it's not there yet)
11. Copy WEBSHARPE_TOMCAT/WEB-INF/lib/xml-apis.jar to SHIB_TOMCAT/WEB-INF/lib (if it's not there yet)
12. modify SHIB_HOME/etc/idp.xml to use SharpeCore ARP System class
    • Modification of idp.xml:
    • This file needs to use SharpeCore's ARP module, hence adopt the changes accordingly, i.e. the example here shows FileSystemArpRepository^? implementation

      Change from:
      
      <ReleasePolicyEngine>
         <ArpRepository 
            implementation="edu.internet2.middleware.shibboleth.aa.arp.provider.FileSystemArpRepository">
      
      To:
      
      <ReleasePolicyEngine>
         <ArpRepository 
            implementation="au.edu.mq.melcoe.mams.sharpe.shib.aa.arp.provider.ShibFileSystemArpRepository">
      

13. modify SHIB_TOMCAT/WEB-INF/web.xml to use SharpeCore files:
    • Modification to web.xml, add the following entries in the context-param section.

      <context-param>
         <param-name>CrosswalkConfigFile</param-name>
         <param-value>file:SHIB_HOME/etc/crosswalk.properties</param-value>
      </context-param>
      <context-param>
         <param-name>CrosswalkPath</param-name>
         <param-value>file:SHIB_HOME/etc/mapper/</param-value>
      </context-param>
      <context-param>
         <param-name>ServiceDescriptorConfigFile</param-name>
         <param-value>file:SHIB_HOME/etc/services.xml</param-value>
      </context-param>
      
      
      modify from:
      
      <servlet>
         <servlet-name>IdP</servlet-name>
         <display-name>Shibboleth Identity Provider</display-name>
         <servlet-class>edu.internet2.middleware.shibboleth.idp.IdPResponder</servlet-class>
      </servlet>
      
      
      To:
      
      <servlet>
         <servlet-name>IdP</servlet-name>
         <display-name>Shibboleth Identity Provider</display-name>
         <servlet-class>edu.internet2.middleware.shibboleth.idp.ShibIdPResponder</servlet-class>
      </servlet>
      

14. modify SHIB_HOME/etc/resolver.ldap.xml file (change password etc accordingly!!!)
    • Modify resolver (example of resolver.ldap.xml shown here):

      <!--
      the following shows that a "group.member" is a special id to be
      used to indicate that the attributes are to be used to pull all
      group membership of the user. So, if we want to know user's X's
      group membership, we would query the "groups" attribute for it.
      
      the "group.listing" is used to list ALL group memberships in the
      system irrespective of the user.
      
      The following is just an example of what the content looks like,
      modify and add according to your own needs.
      
      the "group.member.testing" here shows that it refers to "groups"
      attribute in the "directory". It is CRUCIAL to ensure that there
      is existence of "groups" attribute in the "directory" connector.
      Please modify "groups" to whatever attribute that carries information
      regarding user's group information.
      
      The "group.listing.testing" example shown here specifies different
      data connector to get the information. It basically will query
      "group.listing.directory" for the list of values resolved from 
      "groups" attribute. Again, modify the attribute "groups" to 
      something corresponding to your system.
      -->
      
      <SimpleAttributeDefinition id="group.member.testing" sourceName="eduPersonAffiliation">
         <DataConnectorDependency requires="directory"/>
      </SimpleAttributeDefinition>
      
      <SimpleAttributeDefinition id="group.listing.testing" sourceName="eduPersonAffiliation">
         <DataConnectorDependency requires="group.listing.directory"/>
      </SimpleAttributeDefinition>
      
      <!--
      example of targetedID implementation by calculating hash of
      other attribute. the dependent attribute has to be declared
      somewhere in this resolver. remove this declaration if you
      have no intention
      -->
      <CustomAttributeDefinition
         id="urn:mace:dir:attribute-def:eduPersonTargetedID"
         class="au.edu.mq.melcoe.mams.sharpe.shib.aa.attrresolv.provider.CrosswalkAttributeDefinition"
         haltOnFirstFound="false">
         <AttributeDependency requires="urn:mace:dir:attribute-def:mail"/>
      </CustomAttributeDefinition>
      
      <!-- Finally the connector for group.listing is shown here -->
      <JNDIDirectoryDataConnector id="group.listing.directory" mergeMultipleResults="true">
         <Search filter="uid=*">
            <Controls returningObjects="false" searchScope="SUBTREE_SCOPE"/>
         </Search>
         <Property name="java.naming.factory.initial" value="com.sun.jndi.ldap.LdapCtxFactory"/>
         <Property name="java.naming.provider.url" value="ldap://idp-ldap.mams.org.au:389/ou=demo,dc=mams,dc=org,dc=au"/>
         <Property name="java.naming.security.principal" value="uid=binduser,ou=demo,dc=mams,dc=org,dc=au"/>
         <Property name="java.naming.security.credentials" value="test"/>
      </JNDIDirectoryDataConnector>
      

15. Check List: make sure the following has been changed in the resolver
    • group.member.XXX points to correct sourceName
    • group.listing.XXX points to correct sourceName
    • BOTH JNDI connectors point to correct LDAP settings
    • Search Filter of group.listing.directory is correct and you have permission to do such search
16. Copy WEBSHARPE_TOMCAT/WEB-INF/classes/conf/mapper.default_hashmap.xml to SHIB_HOME/etc/mapper. If this file doesn't exist, then there is no harm done except eduPersonTargetedID above is not going to be resolved properly.
17. Make sure that the resolver "mail" being resolved since targetedID above requires it. "mail" need not be released in ARP, but at least it should be mentioned and resolved in resolver.
18. Restart Apache and Tomcat. This IdP now is now using SharpeCore and ready to use WebSharpe to manage its ARPs.
19. Access your WEBSHARPE at http://IdP_HOSTNAME/WebSharpe/userLogin.jsp with login admin password test
20. If all is good, BACK UP the following fully configured files:

• copy WEBSHARPE/WEB-INF/classes/conf/ARPAdminModel.xml to WEBSHARPE/WEB-INF/classes/conf/ARPAdminModel.xml.backup
• copy SHIB_HOME/etc/resolver.ldap.xml to SHIB_HOME/etc/resolver.ldap.xml.backup
• you will need the above files for "resetting" Sharpe as mentioned in FAQs.

Limitations

1. Current WebSharpe will re-generate all ARPs everytime the user creates or modifies contracts. It is therefore RECOMMENDED that this initial release to be used solely by ADMIN alone (despite it has been designed for both normal users and admins).
2. SharpeCore is sitting on top of the current IdP. Any modification performed in WebSharpe will impact the IdP straight away. It will modify the ARPs as well as resolver file dynamically. Misconfiguration or misuse will halt the IdP.
3. As usual, report errors back to us whenever something not right happens.

Resources

• WebSharpe user manual
• How to use WebSharpe

-- BrucLiong - 16 Feb 2006
to top