ArpViewer - SWITCH · 2007. 10. 11. · SWITCH – Teleinformatikdienste für Lehre und Forschung /...

SWITCHaai

SWITCH – Teleinformat ikdienste für Lehre und Forschung / Services de téléinformatique pour l ’enseignement et la recherche SWITCH / P.O. Box / CH-8021 Zür ich www.switch.ch

ArpViewer Manual Version 1.0.6 Datum 30.9.2007

AAI

C.Witzig

Seite 2/16 SWITCH – Teleinformat ikdienste für Lehre und Forschung / Services de téléinformatique pour l ’enseignement et la recherche SWITCH / P.O. Box / CH-8021 Zür ich www.switch.ch

Content 1. Introduction...................................................................................................................3 2. Functional Description ..................................................................................................3 3. Description of the Components.....................................................................................3

3.1. Arpfilter ..................................................................................................................3 3.2. Controller................................................................................................................4 3.3. User_edit .................................................................................................................7

4. ArpViewer Datastore ....................................................................................................8 4.1. The file-based datastore..........................................................................................9 4.2. The SQL datastore..................................................................................................9

4.2.1. Table ArpUser................................................................................................10 4.2.2. Table ShibProvider ........................................................................................10 4.2.3. AttrReleaseApproval .....................................................................................10 4.2.4. ProviderAccess ...............................................................................................10

5. Installation ...................................................................................................................11 6. Configuration ..............................................................................................................13 7. Advanced configuration ..............................................................................................14

7.1. Logging..................................................................................................................14 7.2. Support for other JDBC databases ......................................................................15 7.3. Adding a new language or modification of supported languages .......................15 7.4. Adding the user_edit web application..................................................................15


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.

3.1. 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.


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.

Figure 1 arpfilter flow logic


Figure 2: Terms of use JSP page


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.


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.


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).


4.1. The file-based datastore The file-based datastore consists of an XML file. Its location is configured in the ArpViewer.properties file.

4.2. 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:


4.2.1. 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

4.2.2. 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

4.2.3. 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 ‘;’

4.2.4. 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.


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, 1.4.2 ok) • Shibboleth (including the Shibboleth source code as it is downloaded from the SWITCH site,

normally called shibboleth-install-) • 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).


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.z-bin.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 ’. (’ 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)


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

…….. JkMount /arpviewer/* ajp13

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 5.5.9 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”.


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 Top level debug for the arpfilter log4j.logger.ch.SWITCH.aai.arpviewer.Controller Top level debug for the ArpViewer

servlet log4j.logger.ch.SWITCH.aai.common.ArpUtil Debug for utilities, useful for observing

how the user is extracted out of the request

log4j.logger.ch.SWITCH.aai.common.myJdbcInterface Debugging the JDBC connection and SQL statements

log4j.logger.ch.SWITCH.aai.common.model.ArpLogInfoJdbc Debugging how the user info is extracted from / stored in the database


log4j.logger.ch.SWITCH.aai.common.model.UserArpLogInfo Debugging the user data log4j.logger.ch.SWITCH.aai.common.ArpDumper Debugging how the ARP is done log4j.logger.ch.SWITCH.aai.common.ArpBlackList Debugging the blacklist log4j.logger.ch.SWITCH.aai.common.ArpConfiguration 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.

7.3. 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.

7.4. 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


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).

ArpViewer - SWITCH · 2007. 10. 11. · SWITCH – Teleinformatikdienste für Lehre und Forschung /...

Documents

Transcript of ArpViewer - SWITCH · 2007. 10. 11. · SWITCH – Teleinformatikdienste für Lehre und Forschung /...