Installation of Autograph

Autograph is a web application. This page shows the steps necessary to get Autograph running on your Identity Provider (IdP). You can start with the installation process if the preconditions are fullfilled.

Preconditions

• An IdP is set up and running properly in a Shibboleth federation. (Autograph is tested with Shibboleth 1.3c.)

• A Tomcat application server is available. (Autograph is tested with Tomcat5.5.)

• You downloaded the web archive (Autograph.war).

Conventions and Definitions

• SHIB_IDP_HOME is the home directory of the Shibboleth installation (e.g. /usr/local/shibboleth-home).

• TOMCAT_HOME is the home directory of the Tomcat server (e.g. /usr/local/tomcat5).

• AUTOGRAPH_HOME is the home of the Autograph installation. By default it is TOMCAT_HOME/webapps/Autograph/WEB-INF/homeDir. When Autograph is used in production it is a good idea to move this directory to another location, otherwise it can be easily overwritten by accidently redeploying the application.

Installation Steps

Deploying the Web Application

• Shutdown Tomcat
  :~# TOMCAT_HOME/bin/shutdown.sh

• Copy the Autograph.war in the TOMCAT_HOME/webapps directory.

• Startup Tomcat
  :~# TOMCAT_HOME/bin/startup.sh

Test: Open the url http://YOUR_HOST:CONNECTOR_PORT/Autograph/view/adminLogin.jsp in a browser. You should see an Autograph login form.

Changing Main Configuration File

AUTOGRAPH_HOME/IAMConfiguration.xml is the main configuration file. It describes where additional configuration information can be found.

• Change the default value (/usr/local/shibboleth-idp) of the SHIB_IDP_HOME property to your shibboleth home path.

• Change the default value (%SHIB_IDP_HOME%/etc/resolver.ldap.xml) of the attributeResolverFileLocation property to the path of the resolver configuration file that is used by your IdP.

• Change the default value (%SHIB_IDP_HOME%/etc/idp.xml) of the idPConfigFileLocation property to the path of the IdP configuration file that is used by your IdP. (Attention: 2 occurencies)

Test: Stop Tomcat; delete the TOMCAT_HOME/logs/Autograph.log file; restart Tomcat; there shouldn't be any ERROR messages in the just created Autograph.log file.

Attribute Configuration

The attributes Autograph shall be aware of have to be defined in the AUTOGRAPH_HOME/connectorConfigs/AttributeInfoPointData.xml file. This file is used by the AttributeInfoPoint connector.

• Go to the AttributeInfoPointData.xml file and add, according to the given examples, all attributes that the user is supposed to see on his idCard if released.

Test: Open the url http://YOUR_HOST:CONNECTOR_PORT/Autograph/view/adminLogin.jsp in a browser. Log into Autograph by using an uid (user id) of an user for whom at least one attribute is released. This attribute should also be one of the attributes that you've defined in the step before. The default password is 'test'.
You should see the the Autograph window with the menu on the left. Select 'SP specific idCards' and choose a Service Provider from the drop down list. The idCard for this Service Provider should show the released attributes for the user.

Protecting Autograph

There are two ways to log into Autograph. First, IdP admins who know the Autograph password can log in as any IdP member using the /Autograph/view/adminLogin.jsp URL. Second, IdP members can log in with their password using the URL /Autograph/Login . This URL has to be protected.
To enable a smooth integration of Autograph in the Single Sign On profile, the /Autograph/Login URL has to be protected in exactly the same way as the /SSO URL of the IdP. More instructions on how to achieve this can be found here.

Test: Open the URL http://YOUR_HOST/Autograph/Login (maybe with https) in a browser. You should be asked to authenticate using the Shibboleth procedure. After that the Autograph page should show up.

Including Autograph in the Single Sing On (SSO) profile

You find background information on the integration of Autograph in SSO here. The necessary steps to enable the integration are listed here:

Some changes have to made to the shibboleth IdP application descriptor (TOMCAT_HOME/webapps/shibboleth-idp/WEB-INF/web.xml). Have a look at the example.

• Create a <context-param/> element like this:(replace the content of the <param-name/> element with AUTOGRAPH_HOME/userProfiles)
  

<context-param>
    <param-name>userProfileStorePath</param-name>
    <param-value>/usr/local/tomcat/webapps/Autograph/WEB-INF/homeDir/userProfiles</param-value>
</context-param>


• Create following <servlet/> element:

<servlet>
    <servlet-name>AutographRedirectionSwitch</servlet-name>
    <display-name>Autograph Redirection Switch</display-name>
    <servlet-class>au.edu.mq.melcoe.mams.autograph.AutographRedirectionSwitch</servlet-class>
</servlet>


• Create following <servlet-mapping/> element:

<servlet-mapping>
    <servlet-name>AutographRedirectionSwitch</servlet-name>
    <url-pattern>/SSO</url-pattern>
</servlet-mapping>


• Change the existing <servlet-mapping/> element from

<servlet-mapping>
    <servlet-name>IdP</servlet-name>
    <url-pattern>/SSO</url-pattern>
</servlet-mapping>


to

<servlet-mapping>
    <servlet-name>IdP</servlet-name>
    <url-pattern>/IdP</url-pattern>
</servlet-mapping>


Changes to idp.xml, locate the ProtocolHandler^? (from /SSO to /IdP):

    Change FROM:
        .../shibboleth-idp/SSO</Location>

    TO:
        .../shibboleth-idp/IdP</Location>

Finally the AutrographRedirectionSwitch class has to be made available.

• Copy the TOMCAT_HOME/webapps/Autograph/WEB-INF/lib/autograph-redirection-switch.jar file to the TOMCAT_HOME/webapps/shibboleth-idp/WEB-INF/lib directory.

• Copy the TOMCAT_HOME/webapps/Autograph/WEB-INF/lib/jdom.jar file to the TOMCAT_HOME/webapps/shibboleth-idp/WEB-INF/lib directory.

• Copy the TOMCAT_HOME/webapps/Autograph/WEB-INF/lib/jaxen-1.1-beta-6.jar file to the TOMCAT_HOME/webapps/shibboleth-idp/WEB-INF/lib directory.

Test: go to a Service Provider of your Federation; authenticate against your just configured IdP;
You should see the Autograph GUI. Follow the instructions. Finally you should come to the Service Provider by clicking the 'go to Service Provider using this idCard' button. (see also basic Autograph scenario (Flash))

Making use of Service Provider Description files (SPDs)

In order to predict the effects of denying or permitting the release of attributes SPDs are necessary. The SPD files have to be placed in AUTOGRAPH_HOME/SPDs directory to make them accessible for the SPDConnector. The SPDs have to be valid against the AUTOGRAPH_HOME/SPDs/schemas/ServiceDescriptor.xsd schema.
There is not yet a standard way of distributing the Service Provider Descriptions in the Federation, because the requirements for this distribution mechanism are not clear and also vary. A straight forward approach could be to have a cron job updating the AUTOGRAPH_HOME/SPDs directory with a central SPD repository where all the SPDs are maintained. How this maintenance is done is also not yet defined.
to top