ArpViewer Manual Version Datum

Transcription

1 SWITCHaai ArpViewer Manual Version Datum AAI C.Witzig

2 Content 1. Introduction Functional Description Description of the Components Arpfilter Controller User_edit ArpViewer Datastore The file-based datastore The SQL datastore Table ArpUser Table ShibProvider AttrReleaseApproval ProviderAccess Installation Configuration Advanced configuration Logging Support for other JDBC databases Adding a new language or modification of supported languages Adding the user_edit web application...15 Seite 2/16

3 1. Introduction The SWITCHaai ArpViewer serves the following purposes: 1. For the user of SWITCHaai it implements a mechanism to inform him about the release of attributes to a SWITCHaai Service Provider (SP) when he accesses the SP for the first time. 2. For the administrator of a SWITCHaai Identity Provider (IdP) a. it provides a tool to implement data protection laws by requiring to obtain user consent before his/her personal attributes are released to a SP, b. it allows to collect information about the release of attributes and accesses to SP (if configured to do so). 2. Functional Description From the user s point of view the ArpViewer is an application which presents him a webpage, on which he may have to accept or decline the Terms of Use of an Shibboleth Identity Provider upon first access to the system (this option can be disabled by configuration) he can globally accept the release of all his/her attributes to any Service Provider he has to accept the release of his/her attributes upon first access to a given Service Provider (if the global release has not been approved) In addition, the user can reset his/her personal settings of the ArpViewer on a separate webpage, such that he/she will be asked again, whenever attributes have to be released. 3. Description of the Components The ArpViewer consists of three components: 1. A filter, called arpfilter, which tests whether the user consent for the release of attributes should to be obtained. 2. A servlet, called Controller, which presents a table containing the attributes to be released together with a checkbox to obtain user consent for the release of these attributes to the SP 3. A (currently) very simple administrative interface, called user_edit, where the user can perform administrative tasks on his ArpViewer settings. In the following we describe these three components Arpfilter Figure 1 shows the decision flow how the arpfilter decides whether the Controller should be invoked in order to obtain the user consent for the attribute release. Seite 3/16

4 Figure 1 arpfilter flow logic 3.2. Controller The controller presents to the user a webpage with the following information: 1. The terms of use (figure 2) (if configured) that the user has to accept. This page will only be shown if a. the user accesses the system for the first time or b. the version of the terms of use have changed since the user last accepted them. The user has to cross the checkbox I accept the terms of use in order to continue. 2. A table (figure 3) with the name and value of the user s attribute that will be released to the SP. If the user decides to release all attributes to all SP in the future, he/she can cross a checkbox at the bottom of the page. In this case the user will never have to approve the release of attributes. Seite 4/16

5 Figure 2: Terms of use JSP page Seite 5/16

6 Figure 3: Attribute release JSP page If the user presses the cancel button on the attribute release JSP page, he/she is redirected to the page shown in figure 4. Seite 6/16

7 Figure 4: Attribute release cancel button 3.3. User_edit The user_edit (see figure 5) is an optional JSP application, which allows the user to reset his/her attribute releases. The installation of this application is not required. It is only supported if the SQL datastore option is used. Seite 7/16

8 Figure 5: Reset of the attribute releases 4. ArpViewer Datastore The ArpViewer application must store the data about the attribute release approvals in a persistent datastore. The following choices for a datastore are supported: 1. File based: this is only recommended for small installations (less than 100 users) 2. mysql database: this option is fully supported 3. any SQL database, which supports the JDBC access layer. Note this option may require advanced configuration (see chapter 7). Seite 8/16

9 4.1. The file-based datastore The file-based datastore consists of an XML file. Its location is configured in the ArpViewer.properties file The SQL datastore Figure 6 shows the database schema for the SQL datastore. Figure 6: ArpViewer database schema It consists of the following database tables: Seite 9/16

10 Table ArpUser This table has an entry for every user. The entry for a given user is inserted the first time he/she accesses the ArpViewer application. ColumnName Type NULL? Comment idxarpuser Unique Id (int) No Primary key auusername String (255) No Shibboleth IdP username aulasttermsversion String (255) No Last version of the terms of use that the user has accepted aufirstaccess Timestamp No First access of the user to the ArpViewer application aulastaccess Timestamp No Most recent access to the ArpViewer application Table ShibProvider This table contains a lists of all Shibboleth Providers to which attributes have been sent in the past. ColumnName Type NULL? Comment idxshibprovider Unique Id (int) No Primary key spprovidername String (255) Yes Name of the Provider. This corresponds to the providerid of the Shibboleth metadata. Note that the value spprovidername = NULL must always be present as it is used for global attribute release flag AttrReleaseApproval This table contains the complete list of every attribute release that the user has made. ColumnNamme Type NULL? Comment idxattrreleaseapproval Unique id (int)) No Primary key araidxarpuser Ref No ArpUser.idxArpUser araidxshibprovider Ref No ShibProvider.idxShibProvider aratimestamp Timestamp No Time of the approval aratermsversion String (255) No Terms Version, when the approval was made araattributes String (variable length) No List of attributes that were release to this service provider, separated by ; ProviderAccess This table contains a history of every provider access by the users. As this information might be in conflict with your data privacy regulation, it is not stored by default. This option can be enabled in the configuration file ArpViewer.properties. Note that this table on one hand references the entry in AttributeReleaseApproval and on the other hand stores the same values as well. This is needed as the user may reset his/her login preferences, which clears all entries in the table AttributeReleaseApproval. Seite 10/16

11 ColumnName Type NULL? Comment idxprovideraccess Unique id (int) No Primary key paidxattrreleaseapproval Ref No AttrReleaseApproval.idxAttrReleaseAppr oval paidxshibprovider Ref No ShibProvider.idxShibProvider paattributessent String (variable length) Yes List of attributes that were released to this service provider, separated by ; patermsversion String (255) Yes Terms Version, when the attribute approval was made pashibhandle String (255) Yes Reserved patimestamp Timestamp No Time of attribute release 5. Installation Note: these instructions apply to Shibboleth version 1.3. Prerequisites: The following packages have to be installed before starting the installation: Java (version 1.5.x advised, ok) Shibboleth (including the Shibboleth source code as it is downloaded from the SWITCH site, normally called shibboleth-install-<version>) If the database is used, then it is advised to install it and its JDBC driver first The following steps have to be taken (on UNIX) to install the ArpViewer on an existing Shibboleth Identity Provider. 1. If the identity provider is not installed, install it according to the instructions on the SWITCHaai website. Do not start installing the ArpViewer until the Shibboleth IdP is working properly. 2. Download the ArpViewer.tat.gz file from the SWITCH website into a writeable directory, e.g. /home/user1/arpviewer 3. cd /home/user1/arpviewer/arpviewer-x.y.z (where x,y are the major, minor version number, z a RBF number) 4. Edit the file ant and set the variable ANT_HOME to the directory, where you have the downloaded version of the SWITCHaai Shibboleth IdP version (e.g. /home/user1/work/shibboleth-1.3a-install). (On Windows take the file ant.bat, to be found in the Shibboleth IdP directory and copy it to the ArpViewer directory). 5. If you are using the file-based datastore, then you can omit this step. If you are not using mysql as database, read section how to use a different database than mysql. Otherwise follow the instruction below: a. Install the MySQL database if you haven t done so b. Edit the file sql/create_db.sql and choose your password for the mysql user arpadmin (currently set to arpadmin123). Seite 11/16

12 c. Create the database and tables by executing: mysql u root p (to enter the mysql shell) \. sql/create_db.sql (to create the database) exit (to exit mysql as root) mysql u arpadmin p arpviewer (to enter the mysql shell as user arpadmin) \. sql/create_tables.sql (to create the database tables) d. Install the JDBC connector library by executing cp sql/mysql-connector-java-x.y.zbin.jar $JAVA_HOME/jre/lib/ext, where x,y,z are the version parameters of the connector library. e. If you want to test the JDBC connection, you can execute the simple test program mysqltest.java (in directory sql). It willl try to read out the table ShibProvider and is invoked by executing java mysqltest <ArpViewerDb.properties>. (<ArpViewerDb.properties> is the database properties file and is configured in step 9 below). 6. Copy the configuration templates from conf/templates into the directory conf: cp conf/templates/* conf 7. Edit the file conf/site-info.properties and enter the values that are relevant for your installation: a. ARP_VIEWER_SRC: points to the directory, where you untared the ArpViewer b. TOMCAT_DIR: points to the tomcat directory c. SHIB_WEBAPP_DIR: points to the shibboleth webapp d. ARPVIEWER_CONFIG_DIR: points to the directory, where the tomcat webapp finds its configuration file. You can safely take the default value. 8. If you want to change the default configuration (directory /etc/shibboleth/arpviewer), you have to edit the file conf/arpviewer.properties. 9. If you use an SQL datastore, then you must also edit conf/arpviewerdb.properties. Enter the password for the user arpadmin that you chose in step 6b. See section Configuration for details. 10. If you are not using the SQL datastore, you must change the database type (property ArpDbType) in conf/arpviewer.properties. 11. Edit the file conf/web.xml according to your installation. The variables that you must set according to your installation are set to the value changeme. Unless you changed the default configuration, you should only have to edit the parameter IdPConfigFile (pointing to the IdP.xml configuration file of Shibboleth) and the ServerName. 12. Do you have any terms of use? If not, make sure its is uncommented in conf/arpviewer.properties and continue with step 13. Otherwise enter the terms of use into the file conf/arpterms.xml. This file contains an empty terms of use. Have a look at the file conf/templates/arpterms_switch.xml for a real example (SWITCH VHO Identity Provider). 13. Become superuser, e.g. sudo bash 14. Build the ArpViewer distribution package: a. Make sure the Java version, with which you built shibboleth, is in your path b../ant clean c../ant build (or just./ant) Seite 12/16

13 15. Stop tomcat, e.g. /etc/init.d/tomcat5 stop 16. execute./ant deploy 17. Edit the Shibboleth-idp web.xml file (located in $TOMCAT_DIR/webapps/shibboleth-idp/WEB- INF/web.xml) and add the section for the arp_filter according to the template doc/web_shibboleth_idp.xml. Note that the arpfilter section should come after the CAS section (if CAS is being used). 18. Follow the steps in section 7 adding the user_edit webapplication if you want to enable the user_edit.jsp application. Note that this step is optional. You can safely omit it and install it at a later point. 19. If you are using apache together with tomcat, you must add the following line in httpd.conf <IfModule mod_jk.c>.. JkMount /arpviewer/* ajp13 </IfModule> 20. Start tomcat, e.g. by executing /etc/init.d/tomcat5 start and check its successful start in the tomcat logfile (e.g. /var/log/tomcat/catalina.out). 21. Exit superuser shell 22. Try to access a Shibboleth Service Provider you should now see the ArpViewer webapplication. Hint: If you want to clear the database content, you can execute the script sql/drop_tables.sql followed by sql/create_tables.sql. However, you will loose any data about attribute release approvals by the user. The arpviewer has been tested under debian using Java 1.5.1, tomcat and the MySql database. 6. Configuration The ArpViewer application has the following configuration files, which have to be configured according to your installation: site_info.properties: global installation options (such as installation directory of Shibboleth IdP, java, tomcat etc). Used by ant while deploying the application. ArpViewer.properties: global configuration options ArpViewerDb.properties: SQL database connection parameters (only needed if SQL datastore is being used). The templates for the configuration files are located in the directory conf/templates. Copy them into the directory conf and edit them according to your installation. The configuration options are described in the template files. Most configuration parameters have default values that do not have to be changed if you are not changing any of the default parameters in the entire configuration step. Parameters that must be changed have the value of changeme. Seite 13/16

14 Note that the file ArpViewerDb.properties contains the password to access the MySQL database and its read access should therefore be limited. In addition it is recommended to change the default password (changes in file sql/create_db.sql and conf/arpviewer.properties). The default installation comes with a SWITCHaai specific header, which is shown on all the screenshots of this manual. It is defined in the file websrc/header.jsp (which is identical to websrc/header_switch.jsp). If you want to change this header, then look at the files websrc/header_neutral.jsp (no header at all) or websrc/header_commented.jsp (shows you where the header text will show up in the browser window). Either modify header.jsp according to your liking or simply overwrite header.jsp with one of the other two example headers files. If your identity provider has a terms of use, then you should enter its terms into the file conf/arpterms.xml. The default version contains an explanatory sentence. See conf/templates/arpterms_switch.xml as an example for the terms of use of the SWITCHaai VHO identity provider. If you log the attribute releases to the SP (only supported in the database mode), then you may want to limit the number of entries of the table ProviderAccess. This can be achieved executing a script which deletes all entries older than a certain number of days. The java program mysqlclean.java (in directory sql) can be used to do that. It obtains the sql delete command from the file ArpViewerDb.properties. Under Unix this program can be executed by cron (see an example cron entry in sql/clean_db). Note that this program is independent of the arpviewer and is not installed automatically. 7. Advanced configuration 7.1. Logging The ArpViewer uses log4j for logging purposes. The directory conf/templates contains an example for the log4j.properties file, which must be present in the CLASSPATH in order to be active. Please note 1. that Shibboleth itself uses log4j, so this file may already be present in the shibboleth webapps 2. the ArpViewer servlet is in another webapps than shibboleth, so either the log4j.properties is also copied into this webapp or put into a directory where the ArpViewer as well as the Shibboleth webapp have access. The table below gives a list log4 debugging flags that may be useful: log4j.logger.ch.switch.aai.arpfilter.arpfilter log4j.logger.ch.switch.aai.arpviewer.controller log4j.logger.ch.switch.aai.common.arputil log4j.logger.ch.switch.aai.common.myjdbcinterface log4j.logger.ch.switch.aai.common.model.arploginfojdbc Top level debug for the arpfilter Top level debug for the ArpViewer servlet Debug for utilities, useful for observing how the user is extracted out of the request Debugging the JDBC connection and SQL statements Debugging how the user info is extracted from / stored in the database Seite 14/16

15 log4j.logger.ch.switch.aai.common.model.userarploginfo log4j.logger.ch.switch.aai.common.arpdumper log4j.logger.ch.switch.aai.common.arpblacklist log4j.logger.ch.switch.aai.common.arpconfiguration Debugging the user data Debugging how the ARP is done Debugging the blacklist Debugging the configuration 7.2. Support for other JDBC databases In principle the ArpViewer can be adapted to support any JDBC accessible database. However, only the MySQL database is currently supported. The following files might have to be changed in order to support another sql database: sql/create_db.sql: to create the database sql/create_tables.sql: to create the database tables conf/arpviewersqlcmdsmysql.properties: All SQL statements are read from this property file. These statements can be modified, as long as the names, datatypes and number of of the arguments are not changed Adding a new language or modification of supported languages The support for different languages is achieved through the use of resource bundles. The following files have to be created (or changed if the existing text should be modified), where XX is the two character language code ( de, fr, en ): lang/resources_first_xx.properties: resource file for the JSP page first.jsp (main ArpViewer application). lang/resources_useredit_xx.properties: resource bundle for the JSP page user_edit.jsp. conf/templates/arpattributedescription_xx.xml: resource bundle for the description of the Shibboleth attributes Adding the user_edit web application The user_edit application is a JSP file, where the user can reset his/her ArpViewer settings. Note that 1. it can only be deployed if you are using a SQL database as datastore (and not the file based datastore!) and 2. the ArpViewer does not require that this application is installed. There are several ways how the user_edit.jsp can be invoked, but it is always required that the username can be located from the http request. One way to achieve that is to simply protect the user_edit.jsp with CAS and SSO. In the following we present another simple solution how this application can be invoked by crossing a checkbox on a CAS login window. Thus, it is assumed that CAS is installed on the Shibboleth IdP. 1. Download the package CASExtensionFilter from the SWITCH website Seite 15/16

16 2. Install CASExtensionFilter (see doc/install.txt in CASExtensionFilter for details). a. build CASExtensionFilter using ant b. cp $CASExtensionFilter/dist/casextensionfilter.jar $TOMCAT_DIR/cas/WEB-INF/lib c. add the filter definition and filter mapping in $TOMCAT_DIR/cas/WEB-INF/web.xml. Note that the filter mapping entry should come after the CAS filter mapping entry. 3. The name of the checkbox (currently set to editarpsettings ) in the file login.jsp must match the following parameters: a. checkbox in login.jsp in webapps/cas b. parameter name in goservice.jsp in webapps/cas c. file $TOMCAT/webapps/cas/WEB_INF/attributestocheck.txt d. parameter ArpConstants.HTTP_REQ_PARAM_ARP_USEREDIT in the file ArpConstants.java (source code needs to be compiled). Seite 16/16