Autograph Installation
Autograph is a Java Servlet application that has been designed to work with Shibboleth 1.3.3. The following instructions detail how to install this Autograph distribution under Tomcat on a Debian system.
This Autograph package consists of three main compontents:
- Autograph.war: the main Autograph application
- Autograph-SSO.jar: the Single Sign On compontent to be integrated with a Shibboleth IdP
- mams-sharpe.tgz: extensions to Shibboleth IdP provided by ShARPE, required by Autograph
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.)
Conventions and Definitions
-
SHIB_IDP_HOME is the home directory of the Shibboleth installation (e.g. /usr/local/shibboleth-idp).
-
TOMCAT_HOME is the home directory of the Tomcat server (e.g. /usr/local/tomcat).
Installation Procedure
1. Copy the file 'Autograph.war' to the directory TOMCAT_HOME/webapps and restart Tomcat. This will cause the war file to be automatically
unpacked. If you are not protecting your Shibboleth
IdP using Tomcat you should remove the entire
security-constraint tag from the file TOMCAT_HOME/webapps/Autograph/WEB-INF/web.xml
2. Copy the files 'Autograph-SSO.jar' and 'mams-idp-ext.jar' to the directory TOMCAT_HOME/webapps/shibboleth-idp/WEB-INF/lib
3. Modify the file TOMCAT_HOME/webapps/shibboleth-idp/WEB-INF/web.xml to reflect the following changes (required to configure Autograph to pop up during the SSO login flow):
Add a
tags for the AutographRedirectionSwitch? and AutographRedirectionSwitch?_Return:
<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>
<servlet>
<servlet-name>AutographRedirectionSwitch_Return</servlet-name>
<display-name>Autograph Redirection Switch</display-name>
<servlet-class>
au.edu.mq.melcoe.mams.autograph.AutographRedirectionSwitch_Return
</servlet-class>
</servlet>
Modify the tag for the IdP servlet to the URL /IdP:
<servlet-mapping>
<servlet-name>IdP</servlet-name>
<url-pattern>/IdP</url-pattern>
</servlet-mapping>
Add new tags for the two Autograph servlets:
<servlet-mapping>
<servlet-name>AutographRedirectionSwitch_Return</servlet-name>
<url-pattern>/AutographRedirectionSwitch_Return</url-pattern>
</servlet-mapping>
<servlet-mapping>
<servlet-name>AutographRedirectionSwitch</servlet-name>
<url-pattern>/SSO</url-pattern>
</servlet-mapping>
In the mapping above the /SSO URL that was previously mapped to the Shibboleth IdP Responder is now mapped to the AutographRedirectionSwitch?. This is the mechanism by which Autograph inserts itself into the SSO flow.
4. The IdP's main configuration file SHIB_IDP_HOME/etc/idp.xml must also be modified to use the MAMSFileSystemArpRepository (from FileSystemArpRepository?) and to reflect that the Shibboleth IdP Responder (ShibbolethV1SSOHandler?) is now mapped to the URL /shibboleth-idp/IdP (from /shibboleth-idp/SSO):
<ReleasePolicyEngine>
<ArpRepository implementation="au.edu.mq.melcoe.mams.sharpe.shib.aa.arp.provider.MAMSFileSystemArpRepository">
<Path>/usr/local/shibboleth-idp/etc/arps/</Path>
</ArpRepository>
</ReleasePolicyEngine>
<ProtocolHandler implementation=
"edu.internet2.middleware.shibboleth.idp.provider.ShibbolethV1SSOHandler">
<Location>https?://[^:/]+(:(443|80))?/shibboleth-idp/IdP</Location>
</ProtocolHandler>
5. The deployment descriptor for Autograph (TOMCAT_HOME/webapps/Autograph/WEB-INF/web.xml) contains a context parameter that sets the location of the Autograph configuration file:
<context-param>
<param-name>AutographConfigurationFileLocation</param-name>
<param-value>./WEB-INF/AutographConfiguration.properties</param-value>
</context-param>
The default setting is to have this configuration file within the web application, you may wish to move it to avoid losing any custom settings when upgrading at a later date.
NOTE: This file also contains the tags and , required if Autograph is to be protected by Tomcat. If Autograph is to be protected by Apache (or some other means), remove
these tags.
6. The configuration file AutographConfiguration?.properties contains a further setting that defines the location of the directory to store state information about end users. By default this directory is also within the web application. It is recommended that this be redefined to a location outside the web application to avoid the erasure of these files during a future upgrade of Autograph:
userProfileDir = WEB-INF/homeDir/userProfiles
7. The Autograph web application must be protected using the same account the user would login to when accesing a Shibboleth-protected resource.Autograph should also be protected using the same mechanism as the
/shibboleth-idp/* URLs to prevent the user from being prompted to enter their credentials twice. If Tomcat Authentication is used, the following line must be present in Tomcat's server.xml configuration file:
<Valve className="org.apache.catalina.authenticator.SingleSignOn" />
This SingleSignOn? valve is what allows Tomcat to reuse the existing authentication session.
8. If ShARPE is not installed on this IdP, the mams-sharpe.tgz tar file will need to be expanded into SHIB_IDP_HOME/etc. This file contains the IdP extensions that are provided by ShARPE and required by Autograph.
9. Ensure that the entire Autograph web application as well as the directory SHIB_IDP_HOME/etc/mams-sharpe are owned by the user Tomcat runs as.For example:
cd TOMCAT_HOME/webapps
chown -R tomcat55:adm Autograph
cd SHIB_IDP_HOME/etc
chown -R tomcat55:adm mams-sharpe
10. Forward requests for "/Autograph/*" to Tomcat (JkMount?, ModProxy etc) For example, when using ModJk? a JkMount line must be added to the appropriate virtual host such as this:
JkMount /Autograph* tomcatAuth
This line forwards any request for a URL beginning with Autograph to the Tomcat worker called tomcatAuth. This worker is defined in the file workers.properties and, in this instance, looks like this:
workers.tomcat_home=/usr/local/tomcat
workers.java_home=/usr/lib/jvm/java-1.5.0-sun
ps=/
worker.list=apacheAuth tomcatAuth
# Definition for local worker using AJP 1.3
# worker.apacheAuth.type=ajp13
worker.apacheAuth.host=localhost
worker.apacheAuth.port=8009
worker.tomcatAuth.type=ajp13
worker.tomcatAuth.host=localhost
worker.tomcatAuth.port=8010
11. Restart Tomcat and Apache.
12. Test by visiting https://locahost/Autograph/Login_AAF
Configuration Options
Autograph is configured by editing the file AutographConfiguration?.properties, stored in the applications WEB-INF directory by default. The location of this configuration file is determined by the Context Parameter AutographConfigurationFileLocation? in Autograph's web.xml.
idpConfigurationFile
The full name of the idp.xml file from the root of the filesystem. ie. /usr/local/shibboleth-idp/etc/idp.xml
idpURL
The URL of the Shibboleth IdP Autograph is installed with (usually /shibboleth-idp/IdP).
userProfileDir
The directory to store state information about Autograph end users.
displayAgreement
When to display the Terms and Conditions page:
once | never | always | new_service_provider (once per SP)
displayAutographSSO
Should Autograph popup when a user accesses a Service Provider?:
never | always | new_service_provider (once per SP until "always release this information" is checked by end user)
blockOnNoService
Should Autograph display the "Go to Service Provider" button if no Service Offerings are currently enabled:
true | false
blockOnNoSOs
Should Autograph display the "Go to Service Provider" button if no Service Offerings are available. NOTE: This could be because there are no Service Offerings defined for this SP (non-AAF SP), or the end user does not have the attributes required to enabled any of the defined Service Offerings.
true | false
to top