• How to install ShARPE

• simplify ARPs management from tidious (and error-prone manual editing of XML) to a simple sequence of clicks
• sleek interface
• integrate with Autograph to support idCard (business card) concept
• contracts (IdP and SP agreement) management in one-roof
• allow discovery of what services the users can access before they release certain attributes

WebSharpe

References

• How to install WebSharpe to existing IdP
• How to use WebSharpe
• How to use Autograph

Complete guide to Sharpe installation, on top of existing IdP from the war file.

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 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
   • arps (if not yet existed)
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:au:federation:sp-afs.melcoe.local), change this according to the IdP identifier

     <context-param>
        <param-name>Shib-Identity-Provider</param-name>
        <param-value>.*:sp-afs.melcoe.local</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 (ssl.conf): 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*"

     <Location /WebSharpe/* >
        AuthType Basic
        AuthName "SP-AFS Authentication"
        AuthLDAPBindDN uid=binduser,ou=demo,dc=mams,dc=org,dc=au
        AuthLDAPBindPassword "aaaa"
        AUTHLDAPURL ldap://localhost/ou=demo,dc=mams,dc=org,dc=au?uid?sub?(objectClass=*)
        require valid-user
     </Location>
     <Location /shibboleth-idp/SSO>
        AuthType Basic
        AuthName "SP-AFS Authentication"
        AuthLDAPBindDN uid=binduser,ou=demo,dc=mams,dc=org,dc=au
        AuthLDAPBindPassword "aaaa"
        AUTHLDAPURL ldap://localhost/ou=demo,dc=mams,dc=org,dc=au?uid?sub?(objectClass=*)
        require valid-user
     </Location>
     

   • Modification on server.xml (usually at /TOMCAT_HOME/conf folder): make sure request.tomcatAuthentication=false is set.

     <Connector port="8009" address="127.0.0.1"
        request.tomcatAuthentication="false"
        enableLookups="false" redirectPort="8443"
        debug="0" protocol="AJP/1.3" />
     

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="groups">
         <DataConnectorDependency requires="directory"/>
      </SimpleAttributeDefinition>
      
      <SimpleAttributeDefinition id="group.listing.testing" sourceName="groups">
         <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>
      
      <!-- example of "directory" connector -->
      <JNDIDirectoryDataConnector id="directory">
         <Search filter="uid=%PRINCIPAL%">
            <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://sp-afs.melcoe.local: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="aaaa"/>
      </JNDIDirectoryDataConnector>
      
      <!-- 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://sp-afs.melcoe.local: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="aaaa"/>
      </JNDIDirectoryDataConnector>
      

15. 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.
16. 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.
17. Restart Apache and Tomcat. This IdP now is now using SharpeCore and ready to use WebSharpe to manage its ARPs.

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.

asdasdas asd -- BrucLiong - 15 Feb 2006