Integrating Blackboard Learning System with Sun Java System Identity Server 6.0, SP1:
A Case Study

Many institutions allow access to their Web resources on a per-application basis only. For example, a university student might have to set up a user ID and password to access the course catalog and set up yet another set of credentials to log in to other campus services. Also, affiliated extranets may require separate user accounts with passwords that meet a different set of criteria. Each of these services requires separate maintenance and integration with the infrastructure of the institution. Maintaining them and their individual user databases and access policies tend to be a costly and cumbersome administration nightmare.

Sun Java System Identity Server (formerly Sun ONE Identity Server, hereinafter called Identity Server), which includes Sun Java System Directory Server (formerly Sun ONE Directory Server and hereinafter called Directory Server), helps solve those types of problems.

Identity Server provides a scalable, reliable, and standards-based way for securely storing the identities of employees, partners, and suppliers--called a Circle of Trust--in a single location. Information management is cost-effective and secure by virtue of a policy structure that is easily configured and administered. Enterprises can then efficiently manage resource accesses and share user identities and attributes, both internally and externally.

Furthermore, Identity Server supports specifications from the Liberty Alliance Project that enable users to federate their identities between identity and service providers.

In the case of a university, for example, you would create a single identity for a student and assign policies that govern which information or services that student can access. Afterwards, you would enforce the policies by deploying policy agents on application or Web servers.

Blackboard Learning System (hereinafter called Blackboard) is an enterprise-grade, comprehensive e-learning software platform that encompasses a course management system. Its advanced architecture allows for integration with back-office systems. Blackboard offers faculties flexible and intuitive tools to incorporate technology into teaching and learning, including content management, discussion boards, online assessments, and chat and gradebook capabilities. With Blackboard, faculties can post syllabi, multimedia files, course documents, and other materials that are available to students any time, anywhere.

This paper describes the integration process of Blackboard with Identity Server--a process that implements Single Sign-On (SSO) between Blackboard and other applications in the same Circle of Trust. Once SSO is in place, federated identity becomes a reality with only a few configuration steps.

• Benefits of Identity Server Integration
• Overview of Architecture
• Integration Process
  • Integration Procedure on System A
  • Integration Procedure on System B
• Process Verification
• References

The benefits that accrue from the Identity Server integration are manyfold:

• Authentication — Applications can externalize the authentication tasks to Identity Server. That way, applications take advantage of the server's multilevel (chained) and multifactor authentication capabilities (UNIX password, Secure ID card, biometrics, and others).
  
  
• Authorization — Identity Server supports Security Assertions Markup Language (SAML) and a referral-based authorization model. Applications can capitalize on the server for its role and extensible and rule-based policy framework that meets a broad range of end-user requirements.
  
  
• SSO — SSO enhances security and reduces support costs for password management, yielding a good return on investment. Identity Server offers SSO capability for application access from multiple vendors that specialize in human resources management, supply chain management, customer relationship management, portals, and so forth, along with a portfolio of enterprise resource planning vendors with whom it integrates.
  
  
• Federated Identity — The Identity Server implementation and APIs automatically enable applications with federated identities from Liberty Alliance. For applications that feature collaboration with users and provide access to cross-domain resources, you can leverage the Liberty standards to extend enterprise security and deliver controlled access to applications.

User authentication proceeds as follows:

1. A user clicks the Login button on the home page of the Blackboard application.
   
   
2. The Identity Server URL policy agent for Apache Web Server, which protects the application, intercepts the request and redirects the user to Identity Server for authentication.
   
   
3. Once authentication is complete, the URL policy agent enables the user to access the application through a custom authentication module.
   
   

Figure 1 illustrates the high-level architecture.

Figure 1: Architecture of Blackboard Learning System-Identity Server Integration (click to enlarge)

Configuring the integration involves two systems, installed with the Solaris 8 Operating System, Update 7:

• System A — This system is installed with Identity Server 6.0, SP1 and Directory Server 5.1. We created a user ID bb in Identity Server and defined a policy with the policy framework for the organization that allows System B users to access Blackboard.
  
  
• System B — This system is installed with the following components:
  • Blackboard 6.0.11 on top of Apache Web Server
  • Identity Server 2.1 Apache 1.3.29 URL policy agent on the Apache Web Server
  • Identity Server 6.0 SP1 SUNWamsdk package (for the enabling of SSO APIs)
  
  As with System A, we created a user ID bb. We then compiled and loaded a custom authentication module that plugs in to Blackboard. (See the source file.) This module, which extends the default implementation in Blackboard, uses the policy agent to retrieve the user ID from the headers and then returns that user to the upper layer of the Blackboard application for further action. The module also enables logouts from Identity Server and Blackboard with SSO APIs.

Figure 2 illustrates how the components work together.

Figure 2: Schematic of Components (click to enlarge)

Integration Procedure on System A
This section describes the installation and configuration procedures on System A.

Installing Identity Server on System A
Follow these steps to install Identity Server on System A:

1. Install Identify Server 6.0, SP1.
   Directory Server is included with this installation.
   
   
2. Set the root suffix of the directory tree to dc=xyz,dc=com.
   
   
3. Install patch 114772-01.

Configuring Identity Server on System A
To configure Identity Server on System A, do the following:

1. Log in to the Administration Console of Identity Server with amadmin as the user ID and the password you set up during installation.
   
   
2. Click the Identity Management tab and then choose Users from the View menu on the left panel.
   
   A list of fields (First Name, Last Name, and so on) is displayed on the right panel.
   
   
3. Fill in the fields for a user named bb (same first name and last name). Click Save.
   
   
4. Create an Identity Server policy called Allow BB Users. Do the following:
   

   a.	Click the Identity Management tab and choose Policies on the left panel, then click New. A New Policy screen is displayed on the right panel.
   b.	Select Normal under Type of Policy and type "Allow BB users" under Name. Click Create. A dialog box entitled Edit Allow BB Users is displayed on the right panel.
   c.	Choose Rules from the View menu and click Add to add a new rule. Identity Server sets the value URL Policy Agent under Service.
   d.	Type "BB rule" under Rule Name and http://B.domainname:80/* under Resource Name. Under Actions, select GET and Allow, and then select POST and Allow. Click Create at the bottom and Save in the next screen that is displayed. Identity Server confirms with a message, "The policy properties have been saved."
   e.	Choose Subjects under View on the right panel and then click Add in the next screen. The Add Subject screen is displayed.
   f.	Select Organization under Type and click Next. The next Add Subject screen is displayed.
   g.	Type a name of your choice under Name. Click Search under Organization. A list of organizations is displayed under Available.
   h.	Click the appropriate organization name to highlight it and move it to the field below (Selected) by clicking Add. The organization name is displayed under Selected.
   i.	Click Create at the bottom to create the subject. Click Save at the bottom of the next screen. Identity Server confirms with a message, "The policy properties have been saved."

Integration Procedure on System B
This section describes the installation and configuration procedures on System B.

Installing Blackboard 6.0.11
Install Blackboard 6.0.11 on top of Apache Web Server by following the procedures in the Blackboard Learning System Setup Guide for Sun Solaris and Linux.

Note these tips:

• Be sure to also install and configure Oracle 8.1.7 as described in the Blackboard Learning System Setup Guide for Sun Solaris and Linux.
  
  You might encounter this error message:
  
  Invalid User name / Password
  
  If you do, then change the default password (change_on_install) for the Oracle user ID sys to a new one by executing the following command in SQL *Plus:
  
  alter user sys identified by new_password;
  
  This command ensures that the password is synchronized between the Oracle database and the password file (orapwSID).
  
  
• The setup guide recommends that you use Java Development Kit (JDK) version 1.3.1_08 and then upgrade to 1.4.2_xx or the latest version. To effect the upgrade, revise the bbconfig.properties file with the latest JDK location and then run the script /usr/local/blackboard/tools/admin/PushConfigUpdates.sh.

When installation is complete, Blackboard creates a symbolic link of the installation directory to /usr/local/blackboard.

Configuring Blackboard 6.0.11
To configure Blackboard 6.0.11, do the following:

1. Create a user ID bb (same first name and last name) with the password bb by clicking Create Account at the startup page (http://hostname.domainname:80.2). Follow the screen prompts.
   
   
2. Update the Blackboard files to point to the custom authentication module, as follows:
   

   a.

   Add the following to the file: $BB_HOME/config/authentication.properties: ###################################################### ## ## Custom Authentication Properties ## ## ( default authentication scheme, ## uses challenge-response authentication ) ## ####################################################### auth.type.custom.impl=com.blackboard.custom.SJESIdentity6

   b.

   Edit the file $BB_HOME/config/bbconfig.properties. Change the line bbconfig.auth.type=rdbms to bbconfig.auth.type=custom Afterwards, the main application configurations read as follows: ############# main application config - generic ################ bbconfig.basedir=/blackboard/blackboard bbconfig.java.home=/jdk/j2sdk1.4.2_02 bbconfig.library.version=6.0 beta bbconfig.auth.type=custom bbconfig.version.number=6.0.10.40

3. Edit the $BB_HOME/apps/tomcat/bin/tomcat.sh file to load the files that are specific to Identity Server. Do the following:
   

   a.	Add the path LD_LIBRARY_PATH, as follows (all on one line): LD_LIBRARY_PATH=/opt/SUNWam/lib/solaris/sparc/jss:/opt/SUNWam/ lib/solaris/sparc:$LD_LIBRARY_PATH export LD_LIBRARY_PATH
   b.	Change the path CLASSPATH to the following: Add the line below the comment SJES Identity Change. # --------------------- Add all Bb relative classes (rp) CLASSPATH=${CLASSPATH}:${BB_PATH} # --------------------- SJES Identity Change CLASSPATH=${CLASSPATH}:/opt/SUNWam/locale # ---------------------
   c.	Locate the comment for Java runtime options (Process options) and add the following lines: -Djava.protocol.handler.pkgs=com.iplanet.services.comm \ -Dcom.iplanet.coreservices.configpath=/opt/SUNWam/config/ums The completed process options look like this: ## -------------------- Process options -------------------- # add tomcat.policy: Even if we don't use sandbox, it doesn't hurt TOMCAT_OPTS="$TOMCAT_OPTS \ -Djava.security.policy==$TOMCAT_HOME/conf/tomcat.policy \ -Djava.security.manager \ -Dtomcat.home=$TOMCAT_HOME \ -Dblackboard.home=$BBDIR \ -Djava.protocol.handler.pkgs=com.iplanet.services.comm \ -Dcom.iplanet.coreservices.configpath=/opt/SUNWam/config/ums -Dbbservices_config=$BBDIR/config/service-config.properties"
   d.	Set up debugging for the custom authentication module. Edit the file $BB_HOME/config/service-config.properties. Change the line blackboard.service.log.param.logdef.default.verbosity=warning to blackboard.service.log.param.logdef.default.verbosity=debug

Installing Identity Server 2.1 Apache 1.3.29 URL Policy Agent
To install the Apache URL policy agent, do the following:

1. From the Sun Download Center, download the Identity Server 2.1 Apache 1.3.29 agent and run the setup script.
   
   
2. Accept the license and specify /opt as the installation directory.
   The next screen displays a set of questions regarding the server instance that the agent is protecting.
   
   
3. Answer the questions as follows:
   

   Enter information about the server instance this agent will protect.
   
   Host Name [B.domainname] {"<" goes back, "!" exits}: B.domainname
   
   Apache Configuration Directory [] {"<" goes back, "!" exits}:
   /usr/local/blackboard/apps/httpd/conf/
   Web Server Port [80] {"<" goes back, "!" exits}: 80
   Web Server Protocol [http] {"<" goes back, "!" exits}: http
   Agent Deployment URI [/amagent] {"<" goes back, "!" exits}: /amagent
   SSL Ready [true] {"<" goes back, "!" exits}: true
   
   

   The next screen displays a set of questions regarding the Identity Server information for this agent.
   
   
4. Answer the questions as follows:
   

   Enter the Sun Java System Identity Server Information for this Agent.
   
   Primary Server Host [B.domainname] {"<" goes back, "!" exits}: A.domainname
   Primary Server Port [58080] {"<" goes back, "!" exits}: 58080
   Primary Server Protocol [http] {"<" goes back, "!" exits}: http
   
   Primary Server Deployment URI [/amserver] {"<" goes back, "!" exits}: /amserver
   Primary Console Deployment URI [/amconsole] {"<" goes back, "!" exits}:
   /amconsole
   Failover Server Host [] {"<" goes back, "!" exits}: [Press Return.]
   Agent-Sun Java System Identity Server Shared Secret: [Type the
   amldapuser password you specified while installing Identity Server on
   System B.]
   Re-enter Shared Secret: [Retype the password.]
   
   CDSSO Enabled [false] {"<" goes back, "!" exits}: [Press Return.]
   

   A summary is then displayed for your reference.
   
   
5. Select Install to install the agent.

Configuring Identity Server 2.1 Apache 1.3.29 URL Policy Agent
To configure the policy agent, edit the settings in the AMAgent.properties file in the directory /etc/opt/SUNWam/agents/apache/config/
_BLS_install_dir_apps_httpd_conf, as follows:

1. Set the Boolean attribute to enable or disable the additional policy response attributes to be introduced into the HTTP headers. Make that line read:
   com.sun.am.policy.am.fetchHeaders=true
   The policy agent can then obtain the user name that has been successfully authenticated from these headers.
   
   
2. Add the not-enforced list, that is, the list of Blackboard URLs for which authentication is not required, as follows (all on one line):
   

   com.sun.am.policy.agents.notenforcedList=http://B.domainname:80/
   index.html http://B.domainname:80/index.html?bbatt=Y http://
   B.domainname:80/ http://B.domainname:80/bin/entry_leftpanel.pl
   http://B.domainname:80/bin/entry_rightpanel.pl http://B.domainname:80
   http://B.domainname:80/images/spacer.gif http://B.domainname:80/
   images/ci/logos/BbBlackboard_R_URL-f.gif http://B.domainname:80/
   images/ci/listbtns/entry_login.gif http://B.domainname:80/images/ci/
   listbtns/entry_coursecatalog.gif http://B.domainname:80/images/ci/
   listbtns/entry_createaccount.gif http://B.domainname:80/bin/
   new_account.pl?new_loc=/webapps/portal/frameset.jsp http://
   B.domainname/webapps/login?action=logout
   http://B.domainname:80/ui/styles/blackboard.css http://
   B.domainname:80/ui/styles/palette.css http://B.domainname:80/login/
   blackboard_2002.jpg http://B.domainname:80/images/ci/logos/
   Powered_Bb_090.jpg http://access.blackboard.com
   
   

   This list also includes the URL at which to create a new account in Blackboard.
   
   
3. Add the policy attributes to be added to the HTTP header, as follows (all on one line):

   com.sun.am.policy.am.headerAttributes=cn|common-
   name,ou|organizational-unit,o|or
   ganization,mail|email,employeenumber|employee-
   number,c|country,uid|userid

   In this case, we are specifically adding the userid and uid attributes to obtain the user name.
   
   
4. Set the cookie_reset_enabled attribute to true, as follows:
   com.sun.am.policy.agents.cookie_reset_enabled=true
   By default, this value is set to false. You set it to true in case the agent must reset cookies in a response before redirecting to Identity Server for authentication.
   
   
5. Add the Blackboard application cookies to the reset_cookie_list attribute, as follows:
   com.sun.am.policy.agents.cookie_reset_list=session_id;Domain=
   The reset_cookie_list attribute must be included in a redirect response to Identity Server and is valid only if the cookie_reset_enabled attribute is set to true (see step 4).
   
   

Adding SUNWamsdk from Identity Server to System B
To add the SUNWamsdk package from Identity Server 6.0 to System B, do the following:

1. Log in as root.
   
   
2. Change directory to the distribution of Identity Server 6.0.
   
   
3. Run the following command:
   # pkgadd -d .
   
   
4. Select the SUNWamsdk option.
   Here is how to answer the questions that are posted during installation and the relevant output:

   What is the base directory for install? [/opt] [Press Return.]
   What is the host name of the machine where the Sun Java System
   Identity Server will run? [B] A
   What is the sub-domain name? [B's sub-domain] A's sub-domain
   
   What is the domain name? [domainname] domainname
   
   Verifying A.domainname succeeded!
   
   What is the Sun Java System Identity Server port? [58080] [Press
   Return.]
   What is the protocol? [http] [Press Return.]
   What directory is the jdk installed as? [/usr/java]
   /jdk/j2sdk1.4.2_02
   What is the Sun Java System Identity Server services Deploy URI
   prefix?  [/amserver] [Press Return.]
   What is the host name of the machine where the Directory Server will
   run? [A] [Press Return.]
   What is the sub-domain name? [A's sub-domain] A's sub-domain
   
   What is the domain name? [domainname] domainname
   
   Verifying A.domainname succeeded!
   
   What is the profile server port? [389] [Press Return.]
   What is the root suffix of your directory tree? [dc=xyz,dc=com]
   [Press Return.]
   
   The installation will proceed now.
   

5. Apply the patch 114772-01 on top of the package.
   Here's the output of a sample run:

   Do you agree to the license terms? y/[n] y
   
   What is the dn of the Directory Manager [cn=Directory Manager] [Press
   Return.]
   What is the password for the Directory Manager [] password
   Verifying sufficient filesystem capacity (dry run method) ...
   Installing patch packages ...
   
   Patch number 114772-01 has been successfully installed.
   See /var/sadm/patch/114772-01/log for details
   
   Executing postpatch script ...
   
   Patch packages installed:
   SUNWamsdk
   

Configuring Identity Server SDK
To configure the Identity Server SDK, do the following:

1. Copy the following files to the /usr/local/blackboard/apps/tomcat/lib/common directory:

   
   /opt/SUNWam/lib/am_sdk.jar
   /opt/SUNWam/lib/am_services.jar
   /opt/SUNWam/lib/jaas.jar
   /opt/SUNWam/lib/jss311.jar
   /opt/SUNWam/lib/AMConfig.properties
   /opt/SUNWam/lib/SSOConfig.properties

2. Change the permissions for these files to provide access to Apache Web Server, which is running as bbuser. Type:
   % chmod 644 filename

Configuring the Custom Authentication Module
The authentication module enhances the default implementation by extending the class BaseAuthenticationModule, overriding the doAuthenticate() and doLogout() methods. The doAuthenticate() method retrieves the user ID from the headers that are returned after a successful authentication with Identity Server. The doLogout() method uses SSO APIs to destroy the SSO token and then resets the cookie. This procedure is necessary because a logout action from the Blackboard portal must terminate the user's sessions on both Identity Server and Blackboard.

For details, see the Blackboard Learning System Advanced Integration and Data Management Manual and the Sun Java System Identity Server 6.0 Programmer Guide.

To configure the authentication module, copy the compiled file bb-custom.jar to the /usr/local/blackboard/apps/tomcat/lib/common directory.

See the Makefile and the source file SJESIdentity6.java, which assume the following:

• During installation, Blackboard creates a link from the installation directory to /usr/local/blackboard.
  
  
• SJESIdentity6.java resides in the com/blackboard/custom directory relative to the directory that contains the Makefile.

As a final step, verify that the integration is successful. Do the following:

1. Restart the Apache Web server for Blackboard.
   
   
2. Click Login on the home page of the Blackboard application.
   Blackboard then redirects you to Identity Server for authentication, after which you can access the Blackboard portal.
   
   

• Sun Java System Identity Server main page
  
• Sun Java System Identity Server documentation
  
• Blackboard Learning System
  

• Rajeev Angal, architect, Sun Java System Identity Server, Sun Microsystems, Inc.
• Ramsey Chambers, alliance manager, corporate development, Blackboard Inc.
• Christopher Etesse, senior director, product development, Blackboard Inc.
• Lily Hsiao, staff engineer, Sun Java System Identity Server, Sun Microsystems, Inc.

About the Authors
Ezhilan Narasimhan is a member of technical staff of the Market Development Engineering group at Sun. He works with independent software vendors on performance engineering, database design, and application architecture.

Sujeet Vasudevan, also a technical member at Market Development Engineering at Sun, collaborates with independent software vendors in developing and integrating applications with Sun Java Enterprise System products.

Marina Sum is a staff writer for Sun Developer Network. She has been writing for Sun for 15 years, mostly in the technical arena.