Academic History Web Service Configuration Guide

Added by Steve Wheat, last edited by Steve Wheat on Dec 15, 2009  (view change)

Purpose

The purpose of this guide is to assist in the configuration of the Academic History Web Service to use alternate authentication methods and student information systems.  For instructions on how to get up and running with a demonstration version of the Academic History Web Service in a web service framework, see the Quick Start Guide.  For more detailed background on what the Academic History Web Service is, how it works, and why it is useful, see the Academic History Web Service Deployment Guide.  To develop custom authenticators and providers for the service, see the Developer's Guide[].

Configuring Authentication Methods

The Academic History Web Service uses pluggable components called Authenticators to authenticate service users and return a Student object which can be passed to the AcedmicHistoryProvider to retrieve and AcademicHistory.  The OpenEAI Academic History Web Service package presently includes two implementations of the Authenticator, these are:

  • DummyAuthenticator (does no authentication, just returns a student object)
  • DirectoryAuthenticator (authenticates a user against and LDAP or Active Directory)

The project plans to add more Authenticators as they become available through experimentation and implementation at various sites.  Sites can also implement their own authenticators.  For example, Midland's Tech has implemented their own Authenticator that authenticates students against their Datatel Student Information system.  AcademyOne has implemented a BannerAuthenticator in its work implementing the web service at sites that use SunGard Banner as a student information system.  The following is a list of known Authenticators and who is using them.  These Authenticators may or may not be available for use by other sites, depending on the nature of the Authenticator.  The OpenEAI Project is working with people who develop Authenticators to get them worked into the open source release whenever possible and whenever intellectual property rules allow such sharing.

  • DatatelAuthenticator (authenticates a student against Datatel at Midland's Tech)
  • BannerAuthenticator (authenticates a student against Banner with the same pricipal and credential they would use for Banner self service)

To change authentication method, one must change the value of the authenticatorClassName property in the GeneralProperties object of the AcademicHistoryRequest command.  This can be found in the AcademicHistoryService.xml file of your deployment.  If your deployment looks like the Quick Start package openeai-academichistory-tomcat-1.0 it is located in AHWS_HOME/configs/messaging/Environments/Examples/Deployments/AcadmicHistoryService.xml.  The following is an example from that file:

<PropertyConfig name="GeneralProperties">
	<ConfigClass>org.openeai.config.PropertyConfig</ConfigClass>
	<Property>
		<PropertyName>responseDocumentUri</PropertyName>
		<PropertyValue>./message/releases/com/academyone/Student/AcademicHistory/1.0/xml/Provide-Reply.xml</PropertyValue>
	</Property>
	<Property>
		<PropertyName>authenticatorClassName</PropertyName>
		<PropertyValue>org.openeai.services.academichistory.DummyAuthenticator</PropertyValue>
	</Property>
	<Property>
		<PropertyName>academicHistoryProviderClassName</PropertyName>
		<PropertyValue>org.openeai.services.academichistory.DummyAcademicHistoryProvider</PropertyValue>
	</Property>
</PropertyConfig>

To change the web service to use the DirectoryAuthenticator, specify its class name instead of the DummyAuthenticator.  For example:

<PropertyConfig name="GeneralProperties">
	<ConfigClass>org.openeai.config.PropertyConfig</ConfigClass>
	<Property>
		<PropertyName>responseDocumentUri</PropertyName>
		<PropertyValue>./message/releases/com/academyone/Student/AcademicHistory/1.0/xml/Provide-Reply.xml</PropertyValue>
	</Property>
	<Property>
		<PropertyName>authenticatorClassName</PropertyName>
		<PropertyValue>org.openeai.services.academichistory.DirectoryAuthenticator</PropertyValue>
	</Property>
	<Property>
		<PropertyName>academicHistoryProviderClassName</PropertyName>
		<PropertyValue>org.openeai.services.academichistory.DummyAcademicHistoryProvider</PropertyValue>
	</Property>
</PropertyConfig>

In addition to specifying the authenticatorClassName, one may also need to add a properties object for configurable parameters of the Authenticator.  This will vary by Authenticator and the configurable parameters should be documented in the Javadoc and other documentation of the Authenticator.  For example, DirectoryAuthenticator requires a properties object called "DirectoryProperties".  The following is an example of how to configure DirectoryProperties for an LDAP directory:

<PropertyConfig name="DirectoryProperties">
	<ConfigClass>org.openeai.config.PropertyConfig</ConfigClass>
	<Property>
		<PropertyName>providerUrl</PropertyName>
		<PropertyValue>ldap://ldaptest.openeai.org:389</PropertyValue>
	</Property>
	<Property>
		<PropertyName>searchBase</PropertyName>
		<PropertyValue>ou=Test,ou=People,dc=openeai,dc=org</PropertyValue>
	</Property>
	<Property>
		<PropertyName>userDirectoryTreeBase</PropertyName>
		<PropertyValue>ou=Test,ou=People,dc=openeai,dc=org</PropertyValue>
	</Property>
	<Property>
		<PropertyName>initialContextFactory</PropertyName>
		<PropertyValue>com.sun.jndi.ldap.LdapCtxFactory</PropertyValue>
	</Property>
	<Property>
		<PropertyName>securityPrincipal</PropertyName>
		<PropertyValue>cn=AcademicHistoryWebService,dc=openeai,dc=org</PropertyValue>
	</Property>
	<Property>
		<PropertyName>securityCredentials</PropertyName>
		<PropertyValue>secret</PropertyValue>
	</Property>
	<Property>
		<!-- Set this to true for detailed logging messages from the authenticator. -->
		<PropertyName>verbose</PropertyName>
		<PropertyValue>false</PropertyValue>
	</Property>
	<Property>
		<!-- Set this to true to log the user credential to the log file. -->
		<PropertyName>logPassword</PropertyName>
		<PropertyValue>false</PropertyValue>
	</Property>
	<Property>
                <!-- The attribute your directory uses for first name -->
		<PropertyName>firstNameAttributeName</PropertyName>
		<PropertyValue>givenName</PropertyValue>
	</Property>
	<Property>
                <!-- The attribute your directory uses for last name -->
		<PropertyName>lastNameAttributeName</PropertyName>
		<PropertyValue>sn</PropertyValue>
	</Property>
	<Property>
                <!-- A comma-separated list of attribute names you would
                     like to make available in the Student object to the
                     AcademicHistoryProvider component
                -->
		<PropertyName>identifierAttributeNames</PropertyName>
		<PropertyValue>uid, cn</PropertyValue>
	</Property>
</PropertyConfig>

The following is an example of how to configure DirectoryProperties for Microsoft Active Directory:

<PropertyConfig name="ActiveDirectoryProperties">
	<ConfigClass>org.openeai.config.PropertyConfig</ConfigClass>
	<Property>
		<PropertyName>providerUrl</PropertyName>
		<PropertyValue>ldap://yoda.n2services.net:389</PropertyValue>
	</Property>
	<Property>
		<PropertyName>searchBase</PropertyName>
		<PropertyValue>cn=Users,dc=yoda,dc=n2services,dc=net</PropertyValue>
	</Property>
	<Property>
		<PropertyName>userDirectoryTreeBase</PropertyName>
		<PropertyValue>cn=Users,dc=yoda,dc=n2services,dc=net</PropertyValue>
	</Property>
	<Property>
		<PropertyName>initialContextFactory</PropertyName>
		<PropertyValue>com.sun.jndi.ldap.LdapCtxFactory</PropertyValue>
	</Property>
	<Property>
		<PropertyName>securityPrincipal</PropertyName>
		<PropertyValue>cn=Administrator,cn=Users,dc=yoda,dc=n2services,dc=net</PropertyValue>
	</Property>
	<Property>
		<PropertyName>securityCredentials</PropertyName>
		<PropertyValue>secret</PropertyValue>
	</Property>
	<Property>
		<!-- Set this to true for detailed logging messages from the authenticator. -->
		<PropertyName>verbose</PropertyName>
		<PropertyValue>false</PropertyValue>
	</Property>
	<Property>
		<!-- Set this to true to log the user credential to the log file. -->
		<PropertyName>logPassword</PropertyName>
		<PropertyValue>true</PropertyValue>
	</Property>
	<Property>
                <!-- The attribute your directory uses for first name -->
		<PropertyName>firstNameAttributeName</PropertyName>
		<PropertyValue>givenName</PropertyValue>
	</Property>
	<Property>
                <!-- The attribute your directory uses for last name -->
		<PropertyName>lastNameAttributeName</PropertyName>
		<PropertyValue>sn</PropertyValue>
	</Property>
	<Property>
                <!-- A comma-separated list of attribute names you would
                     like to make available in the Student object to the
                     AcademicHistoryProvider component
                -->
		<PropertyName>identifierAttributeNames</PropertyName>
		<PropertyValue>sAMAccountname, distinguishedName</PropertyValue>
	</Property>
</PropertyConfig>

Configuring Providers

Providers are pluggable components for retrieving academic history and academic calendar data from student information systems.  Providers are also used to implement the ping and statistics functionality of the web service, but most sites will not need to change, reconfigure, or provide their own implementations of ping and statistics providers.  On the other hand, there are many different student information systems and different versions of student information systems, so it is likely that sites will need to different academic history and academic calendar providers.  To reconfigure the web service to use a different academic history provider, one must change the value of the academicHistoryProviderClassName property in the GeneralProperties object of the AcademicHistoryRequest command.  This can be found in the AcademicHistoryService.xml file of your deployment.  If your deployment looks like the Quick Start package openeai-academichistory-tomcat-1.0 it is located in AHWS_HOME/configs/messaging/Environments/Examples/Deployments/AcadmicHistoryService.xml.  The following is an example from that file:

<PropertyConfig name="GeneralProperties">
	<ConfigClass>org.openeai.config.PropertyConfig</ConfigClass>
	<Property>
		<PropertyName>responseDocumentUri</PropertyName>
		<PropertyValue>./message/releases/com/academyone/Student/AcademicHistory/1.0/xml/Provide-Reply.xml</PropertyValue>
	</Property>
	<Property>
		<PropertyName>authenticatorClassName</PropertyName>
		<PropertyValue>org.openeai.services.academichistory.DummyAuthenticator</PropertyValue>
	</Property>
	<Property>
		<PropertyName>academicHistoryProviderClassName</PropertyName>
		<PropertyValue>org.openeai.services.academichistory.DummyAcademicHistoryProvider</PropertyValue>
	</Property>
</PropertyConfig>

To change the web service to use the BannerAcademicHistoryProvider, specify its class name instead of the DummyAcademicHistoryProvider.  For example:

<PropertyConfig name="GeneralProperties">
	<ConfigClass>org.openeai.config.PropertyConfig</ConfigClass>
	<Property>
		<PropertyName>responseDocumentUri</PropertyName>
		<PropertyValue>./message/releases/com/academyone/Student/AcademicHistory/1.0/xml/Provide-Reply.xml</PropertyValue>
	</Property>
	<Property>
		<PropertyName>authenticatorClassName</PropertyName>
		<PropertyValue>org.openeai.services.academichistory.DirectoryAuthenticator</PropertyValue>
	</Property>
	<Property>
		<PropertyName>academicHistoryProviderClassName</PropertyName>
		<PropertyValue>com.academyone.services.academichistory.BannerAcademicHistoryProvider</PropertyValue>
	</Property>
</PropertyConfig>

Each provider may have its own additional configuration requirements.  For example, the BannerAcademicHistoryProvider will require a database connection pool configured to connect to the Banner database.  See the instructions and release notes for any custom provider.  Most should also come with a sample configuration to use as a configuration template.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.