Installation of uApprove.jp with uApprove-2.1.3

// ----------------------------------------------------------------------------
0. Reference
   You may want to refer installation manual for original uApprove-2.1.3:
   https://www.switch.ch/aai/downloads/uApprove-2.1.3-manual.html

// ----------------------------------------------------------------------------
1. Installation of Shibboleth IdP 2.1.3
   After installation of the Shibboleth IdP, run tomcat once to
   deploy files in $TOMCAT_HOME/webapps/idp.war.

// ----------------------------------------------------------------------------
2. Installation of database
   The uApprove uses database to preserve user preferences.
   Use of MySQL is recommended. File-base DB is also provided
   for small sites of less than 100 users. Basic configuration
   of DB is as same as the manual of uApprove-2.1.3 by SWITCH.
   https://www.switch.ch/aai/downloads/uApprove-2.1.3-manual.html
   The uApprove.jp uses another table name of DB.

// ----------------------------------------------------------------------------
3. Installation of the original uApprove with uApprove.jp

3-1. create a directory for configurations
   mkdir /opt/shibboleth-idp/uApprove (can be changed)

3-2. get uApprove.jp-2.1.3-bin.zip and unzip

3-3. unzip 2 archives included in uApprove.jp-2.1.3-bin.zip
   cd uApprove.jp-2.1.3
   unzip idp-plugin-2.1.3-bin.zip
   unzip viewer-2.1.3-bin.zip

3-4. copy IdP plugin files into the IdP system
   cp idp-plugin-2.1.3/conf-template/* /opt/shibboleth-idp/uApprove
   cp idp-plugin-2.1.3/lib/* $TOMCAT_HOME/webapps/idp/WEB-INF/lib/
     The following files are stored in the idp-plugin-2.1.3/lib directory
	bcprov-jdk15-140.jar
	commons-cli-1.1.jar
	idp-plugin-2.1.3.jar
	mysql-connector-java-5.1.6.jar
	common-2.1.3.jar
	commons-logging-1.1.1.jar
	json-simple-1.0.jar
	vt-crypt-2.0.jar
	shibboleth-uApprove-1.0.0.jar (new module for uApprove.jp)

3-5. copy viewer files into the IdP system
   cp viewer-2.1.3/conf-template/* /opt/shibboleth-idp/uApprove
   (There are some duplicated files which has same content as files
   of IdP plugin.)
   cp -r viewer-2.1.3/webapp $TOMCAT_HOME/webapps/uApprove

// ----------------------------------------------------------------------------
4. Configuration of uApprove.jp

4-1. edit path in config files copied into /opt/shibboleth-idp/uApprove
    (default is /path/to/config)

4-2. edit /opt/shibboleth-idp/uApprove/common.properties
   termsOfUse=/opt/shibboleth-idp/uApprove/terms-of-use.xml	<= HERE (DIR)
   storageType=database	<= ENABLE
   databaseConfig=/opt/shibboleth-idp/uApprove/database.properties	<= HERE (ENABLE)
   #storageType=file	<= DISABLE
   #flatFile=/path/to/config/uApprove-log.xml	<= DISABLE

4-3. edit /opt/shibboleth-idp/uApprove/database.properties
   parameters to access DB
   password=uApprove	<= HERE
   sqlCommands=/opt/shibboleth-idp/uApprove/mysql.commands	<= HERE (DIR)

4-4. edit /opt/shibboleth-idp/uApprove/idp-plugin.properties
   spBlacklist = /opt/shibboleth-idp/uApprove/sp-blacklist	<= HERE (DISABLE)
   uApproveViewer=https://idp.example.org/uApprove/Controller	<= HERE (URL)

4-5. edit /opt/shibboleth-idp/uApprove/viewer.properties
   useLocale = en_US	<= HERE (CHARSET)
   attributeList=/opt/shibboleth-idp/uApprove/attribute-list	<= HERE (DIR)
   loggingConfig=/opt/shibboleth-idp/uApprove/logging.xml	<= HERE (DIR)

4-6. edit /opt/shibboleth-idp/uApprove/attribute-list
    Attributes described in this list will be shown for user consent before
    release.
    Attribute names must be same as id of <resolver:AttributeDefinition>
    defined in attribute-resolver.xml. Adding prefix "!" on attribute
    names to hide from list shown for user consent, to release without
    user consent according to policy of attribute-filter.
    The following attribute names should be defined:
	eduPersonPrincipalName
	eduPersonTargetedID
        organizationName
        organizationalUnit
        eduPersonEntitlement
        eduPersonAffiliation
        eduPersonScopedAffiliation
        email
        givenName
        surname
        displayName
        jasurname
        jagivenName
        jadisplayName
        jaorganizationName
        jaorganizationalUnit

    uApprove.jp will require re-consent when any value of attribute
    to be released is changed even if the user already allowed once to relase.
    But attributes with prefix "!" will not cause re-consent.

4-7. edit /opt/shibboleth-idp/uApprove/logging.xml
   <file>/opt/shibboleth-idp/log/uApprove.log</file>	<= HERE (DIR)

// ----------------------------------------------------------------------------
5. Configuration of IdP

5-1. Add settings for tomcat configuration to work with uApprove plugin
   edit $TOMCAT_HOME/webapps/idp/WEB-INF/web.xml and add <filter> and
   <filter-mapping> element in the <web-app> definition.

     <web-app>
     :
       <filter>
         <filter-name>uApprove IdP plugin</filter-name>
         <filter-class>
           ch.SWITCH.aai.uApprove.idpplugin.Plugin
         </filter-class>
         <init-param>
           <param-name>Config</param-name>
           <param-value>
             /opt/shibboleth-idp/uApprove/idp-plugin.properties;
             /opt/shibboleth-idp/uApprove/common.properties;
           </param-value>
         </init-param>
       </filter>

       <filter-mapping>
         <filter-name>uApprove IdP plugin</filter-name>
         <url-pattern>/profile/*</url-pattern>
         <dispatcher>REQUEST</dispatcher>
         <dispatcher>FORWARD</dispatcher>
       </filter-mapping>
      :	  ...
     <web-app>

5-2. Add a checkbox to reset previous consent
   edit $TOMCAT_HOME/webapps/idp/login.jsp

5-3. How to configure attribute-filter to utilize uApprove.jp
   uApprove.jp provides a new filter "AttributeUpprove".
   Configure /opt/shibboleth-idp/conf/attribute-filter.xml according to
   policy of your site.

   Define namespace "http://upki-portal.nii.ac.jp/docs/fed/ns/uapprove-jp"
   in <AttributeFilterPolicyGroup> to enable "AttributeUpprove"
     <AttributeFilterPolicyGroup id="ShibbolethFilterPolicy"
       xmlns="urn:mace:shibboleth:2.0:afp"
       xmlns:basic="urn:mace:shibboleth:2.0:afp:mf:basic"
       xmlns:saml="urn:mace:shibboleth:2.0:afp:mf:saml"
       xmlns:uapprove="http://upki-portal.nii.ac.jp/docs/fed/ns/uapprove-jp" <=HERE
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="urn:mace:shibboleth:2.0:afp
       classpath:/schema/shibboleth-2.0-afp.xsd
       urn:mace:shibboleth:2.0:afp:mf:basic
       classpath:/schema/shibboleth-2.0-afp-mf-basic.xsd
       urn:mace:shibboleth:2.0:afp:mf:saml
       classpath:/schema/shibboleth-2.0-afp-mf-saml.xsd
       http://upki-portal.nii.ac.jp/docs/fed/ns/uapprove-jp
       classpath:/schema/shibboleth-2.0-afp-mf-uapprove.xsd"> <=HERE

   add AttributeFilterPlicy for uApprove in <AttributeFilterPolicyGroup>

   Pattern A: "permit by uApprove.jp"
     - only one AttributeRule is applied to the SP

     <AttributeFilterPolicy id="PolicyforUapproveSP">
       <PolicyRequirementRule xsi:type="uapprove:AttributeUapprove" />

       <AttributeRule attributeID="eduPersonPrincipalName">
         <PermitValueRule xsi:type="uapprove:AttributeUapprove" />
       </AttributeRule>
       :
     </AttributeFilterPlicy>

   Pattern B: "deny by uApprove.jp"
     - combination of AttributeRule is applied to the SP

     <AttributeFilterPolicy id="PolicyforAnyone">
       <PolicyRequirementRule xsi:type="basic:ANY" />
       :
       <AttributeRule attributeID="eduPersonPrincipalName">
         <PermitValueRule xsi:type="basic:ANY" />
       </AttributeRule>
     </AttributeFilterPolicy>

     <AttributeFilterPolicy id="PolicyforUapproveSP">
       <PolicyRequirementRule xsi:type="uapprove:AttributeUapprove" />
       :
       <AttributeRule attributeID="eduPersonPrincipalName">
         <DenyValueRule xsi:type="uapprove:AttributeUapprove"
           isApproved="false"/>
       </AttributeRule>
       :
     </AttributeFilterPlicy>

   isApproved boolean of uApprove:AttributeUapprove will be set
     true  - if user allows to release the attribute
     false - if user denies to release the attribute

// ----------------------------------------------------------------------------
6. Configuration of uApprove web

6-1. Configuration in $TOMCAT_HOME/webapps/uApprove/WEB-INF/web.xml
     (change directory location)
     <web-app>
     :
       <context-param>
         <param-name>Config</param-name>
         <param-value>
           /opt/shibboleth-idp/uApprove/viewer.properties;	<= HERE
           /opt/shibboleth-idp/uApprove/common.properties;	<= HERE
         </param-value>
       </context-param>
      :
     <web-app>

6-2. Configuration in Apache
   Add the following configuration in /etc/httpd/conf.d/ssl.conf
     <VirtualHost _default_:443>
     :
     ProxyPass /uApprove/ ajp://localhost:8009/uApprove/	<= HERE
     :
     </VirtualHost>

7. Specifing mandatory attributes in SP matadata
   Add <RequestedAttribute> element in <AttributeConsumingService>
   of <SPSSODescriptor>
   Mandatory attributes must have isRequired="true" setting in the
   <RequestedAttribute> element.

   Example:
     <AttributeConsumingService index="1" isDefault="true">
       <ServiceName xml:lang="en">Sample Service</ServiceName>
       <ServiceDescription xml:lang="en">An example service
         that requires a human-readable identifier and optional
         name and e-mail address.
       </ServiceDescription>
       <RequestedAttribute FriendlyName="eduPersonPrincipalName"
         Name="urn:mace:dir:attribute-def:eduPersonPrincipalName"
         NameFormat="urn:mace:shibboleth:1.0:attributeNamespace:uri"
         isRequired="true">
       </RequestedAttribute>
       <RequestedAttribute FriendlyName="mail"
         Name="urn:mace:dir:attribute-def:mail"
         NameFormat="urn:mace:shibboleth:1.0:attributeNamespace:uri">
       </RequestedAttribute>
       <RequestedAttribute FriendlyName="displayName"
         Name="urn:mace:dir:attribute-def:displayName"
         NameFormat="urn:mace:shibboleth:1.0:attributeNamespace:uri">
       </RequestedAttribute>
     </AttributeConsumingService>

// ----------------------------------------------------------------------------
8. Restart of tomcat, httpd

// ----------------------------------------------------------------------------

A. Appendix
A-1. compilation of uApprove.jp
   unzip uApprove-2.1.3-src.zip
   apply uApprove-jp-2.1.3.patch in the uApprove-2.1.3 directory
     cd uApprove-2.1.3
     patch -p1 < $WORKDIR/uApprove-jp-2.1.3.patch
   compile source files
     mvn clean compile jar:jar
   (Maven must be installed to compile)

A-2. compilation of shibboleth-uApprove
   extract files from shibboleth-uApprove-1.0.0.tgz
   compile source files in shibboleth-uApprove-1.0.0 directory
     cd shibboleth-uApprove-1.0.0
     mvn clean compile jar:jar

[EOF]