Blackboard Learn 9.1 Server Administration Guide

Release 9.
Server Administration Guide
2010 Blackboard Inc. Proprietary and Confidential
Publication Date: March 29, 2010 Worldwide Headquarters Blackboard Inc. 650 Massachusetts Avenue NW Sixth Floor Washington, DC 20001-3796 +1 800 424 9299 toll free US & Canada +1 202 463 4860 telephone +1 202 463 4863 facsimile www.blackboard.com +31 20 5206884 (NL) telephone +31 20 5206885 (NL) facsimile www.blackboard.com International Headquarters Blackboard International B.V. Dam 27 2nd Floor 1012 JS Amsterdam The Netherlands
Copyright 1997-2010. Blackboard, the Blackboard logo, BbWorld, Blackboard Learn, Blackboard Transact, Blackboard Connect, the Blackboard Outcomes System, Behind the Blackboard, and Connect-ED are trademarks or registered trademarks of Blackboard Inc. or its subsidiaries in the United States and other countries. U.S. Patent Numbers: 6,988,138; 7,493,396; 6,816,878. Apache and the Apache feather logo are trademarks of The Apache Software Foundation. Linux is a registered trademark of Linus Torvalds. Microsoft, Active Directory, SQL Server, and Windows are registered trademarks of Microsoft Corporation in the United States and/or other countries. Oracle is a registered trademark of Oracle Corporation and/or its affiliates. Red Hat and Red Hat Enterprise Linux are registered trademarks of Red Hat, Inc. in the U.S. and other countries. Sun, Java, JDBC, JDK, and Solaris are trademarks of Sun Microsystems, Inc. in the United States and/or other countries. UNIX is a registered trademark of The Open Group. Other product and company names mentioned herein may be the trademarks of their respective owners. No part of the contents of this manual may be reproduced or transmitted in any form or by any means without the written permission of the publisher, Blackboard Inc.
Blackboard Learn Server Administration Guide

Page 2
Contents
About the Server Administration Guide..................................................................................... 9 Where to Start..................................................................................................................... 9 Other Resources for Administrators ................................................................................... 9 PushConfigUpdates ............................................................................................................ 9 Blackboard Learn - Basic Edition Limitations ..................................................................... 9 Authentication.............................................................................................................................. 10 Overview ........................................................................................................................... 10 In this Section ................................................................................................................... 10 Introduction to Blackboard Learn Authentication .................................................................... 12 Overview ........................................................................................................................... 12 Customize the Default Authentication .............................................................................. 12 Return to the Default Authentication ................................................................................ 12 Authentication Properties ................................................................................................. 12 Introduction to LDAP Authentication ....................................................................................... 14 Overview ........................................................................................................................... 14 LDAP Authentication ........................................................................................................ 14 LDAP Module .......................................................................................................................... 15 Overview ........................................................................................................................... 15 Limitations......................................................................................................................... 15 LDAP Configuration Overview ................................................................................................ 16 Overview ........................................................................................................................... 16 LDAP Configuration .......................................................................................................... 16 Open LDAP UNIX Operating Systems Only.................................................................. 16 LDAP Properties ..................................................................................................................... 17 Overview ........................................................................................................................... 17 File format ......................................................................................................................... 17 Editing the properties file .................................................................................................. 17 LDAP Property Configuration ........................................................................................... 17 Example ............................................................................................................................ 19 Troubleshooting LDAP ............................................................................................................ 21 Overview ........................................................................................................................... 21 Debugging LDAP Authentication ...................................................................................... 21 Troubleshooting LDAP Authentication Properties for Windows ....................................... 21 Troubleshooting LDAP Authentication Properties for UNIX ............................................. 22 Revert to Default Authentication ....................................................................................... 23 Blackboard Application Log .............................................................................................. 23 Common Problems ........................................................................................................... 23 LDAP Scenarios ............................................................................................................... 24 Troubleshooting LDAP with SSL ...................................................................................... 24

Page 3
LDAP Fail Over Considerations .............................................................................................. 29 Overview ........................................................................................................................... 29 Automatic Fail Over for LDAP Server Error ...................................................................... 29 Automatic Fail Over for Users who Do Not Exist in LDAP Database ............................... 29 Security Risks ................................................................................................................... 29 Changing the Default Configuration for LDAP Server Error ............................................. 30 Changing the default configuration for users that do not exist in LDAP database ........... 30 LDAP with Active Directory ..................................................................................................... 31 Overview ........................................................................................................................... 31 Connecting via an Anonymous Bind ................................................................................ 31 Connecting via a Privileged Bind ...................................................................................... 31 Troubleshooting LDAP with Active Directory.................................................................... 32 Introduction to Web Server Delegation Authentication........................................................... 33 Overview ........................................................................................................................... 33 Management ..................................................................................................................... 33 Implementation ................................................................................................................. 33 Web Server Delegation with Windows 2003 ........................................................................... 34 Overview ........................................................................................................................... 34 Configure Web Server Delegation with Windows 2003 ................................................... 34 Introduction to Active Directory Authentication ...................................................................... 35 Overview ........................................................................................................................... 35 Active Directory Authentication......................................................................................... 35 Limitations......................................................................................................................... 35 Active Directory Authentication and Portal Direct Entry ................................................... 35 Active Directory Configuration ................................................................................................ 36 Overview ........................................................................................................................... 36 File format ......................................................................................................................... 36 Set authentication type ..................................................................................................... 36 Property Configuration ...................................................................................................... 36 Example ............................................................................................................................ 37 Active Directory Security Considerations ................................................................................ 38 Overview ........................................................................................................................... 38 Security Considerations .................................................................................................... 38 Introduction to Custom Authentication .................................................................................... 39 Overview ........................................................................................................................... 39 Audience ........................................................................................................................... 39 Data Model ....................................................................................................................... 39 Object Model ........................................................................................................................... 40 Overview ........................................................................................................................... 40 Authentication Object Model............................................................................................. 40

Page 4
Authentication Process ........................................................................................................... 41 Overview ........................................................................................................................... 41 Login ................................................................................................................................. 41 Logout ............................................................................................................................... 42 Authentication API................................................................................................................... 43 Overview ........................................................................................................................... 43 Authentication Processing Methods ................................................................................. 43 Configuration File Processing Methods ............................................................................ 46 Implementation Details............................................................................................................ 47 Overview ........................................................................................................................... 47 Blackboard Default Implementation ................................................................................. 47 LDAP Implementation ....................................................................................................... 47 Web Server Delegation Implementation ........................................................................... 47 Extending Other Blackboard-created Authentication Modules ......................................... 48 Sample Custom Authentication Module ........................................................................... 48 Sample IUserPassAuthModule Code ............................................................................... 52 Customizing Authentication Page Flow .................................................................................. 53 Overview ........................................................................................................................... 53 Implementing requestAuthenticate() ................................................................................ 53 Redirecting to the Original Target URL ............................................................................ 53 Creating and Deploying Custom Implementations ................................................................. 54 Overview ........................................................................................................................... 54 Extending Blackboard-provided Implementations ............................................................ 54 Extending the Blackboard Default Implementation .......................................................... 54 Creating a Custom LDAP Implementation ....................................................................... 55 Creating a Custom Web Server Delegation Implementation ........................................... 55 Deploying Custom Implementations ................................................................................. 55 Updating the Collaboration Server ................................................................................... 56 Updating the launch-tool Script ........................................................................................ 56 Using WebDAV with a Custom Implementation ............................................................... 57 Troubleshooting Custom Implementations ....................................................................... 57 Blackboard Learn Architecture .................................................................................................. 58 Overview ........................................................................................................................... 58 In this Section ................................................................................................................... 58 File System ............................................................................................................................. 59 Overview ........................................................................................................................... 59 Command Line Tools ....................................................................................................... 59 HTTP Compression .......................................................................................................... 59 Content Storage ............................................................................................................... 59 Queries ............................................................................................................................. 60 Logs .................................................................................................................................. 60

Page 5
Databases ............................................................................................................................... 61 Overview ........................................................................................................................... 61 BBLEARN_ADMIN ........................................................................................................... 61 BBLEARN ......................................................................................................................... 61 BBLEARN_STATS ........................................................................................................... 61 Database Users ................................................................................................................ 61 Oracle RAC Support, UNIX ..................................................................................................... 62 Overview ........................................................................................................................... 62 Configuration .................................................................................................................... 62 Prerequisites ..................................................................................................................... 62 Configure the Oracle RAC Environment .......................................................................... 62 Configure Single Instance Mode ...................................................................................... 64 Upgrading Blackboard Learn in an Oracle RAC Environment ......................................... 65 Special RAC Patches on Oracle RAC with 10g R2 .......................................................... 65 Best Practices ................................................................................................................... 65 Services .................................................................................................................................. 67 Definition of Blackboard Services ..................................................................................... 67 Starting and Stopping Services ........................................................................................ 67 Starting and Stopping the bb-collab Service .................................................................... 68 Tomcat Clusters ...................................................................................................................... 69 Overview ........................................................................................................................... 69 Installing One or More Tomcat Clusters ........................................................................... 69 Troubleshooting Installation Issues .................................................................................. 72 Cache Replication ............................................................................................................ 73 Removing a Cluster Node ................................................................................................ 74 Best Practices ................................................................................................................... 74 Operating System and Database Maintenance ...................................................................... 75 Overview ........................................................................................................................... 75 Applying a Service Pack or Security Patch after Installing Blackboard Learn ................. 75 Backup and Recovery ............................................................................................................. 76 Overview ........................................................................................................................... 76 System backup and recovery ........................................................................................... 76 Incremental data protection .............................................................................................. 76 Avoiding Recovery of Files During Upgrade .................................................................... 76 Command Line Tools .............................................................................................................. 77 Overview ........................................................................................................................... 77 PurgeAccumulator ............................................................................................................ 77 PushConfigUpdates .......................................................................................................... 78 RotateLogs ....................................................................................................................... 79 ServiceController .............................................................................................................. 79 SystemInfo ........................................................................................................................ 80

Page 6
Using a Proxy Server .............................................................................................................. 81 Overview ........................................................................................................................... 81 Configure the Proxy Server, UNIX.................................................................................... 81 Configure the Proxy Server, Windows ............................................................................. 81 Content Management Administration ....................................................................................... 82 Overview ........................................................................................................................... 82 In this Section ................................................................................................................... 82 Introduction to Content Management Administration .............................................................. 83 Overview ........................................................................................................................... 83 Turn on the Content Collection ............................................................................................... 84 Overview ........................................................................................................................... 84 Enable SSL ....................................................................................................................... 84 Set up the Portal ............................................................................................................... 84 Configure Content Management Settings ........................................................................ 84 Configure Full Text Search ............................................................................................... 85 Configure Display Options ................................................................................................ 85 Enable Content Management Features ........................................................................... 86 Enable Content System Features in Courses .................................................................. 86 Access the Content Collection.......................................................................................... 86 Configuration Changes ........................................................................................................... 87 Overview ........................................................................................................................... 87 Configure the System ....................................................................................................... 87 Command Line Tools .............................................................................................................. 88 Overview ........................................................................................................................... 88 PurgeAccumulator ............................................................................................................ 88 PushConfigUpdates .......................................................................................................... 89 RotateLogs ....................................................................................................................... 89 ServiceController .............................................................................................................. 90 SystemInfo ........................................................................................................................ 91 Setting Up SSL ............................................................................................................................. 92 Overview ........................................................................................................................... 92 In this Section ................................................................................................................... 92 About SSL and SSL Choice .................................................................................................... 93 Overview ........................................................................................................................... 93 How Does SSL Work? ...................................................................................................... 93 Obtain a Certificate ........................................................................................................... 93 How Does SSL Appear to Users? .................................................................................... 94 SSL Choice ....................................................................................................................... 94 Configure SSL for IIS .............................................................................................................. 95 Overview ........................................................................................................................... 95 Configure SSL for IIS ........................................................................................................ 95

Page 7
Configuring SSL for the Collaboration Tool, Windows ............................................................ 97 Overview ........................................................................................................................... 97 Load-Balanced Configurations ......................................................................................... 97 Create the Keystore .......................................................................................................... 98 Configure Tomcat to Work with the SSL Certificate ......................................................... 98 Configuring SSL for Apache ................................................................................................. 100 Overview ......................................................................................................................... 100 Configure SSL for Apache .............................................................................................. 100 Configuring SSL for the Collaboration Tool, UNIX ................................................................ 102 Overview ......................................................................................................................... 102 Configure the Collaboration Tool with a Self-signed Sertificate ..................................... 102 Configure the Collaboration Tool with a Signed Certificate ............................................ 102 Create the Keystore ........................................................................................................ 103 Configure Tomcat to Work with the SSL Certificate ....................................................... 103 SSL Choice ........................................................................................................................... 105 Overview ......................................................................................................................... 105 Find this Page ................................................................................................................. 105 SSL Choice Page Fields ................................................................................................. 105 Setting Up SIF Integration ........................................................................................................ 106 Overview ......................................................................................................................... 106 In this Section ................................................................................................................. 106 About SIF .............................................................................................................................. 107 Exchanging and Synchronizing Data ............................................................................. 107 The Blackboard SIF Agent ............................................................................................. 107 Configure the Blackboard SIF Agent .................................................................................... 108 Overview ......................................................................................................................... 108 Edit the service-config.properties File ............................................................................ 108 Configure Settings in the bb-config.properties File ........................................................ 108 Example: ......................................................................................................................... 110 Sample bb-sif-agent-config.xml ...................................................................................... 111 Configure SSL for SIF ........................................................................................................... 112 Overview ......................................................................................................................... 112 Create and Configure the Keystore ................................................................................ 112 Configure TrustStore ...................................................................................................... 114 Data Mapping ........................................................................................................................ 115 Overview ......................................................................................................................... 115 Data Map ........................................................................................................................ 115

Page 8
About the Server Administration Guide

The Blackboard Learn Server Administration Guide covers the configuration of server-side options such as authentication and security.
Where to Start
Institutions that have just installed Blackboard Learn should become familiar with the environment before making it available to users. After installation, read the available Blackboard Learn documentation and then develop and revise a plan for managing the system. Consider: Authentication: Should users login to Blackboard Learn using a unique user name and password or should users authenticate once on the network and then have seamless access to Blackboard Learn? Read the section on Authentication for information on how to integrate Blackboard Learn with an authentication system already on campus (such as LDAP or Active Directory). Security: Should user communications with Blackboard Learn be protected by SSL? Will users suffer with slower performance due to SSL? Read the section on SSL to encrypt user communications with Blackboard Learn. Maintenance: Read the Blackboard Learn Architecture section for guidance on server maintenance. This section also reviews the file system and database structure and the command line tools available to administrators.
Other Resources for Administrators

It is important that administrators read the Release Notes and review the Known and Resolved Issues. Blackboard also provides an Operations Workbook and Guide to help administrators organize their resources and plan tasks. The Operations Workbook is the outline of an administrator's "run book" and is designed to be modified and extended to meet individual needs. For information about optimizing Blackboard Learn to perform best in a particular environment, see Blackboard Learn Performance Optimization Guide.
PushConfigUpdates
The PushConfigUpdates command automatically updates the admin data in the database by reading the value in the config.xml. It automatically pushes the changes of the database hostname and port, instance name, and externally visible web server hostname to the database. When the PushConfiguUpdates command is complete, it will not display whether or not dynamic compression is enabled on your IIS installation. Verify this setting in IIS 6.0 by visiting Configure Compression in IIS 6.0 using Windows 2003 or in IIS 7.0 by visiting Configure Compression in IIS 7.0 using Windows 2008.
Blackboard Learn - Basic Edition Limitations

Several of the server-side options described in this manual are not available to Institutions running the Blackboard Learn - Basic Edition. Blackboard Learn - Basic Edition administrators will find the Architecture section valuable. Integrated authentication and SSL are not available with the Blackboard Learn - Basic Edition.

Page 9
Authentication
Overview
This section reviews the configuration, and management of several different Authentication models supported with Blackboard Learn.
In this Section
This section includes the following topics: T opic Introduction to Blackboard Learn Authentication LDAP Authentication Introduction to LDAP LDAP Module LDAP Configuration Overview LDAP Properties Troubleshooting LDAP LDAP Failover Considerations LDAP with Active Directory Web Server Delegation Introduction to Web Server Delegation Authentication Web Server Delegation with Windows 2003 Active Directory Authentication Introduction to Active Directory Authentication Active Directory Configuration Active Directory Security Considerations This topic defines Active Directory authentication and the implementation process. This topic reviews the options available when setting up Active Directory authentication. This topic presents information on Active Directory security. This topic presents information on implementing a Web Server authentication solution. This topic covers Web Server Delegation with Windows 2003. This topic defines LDAP. This topic presents the set of included code that supports LDAP. This topic defines how to setup Blackboard Learn to use LDAP. This topic defines the configurable properties that define how LDAP works with Blackboard Learn. This topic presents solutions to some common problems encountered with LDAP. This topic describes the decisions that control the authentication process when an issue is encountered. This topic describes how to use LDAP with Active Directory. De s cr ip t io n This topic defines the default authentication model.

Page 10
T opic Custom Authentication Introduction to Custom Authentication Object Model Authentication Process Authentication API Implementation Details
De s cr ip t io n
This topic describes the APIs that can be used to create a custom authentication model. This topic reviews the object model of the Authentication APIs. This topic describes the authentication process. This topic provides information on the Authentication APIs. This topic describes some of the issues that must be resolved when implementing a custom authentication model. This topic covers changing the authentication page flow. This topic describes how to implement a custom authentication model.
Customizing Authentication Page Flow Creating and Deploying Custom Implementations

Page 11
Introduction to Blackboard Learn Authentication

Overview
The default authentication for Blackboard Learn authenticates the users login credentials against the Blackboard Learn database.
Customize the Default Authentication

Changing the Blackboard Learn Authentication process and options does not require any database changes. All of the options are stored in a properties file. Modify the authentication.properties file to customize the default authentication for Blackboard Learn.
Return to the Default Authentication

If, in the Course of setting up a customized Authentication solution, it is necessary to return to Blackboard Learn default authentication (rdbms), the authentication type (bbconfig.auth.type) can be set via the command line. This allows Blackboard Learn, at start up, to select the appropriate set of auth.type*.* entries. Follow these steps to reset the system to use the default authentication model: 1. 2. Change to the following directory: cd BB_DEPLOY_DIR\blackboard\config Edit the authentication.properties file as shown. auth.type.rdbms.impl=blackboard.platform.security.authentication. BaseAuthenticationModule auth.type.rdbms.use_challenge=true 3. 4. Edit the bb-config.properties file. Change the property to bbconfig.auth.type=rdbms. Run the PushConfigUpdates command line tool to activate the changes.
Authentication Properties
The table below details the properties applicable to the default authentication model. These properties are configured through the authentication.properties file. The authentication.properties properties file is found in <blackboard_install_directory>/bbservices/config. P ro p e rt y auth.type.rdbms.impl De s cr ip t io n Defines the class which must conform to the HttpAuthModule interface. The default value, blackboard.platform.security. authentication.BaseAuthenticationModul e, should not be changed unless the Institution builds and implements its own class for Blackboard

Page 12
P ro p e rt y
De s cr ip t io n Learn default authentication.
auth.type.rdbms.use_challenge
Defines the encryption setting where a value of false indicates the password is encrypted with base 64 and a value of true indicates the password is encrypted with MD5. The default value is true. MD5 encryption offers stronger security for passwords. Base64 is similar to sending the password in plain text.

Page 13
Introduction to LDAP Authentication

Overview
Blackboard Learn includes an LDAP (Lightweight Directory Access Protocol) module that will authenticate users against an Institutions directory server or servers using LDAP. All the files necessary to support LDAP authentication are included with Blackboard Learn.
LDAP Authentication
LDAP is an Internet standard that provides access to information from different computer systems and applications. LDAP uses a set of protocols to access information directories and retrieve information. A directory is like a database, but contains information that is more descriptive and attribute-based. Information in a directory is generally read more often than it is written or modified. LDAP allows an application, running on the Institutions computer platform, to obtain information such as user names and passwords. Centralizing this type of information is very beneficial. It simplifies the job of the System Administrator by providing a single point of administration. It also provides a single location for user information, reducing the storage of duplicate information. This, in turn, reduces maintenance needs. LDAP authentication also enables users to have a single login and password to access a number of different applications.

Page 14
LDAP Module
Overview
Standard LDAP authentication is fully integrated with Blackboard Learn. All necessary .jar files, including those for setting up an SSL connection between Blackboard Learn application server and the directory servers, are provided in the /systemlib directory. The application server startup executables include the .jar files in their classpath. Note that all configuration options in the authentication.properties file are set to default values. Some of these default values are place holders and must be changed by the Administrator for LDAP authentication to work successfully. To begin authenticating against an LDAP server or servers, set the properties found in the authentication.properties file. The SSL Configuration topic has specific information on enabling the Blackboard Learn application server and the directory servers to communicate over SSL.
Limitations
The limitations of this version of the LDAP module are summarized in the following list. The module only supports authentication through a successful bind with the directory server using the FDN for this Blackboard userthe module cannot retrieve any information from the directory.
The module only supports binding anonymously or binding with a privileged user and then performing a search for the user's FDN. Check with Blackboard Technical Support if you have any questions regarding these limitations. For installation problems or questions while using this document, contact Blackboard Technical Support by logging in to Behind the Blackboard at https://behind.blackboard.com. For planning, architectural analysis, best practices, or assistance with implementation, call Blackboard Technical Solutions.

Page 15
LDAP Configuration Overview

Overview
This topic provides an overview of the LDAP Installation process. This process consists of a set of steps that will enable the System Administrator to use LDAP authentication.
LDAP Configuration
The following steps outline the LDAP configuration process: 1. Edit the /blackboard/config/authentication.properties file. See the next topic, LDAP Property Configuration for specific information on the properties and possible values in this file. Configure the bbconfig.auth.type property to LDAP. This must be done for the configuration to proceed correctly. Make the following change in the bbconfig.properties file: bbconfig.auth.type=ldap 3. Run PushConfigUpdates to activate the changes.
2.
Open LDAP UNIX Operating Systems Only

Blackboard has two versions of LDAP client authentication modules, the default and OpenLDAP. Two modules exist because the default LDAP client does not release file descriptors when it is under heavy load. A file descriptor is used by UNIX Operating Systems to keep track of open files and network connections. If the system continually accumulates file descriptors, the server will reach a maximum number of allowed file descriptors, at which point no more files can be opened and no more network connections can be accepted. Administrators of UNIX Operating Systems who experience this file descriptor issue under heavy load may deploy OpenLDAP as a workaround. If OpenLDAP is used, the .jar files must be updated so the command line tools do not fail. A copy of the jar file should be in /systemlib. Additionally, edit /system/build/bin/launch-tool.sh and append the .jar files to the BB_CP variable. Otherwise, command line tools that bootstrap the core services (for example, LogRotation or PurgeAccumulator) will not work.

Page 16
LDAP Properties
Overview
The properties set in the authentication.properties file include general properties for LDAP configuration, as well as properties for individual directory servers. When adding multiple servers the variable x represents the sequence number. Parameters must be set for each directory server that Blackboard Learn will authenticate against. The LDAP module will access the servers according to the sequence number.
File format
The authentication.properties and bb-config.properties files contain a series of properties that must be set before authentication against the Institutions directory server or servers can occur. Each property is listed with an equal sign followed by the corresponding value.
Editing the properties file

Open the authentication.properties file in an editor and set the LDAP specific properties to match the Institution. Descriptions of the properties appear in the following section. Properties that are suffixed with a number are properties that are associated with an individual directory server. To add information for additional directory servers, add a group of properties suffixed with the next available sequence number. The LDAP module will access the servers in the order in which they are sequenced.
LDAP Property Configuration

The table below details the LDAP properties configured through the authentication.properties file. P ro p e rt y auth.type.ldap.impl De s cr ip t io n Defines the class which must conform to the HttpAuthModule interface. The default value, blackboard.platform.security. authentication.LDAPAuthModule, should not be changed unless the Institution builds and implements its own class for LDAP authorization. auth.type.ldap.use_ challenge Defines the encryption setting where a value of false indicates base 64 encryption and a value of true indicates MD5 encryption. The default value is false. MD5 encryption should only be used if the LDAP servers use MD5 encryption in the same manner as Blackboard. In most cases, using base 64 encryption and securing the connection between Blackboard Learn and the LDAP servers with SSL is the best approach.

Page 17
P ro p e rt y auth.type.ldap.num_ servers
De s cr ip t io n Defines the number of directory servers in use. For each server, there must be a corresponding set of server properties. This property must be kept current; update it each time a new servers entries are added to the authentication.properties file. Can be set to true or false. By default, this property is set to false due to the security considerations outlined in LDAP Security Considerations. If set to true the module will attempt to authenticate the user using the password in Blackboard Learn database if the user is not found in any of the directory servers. Can be set to true or false. By default, this property is set to false due to the security considerations outlined in LDAP Security Considerations. If set to true the module will attempt to authenticate the user using the password in Blackboard Learn database if there is an error connecting to any of the directory servers.
auth.type.ldap.user _not_found_fallback
auth.type.ldap.erro r_fallback_to_bb
Server Specific Properties auth.type.ldap.serv er_url.x The URL of the directory server including port. Example: ldap://directory.university.edu:389 If the LDAP server is setup to communicate over SSL, the URL should be: ldaps://directory.university.edu:636 auth.type.ldap.serv er_ssl.x Must be set to true or false. If set to true the module will attempt to connect to the LDAP directory using SSL. The LDAP server must be set up to handle SSL connections. See the SSL Configuration section for more information. Must be set to true or false. If set to true the module will bind to the LDAP server as a privileged (specific) user when searching for the FDN of the user to authenticate. The user binds as this FDN. Leave as (none) if not applicable. The password of the privileged user. Leave as (none) if not applicable. Set this property to configure how aliases are dereferenced during search operations. The following values are defined for this property: auth.type.ldap.user _tag.x always: Always dereference aliases. never: Never dereference aliases. finding: Dereference aliases only during name resolution (that is, while locating the target entry). searching: Dereference aliases once name resolution has been completed (that is, after locating the target entry).
auth.type.ldap.use_ priv_user.x auth.type.ldap.user _fdn.x auth.type.ldap.user _pwd.x auth.type.ldap.dere f_aliases.x
Set this property to the attribute containing Blackboard Learn User Name. This setting is domain specific.

Page 18
P ro p e rt y auth.type.ldap.serv er_error_fatal.x auth.type.ldap.cont ext_factory.x
De s cr ip t io n Must be set to true or false. If set to true the module will exit with a fatal error if there is an error connecting to the server. Set this property to handle password expiration warnings for LDAP accounts. The following values are defined for this property: blackboard.platform.security.authentication.Password PolicyContextFactory for IETF-compatible LDAP servers (Novell, Active Directory). This is the default value. blackboard.platform.security.authentication.Response PolicyContextFactory for Netscape-compatible LDAP servers supporting the Netscape response control specification.
auth.type.ldap.refe rral.x
The value of this property is a string that specifies how referrals should be handled by the module. The following values are defined for this property: follow: Automatically follow any referrals. throw: Throw a Java ReferralException for each referral. This will result in an error condition for this server. ignore: Ignore referrals if they appear in results. In debug mode, a log message will be generated to indicate an incomplete result, but this will not result in an error condition for this server.
auth.type.ldap.refe rral_limit.x base_search_fdn
The value of this property is a string of decimal digits specifying the maximum number of referrals to follow in a chain of referrals. A setting of zero indicates that there is no limit. The starting point in the LDAP directory structure for searching for a Blackboard Learn user.
Example
Below is an example of the LDAP properties configured through the authentication.properties file. auth.type.ldap.impl=blackboard.platform.security.authentication. LDAPAuthModule auth.type.ldap.use_challenge=false auth.type.ldap.error_fallback_to_bb=false auth.type.ldap.user_not_found_fallback_to_bb=false auth.type.ldap.log_level=error # Available property values for auth.type.ldap.log_level are fatal,error,warning,information,debug auth.type.ldap.num_servers=2 # The auth.type.ldap.num_servers property value must be increased with each server configuration addition. If there are

Page 19
three server configurations, then the value must be 3 for this parameter.
Server #1 Configuration auth.type.ldap.server_ssl.1=false # The auth.type.ldap.server_ssl property value sets SSL interaction between # the Blackboard installation server and LDAP server to true or false. auth.type.ldap.base_search_fdn.1=dc=dc,dc=blackboard,dc=com auth.type.ldap.deref_aliases.1=never auth.type.ldap.server_url.1=ldap://lsvr1 auth.type.ldap.use_priv_user.1=true auth.type.ldap.user_fdn.1=uid=UserA,ou=Special Users,dc=dc,dc=blackboard,dc=com auth.type.ldap.user_pwd.1=test1 auth.type.ldap.user_tag.1=uid auth.type.ldap.referral.1=ignore auth.type.ldap.referral_limit.1=0 auth.type.ldap.server_error_fatal.1=true auth.type.ldap.context_factory.1=blackboard.platform.security.au thentication.PasswordPolicyContextFactory
Server #2 Configuration auth.type.ldap.server_ssl.2=false # The auth.type.ldap.server_ssl property value sets SSL interaction between # the Blackboard installation server and LDAP server to true or false. auth.type.ldap.base_search_fdn.2=dc=dc,dc=blackboard,dc=com auth.type.ldap.deref_aliases.2=never auth.type.ldap.server_url.2=ldap://lsvr2 auth.type.ldap.use_priv_user.2=true auth.type.ldap.user_fdn.2=uid=UserB,ou=Special Users,dc=dc,dc=blackboard,dc=com auth.type.ldap.user_pwd.2=test2 auth.type.ldap.user_tag.2=uid auth.type.ldap.referral.2=ignore auth.type.ldap.referral_limit.2=0 auth.type.ldap.server_error_fatal.2=true auth.type.ldap.context_factory.2=blackboard.platform.security.au thentication.PasswordPolicyContextFactory

Page 20
Troubleshooting LDAP
Overview
The LDAP module should function with minimal maintenance if the authentication.properties file is configured properly. This topic includes information on how to troubleshoot configuring the properties files and on maintenance for LDAP authentication.
Debugging LDAP Authentication

Administrators may debug the LDAP authentication as part of troubleshooting. The steps below explain how to debug LDAP authentication: 1. Modify /blackboard.config/service-config.properties. Under Logging Service in the service-config.properties file set: blackboard.service.log.param.logdef.default.verbosity=debug Restart the services. /<blackboard_install_directory>/tools/admin/ServiceController services.stop /<blackboard_install_directory>/tools/admin/ServiceController services.stop Login to the system again. Search /<blackboard_install_directory>/logs/bb-services-log.txt for references to LDAPAuthModule. Windows users: Open the log file in a text editor and search for LDAPAuthModule. UNIX users: Execute the following: tail -f -n200 /<blackboard_install_directory>/config/service-config.properties | grep "LDAPAuthModule"
2.
3. 4.
Troubleshooting LDAP Authentication Properties for Windows

For Administrators using a Windows workstation, the LDP executable may be used to troubleshoot LDAP authentication properties. The LDP executable, found on the Windows 2003 Server CD in the \SUPPORT\TOOLS folder, is used to search for specific data against the Active Directory and includes a graphical user interface. For users not using Active Directory, this tool may be used in the same way against other LDAP servers. The following steps explain how to use the LDP Tool: 1. 2. 3. 4. 5. Go to the Connection menu, uncheck the NTLM/Kerberos check box, and select Bind. Enter the LDAP privileged user DN in the User: field and the LDAP password in the Password: field. Locate the defaultNamingContext attribute. Go to the View menu and select Tree. Enter the defaultNamingContext attribute value into the BaseDN: field and click OK.

Page 21
6.
Locate the container for user records (by default, the DN for this container starts with CN=Users; however the user records may be located elsewhere; try to locate the DN that contains all faculty and student user records). Record the DN that contains all faculty and student user records Double-click on the tree view of this container to see all user records. Go to the Options menu and select Search. Customize fields in the user records returned from the search. (This step may not be necessary) With the container selected, go to the Browse menu and select Search. Enter the user field to search by. The user field is the user tag property, for example, (CN=jsmith). Record the distinguishedName attribute for this user record. Verify that you can find a sample user. Enter the baseDN from Step 7 and (user_tag=someUserValue) where user_tag is the name of the LDAP user record field that the client expects users to enter in the Blackboard login form. (For example, if the client expects users to login by entering their email address as the username in the Blackboard login form, then the user_tag should be the name of the field that stores the users email address). Next, Administrators must update authentication.properties: Set auth.type.ldap.base_search_fdn.1 to the DN for the container for user records (See Step 7 above). Set auth.type.ldap.user_fdn.1 to the distinguishedName attribute value for the LDAP user (See Step 13 above). Windows Operating System only: Set auth.type.ldap.user_tag.1 to sAMAccountName if the client wants users to login to Blackboard using a Windows username. sAMAccountName is the name of the Active Directory user record field that stores the Windows username.
7. 8. 9. 10. 11. 12. 13. 14.
15.
Troubleshooting LDAP Authentication Properties for UNIX

For Administrators using a UNIX workstation, the LDAP Browser may be used to troubleshoot LDAP authentication properties. This tool may be found at http://www.iit.edu/~gawojar/ldap/. The following steps explain how to use the tool: 1. 2. 3. 4. 5. 6. Open the LDAP browser. Click File Menu and select Connect. Enter the LDAP server hostname in the Host: field. Enter the port number that the LDAP server is listening on in the Port: field. Enter the base search DN in the Base DN: field. If a privileged bind is required, uncheck Anonymous bind. Enter the privileged user DN in the User DN: field. If Append base DN is checked, the Administrator only needs to add the relative DN ( for example, if the base DN is "OU=test users,dc=blackboard,dc=com" and the privileged user's full DN is

Page 22
"CN=privldap,OU=ldap testers,OU=test users,dc=blackboard,dc=com", then only enter "CN=privldap,OU=ldap testers"). 7. 8. Click Connect. Click Search to search for a given user DN, or scroll through the list.
Revert to Default Authentication

To revert to the default authentication from LDAP, change bbconfig.auth.type to "rdbms, and restart Blackboard Learn application server. For more information, see Return to Default in the Introduction to Blackboard Learn Authentication topic.
Blackboard Application Log

Blackboard Learn log records all application events handled by the Java API. Within the log the Blackboard LDAP module writes error, warning, informational, and debug messages to the bbservices-log.txt file.
Common Problems
The table below outlines some of the common problems that may occur when authenticating Blackboard Learn users against LDAP servers. P ro b le m The LDAP module loads but users cannot log in using their LDAP passwords. An error is posted to the bbservices-log.txt whenever a user tries to log into the system. The module is configured to use SSL. The LDAP module loads, but users cannot log in. Nothing is displayed in the logs, or the messages that are displayed are insufficient to diagnose the problem. Ac t io n Ensure that all of the users logging in have a Blackboard Learn User Name. Blackboard Learn needs a user record to associate Course and other information to the user. Ensure that the server certificate for your LDAP directory has been imported into the keystore of the JVM on Blackboard Learn application server. The JVM needs this certificate to allow SSL connections to the LDAP directory. Re-run the auth-type.properties file and specify a log_level of debug. Log messages will generate with more detail.

Page 23
LDAP Scenarios
The table below details the systems response to a number of potential LDAP situations. The default configuration of LDAP will support the set of behaviors described here. Is su e The LDAP server is down S ymp t o m Authentication should fail with an appropriate message. Authentication should fail with an appropriate message. Authentication should fail with an appropriate message. Authentication should fail with an appropriate message. Blackboard Learn configuration file must be updated to proceed. Authentication should fail with an appropriate message. Blackboard Learn configuration file must be updated to proceed. The search domain would be restricted to a specific context within the directory tree. The first account returned will be the one used. It is the Institution's responsibility to set the base_search_fdn property correctly to avoid this situation. Authentication should fail with an appropriate message. The LDAP SSL certificate must be updated to proceed.
The user exists in Blackboard but not in LDAP The user exists in LDAP but not in Blackboard The privileged user doesn't exist or has expired The privileged user password has changed There are multiple LDAP accounts for a specific user
The LDAP SSL certificate expires
Troubleshooting LDAP with SSL

This section explains how to troubleshoot the SSL connection between the Blackboard server and the LDAP server for clients who are using an SSL connection to secure their LDAP server. Follow these instructions for debugging and clean up on UNIX: 1. 2. 3. 4. Save /<blackboard_install_directory>/apps/tomcat/bin/tomcat.sh as tomcat.sh.prod Enter the following command: cp tomcat.sh.prod tomcat.sh.debug Insert -Djavax.net.debug=all,record,plaintext into tomcat.sh.debug Go to line 207 of tomcat.sh.debug Edit this line to read: $JAVACMD -Djavax.net.debug=all,record,plaintext $TOMCAT_OPTS $JAVA_OPTS $MAIN start $@ \

Page 24
5. 6. 7. 8.
Enter the following command: cp tomcat.sh.debug tomcat.sh Restart services Login with the LDAP username and password. Copy the SSL-connection trace information from /usr/local/blackboard/logs/tomcat-jvm-stdout.txt. See the log file example below. Repeat Steps 6 and 7 until debugging is complete. Enter the following command: cp tomcat.sh.prod tomcat.sh Restart services.
9. 10. 11.
Follow these instructions for debugging and clean up on Windows: 1. Save D:\<blackboard_install_directory>\apps\tomcat\conf\jk\wrapper.pro perties as wrapper.properties.prod. Copy wrapper.properties.prod and name the copy wrapper.properties.debug. Insert -Djavax.net.debug=all,record,plaintext into wrapper.properties.debug. Go to line 163 of wrapper.properties.debug. Edit that line to read: "wrapper.cmd_line=$(wrapper.javabin) $(wrapper.java_opts) Djavax.net.debug=all,record,plaintext Djava.security.policy=="$(wrapper.tomcat_policy)" Djava.security.manager -Dtomcat.home="$(wrapper.tomcat_home)" Dblackboard.home="$(bbapp.root)" Dbbservices_config="$(bbapp.root)\config\serviceconfig.properties" Dorg.apache.tomcat.apps.classpath="$(wrapper.class_path.apps)" classpath $(wrapper.class_path) $(wrapper.startup_class) -config $(wrapper.server_xml)" 6. 7. 8. 9. 10. 11. 12. Delete wrapper.properties then copy wrapper.properties.debug and name the copy wrapper.properties. Restart services. Login with the LDAP username and password. Copy the SSL-connection trace information from D:\blackboard\logs\tomcatjvm-stdout.txt. See the log file example below. Repeat until debugging is complete. Delete wrapper.properties then copy wrapper.properties.prod and name the copy wrapper.properties. Restart services.
2. 3. 4. 5.

Page 25
Log File Example If the SSL -connection-setup process cannot continue, the reason for the SSL connection setup failure is printed to the tomcat-jvm-stdout.txt log. After this failure appear in the log the SSL-debug output stops. There are a number of reasons why the application server may have trouble connecting to the LDAP server over SSL. The problem can be found in the SSL-debug output. Open the tomcat-jvm-stdout.txt log; go to the end of the debug output (where it gives the reason for quitting) and then scroll backwards through the output, looking for the detailed error message. For example, in the debug output below, the end of the output shows the message Thread-31, SEND SSL v3.0 ALERT: fatal, description = certificate_unknown. Scrolling backwards through the log, the message out of date cert appears before the last certificate was processed; the certificates information shows that the certificate had expired in 2002. The example below includes the beginning of the debug output and the last section with the error: keyStore is : keyStore type is : jks init keystore init keymanager of type SunX509 trustStore is: /usr/java1.3/jre/lib/security/cacerts trustStore type is : jks init truststore adding as trusted cert: [ out of date cert: [ [ Version: V3 Subject: O=HC, CN=204.165.200.98 Signature Algorithm: SHA1withRSA, OID = 1.2.840.113549.1.1.5 Key: com.sun.net.ssl.internal.ssl.JSA_RSAPublicKey@187197 Validity: [From: Sun Jun 18 07:16:00 EDT 2000, To: Tue Jun 18 07:16:00 EDT 2002] Issuer: O=HC, OU=Organizational CA SerialNumber: [ 021411e9 6f9a05e1 28e9293c c80ae5b5 1166338c 1cbc0201 0c] Certificate Extensions: 3 [1]: ObjectId: 2.16.840.1.113719.1.9.4.1 Criticality=false Extension unknown: DER encoded OCTET string = 0000: 04 82 01 BD 30 82 01 B9 04 02 01 00 01 01 FF 13 ....0........... 0010: 1D 4E 6F 76 65 6C 6C 20 53 65 63 75 72 69 74 79 .Novell Security 0020: 20 41 74 74 72 69 62 75 74 65 28 74 6D 29 16 43 Attribute(tm).C 0030: 68 74 74 70 3A 2F 2F 64 65 76 65 6C 6F 70 65 72 http://developer 0040: 2E 6E 6F 76 65 6C 6C 2E 63 6F 6D 2F 72 65 70 6F .novell.com/repo 0050: 73 69 74 6F 72 79 2F 61 74 74 72 69 62 75 74 65 sitory/attribute 0060: 73 2F 63 65 72 74 61 74 74 72 73 5F 76 31 30 2E s/certattrs_v10.

Page 26
0070: 68 74 6D 30 htm0..J.....0.0. 0080: 02 01 01 02 .....F0.0....... 0090: 02 01 69 A1 ..i.....0.0..... 00A0: 01 46 30 08 .F0.0.........i. 00B0: 06 02 01 17 ............Z... 00C0: 02 02 00 FF ................ 00D0: 00 00 00 00 ................ 00E0: 00 30 18 30 .0.0............ 00F0: FF FF 01 01 ..........H0.0.. 0100: 01 00 02 08 ................ 0110: 04 06 F0 DF ....H0X.X....... 0120: 02 01 00 03 ......@......... 0130: 00 00 03 09 .....@.......0.0 0140: 10 02 01 00 ................ 0150: 00 02 04 11 .....o.0.0...... 0160: 7F FF FF FF ...............o 0170: 9A A2 4E 30 ..N0L........... 0180: 0D 00 80 00 ................ 0190: 00 80 00 00 .........0.0.... 01A0: 02 08 7F FF .............0.0 01B0: 10 02 01 00 ................ 01C0: 00
82 01 4A A0 01 46 30 08 1A 01 01 00 30 06 02 01 01 01 FF A3 02 01 00 03 00 00 03 09 10 02 01 00 00 02 04 06 7F FF FF FF 48 30 58 A1 0D 00 40 00 00 40 00 00 02 08 7F FF E9 6F 9A 30 FF FF FF FF 4C 02 01 02 00 00 00 00 00 00 00 00 FF FF FF FF 02 08 7F FF
1A 01 01 00 30 08 30 06 30 06 02 01 01 02 01 0A 30 08 30 06 02 01 01 02 01 02 01 0A 02 01 69 A2 82 01 06 A0 5A 02 01 02 0D 00 80 00 00 00 00 00 00 80 00 00 00 00 00 00 02 08 7F FF FF FF FF FF F0 DF 48 30 18 30 10 02 FF FF FF FF 01 01 00 02 58 02 01 02 02 02 00 FF 00 00 00 00 00 00 00 00 00 00 00 00 00 30 18 30 FF FF FF FF FF FF 01 01 18 30 10 02 01 00 02 08 01 01 00 02 04 11 E9 6F 02 01 00 02 02 00 FF 03 00 00 00 00 00 00 03 09 00 30 12 30 10 02 01 00 FF FF 01 01 00 30 12 30 FF FF FF FF FF FF 01 01 .
[2]: ObjectId: 2.5.29.35 Criticality=false AuthorityKeyIdentifier [ KeyIdentifier [ 0000: 01 ] ] [3]: ObjectId: 2.5.29.15 Criticality=false KeyUsage [ DigitalSignature

Page 27
Key_Encipherment ] ] Algorithm: [SHA1withRSA] Signature: 0000: 50 75 22 E0 14 FE E7 50 FE 44 3B 36 D2 C8 EC 10 Pu"....P.D;6.... 0010: 49 8D 48 1D 6F E6 91 1A 05 1E 8E FD 69 D3 4D 70 I.H.o.......i.Mp 0020: C3 3C FE 14 D0 D4 99 DE CA BF 23 57 80 A0 04 F2 .<........#W.... 0030: 45 33 BD B0 53 2D 72 A1 43 DD 7C 80 DD 6B 3E EC r.C....k>. 0040: 94 73 F9 83 21 2C 80 17 B1 CE 6E 19 FD 14 FF A8 .s..!,....n..... 0050: C0 CB 51 C7 1A C1 C0 E4 71 2F 46 9D 50 91 52 E8 ..Q.....q/F.P.R. 0060: 5B CA 24 84 FF 7F 3E 84 32 09 AA 43 66 E8 CD AB [.$...>.2..Cf... 0070: 65 EC 5C 89 88 43 3C 15 07 3C 9D 52 AA CF 31 A1 e.\..C<..<.R..1. 0080: C9 B6 3A 7A CC 35 1B 66 CB 3C 80 00 32 15 76 2F ..:z.5.f.<..2.v/ 0090: 86 82 26 31 2F C3 EC 58 CE DD E8 E6 A4 58 6E F0 ..&1/..X.....Xn. 00A0: 70 14 36 DF CB 29 E0 E7 D4 1A 33 62 4E B7 62 3C p.6..)....3bN.b< 00B0: 77 54 9E AA BE 57 0E 7C F2 E1 92 D5 B0 AF E9 BB wT...W.......... 00C0: 20 CA A7 AA 4F D4 37 02 DE B2 16 9D FC 7E 90 63 ...O.7........c 00D0: 10 22 49 20 76 97 83 8A 83 0E BB A6 7B B0 E4 DE v........... 00E0: FB 62 51 FD 92 EB 9F C7 B6 91 F2 94 5C 93 29 11 .bQ.........\.). 00F0: B9 A2 AE 28 46 00 BE 14 EC 1C F8 6C 63 A3 10 BA ...(F......lc... ] Thread-31, SEND SSL v3.0 ALERT: fatal, description = certificate_unknown Thread-31, WRITE: SSL v3.0 Alert, length = 2
E3..S-
."I

Page 28
LDAP Fail Over Considerations

Overview
Administrators must determine how Blackboard Learn should function if the directory servers are not functioning correctly at the time of an authentication request or if a user who does not exist in the LDAP database attempts to login to Blackboard Learn. Automatic authentication fail over may be set for one or both of the following properties: auth.type.ldap.error_fallback_to_bb auth.type.ldap.user_not_found_fallback Automatic fail-over functionality poses certain security risks that are discussed below in the Security Risks section. Note The behaviors listed in the LDAP Scenario topic on the Troubleshooting page do not apply if the default configuration is changed.
Automatic Fail Over for LDAP Server Error

LDAP authentication is intended as an enterprise-level integration; therefore, the expectation is that the LDAP server will be managed administratively as a mission-critical system. The LDAP interface was developed to depend upon the constant availability of the directory servers. Automatic fail over in the case of LDAP server error enables Institutions that are not supporting LDAP as a mission-critical system to allow users access to the system if the LDAP server fails. Automatic authentication fail over will allow Blackboard Learn to continue to run in the event that the LDAP server or servers do not function correctly. In this instance, automatic fail over is set for the auth.type.ldap.error_fallback_to_bb property.
Automatic Fail Over for Users who Do Not Exist in LDAP Database
This fail over option allows users who do not exist in the LDAP database to log into Blackboard Learn. Examples are an Administrator user or students who are auditing, but are not enrolled, in a class. In this instance, automatic fail over is set for the auth.type.ldap.user_not_found_fallback property.
Security Risks
Automatic authentication fail over has some additional security risks: Passwords are not synchronized: Blackboard Learn will not know the passwords in LDAP, so Administrators have to keep track of separate passwords. Security back doors: Automatic fail over for authentication may introduce serious security problems not related to Blackboard Learn. For example, if a user attempted a denial of service (DOS) they could shut down the directory server and attempt to log in with default passwords, which is the user name.

Page 29
Synchronizing user data between the LDAP servers and Blackboard Learn (via Snapshot or the Event Driven APIs) can prevent failover from using default passwords and also enable failover to require the same password as the normal LDAP authentication.
Changing the Default Configuration for LDAP Server Error

Follow the steps below to enable authentication fail over in case of an LDAP server error: 1. 2. 3. Set the authentication property auth.type.ldap.error_fallback_to_bb to true. Populate Blackboard Learn database with correct username and password information. Restart the application server.
For more information, see LDAP Properties.
Changing the default configuration for users that do not exist in LDAP database
Follow the steps below to enable authentication fail over if a user does not exist in the LDAP database: 1. 2. 3. Set the authentication property auth.type.ldap.user_not_found_fallback to true. Populate Blackboard Learn database with correct username and password information. Restart the application server.
For more information, see LDAP Properties.

Page 30
LDAP with Active Directory

Overview
Administrators may decide to use Active Directory via LDAP. This may be done by connecting to Active Directory via an anonymous bind or by using a privileged user. The following topic explains how to set up an anonymous connection or a privileged connection, and some accompanying security risks.
Connecting via an Anonymous Bind

Active Directory does not allow anonymous access by default, but Administrators may enable anonymous searches if they choose. Note There are security risks with allowing anonymous LDAP binds with Active Directory; in this case, any users who have network access to the Active Directory server can search Active Directory.
To enable anonymous searches on the Active Directory server, follow the steps below: 1. 2. 3. 4. On the Windows 2000 Active Directory server, run the Active Directory Users and Groups administration tool. Select the top level of the directory from the tree view in the left hand panel, and right click. Select the first item on the menu, which begins with Delegate Control. Click Next. In the next window, titled "Users or Groups" click Add. On the next list, select ANONYMOUS LOGON and click Add. Administrators may also need to select Everyone and the Guests group, depending on how Active Directory is configured. Click OK when this is done. Click Next. Select Create a custom task to delegate and click Next. In the next list, select Read. Read All Properties will be selected at the same time. Click Next. Click Finish.
5. 6. 7.
Connecting via a Privileged Bind

By default, Active Directory can only be searched via LDAP if a privileged user is used to connect to the LDAP server. A privileged bind requires the distinguished name (DN) and password for the user. There are two options for connecting via a privileged bind: Note Create a new Windows user within Active Directory. Assign this user only the right to read access to the directory. Use this user as the privileged user. Use an existing Windows user as the privileged user.
There are security risks with connecting via a privileged bind to Active Directory. Any user who can navigate to the file system and locate the authentication.properties file may find the user ID and password of the privileged user.

Page 31
Troubleshooting LDAP with Active Directory

For Administrators using a Windows workstation, the LDP executable may be used to troubleshoot LDAP authentication properties. The LDP executable, found on the Windows 2003 Server CD in the \SUPPORT\TOOLS folder, allows LDAP operations to be performed against Active Directory and includes a graphical user interface. More information about this may be found in the topic Troubleshooting LDAP. The only change for this procedure is in Steps 2, 10 and 12. Follow the steps below when using the LDP executable against Active Directory: 1. 2. 3. Login as the Windows user (username, password, domain) whose username and password are being used for the privileged bind. Add 'sAMAccountName' to the Attributes field and click OK. Enter the (sAMAccountName=someWindowsUserName) in the Filter field, where 'someWindowsUserName' is the Windows username that will be used as the privileged user for binding to LDAP.
For Administrators using a UNIX workstation, the LDAP Browser may be used to troubleshoot LDAP authentication properties. More information about this may be found in the topic Troubleshooting LDAP.

Page 32
Introduction to Web Server Delegation Authentication

Overview
Web servers support a range of technologies for identifying and authenticating users. By default, the application server (Tomcat) handles authentication. During Web Server Delegation authentication, the application server delegates some aspects of authentication to the Web server (Apache or IIS).
Management
When using Web server delegation much of the work related to the authentication is handled on the Web server. The process for Web server authentication is: 1. 2. 3. 4. Obtain the credentials of the user. Verify the users credentials. Set a header in the request that is populated with the value for the CGI variable REMOTE_USER. If a custom module has been created, it will look for the header name that was set in Step 3. If it finds this header, the value will be used as the external user ID.
Step 1 through Step 3 must be implemented by a Web server module/filter. For example, Blackboard provides an Active Directory filter for IIS. Clients using UNIX can set up Kerberos with Apache. The System Administrator must ensure that the authentication filter has been installed on the Web server. If using Windows, please see the Active Directory section for more information. Step 4 takes place within the application server and requires that the authtype.webserver.impl is specified in the authentication.properties file. Note Kerberos authentication may be incompatible with direct access to WebDAV. Institutions using this type of authentication may be able to take advantage of WebDAV by first authenticating with Blackboard Learn, and then launching the Web Folder from within the user interface.
Implementation
The following are steps for implementing Web server delegation: 1. 2. 3. Install the appropriate filter (for example, Kerberos on Apache). Update the authentication.properties file if needed. Restart the application server and the Web server.

Page 33
Web Server Delegation with Windows 2003

Overview
It is necessary to complete some additional steps to use Web Server Delegation with Windows 2003. Note that Active Directory authentication is a form of Web Server Delegation.
Configure Web Server Delegation with Windows 2003

Follow these steps to configure Web Server Delegation with Windows 2003. 1. 2. 3. Edit the authentication.properties file. For more information, see the Property Configuration section under Active Directory Authentication. Edit the bb-config.properties file to change bbconfig.auth.type to bbconfig.auth.type=webserver. Deploy configuration updates: cd BB_DEPLOY_DIR\tools\admin PushConfigUpdates.bat 4. 5. Run PushConfigUpdates.bat. PushConfigUpdates.bat will overwrite any customizations to the configuration. Run the websitereinstall.bat which will delete and recreate the Blackboard website. All custom changes to IIS will be removed, including configurations to support SSL Choice. Open IIS 6.0. Right click on the Blackboard website and click Properties. In the IIS Management Console for Blackboard Learn, select the authentication method or methods. The options are Basic, Digest, and Integrated Windows authentication. One or more options may be selected. Select the ISAPI Filters tab. Verify that the Windows.dll has been added. Also, verify the order of the filters. They should be in the following order: Sessiontracker, Windows, Jakarta. If they are not in order, move them into the correct order. Click Apply. Click OK.
6. 7. 8.
9.
10. 11.

Page 34
Introduction to Active Directory Authentication

Overview
Blackboard Learn supports Web server delegated authentication. It includes a Web server filter for Active Directory that will authenticate users against an Institutions Active Directory server. All the files necessary to support Active Directory authentication are included with Blackboard Learn.
Active Directory Authentication

Microsoft Active Directory is a part of the Windows 2003 network architecture. It allows Organizations to share and manage information about network resources and users. In addition, Active Directory acts as the central authority for network security, letting the operating system verify a user's identity and control his or her access to network resources, such as data, applications, or printers. There are a number of benefits to using Active Directory. Administrators have a single point of management for Windows-based user accounts, clients, servers, and applications. Active Directory authentication also allows for standardized business rules for applications and network resources.
Limitations
The users Blackboard Learn User Name is associated with their Microsoft Windows login. This means that the users database record is linked to their Windows User Name and password allowing them to only have one Blackboard Learn User Name. For example, Windows user jdoe can only have one Blackboard Learn login; he or she cannot be Instructor1 and Student2 in Blackboard Learn. To ensure the safety of user accounts, the browser must be closed and the user must log off of Windows when a session on a shared computer is ended. For questions about these limitations, contact Blackboard Technical Support by logging in to Behind the Blackboard at https://behind.blackboard.com.
Active Directory Authentication and Portal Direct Entry

Blackboard does not currently support using Web Server Delegation with Portal Direct Entry. Clients who would like to set up a customized authentication with Web Server Delegation and Portal Direct Entry should contact Blackboard Global Services.

Page 35
Active Directory Configuration

Overview
The properties set for Active Directory authentication are found in the auth.type.webserver section of the authentication.properties file. Note There is no special configuration needed for IIS.
File format
The authentication.properties file contains a series of properties that must be set before authentication against the Institutions Active Directory server or servers can occur. Each property is listed with an equal sign followed by the corresponding value.
Set authentication type

Prior to editing the authentication.properties file, the authentication type (bbconfig.auth.type) must be edited in the bb-config.properties file. This allows Blackboard Learn to select the appropriate set of auth.type*.* entries at start up. The following steps are instructions for setting the authentication to Active Directory. 1. 2. 3. 4. Edit the authentication.properties file. Edit the bb-config.properties file so that bbconfig.auth.type=webserver Run the PushConfigUpdates command. IIS only: Run the Website Reinstaller tool. This tool removes and reinstalls IIS. <blackboard_install_directory>\tools\admin\WebsiteReinstall.bat In the IIS Management Console for Blackboard Learn, select the authentication method or methods. The options are Basic, Digest, and Integrated Windows authentication. One or more options may be selected. Note All custom changes to IIS will be removed after running this tool. For example, configurations to IIS to support SSL Choice will be erased.
Property Configuration
The table below details the properties configured through the authentication.properties file. P ro p e rt y auth.type.webserver.impl=blackb oard.platform.security.authenti cation.WindowsAuthModule De s cr ip t io n Defines the class which must conform to the HttpAuthModule interface. The default value, blackboard.platform.security. authentication.WindowsAuthModule, should not be changed unless the Institution

Page 36
P ro p e rt y
De s cr ip t io n builds and implements its own class for Web Server Delegation authorization. If using Kerberos or another type of Web Server Delegation and it is configured to set the standard REMOTE_USER header then use blackboard.platform.security. authentication.ExternalAuthModule.
auth.type.webserver.user_accoun t=reconcile, create or deny
Describes how external users are handled by Blackboard Learn. It is set to reconcile, create or deny. The first thing the system does for any of these settings is check for an existing user account that is associated with the external User ID. If one is not found, the following will occur: If set to reconcile the system will display a page that allows the user to login as an existing Blackboard user once, associate that Blackboard user account with the external user ID, and then will log them in via Web server delegated authentication in the future. If set to create, the system will try and create a new user account with minimal information that has to be updated by the user or Administrator. The user name is automatically webserver-user-user number (for example, webserver-user-100). If set to deny, a message will be displayed for the user to contact the Administrator.
auth.type.webserver.suppress
This property, if set to "true hides the login form fields. This should be used when an external authority is the only place where passwords should be entered, as is standard with web-based authentication.
Example
The example below details the properties configured for Web server delegation through the authentication.properties file. The example uses reconcile to handle external users. Create and Deny are also valid options for this property. auth.type.webserver.impl=blackboard.platform.security.authentica tion.WindowsAuthModule auth.type.webserver.user_account=reconcile auth.type.webserver.suppress=true

Page 37
Active Directory Security Considerations

Overview
Active Directory authentication is intended as an enterprise-level integration. Active Directory works with Microsoft Windows and creates a centralized place to share and manage information about users and the network. Active Directory also acts as the systems center for network security. There are a few security considerations to keep in mind when using Blackboard Learn and Active Directory.
Security Considerations
When the Active Directory authentication is implemented a user has a single Microsoft Windows User ID and a single Blackboard Learn User Name. The database has a single entry for this user. The level of security for the Windows User ID and password is the same as that for Blackboard Learn User Name and password. When users are working on a shared computer they must close the browser and log out of Windows at the end of the session to ensure their security in maintained.

Page 38
Introduction to Custom Authentication

Overview
Custom authentication enables developers to create a customized authentication module that may be plugged into the authentication framework of Blackboard Learn. Blackboard Learn ships to clients with several authentication techniques, each with its own associated module. Developing customized authentication allows clients to do either of the following: replace the pre-built modules with a module provided by the client or by a third party specify a different authentication technique with its own properties
Any module that conforms to the Blackboard End-User Authentication API may be substituted. The Blackboard Challenge-Response authentication type is installed by default, and will be referred to as the default authentication type throughout this section. Module refers to a Java class that implements the interface blackboard.platform.security.authentication.HttpAuthModule. Please see the Authentication API for more details on this interface. Note For questions on creating highly customized authentication implementations, please contact Blackboard Technical Solutions.
Audience
Developers who wish to create a customized authentication module should have the following: a good understanding of general security principles, especially regarding authentication and Web based security experience with Java servlet programming
Data Model
There is no dedicated data model for authentication, however the default authentication process relies on the password and user name attributes of the user entity. See the Blackboard Building Blocks Extension Developers Guide for details on the data model.

Page 39
Object Model
Overview
There are three objects used in Blackboards default authentication type: HttpAuthManager HttpAuthModule BaseAuthenticationModule
The HttpAuthManager class and the HttpAuthModule interface cannot be modified. Institutions can plug-in their own module for a supported authentication type.
Authentication Object Model

The BaseAuthenticationModule class implements the HttpAuthModule interface and supports the default authentication type. The following object model depicts the HttpAuthModule implementations for LDAP and Web server delegation. IIS Web server delegation support is implemented in the class WindowsAuthModule. Apache Web server delegation support is implemented in the class ExternalAuthModule.
Note
Although WindowsAuthModule are public Java classes, it is not permitted to extend these classes. Most authentication modules will extend BaseAuthenticationModule. The PassportAuthModule is not supported in Release 7.0 and higher.

Page 40
Authentication Process
Overview
The servlet that initializes Blackboard Learn calls HttpAuthManager.init()which does the following: loads the authentication configuration settings creates and initializes an instance of an HttpAuthModule implementation class installs the instance into the HttpAuthManager class
Login
Authentication processing in the Blackboard Learn is centralized in a login-broker servlet, installed at /webapps/login. The login-broker servlet processes all login requests for the Blackboard Learn. Login request universal resource identifiers (URIs) take the form of /webapps/login. Every JSP page in Blackboard Learn that requires an authenticated user session does one of the following: redirects to the login broker displays a link to the login broker if the current user is not logged in or is not logged in as a user with sufficient authorization for the page The image below demonstrates how the login-broker servlet processes login requests.
The login-broker servlet invokes the method validateSession() on a HttpAuthManager instance. The HttpAuthManager method validateSession() calls the doAuthenticate method on the module installed on the HttpAuthManager class. The servlet uses the boolean result of this method to determine whether to invoke the method sendNewLocRedirect() on the HttpAuthUtil class, or to trigger the requestAuthenticate() method on HttpAuthManager object.

Page 41
The sendNewLocRedirect() method on the HttpAuthUtil class retrieves the new_loc parameter in the request, translates it to a URL and forwards the request to that URL. Please see Customizing Authentication Page Flow for more information on the new_loc parameter. The requestAuthenticate() method on the HttpAuthManager calls the requestAuthenticate()method on the module that was installed during system startup. The modules requestAuthenticate() method is called so the implementation may prompt the user for credentials. These credentials must then be submitted to the login broker via HTTP.
Logout
The login-broker servlet also processes all logout requests for the Blackboard Learn. Logout request URIs take the form of /webapps/login?action=logout. The servlet invokes the method invalidateSession() on a HttpAuthManager instance. After the session is invalidated, the servlet forwards the request to the index page Blackboard Learn. When a users session has timed out, and the user tries to access a page in the Blackboard Learn that requires an authenticated user session, the system redirects the user to the login broker.

Page 42
Authentication API
Overview
This section explains the different methods that require implementation for the authentication process. The Authentication API is defined by the Java interface blackboard.platform.security.authentication.HttpAuthModule. All custom authentication modules must implement this interface. Please see the API Specification for more information on the arguments and returns for each method.
Authentication Processing Methods

The following authentication processing methods are implemented in the authentication module. See the sample authentication module below for an example of the usage of these methods. init() is called by the authentication framework when it creates an instance of HttpAuthManager, which in turn creates an instance of the appropriate authentication module and allows the implementation class to perform any required initialization. The sole argument passed in is the ConfigurationService object created during system startup. This method is intended to cache properties relevant to custom authentication that are defined at system startup. Installation specific properties can be obtained from the ConfigurationService and is different from the properties passed in setConfig(). See the following method example. An authentication module that needs to insert a completely new set of entries in the authentication.properties must implement an init() method that calls the configure() method on the class HttpAuthConfig. Please see Configuration File Processing below for more details. /* * Module initialization. This method gets called when Tomcat starts up. */ public void init(ConfigurationService arg0) throws IllegalStateException { //Although this is not necessary for subclasses of //BaseAuthenticationModule, it is a good practice to do this //unless there is a reason not to. super.init(arg0); try { // Set up logging _logger = BbServiceManager.getLogService(); } catch (RuntimeBbServiceException e) { e.printStackTrace(); } if (_logger == null) { // This println statement will output to the

Page 43
//stdout-stderr.log file. System.out.println("logger is null"); } else { _logger.logWarning("Custom Auth Module: init()"); } }
requestAuthenticate() is called if the user is not logged into the Blackboard Learn. The implementation may prompt the user for their credentials. This method may be used for the following: to generate a HTTP-302 status in the response, or Javascript, to redirect to a login URL to generate a login form programmatically via the servlet API to generate an HTTP-401 response to forward the user to the appropriate point in the customized Blackboard Learn (for example, by using a javax.servlet.RequestDispatcher.forward()) /* * Gets called when the user needs authenticating. */ public void requestAuthenticate( HttpServletRequest request, HttpServletResponse response) throws BbSecurityException { //Do the superclass implementation, redirect to the Default Login //Page _logger.logWarning("Custom Auth Module: requestAuthenticate()"); super.requestAuthenticate(request, response); }
Please see Customizing Authentication Page Flow in this document for related information. doAuthenticate() is called for the implementation to: parse the request extract any credentials perform the authentication work /* * Does the work of authenticating the user. */ public String doAuthenticate( HttpServletRequest request, HttpServletResponse response) throws BbSecurityException, BbAuthenticationFailedException,

Page 44
BbCredentialsNotFoundException { //Do custom processing here, just make sure //the user name is returned or the appropriate exception //is thrown. _logger.logWarning("Custom Auth Module: doAuthenticate()"); return super.doAuthenticate(request, response); } doLogout() is called when the user explicitly logs out. The implementation may perform any tasks required of its authentication authority and remove any session variables. Custom authentication modules that subclass BaseAuthenticationModule may use its implementation to clean up Blackboard Learn specific session information. /* * Gets called when the user explicitly logs out. */ public void doLogout( HttpServletRequest request, HttpServletResponse response) throws BbSecurityException { _logger.logWarning("Custom Auth Module logging out"); //If subclassing BaseAuthenticationModule, the superclass //implementation can be called. It basically performs the //work of invalidating a users session. SessionStub sessionStub = new SessionStub( request ); sessionStub.disassociateCurrentSessionAndUser(); } Note This method may not be called since users may close their browser and not explicitly log out.
isAuthenticated() has been deprecated and is only included to maintain backward compatibility. If BaseAuthenticationModule is being extended, no implementation is necessary. Note Implementing this method will not over-ride the login brokers internal checks that determine whether the current Blackboard Learn session is authenticated.
Of the above interface methods, the key methods for cooperating with the login broker are doAuthenticate(), requestAuthenticate() and doLogout().

Page 45
Configuration File Processing Methods

The authentication framework expects to find an authentication.properties file in the /blackboard/config directory of Blackboard Learn. The class blackboard.platform.security.authentication.HttpAuthConfig loads the authentication.properties settings into memory and manages the process of configuring an HttpAuthModule object with the appropriate settings. If an Institution wishes to create a custom authentication module that requires a completely new set of entries in the authentication properties file, then all three HttpAuthModule methods described below must be implemented by the custom authentication module. getAuthType() returns a String identifier for the authentication technique. The four authentication techniques supported by the Blackboard Learn (Blackboard default authentication, LDAP, and Web server delegation) are represented as rdbms, ldap, and webserver. The authentication framework loads this String identifier from the bb-config.properties setting for bbconfig.auth.type. The authentication framework then requests that the HttpAuthConfig class, which has loaded all settings found in the authentication.properties setting, creates an HttpAuthConfig instance which stores all authentication.properties settings with the given auth.type identifier. For example, if bbconfig.auth.type is set to ldap, then all property settings that match auth.type.ldap are loaded into a new HttpAuthConfig instance. This method should be implemented for every authentication module class. For example, with the Sample Custom Authentication Module, the following entry needs to be changed in the bb-config.properties file: auth.type.custom.impl=blackboard.authentication.test.CustomAuthM odule getPropKeys() returns a String array of the keys to an authentication module's configuration properties. For example, the BaseAuthenticationModule has the keys impl and use_challenge. This method should be implemented for every authentication module class. The array must contain all of the property keys for the custom implementation. At a minimum, the method should return the impl property which specifies the fully qualified class name of the HttpAuthModule implementation. In order to obtain the value of the properties, the authentication module can use the HttpAuthConfig.getProperty() method with the property name. Only the property name need be specified, not the entire entry in the authentication.properties file. For example, with the Sample Custom Auth Module, the following entries need to be added to the authentication.properties file: auth.type.custom.impl=blackboard.authentication.test.CustomAuthM odule auth.type.custom.prop1=test To get the property of prop1, the following method can be used: // _config has already been defined as a member variable of type HttpAuthConfig String prop1 = _config.getProperty(prop1); setConfig(HttpAuthConfig config) implies a contract between HttpAuthModule and HttpAuthConfig, such that HttpAuthConfig is expected to supply the correct object for a given property key. Subclasses of BaseAuthenticationModule do not need to implement this method, and can use the _config member variable to obtain configuration properties.

Page 46
Implementation Details
Overview
This topic includes information on how the different authentication types (Blackboard default authentication, LDAP, and Web server delegation) are implemented. This information may be helpful to developers creating a custom authentication for their Blackboard Learn.
Blackboard Default Implementation

The default implementation (realized in the class BaseAuthenticationModule) is implemented as a challenge response protocol, using a form submitted by HTTP-POST. This is a mechanism that avoids sending the actual password over the network in an unprotected fashion. In a nave authentication implementation, username/password combinations would simply be transmitted across the network in clear text. The problem with this method is that malicious users would be able to see the username and password. To facilitate greater security the authentication framework generates a pseudo-random number for each authentication attempt that is MD5-hashed against the servlet engines session ID. This challenge string is sent to the client. The challenge string increases system security by improving the chances that the transmitted code has not been tampered with. When the user enters their password, it is MD5-hashed, then that hash string is combined with the challenge string sent by the server, and the resulting string is MD5-hashed. The resulting string is cryptographically secure in that the hash is one-way (MD5). This means that it is not possible to reconstruct its inputs, or to find inputs that result in the same hashed value. This compound hash is called the response. The server, when it receives the client response, performs the same calculations the client performed (except on the server-side, the password is already hashed). Additionally, the challenge string is also re-calculated from the stored pseudo-random number (to help prevent session hijacking). If the results match the client response, the authentication is successful.
LDAP Implementation
Blackboard has implemented a simple LDAP authentication module that uses data from the authentication.properties configuration file to bind to an LDAP server, or series of LDAP servers, and perform a lookup of a given user. For more information about the configuration settings for LDAP authentication, see LDAP Authentication.
Web Server Delegation Implementation

Blackboard has implemented a Windows-specific Web server delegation authentication module that assumes the installation of a Blackboard-created ISAPI filter on the Web server; the ISAPI filter populates a request header containing the Active Directory username for the Windows user. The WindowsAuthModule authentication module parses the request, extracts the unique identifier and attempts to match that identifier to a user in Blackboard Learn database. WindowsAuthModules parent class, ExternalAuthModule, is a simple, general implementation for Web server-delegated authentication. It assumes that a module or filter has been installed on the Web server that populates the Computer Gateway Interface (CGI) variable REMOTE_USER in the request headers.

Page 47
Extending Other Blackboard-created Authentication Modules

Extending other Blackboard-created implementations such as WindowsAuthModule is not permitted at this time.
Sample Custom Authentication Module

The following is an example of a Custom Authentication Module: package blackboard.authentication.test; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import blackboard.platform.BbServiceManager; import blackboard.platform.RuntimeBbServiceException; import blackboard.platform.config.ConfigurationService; import blackboard.platform.log.LogService; import blackboard.platform.security.authentication.BaseAuthenticationMo dule; import blackboard.platform.security.authentication.BbAuthenticationFail edException; import blackboard.platform.security.authentication.BbCredentialsNotFoun dException; import blackboard.platform.security.authentication.BbSecurityException; import blackboard.platform.security.authentication.HttpAuthConfig; import blackboard.platform.security.authentication.SessionStub; /** * @author Blackboard Development * * A Sample Custom Authentication Module. */ public class CustomAuthModule extends BaseAuthenticationModule { //Save the log service so that we can log events. private LogService _logger; /* * Module initialization. This method gets called when Tomcat starts up. */

Page 48
public void init(ConfigurationService arg0) throws IllegalStateException { //Although this is not necessary for subclasses of //BaseAuthenticationModule, it is a good practice to do this //unless there is a reason not to. super.init(arg0); try { // Set up logging _logger = BbServiceManager.getLogService(); } catch (RuntimeBbServiceException e) { e.printStackTrace(); } if (_logger == null) { //This println statement will output to the //stdout-stderr.log file. System.out.println("logger is null"); } else { _logger.logWarning("Custom Auth Module: init()"); } } /* * Does the work of authenticating the user. */ public String doAuthenticate( HttpServletRequest request, HttpServletResponse response) throws BbSecurityException, BbAuthenticationFailedException, BbCredentialsNotFoundException { //Since this module uses the standard Learn login form, //use the superclass implementation. The authenticated() method is then //overridden to customize behavior. Other authentication modules //could do something else here if needed, as long as the //userid is returned or an exception is thrown. _logger.logWarning("Custom Auth Module: doAuthenticate()"); return super.doAuthenticate(request, response); } /* * Gets called when the user explicitly logs out.

Page 49
*/ public void doLogout( HttpServletRequest request, HttpServletResponse response) throws BbSecurityException { _logger.logWarning("Custom Auth Module logging out"); //perform custom logout work here } /* * Gets called when the user needs authenticating. */ public void requestAuthenticate( HttpServletRequest request, HttpServletResponse response) throws BbSecurityException { //Do the superclass implementation, redirect to the Default Login //Page _logger.logWarning("Custom Auth Module: requestAuthenticate()"); super.requestAuthenticate(request, response); } /* * Returns a String containing the authentication type. */ public String getAuthType() { return "custom"; }
/* * Returns a String array of properties used by this authentication * type. */ public String[] getPropKeys() { String[] props = {"impl", "prop1"}; return props; }

Page 50
/* * Blackboard Learn calls this to hand the authentication module the * configuration properties. This gets called before init so that it can * use its properties if needed. */ public void setConfig(HttpAuthConfig config) { //Just use BaseAuthenticationModule implementation. It will set //the member variable _config. Most modules that extend //BaseAuthenticationModule need not override this method. super.setConfig(config); } /* * Overrides BaseAuthenticationModule to do something different. */ protected String authenticate( String username, String password, SessionStub sessionStub, boolean useChallenge) throws BbAuthenticationFailedException, BbSecurityException { //Do authentication logic here; validate password against an external //source... Could also call the superclass implementation to "fall //back" to Blackboard. //This implementation just tries out the exceptions that can be //thrown. if (username.equals("error1")) { throw new BbAuthenticationFailedException("Custom auth module, error1."); } if (username.equals("error2")) { throw new BbSecurityException("Custom auth module, error2."); }

Page 51
if (username.equals("error3")) { //null parameters, should display standard message. throw new BbAuthenticationFailedException(); } //otherwise, return the user passed without checking. The user must //exist in Blackboard Learn for this to work properly. return username; } } //End CustomAuthModule
Sample IUserPassAuthModule Code

You need to implement IUserPassAuthModule in a custom authentication module and add the getUserFromUsernamePassword(x,y) method as follows: public class CustomAuthModule extends BaseAuthenticationModule implements IUserPassAuthModule{ public User getUserFromUsernamePassword(String username, String password) throws PersistenceException, BbAuthenticationFailedException, BbSecurityException { // Required when implementing IUserPassAuthModule // IUserPassAuthModule is necessary to ensure compatibility with Content System (WebDAV) String validatedUsername = authenticate(username, Base64Codec.encode(password), null, false); if (validatedUsername == null) return null; User user; try { user = UserDbLoader.Default.getInstance().loadByUserName(validatedUsern ame); } catch (KeyNotFoundException e) { return null; } catch (Exception e) { return null; } } return user; } }

Page 52
Customizing Authentication Page Flow

Overview
This section discusses how to customize the routing between pages in Blackboard Learn. An Institution may customize routing by uploading a custom login page to Blackboard Learn server (via the Customize Login Page link on the System Control Panel), or by implementing the requestAuthenticate() method on the HttpAuthModule interface. The Customize Login Page function on the System Control Panel allows the Administrator to download a template for the login page and then upload a modified template to the server. This allows the Administrator to add extra script functionality to the login page hosted by Blackboard Learn. Note Institutions interested in customizing their Blackboard Learn login page must not remove the JSP tags on the page.
Implementing requestAuthenticate()
If the user wishes to redirect to a login form on a page hosted by another application, instead of using the Customize Login Page function, the user should implement the HttpAuthModule interface method requestAuthenticate() to do a redirect. For authentication to function properly, any login form on a page hosted by another application must submit the form to the login broker at the Institutions URL (for example, a login page hosted at http://another.institution.com must submit its login form to the URL http://your.institution.edu/webapps/login).
Redirecting to the Original Target URL

If a user has clicked a bookmarked URL that leads into the Blackboard Learn, but they are not currently authenticated, the application will route the user to the login broker URI with the originally requested URL preserved. The login broker expects that the rest of the application will preserve the originally-requested URL, in URL-encoded form, as either a hidden form variable or a query string parameter named new_loc. Any custom Login page uploaded to the Blackboard Learn server, or any third-party script page that requestAuthenticate() redirects to, must keep this contract as well. If not, the Blackboard Learn will route to its default entry page.

Page 53
Creating and Deploying Custom Implementations

Overview
This section explains how developers may use the implementations provided by Blackboard Learn to create custom authentication modules for their Institution. It also reviews how to extend Blackboard Learn default implementation for a custom authentication module and how to create custom authentication modules for LDAP and Web server delegation.
Extending Blackboard-provided Implementations

Rather than creating a custom implementation of the HttpAuthModule interface from scratch, clients may create a Java class that inherits from one of the HttpAuthModule implementations included with Blackboard Learn. Re-using existing application components allows for custom authentication functionality with a minimum of development effort.
Extending the Blackboard Default Implementation

The default implementation may be re-used to simplify implementations that only require custom processing of the user credentials. This has the added benefit of being able to re-use the challenge/response features of the default implementation without duplicating code. The simplest way to extend the default implementation is to extend the class BaseAuthenticationModule, over-riding only the doAuthenticate() method. The doAuthenticate() method returns a string representing the username for the user who has been authenticated. Subclasses of BaseAuthenticationModule may either completely over-ride the doAuthenticate() method, or re-use the result. The following is an outline of an implementation that re-uses the result: import blackboard.platform.security.authentication.*; public class CustomAuthModule extends BaseAuthenticationModule throws BbSecurityException, BbAuthenticationFailedException, BbCredentialsNotFoundException { public String doAuthenticate(HttpServletRequest request, HttpServletResponse response) { // Get the default authentication techniques result String username = super.doAuthenticate( request, response ); /* OUTLINE OF POSSIBLE CUSTOM AUTH CODE */ // Check some data source external to Blackboard Learn // Do some extra processing related to custom authentication check

Page 54
// Return the username if no exceptions have been thrown return username; } } Alternatively, any or all of the methods in the HttpAuthModule interface may be overridden in custom authentication modules.
Creating a Custom LDAP Implementation

The Blackboard LDAPAuthModule is a very straightforward implementation of LDAP authentication. Custom LDAP implementations that wish to extend the functionality of the Blackboard LDAPAuthModule by binding to a given LDAP schema and performing queries specific to that schema can do so by subclassing from the Blackboard class and overriding its authenticate() method. The LDAP module may be extended to add additional behavior (such as additional processing after calling super.authenticate()). However, changing the behavior of the LDAP module cannot be overridden. If the Blackboard-supplied LDAP module is not sufficient, a completely new module (extending BaseAuthenticationModule) could be developed to access the LDAP directory in a specialized way Please see LDAP Properties for a detailed discussion of the property settings for LDAP authentication.
Creating a Custom Web Server Delegation Implementation

For custom authentication implementations that rely on Web server modules or filters, ExternalAuthModule has been provided as the simplest possible implementation. The ExernalAuthModule method parses the request and extracts the CGI variable REMOTE_USER as the user name to authenticate against. The custom Web server delegation implementation would only need to install a module or filter (for example, Kerberos on Apache) on the Web server and configure it to populate the request with the CGI variable REMOTE_USER.
Deploying Custom Implementations

Once the .JAR file containing the .class file for the custom authentication class is built, place the .JAR file in the tomcat auto load directory. The custom .JAR files are stored in the common classloader of Tomcat. Follow the steps below: 1. 2. 3. Note Open the directory config/tomcat/classpath and create a new text file named yourinstitution-common.classpath.bb. Open this text file and enter the full name of the .JAR files that should be included in the classpath. Run PushConfigUpdates to copy the file to the correct location. A copy of the jar file should be in /systemlib. Additionally, edit /system/build/bin/launch-tool.bat (or .sh on Unix) and append the .jar files to the BB_CP variable. Otherwise, command line tools that bootstrap the core services (for example, LogRotation or PurgeAccumulator) will not work.

Page 55
Updating the Collaboration Server

Administrators who use custom authentication may experience issues with the Collaboration server. The collaboration server breaks because of the AccessManager in service-configcollab-server.properties. This issue may be resolved by adding the custom authentication module class to the collaboration server's classpath. Follow the steps below: Windows 1. Add the classpath to the location of the authentication module classes (either a path to a directory, or a path to a jar file) to the install-nt-services.bat.bb. Administrators may use the wildcard syntax for the Blackboard install directory. Run PushConfigUpdates. When updates to the system are installed, the .bb file may be overwritten. Save a copy of the .bb file before an update and use this copy to replace the .bb template.
2. Note
UNIX 1. Add the classpath to the location of the authentication module classes (either a path to a directory, or a path to a jar file) to the collabserverctl.sh.bb. Administrators may use the wildcard syntax for the Blackboard install directory. Run PushConfigUpdates. When updates to the system are installed, the .bb file may be overwritten. Save a copy of the .bb file before an update and use this copy to replace the .bb template.
2. Note
Updating the launch-tool Script

Administrators should add the custom authentication jar file to the classpath of the launch-tool and launch-app scripts to prevent issues with the PurgeAccumulator tool and other administrative tools. Windows Add the classpath to the location of the authentication module classes (either a path to a directory, or a path to a jar file) to the launch-tool.bat. This file is located in blackboard\system\build\bin. Note UNIX Add the classpath to the location of the authentication module classes (either a path to a directory, or a path to a jar file) to the launch-tool.sh. This file is located in blackboard/system/build/bin. Note Save a copy of the files before attempting to add the classpath. Save a copy of the files before attempting to add the classpath.

Page 56
Using WebDAV with a Custom Implementation

For WebDAV access to the Content Collection to function correctly when a Custom Authentication Module is deployed, the module must implement IUserPathAuthModule for LDAP implementations or ExternalAuthModule for all other custom implementations. See Implementation Details for information on implementing IUserPathAuthModule.
Troubleshooting Custom Implementations

This section explains how to troubleshoot problems that may occur when installing a custom authentication module. Examine the tomcat logs in \blackboard\logs\tomcat and \blackboard\logs\bb-services-log.txt files for Java errors that may occur Ensure that the class name is correct Ensure that all of the properties are correctly defined in the authentication.properties file Ensure that the authentication module (and all of its dependencies) are in the .JAR file and are in the proper location If subclassing BaseAuthenticationModule or other implementations, make sure that there are no namespace conflicts that may affect processing

Page 57
Blackboard Learn Architecture

Overview
This section describes the Blackboard Learn from the operating system and database perspective. For information about optimizing Blackboard Learn to perform best in a particular environment, see Blackboard Learn Performance Optimization Guide.
In this Section
This section includes the following topics. T opic File System Databases Services Tomcat Clusters Operating System and Database Maintenance Backup and Recovery Command Line Tools Using a Proxy Server De s cr ip t io n This topic covers the directory and file structure of the Blackboard Learn. This topic covers the databases and database users that are installed as part of the Blackboard Learn. This topic covers the services that run as part of the application. This topic covers the installation, configuration, and removal of Tomcat Clusters. This topic covers updates to the supported operating systems and databases. This topic introduces system-wide backups and incremental Course and Organization data protection. This topic covers the utilities that are available from the command line. This topic explains how to use the Blackboard Learn with a proxy server.

Page 58
File System
Overview
The Blackboard Learn installs into a home directory that is always named blackboard. This directory not only holds all the application files but it is also the location where content items and log files are stored. Administrators should not have a reason to delete or modify any of the application files. Doing so may cause the system to fail. This topic reviews several of the more important areas of the file system.
Command Line Tools

Most of the command line utilities are stored in <blackboard_install_directory>/tools/admin directory. The tools for batch archive/restore/export/import and batch copy are found in the <blackboard_install_directory>/apps/content-exchange/bin. For more information on the command line tools, see Command Line Tools. For more information about the batch archive/restore/export/import and batch copy tools, see the Blackboard Learn Administrator Manual.
HTTP Compression
Enable GZip compression through the bb-config.properties file by toggling it on or off. Both IIS and Apache support GZip as a native compression ability.
Content Storage
Content is stored in the <blackboard_install_directory>/content/vi directory. Within each directory there are the following folders: admin: This directory stores images associated with System Reporting. branding: This directory stores the HTML that determines how the Gateway page is displayed. Information for modifying the Gateway page can be found in the Blackboard Learn Administrator Manual. Courses: This directory includes storage areas for each Course and Organization. Content items uploaded to the Course or Organization are stored here. images: This directory stores images used on the system. modules: This directory stores JSP pages for portal modules. plugins: This directory stores System Extensions. recyclebin: This directory includes deleted Course content. Content must be removed from this directory or it will be stored indefinitely. sessions: This directory stores session-specific data for users. sponsors: This directory stores sponsorship information and images.

Page 59
Queries
Paged searching is used in admin panel user and course searches, course search/catalog, and the user directory. Only one page of necessary data records are loaded at a time by using highly tuned SQL queries. The consumption of memory is relatively low with this type of query, and results in a short Garbage Collection time to reclaim the used memory. Hierarchical data uses the native database syntax CONNECT BY statements in Oracle, and recursive Common Table Expressions in SQL Server when performing a hierarchical query.
Logs
All logs are stored in the <blackboard_install_directory>\logs directory. Logs can be managed and viewed from the Logs link on the System Control Panel in the user interface. Notable logs are bb-session-log.txt which records suspicious session fingerprint activity, and bb-sms-log.txt which records automatic sync attempts. For more information about managing and viewing logs, see the Blackboard Learn Administrator Manual. The verbosity of some logs can be adjusted to provide more or less information. Adjusting the verbosity of a log file will require running PushConfigUpdates to take effect. The verbosity of the <blackboard_install_directory>/logs/bb-services-log.txt log is controlled by the blackboard.service.log.param.logdef.default.verbosity property in the service-config.properties file. The default value, fatal, logs only fatal events. The valid options from less verbosity to more verbosity are: fatal,error,warning,information,debug. Adjusting the verbosity of a log file will require running PushConfigUpdates to take effect.

Page 60
Databases
Overview
Blackboard Learn initially installs three databases and three database users. This topic reviews the databases and database users of Blackboard Learn. Administrators should not add data directly to the database or modify data in the database directly. Doing so may create serious problems in the system..
BBLEARN_ADMIN
This database manages information about the databases. Legacy users will instead use the database name BB_BB60_ADMIN.
BBLEARN
This is the main database. Legacy users will instead use the database name BB_BB60.
BBLEARN_STATS
This is the statistics database. Legacy users will instead use the database name BB_BB60_STATS. It is useful for Administrators who wish to generate reports on usage, performance, and other metrics. Tracking data is sent to this database daily. For more information on generating reports and managing the information in this database please see the Advanced System Reporting topic in the Blackboard Learn Administrator Manual.
Database Users
The following database users are created when Blackboard Learn is installed. bblearn_admin bblearn bblearn_stats services.threaddump services.statusS
The bblearn_report user has limited access to view the BBLEARN database and can only see a subset of tables and columns. Change the value in the bb-config.properties file and then run the PushConfigUpdates command to change the password of a database user. Remember that the password must also be changed within the database to match the new password or the Blackboard Learn will not work properly. Note For performance reasons, CURSOR_SHARING should be set to EXACT or FORCE, especially when using Oracle 10g and licensing the content management capabilities of Blackboard Learn. Access issues with groups and files may also occur.

Page 61
Oracle RAC Support, UNIX

Overview
Oracle Real Application Clusters (RAC) provides advantages such as high availability, and failover by clustering multiple database instances. Blackboard Learn is installed and upgraded, by default, using the thin JDBC driver though the environment can later be configured to use Oracle RAC. After the installation is complete, the OCI driver will be utilized to allow for transparent application failover and other advanced Oracle configurations. Once the Blackboard Learn environment has been configured to use Oracle RAC, subsequent upgrades will require returning to the JDBC driver until after the upgrade has completed.
Configuration
Configuring Blackboard Learn to connect with Oracle RAC is a supported configuration as of version 9.1 of Blackboard Learn. Earlier versions of the application are considered customized solutions and assistance with that type of configuration is available through Blackboard Consulting.
Prerequisites
Oracle 10g R2 RAC environment has been installed and set up properly according to Oracle's documentation. Blackboard Learn 9.1 is installed and configured using one of the RAC instances with default JDBC connectivity Blackboard Learn 9.1 has been properly tested and updated with any customizations or advanced configurations. Failover has been tested at the database level with the Oracle RAC environment according to Oracle's documentation.
Configure the Oracle RAC Environment

1. 2. Go to the <oracle_home>/network/admin folder. Make a backup of the tnsnames.ora file. 1. 2. 3. cp tnsnames.ora tnsnames.ora.single_<date> cp tnsnames.ora.bb tnsnames.ora.bbsingle_<date>
Add entries to the tnsnames.ora.bb file which match the RAC environment configuration. In the following tnsnames.ora example, the RAC consists of two instances on nodes rac01.foo.com and rac02.foo.com with the service name bbrac-db : bbrac = (DESCRIPTION= (LOAD_BALANCE=on) (FAILOVER=on )

Page 62
(ADDRESS= (PROTOCOL=tcp)(HOST = rac01.foo.com)(PORT=1521) ) (ADDRESS= (PROTOCOL=tcp)(HOST = rac02.foo.com)(PORT=1521) ) (CONNECT_DATA= (SERVICE_NAME= bb-rac-db) (FAILOVER_MODE=(TYPE=select)(METHOD=basic) ) ) ) 4. Test the connection: sqlplus <database_schema>@<alias_name> Stop your server by issuing ./<blackboard_install_directory>/tools/admin/ServiceController.sh services.stop Go to <blackboard_install_directory>/config Open the bb-config.properties file to switch the JDBC driver as OCI and tns for RAC. The alias for bbconfig.database.type.oracle.tns parameter must match the parameter as defined in the tnsnames.ora.bb file. bbconfig.oracle.client.drivertype=oci bbconfig.database.type.oracle.tns=bbrac 8. Connect to the database with a user that has permissions to the BBLEARN_CMS schema then query the database and update the connection. sqlplus <database_schema>@<alias_name> SQL> select DB_USERNAME,DB_PASSWORD,JDBC_CONNECTION_URL from $cms_schema.XY_FILE_SYSTEMS; SQL> update <cms_schema>.xy_file_systems set jdbc_connection_url='jdbc:oracle:oci:@bbrac '; 2 rows updated. SQL> commit; Commit complete. 9. 10. 11. Go to <blackboard_install_directory>/tools/admin Launch the Push Config Updates script by issuing ./PushConfigUpdates.sh Verify the application has connected to the Oracle RAC environment and is working as expected.
5.
6. 7.

Page 63
Note
The ORACLE_HOME location is defined by the property bbconfig.database.local.oracle.home in bb-config.properties. The default ORACLE_HOME is <blackboard_install_directory>/apps/oracleclient/
Configure Single Instance Mode

1. 2. Verify that Blackboard Learnis connected to Oracle RAC instances and functioning properly. Stop your server by issuing ./<blackboard_install_directory>/tools/admin/ServiceController.sh services.stop Go to <blackboard_install_directory>/config Open the bb-config.properties file to switch back to the JDBC driver and unset tns for RAC. bbconfig.oracle.client.drivertype=thin bbconfig.database.type.oracle.tns= 5. Verify that the bbconfig.database.server.* parameters in bbconfig.properties points to one of the RAC instances as follows: bbconfig.database.server.name= rac01 bbconfig.database.server.fullhostname= rac01.foo.com bbconfig.database.server.instancename= bb-rac-db01 bbconfig.database.server.portnumber=1521 bbconfig.database.server.systemuserpassword=oracle 6. Connect to the database with a user that has permissions to the BBLEARN_CMS schema then query the database and update the connection where rac01 is the name of the first database instance and bb-rac-db01 is the server name where the first instance is running : sqlplus <database_schema>@bbrac SQL> select DB_USERNAME,DB_PASSWORD,JDBC_CONNECTION_URL from <cms_schema>.XY_FILE_SYSTEMS; SQL> update <cms_schema>.xy_file_systems set jdbc_connection_url='jdbc:oracle:thin:@rac01:1521: bb-rac-db01'; 2 rows updated. SQL> commit; Commit complete. 7. 8. Go to <blackboard_install_directory>/tools/admin Launch the Push Config Updates script by issuing ./PushConfigUpdates.sh
3. 4.

Page 64
9.
Verify the application has connected using the JDBC driver and all components are working as expected.
Upgrading Blackboard Learn in an Oracle RAC Environment

1. Prior to upgrading Blackboard Learn in an Oracle RAC environment, all modifications to the configuration must be reversed. Follow the instructions in Configure Single Instance Mode to ensure that properties relating to the database server are pointing to one RAC node. Stop your server by issuing ./<blackboard_install_directory>/tools/admin/ServiceController.sh services.stop While connected to one of the RAC nodes, perform a standard upgrade of Blackboard Learn Verify the application has connected using the JDBC driver and all components are working as expected. Follow the instructions in Configure the Oracle RAC Environment to reconfigure the application to use an Oracle RAC environment.
2.
3. 4. 5.
Special RAC Patches on Oracle RAC with 10g R2

Problem: ORA-00600: internal error code, arguments: [kkocxj : pjpCtx] while complex sqls. Solution: To work around this Oracle bug, logon as sysdba and alter system set "_optimizer_push_pred_cost_based" = false scope =both; Reference: http://forums.oracle.com/forums/thread.jspa?threadID=836121
Best Practices
Review all requirements for Blackboard Learn 9.1 application configuration prior to installation Use only 1 application and database instance to configure the environment to connect to Oracle RAC. Always test application functionality to verify the application is working as expected. Test failover of the database by shutting down one database instance and test the application functionality Check netstat to ensure that the application is connected to the correct IP/alias for the instance If you want to configure the application server, cloning the first application server and updating the configuration files is the most efficient method for initial installation

Page 65
If upgrading, always reverse configuration and customizations, then test functionality before running the installer If you require additional planning or assistance with the configuration contact Blackboard Consulting.

Page 66
Services
After Blackboard Learn is installed, it adds the bb-collab and bb-tomcat services to the operating system. In addition, for Blackboard Learn to run properly on Windows, the IIS service must be running and the SQL Server database must be started. When running on a UNIX operating system, the Apache process must be running and the Oracle database must be started and running correctly. When performing maintenance or upgrade tasks it may be necessary to stop some of these services. For most upgrade tasks, including installing Blackboard Learn software updates, the bb-collab, bb-tomcat, and IIS or Apache services should be stopped but the database should be running. While this is a good general rule, please refer to the specific instructions for each task to confirm. Blackboard uses the "service" terminology familiar to Windows users. UNIX users should think of services as processes.
Definition of Blackboard Services

bb-collab: The bb-collab service runs the Collaboration Tool within Blackboard Learn. Stopping this service will make the Collaboration Tool unavailable to users. bb-tomcat: The bb-tomcat service runs the Java servlet engine. Stopping this service makes any Java servlet pages unavailable to users, including the Login page.
Starting and Stopping Services

The ServicesController utility is used to start and stop services. This utility must be run from the command line. Windows: C:\<blackboard_install_directory>\tools\admin\ServiceController <argument> UNIX: /<blackboard_install_directory>/tools/admin/ServiceController <argument> Where each <argument> is defined in the following table. Ar g um en t services.start services.stop services.restart services.appserver.start services.appserver.stop services.appserver.restart De s cr ip t io n Starts all the services related to the Blackboard Learn. Stops all the services related to the Blackboard Learn. Stops and immediately starts the services related to the Blackboard Learn. Starts the bb-tomcat service. Stops the bb-tomcat service. Stops and immediately starts the bb-tomcat service.

Page 67
Ar g um en t services.webserver.start services.webserver.stop services.webserver.restart
De s cr ip t io n Starts the IIS or Apache Web service. Stops the IIS or Apache Web service. Stops and immediately starts the IIS or Apache Web service.
Starting and Stopping the bb-collab Service

In rare instances it may be necessary to stop only the bb-collab service but leave all other services running. For example, when setting up a dedicated collaboration server in a multiple Web/app server configuration it is necessary to stop the bb-collab service on all servers except the collaboration server. The bb-collab service (as well as the IIS and bb-tomcat services) can be controlled individually through the Services panel on Windows operating systems. UNIX operating system users employ UNIX commands that control processes to manage the bb-collab and apache "services."

Page 68
Tomcat Clusters
Overview
Tomcat Application Clusters consist of multiple Blackboard Learn java application (JVM) server instances running simultaneously (on the same physical server) and working together to provide increased scalability. Scalability is an application's ability to support a growing number of users. If it takes one application 10 milliseconds to respond to one request, how long does it take to respond to 10,000 requests? If a user logs on at 3 AM do they experience the same responsiveness as they do at 3 PM? Tomcat Application Clusters ensure that Blackboard Learn remains responsive by adding server instances to a cluster without interruption of service. Note Cluster nodes cannot be modified. If a change is required, then the node must be removed and then added again with the updated information.
Tomcat Application Clusters are not meant as a replacement for traditional load balance configurations, but as a complementary scheme that provides improved scalability and failover capabilities. Traditional load-balancing is a physical distribution of server instances across multiple servers. Tomcat Application Clusters are logical instances of the Java application components that reside on a single server, or are distributed across multiple servers. There are two types of server clustering: horizontal and vertical: Horizontal clustering allows server instances to be deployed across multiple physical servers. This method of clustering is not implemented by Blackboard because Blackboard already supports load-balancing. Vertical clusters, also known as multi-home clusters, allow multiple server instances to be run on a single machine. This method takes full advantage of the processing power of a single server. Vertical clusters are load-balanced by the web server.
Tomcat Clustering runs on all Blackboard platforms (Windows, Linux, and Solaris).
Installing One or More Tomcat Clusters

This section includes all of the procedures needed to install and configure Tomcat Application Clusters. These procedures assume an Administrator has full administrative rights as either administrator or root. Before Installing a Cluster The server must be configured to support clustering prior to installing a Tomcat Cluster node. Clustering is disabled by default and must be enabled. Installing a cluster requires that the application instance be shutdown and restarted. Configuring in Windows: 1. 2. 3. Go to the Blackboard Learn home, <blackboard_install_directory>\config Open the bb-config.properties file. Search for the bbconfig.tomcat.cluster.enable variable, and modify the default value from 'FALSE' to 'TRUE'.

Page 69
4. 5. 6. 7. 8.
Open the context.xml file and uncomment the option to disable session persistence across Tomcat restarts. Within the context.xml file, the listening port assigned to the Tomcat nodes must be different for each node. Go to <blackboard_install_directory>\tools\admin Launch the Push Config Updates script by running the PushConfigUpdates.bat file. Create a new ServerGroup in Blackboard Learn a. Navigate to <blackboard_install_directory>\tools\admin b. Create a ServerGroup with a specified port number by running: ServerGroupManager.bat -c -n <new_group_name> -p <new_port_number>
Configuring in UNIX: 1. 2. 3. 4. 5. 6. 7. 8. Go to the Blackboard Learn home, <blackboard_install_directory>/config Open the bb-config.properties file. Search for the bbconfig.tomcat.cluster.enable variable, and modify the default value from 'FALSE' to 'TRUE'. Open the context.xml file and uncomment the option to disable session persistence across Tomcat restarts. Within the context.xml file, the listening port assigned to the Tomcat nodes must be different for each node. Go to <blackboard_install_directory>/tools/admin Launch the Push Config Updates script by issuing ./PushConfigUpdates.sh Create a new ServerGroup in Blackboard Learn a. Navigate to <blackboard_install_directory>/tools/admin b. Create a ServerGroup with a specified port number by issuing: ./ServerGroupManager.sh -c -n <new_group_name> -p <new_port_number> Note In a Windows or UNIX load-balanced environment, the PushConfigUpdates script must be run on each load-balanced server. Each Node must have its own ServerGroup.

Page 70
How to Install These procedures assume an Administrator has full administrative rights as either administrator or root. Upon creating an individual cluster node, the Blackboard services will need to be shutdown and restarted in order to reset the configuration with the new clustered node. P ro p e rt y Cluster ID De s cr ip t ion Must be a unique name with no spaces between any of the letters. Best practice is to identify one naming convention for all nodes and increment numerically to differentiate servers and nodes. Example: Blackboard1 or Blackboard2. Must be a unique port in order to connect to the JVM for the clustered node and shut it down. By default the primary application server installed with Blackboard runs on port 8005, therefore a new value must be supplied to avoid port socket contention. Best practice is to increment the current server shutdown port by 1000. Must be a unique port in order for the web server to communicate to each clustered node. The default port is 8009. Best practice is to increment the current jk connector port by 1000. Must be a unique port for the cluster to replicate session information across the wire. The default port is 4000. Best practice is to increment the current listen port by 1000.
Server Shutdown Port
JK Connector Port Cluster Listener Port
Installing in Windows: 1. Launch the Install Cluster script by running the InstallCluster.batfile. After running the file, you will be prompted for the following information. Configure the settings according to the previous table. a. Cluster ID. b. Server shutdown port. c. JK Connector port. d. Cluster Listener port. 2. 3. 4. The cluster is now created. Stop your server by running ServiceController.bat services.stop Start your server by running ServiceController.bat services.start
Installing in UNIX: 1. Launch the Install Cluster script by issuing ./InstallCluster.sh After running the command, you will be prompted for the following information. Configure the settings according to the previous table. a. Cluster ID. b. Server shutdown port.

Page 71
c. JK Connector port. d. Cluster Listener port. 2. 3. 4. 5. The cluster is now created. Stop your server by issuing ./ServiceController.sh services.stop Start your server by issuing ./ServiceController.sh services.start Run the jps command from your JAVA_HOME to see the bootstrap processes. You should see one Tomcat Process, and the number of Cluster Process IDs. UNIX customers should increase the Apache MaxClients value as they add nodes. Blackboard recommends multiplying the initial value by the number of total JVMs. For example, if MaxClients is 500 for a non-clustered configuration, when 2 JVMs are added, this setting should increase to a minimum of 1500.
Tip
Files that are Affected After a cluster is installed, there are a number of files and directories that are produced. The following table highlights some of these files and directories. Di re ct o r y o r F il e <blackboard_install_di rectory>/apps/tomcat/ cluster/ <blackboard_install_di rectory>/apps/tomcat/c luster/ <node_id> <blackboard_install_di rectory>/apps/tomcat/ conf/jk/workers.proper ties server.xml De s cr ip t io n A new directory that is created when the first node (other than root) is installed. A new directory that is created for every node added. Each directory contains files affecting that node: /conf/server.xml and log files. This file exists before adding a node but changes whenever a node is added to include load-balancing information for that node. For more information about the workers.properties file, see http://tomcat.apache.org. A file that allows you to configure Tomcat nodes through the use of XML descriptors.
Troubleshooting Installation Issues

This topic contains three steps to take if the Tomcat Cluster is not functioning as expected. 1. Check that the following value is present and set to true in the bb-config.properties file located in <blackboard_install_directory>/config: bbonfig.tomcat.enable=true If it is set to false, then run PushConfigUpdates.bat to change. For more information, see Before installing a cluster.

Page 72
2.
Check that the workers.properties file contains the correct information for all of the nodes installed in the cluster. For more information about the workers.properties file, see Files that are affected. Watch the Java processes running on your application server. There should be a Java process running for each node installed and one for the root node. CPU processing should be distributed across the nodes.
3.
Cache Replication
By default Blackboard Learn will install with cache replication in a cluster disabled. To enable replication, you must manually configure the setting and restart your application servers. Replication in Windows: 1. 2. 3. 4. 5. 6. Go to the Blackboard Learn home, <blackboard_install_directory>\config\internal/ Open the ehcache.xml file. Search for the two cacheManagerxxx elements, and remove the comments. Additional information is located within the ehcache.xml file, specific to the elements. Stop your server by running ServiceController.bat services.stop Start your server by running ServiceController.bat services.start
Replication in UNIX: 1. 2. 3. 4. 5. 6. Go to the Blackboard Learn home, <blackboard_install_directory>/config/internal/ Open the ehcache.xml file. Search for the two cacheManagerxxx elements, and remove the comments. Additional information is located within the ehcache.xml file, specific to the elements. Stop your server by issuing ./ServiceController.sh services.stop Start your server by issuing ./ServiceController.sh services.start
After restarting, all caches which are marked as bbconfig.cache.(cachename).needsclusterinvalidation=true in cachesettings.properties will send invalidation notifications to all nodes in the system when entries are removed/flushed/updated.

Page 73
Removing a Cluster Node

These procedures assume an Administrator has full administrative rights as either administrator or root. Upon removing an individual cluster node, the Blackboard services will need to be shutdown and restarted in order to reset the configuration without the clustered node. Removing in Windows: 1. 2. 3. 4. 5. Go to <blackboard_install_directory>\tools\admin Stop your server by running ServiceController.bat services.stop Launch the Remove Cluster script by running RemoveCluster.bat Specify the cluster to be deleted, when prompted. Start your server by running ServiceController.bat services.start
Removing in UNIX: 1. 2. 3. 4. 5. 6. Go to <blackboard_install_directory>/tools/admin Stop your server by issuing ./ServiceController.sh services.stop Launch the Remove Cluster script by issuing ./RemoveCluster.sh Specify the cluster to be deleted, when prompted. Start your server by issuing ./ServiceController.sh services.start Verify the cluster was successfully removed by running the jps command from your JAVA_HOME to see the bootstrap processes.
Best Practices
For information about optimizing Blackboard Learn to perform best in a particular environment, see Blackboard Learn Performance Optimization Guide.

Page 74
Operating System and Database Maintenance

Overview
Blackboard supports operating system and database service packs and security patches for the operating systems and databases supported for use with Blackboard Learn, and Blackboard Learn - Basic Edition. Blackboard will test, certify, and, if necessary, provide fixes to ensure that Blackboard systems work with service packs and security patches. There is, necessarily, a short lag time between a service pack release and the completion of testing. Even during this interim testing period, however, Blackboard will provide support for just released operating system and database service packs and security patches. Note This policy does not include support for subsequent releases. For example, if Blackboard supports version 1 of a database system any security patches or service packs for version 1 will be supported.
Blackboard will not support a version 2 release of the same database system until that version has been properly tested and published as part of the software requirements for that release of the Blackboard system.
Applying a Service Pack or Security Patch after Installing Blackboard Learn

Follow these steps to install a service pack or a security patch to the operating system or database. 1. 2. 3. Back up the system. Shut down Blackboard Learn. Contact Blackboard Technical Support by logging in to Behind the Blackboard at https://behind.blackboard.com to check for any prerequisite maintenance that may be required to ensure compatibility with an OS or DBMS service pack or security patch. Apply the operating system or database service pack or Security patch to the test/development environment. Restart the test/development server. Ensure that system is still shutdown. If auto start mechanisms are configured to restart Blackboard after a server restart, remember to shut down the Blackboard system before continuing. Apply any necessary Blackboard prerequisite maintenance to the test/development Blackboard systems. Restart the Blackboard systems. Check the results either by testing your critical path features or by running your verification procedures. If results are satisfactory, back up the system again. (If not, please log a service request with Blackboard Technical Support by logging in to Behind the Blackboard at https://behind.blackboard.com describing the failure.)
4. 5. 6.
7. 8. 9. 10.

Page 75
Backup and Recovery

Overview
This topic offers some tips on system-wide backups and describes the tools in Blackboard Learn for incrementally backing up Courses and Organizations.
System backup and recovery

System administrators should backup the database and file system according to the needs of the Institution. Blackboard Learn supports full backup and restores at the operating system and database levels. As a general rule, daily backups should be kept for two weeks, as errors may not appear for several days. Recovery plans should include how to restore the entire system. For assistance restoring the system, contact Blackboard Technical Support by logging in to Behind the Blackboard at https://behind.blackboard.com.
Incremental data protection

Blackboard Learn includes the following utilities for incrementally backing up individual Courses and Organizations. Export/Import: Export takes Course content and puts it in a package that can be used in another Course at a later date. One or more Course areas can be included in the package. Archive/Restore: The Archive Course function creates a record of the Course including user interactions. It is most useful for recalling Student performance or interactions at a later time. The archive package is saved as a .ZIP file that can be restored to the system at another time. The command line tool that processes batch operations for Export/Import and Archive/Restore is a powerful tool for backing up Course and Organization data. For detailed information on using these utilities, see the Blackboard Learn Administrator Manual. Note If attempting to import a file over the size of 250 MB, the command line must be used rather than a web browser. If it is necessary to increase the maximum upload limit, modify the parameter located in webapps/blackboard/WEBINF/config/struts/reporting-struts-config.xml. The file size upload limit is tied to Tomcat, therefore it is not encountered with WebDAV uploads. Because the setting is tied to Tomcat, the services must be restarted for the change to take effect.
Avoiding Recovery of Files During Upgrade

During a Blackboard Learnupgrade, items such as custom folders, and archived snapshots which are stored directly beneath the <blackboard_install_directory> directory are moved to a time-stamped backup directory. Customized files and folders which are not Blackboard-owned will be considered unexpected and moved to the backup directory. To avoid your customized non-Blackboard-owned files from being moved during an upgrade, create client-dirs.txt and client-files in your config directory. List each file and folder's relative path to your <blackboard_install_directory> directory on its own line in the respective text file. The files do not accept wildcards, so the files and folders must be specified individually. This method must be used with caution to avoid a partially upgraded environment, and if the file is Blackboardowned and customized it will still be overwritten with the new version.

Page 76
Command Line Tools

Overview
Blackboard Learn includes a set of system administration tools that must be run from the command line. Trying to execute a utility by clicking the .bat file in the Windows GUI will return errors and possibly cause the system to stop functioning. This topic covers each tool and the syntax to invoke the tool. All of the commands described in this topic are found in the <blackboard_install_directory>/tools/admin directory.
PurgeAccumulator
Every 30 days an automatic process runs that synchronizes the data in the stats database with the data in the main database and then deletes the statistical data from the main database that is more than 30 days old. This process can be run at any time using the PurgeAccumulator tool. The PurgeAccumulator tool can also be used to delete data from the statistics database. Windows Syntax: PurgeAccumulator.bat <command> <Database_Name> <days_or_date> UNIX Syntax: PurgeAccumulator.sh <command> <Database_Name> <days_or_date> Ar g um en t <command> De s cr ip t io n purge-live Takes data from Blackboard Learn database and syncs with tables in the statistics database. After synching, it purges statistical data in the main database that is older than the number of days or date set. purge-stats Goes to stats DB and purges all data older than the last x days or older than a specific date. Enter the name of the main database (bbuid) of the database to be purged. The number of days (from the current date) that should not be processed by the PurgeAccumulator tool. It is also possible to set a date in yyyy-mm-dd format. Only data older than the date will be purged.
<Database_Name> <days_or_date>

Page 77
PushConfigUpdates
This tool updates the configuration according to the settings in the bb.config.properties file. Running this command will redeploy all of the properties files. If any customizations have been made to the properties files, they will be lost. The PushConfigUpdates command has been enhanced to improve system management. Now, the PushConfigUpdates automatically updates the admin data in the database by reading the value in the config.xml. It automatically pushes the changes of the database hostname and port, instance name, and externally visible Web server hostname to the database. Running this tool always restarts the services to reflect the changes. The first operation of this tool will replace the existing template files, copying the original template files to a time-stamped sub-directory of <blackboard_install_directory>/backups/templates/<time_stamped>. Use these files to retrieve and re-apply any local customizations. The second operation of this tool is Tomcat specific and requires that Custom Authentication be disabled to successfully complete this operation. The .jar files from apps/tomcat/<server>/lib/directories will be loaded rather than from <blackboard_install_directory>/systemlib/. Be aware that any .jar file found in the directory will be loaded at Tomcat startup. This operation is controlled by the .classpath files located in config/tomcat/classpath. Any changes to the Tomcat configuration files or startup scripts must be made to the templates in the config/tomcat/ directory, in particular this applies to additional MIME types added to the web.xml file. Touch points are files such as web.xml, server.xml, startup scripts, and configuration files used in clustered Tomcat environments. The third operation updates the BBLEARN.SYSTEM_REGISTRY (legacy: BB_BB60.SYSTEM_REGISTRY) database table with the configuration changes. The current performance parameters for the Application server are recorded in the BBLEARN_ADMIN.CONFIG.REGISTRY (legacy: BB_BB60_ADMIN.CONFIG.REGISTRY) database table. The final operation configures content management, which includes license verification, connection information update, then pushing the new information to the database. The version of each database schema is then checked and updated if necessary. Windows Syntax: <blackboard_install_directory>\tools\admin\PushConfigUpdates.bat UNIX Syntax: <blackboard_install_directory>/tools/admin/PushConfigUpdates.sh When using the PushConfigUpdates tool in Windows, it is very important that the tool is run on the command line rather than double-clicking the file from windows explorer. The command line will execute the tool in verbose mode, displaying important messages.

Page 78
RotateLogs
This tool processes a log rotation outside the scheduled log rotations configured through the Manage Log Rotation page. The tool stops all necessary services and starts the services after the rotation is finished. Windows Syntax: <blackboard_install_directory>\tools\admin\RotateLogs.bat UNIX Syntax: <blackboard_install_directory>/tools/RotateLogs.sh This command does not take any arguments. If logs are manually rotated using this tool it will not interrupt the regular intervals. However, the logs that were rotated manually will not be included in the archive files created at the regularly scheduled rotation. For example, if the log rotation is set at 30 days and the logs are manually rotated after 15 days, only the last 15 days of logs will be included in the archives at the next scheduled log rotation. For more information about managing logs, see the Blackboard Learn Administrator Manual.
ServiceController
This tool is used to start and stop services. Windows Syntax: <blackboard_install_directory>\tools\admin\ServiceController <argument> UNIX Syntax: <blackboard_install_directory>/tools/admin/ServiceController <argument> An error may occur when running this tool if a symbolic link in /bin to the correct location of the bash shell does not exist. Run the following command to create this link: ln s /bin/bash /usr/local/bin/bash This assumes that bash resides in /usr/local/bin/bash. If it resides elsewhere, please use that path when creating the symbolic link. Ar g um en t services.start services.stop services.restart services.appserver.start services.appserver.stop De s cr ip t io n Starts all the services related to Blackboard Learn. Stops all the services related to Blackboard Learn. Stops and immediately starts the services related to Blackboard Learn. Starts the bb-tomcat service. Stops the bb-tomcat service.

Page 79
Ar g um en t services.appserver.restart services.webserver.start services.webserver.stop services.webserver.restart
De s cr ip t io n Stops and immediately starts the bb-tomcat service. Starts the IIS or Apache Web service. Stops the IIS or Apache Web service. Stops and immediately starts the IIS or Apache Web service.
SystemInfo
This command will create a detailed report of system settings. The report can be viewed in the /<blackboard_install_directory>/logs/system-info directory. The name of the report will be named yyyymmdd_OS.log. Where OS is the operating system and yyyymmdd is the date in year-month-day format. Windows Syntax: <blackboard_install_directory>\tools\admin\SystemInfo.bat UNIX Syntax: <blackboard_install_directory>/tools/admin/SystemInfo.sh

Page 80
Using a Proxy Server

Overview
Some Institutions require an outbound proxy server to comply with government regulations or Institution practices. Blackboard Learn allows the use of an outbound proxy server to secure communications. In particular, the proxy server works with Course Cartridge downloads and RSS feeds incorporated into community modules.
Configure the Proxy Server, UNIX

Follow these steps to configure Blackboard Learn to use an outbound proxy server. 1. 2. 3. 4. 5. Install the proxy server according to the Institution standards. Open the /<blackboard_install_directory>/config/bb.config.properties file. Add the domain name or IP address of the proxy server to the bbconfig.webserver.ouboundproxyurl property. Save the file. Run the PushConfigUpdates command to finalize the setting.
Configure the Proxy Server, Windows

Follow these steps to configure Blackboard Learn to use an outbound proxy server. 1. 2. 3. 4. 5. Install the proxy server according to the Institution standards. Open the C:\<blackboard_install_directory>\config\bb.config.properties file. Add the domain name or IP address of the proxy server to the bbconfig.webserver.ouboundproxyurl property. Save the file. Run the PushConfigUpdates command to finalize the setting.

Page 81
Content Management Administration

Overview
This section describes how to initially set up and manage the content management capabilities of Blackboard Learn.
In this Section
This section includes the following topics. T opic Introduction to Content Management Administration Turn on the Content Collection Configuration Changes Command Line Tools De s cr ip t io n This topic provides an overview of managing the content management capabilities. This topic describes how to setup the Content Collection after installing the content management capabilities. This topic provides information about configuration options. This topic covers the utilities that are available from the command line.

Page 82
Introduction to Content Management Administration

Overview
The Content Collection is in a disabled mode after installation. This gives the Administrator a chance to configure and configure the Content Collection before making it publicly available for all to access. The Content Collection is very flexible and has numerous options. This section covers the basic steps Administrators that need to get started. Detailed information about administering the Content Collection is located in the Blackboard Learn Administrator Guide.

Page 83
Turn on the Content Collection

Overview
Turn on the Content Collection and appropriate Tools and Features. If Portfolios are enabled, select which roles may use this feature. Turn on the Content Collection and its features from: Administrator Panel>Content Management Settings>Enable/Disable Features and Tools
Enable SSL
Authentication for Web Folders (also known as WebDAV) occurs in plain text. Blackboard strongly recommends running SSL. If SSL is not used, authentication may be compromised. For more information, see Setting Up SSL.
Set up the Portal

This section is relevant only for clients who license the community engagement capabilities of Blackboard Learn. Follow the steps below to set up the Portal: 1. If Portal Direct Entry is enabled, disable the Content Collection for Guests and any other roles that should not use it, such as Prospective Students and (Undefined variable: BbVariables_AS.plural observer)Administrator Panel>Manage Tabs > Modify>Tab Properties Select Properties next to each Content Collection module then set the System Availability of the module. Enable Content System Portal Modules. These include: Bookmarks, Course Content, (Undefined variable: BbVariables_AS.institution content), My Content, My Portfolios, (Undefined variable: BbVariables_AS.organization content), Search Content System, and Workflow Activities. Administrator Panel>Manage Modules>Properties (next to each Content System Module)
2. 3.
Configure Content Management Settings

The following steps explain which Settings must be initially configured: 1. Set up Virtual Hard Drives for users. This determines which roles have folders available in the users directory. The quota for these folders is setup in Default Folder Settings. Administrator Panel>Virtual Hard Drive Select the availability of virtual hard drives. If virtual hard drives are made available, select for which roles folders are created. Set up Default Folder Settings. This determines which folders will be created by default in the Content Collection, such as Course folders within the Courses directory for users with specific roles. It also allows the Administrator to set a quota for user folders. Administrator Panel>Settings>Default Folder Settings >Manage
2. 3.

Page 84
4.
Select Manage next to each top level folder. Set the permissions and default quotas for each top level folder. These options for top level folders may be changed in the future, BUT changes will only affect new folders created. Set up Privacy Settings, this determines whether the Content Collection respects the users privacy. Users have the option of choosing whether or not their user information is made public in the User Directory of the Blackboard Learn. The Privacy Settings page allows Administrators to determine whether these privacy settings chosen by users will be respected during user searches of the Content Collection. Administrator Panel>Settings>Privacy Settings Enable the Deletion Audit Trail for the Document Stores. This setting tracks how long files will remain in the system before being permanently deleted. This log is stored in the database; the lifetime may be set fairly high without affecting system performance. Administrator Panel>Technical Settings>Document Stores>Manage>Deletion Audit Trail Settings Turn on the Deletion Audit Trail for each Document Store by entering the number of days for the Delete Audit Trail Lifetime. Enable persistent cookies. Using persistent cookies increases the usability of WebDAV; users will not be asked to authenticate multiple times. Administrator Panel>Technical Settings>Authentication Properties
5.
6.
7. 8.
Configure Full Text Search

Configure full text search indexing options. This sets the time of day and the duration for the system to rebuild the Full Text Search Indexes. It is recommended that option be set to a minimum of one hour. Administrators may also choose to use the Immediate Update option, which will update the index as files are added to the system. This setting may impact performance. Administrator Panel>Technical Settings>Full Text Search Settings If the system has automated backup, check that the settings on the Full Text Settings page do not interfere with the backup.
Configure Display Options

The Display Options allow the Administrator to set up how the Content Collection appears to users. Administrator Panel>Content System Display Options The following areas must be configured in Display Options: Content List Display Options Set which features are available in the Action Bar, such as Add Folder and Copy. Determine which columns will appear, such as Display Size and Display Permissions. Menu Display Options Choose how the left-hand navigation menu appears to users. Manage Shortcut View Customize the appearance of the Shortcut View. Manage Folder View Customize the appearance of the Folder View.

Page 85
Enable Content Management Features

Follow the steps below to enable some of the features available in the Content Collection: 1. Make Portfolios available on the system. Select which roles have access to this functionality. Administrator Panel>Portfolios>Portfolio Settings Modify Portfolio Templates to suit the Institution and make them available. Administrator Panel>Portfolios>Portfolio Templates Set the availability of eReserves. Administrator Panel>eReserves Enable Web Folders. Administrator Panel>WebFolders Enable the availability of the Learning Objects Catalog. Administrator Panel>Learning Objects Catalog>Catalog Availability Select Catalog Managers. Administrator Panel>Learning Objects Catalog>Catalog Management Options
2. 3. 4. 5. 6.
Enable Content System Features in Courses

Follow the steps below to enable Content System features available in Blackboard Learn Courses: 1. Allow Instructors to check links to Content System items within a Course. Set the Check CS Links tool to Available. Administrator Panel>Course Settings>Course Tools 2. Allows Instructors to copy files from a Course to the Content Collection. Set the Copy Files to CS tool to Available. Administrator Panel>Course Settings>Course Tools
Access the Content Collection

Once enabled, the Content Collection Tab will appear when a user logs into Blackboard Learn. The Administrator may access the Content Collection through this tab or through the Manage Content option on the Administrator Panel.

Page 86
Configuration Changes
Overview
Administrators who are running the Blackboard Learn may make changes to the system configuration. If content management is installed, the Administrator must also update the configuration in the Blackboard Learn. This is done using the push-cs-config-update tool. There are no parameters for this tool. The following are examples of when this command is used: The content management database password is changed The database server name is changed The location of Java SE is modified The Web Server Hostname is changed The Web Server Port is changed Database username and password are modified Blackboard Basedir is changed
Configure the System

Follow the steps below to make changes to the system configuration: 1. 2. Update the \blackboard\config\bb-config.properties file. Update the \blackboard\apps\bbcms\config\bbcms-install.properties file. This step is only necessary if one of the following properties is updated: License Key Content Management database password 3. Run \blackboard\apps\bbcms\bin\push-cs-config-update.

Page 87
Command Line Tools

Overview
Blackboard Learn includes a set of system administration tools that must be run from the command line. Trying to execute a utility by clicking the .bat file in the Windows GUI will return errors and possibly cause the system to stop functioning. This topic covers each tool and the syntax to invoke the tool. All of the commands described in this topic are found in the <blackboard_install_directory>/tools/admin directory.
PurgeAccumulator
Every 30 days an automatic process runs that synchronizes the data in the stats database with the data in the main database and then deletes the statistical data from the main database that is more than 30 days old. This process can be run at any time using the PurgeAccumulator tool. The PurgeAccumulator tool can also be used to delete data from the statistics database. Windows Syntax: PurgeAccumulator.bat <command> <Database_Name> <days_or_date> UNIX Syntax: PurgeAccumulator.sh <command> <Database_Name> <days_or_date> Ar g um en t <command> De s cr ip t io n purge-live Takes data from Blackboard Learn database and syncs with tables in the statistics database. After synching, it purges statistical data in the main database that is older than the number of days or date set. purge-stats Goes to stats DB and purges all data older than the last x days or older than a specific date. Enter the name of the main database (bbuid) of the database to be purged. The number of days (from the current date) that should not be processed by the PurgeAccumulator tool. It is also possible to set a date in yyyy-mm-dd format. Only data older than the date will be purged.
<Database_Name> <days_or_date>

Page 88
PushConfigUpdates
This tool updates the configuration according to the settings in the bb.config.properties file. Running this command will redeploy all of the properties files. If any customizations have been made to the properties files, they will be lost. The PushConfigUpdates command has been enhanced to improve system management. Now, the PushConfigUpdates automatically updates the admin data in the database by reading the value in the config.xml. It automatically pushes the changes of the database hostname and port, instance name, and externally visible Web server hostname to the database. Running this tool always restarts the services to reflect the changes. The first operation of this tool will replace the existing template files, copying the original template files to a time-stamped sub-directory of <blackboard_install_directory>/backups/templates/<time_stamped>. Use these files to retrieve and re-apply any local customizations. The second operation of this tool is Tomcat specific and requires that Custom Authentication be disabled to successfully complete this operation. The .jar files from apps/tomcat/<server>/lib/directories will be loaded rather than from <blackboard_install_directory>/systemlib/. Be aware that any .jar file found in the directory will be loaded at Tomcat startup. This operation is controlled by the .classpath files located in config/tomcat/classpath. Any changes to the Tomcat configuration files or startup scripts must be made to the templates in the config/tomcat/ directory, in particular this applies to additional MIME types added to the web.xml file. Touch points are files such as web.xml, server.xml, startup scripts, and configuration files used in clustered Tomcat environments. The third operation updates the BBLEARN.SYSTEM_REGISTRY (legacy: BB_BB60.SYSTEM_REGISTRY) database table with the configuration changes. The current performance parameters for the Application server are recorded in the BBLEARN_ADMIN.CONFIG.REGISTRY (legacy: BB_BB60_ADMIN.CONFIG.REGISTRY) database table. The final operation configures content management, which includes license verification, connection information update, then pushing the new information to the database. The version of each database schema is then checked and updated if necessary. Windows Syntax: <blackboard_install_directory>\tools\admin\PushConfigUpdates.bat UNIX Syntax: <blackboard_install_directory>/tools/admin/PushConfigUpdates.sh When using the PushConfigUpdates tool in Windows, it is very important that the tool is run on the command line rather than double-clicking the file from windows explorer. The command line will execute the tool in verbose mode, displaying important messages.
RotateLogs
This tool processes a log rotation outside the scheduled log rotations configured through the Manage Log Rotation page. The tool stops all necessary services and starts the services after the rotation is finished.

Page 89
Windows Syntax: <blackboard_install_directory>\tools\admin\RotateLogs.bat UNIX Syntax: <blackboard_install_directory>/tools/RotateLogs.sh This command does not take any arguments. If logs are manually rotated using this tool it will not interrupt the regular intervals. However, the logs that were rotated manually will not be included in the archive files created at the regularly scheduled rotation. For example, if the log rotation is set at 30 days and the logs are manually rotated after 15 days, only the last 15 days of logs will be included in the archives at the next scheduled log rotation. For more information about managing logs, see the Blackboard Learn Administrator Manual.
ServiceController
This tool is used to start and stop services. Windows Syntax: <blackboard_install_directory>\tools\admin\ServiceController <argument> UNIX Syntax: <blackboard_install_directory>/tools/admin/ServiceController <argument> An error may occur when running this tool if a symbolic link in /bin to the correct location of the bash shell does not exist. Run the following command to create this link: ln s /bin/bash /usr/local/bin/bash This assumes that bash resides in /usr/local/bin/bash. If it resides elsewhere, please use that path when creating the symbolic link. Ar g um en t services.start services.stop services.restart services.appserver.start services.appserver.stop services.appserver.restart services.webserver.start services.webserver.stop services.webserver.restart De s cr ip t io n Starts all the services related to Blackboard Learn. Stops all the services related to Blackboard Learn. Stops and immediately starts the services related to Blackboard Learn. Starts the bb-tomcat service. Stops the bb-tomcat service. Stops and immediately starts the bb-tomcat service. Starts the IIS or Apache Web service. Stops the IIS or Apache Web service. Stops and immediately starts the IIS or Apache Web service.

Page 90
SystemInfo
This command will create a detailed report of system settings. The report can be viewed in the /<blackboard_install_directory>/logs/system-info directory. The name of the report will be named yyyymmdd_OS.log. Where OS is the operating system and yyyymmdd is the date in year-month-day format. Windows Syntax: <blackboard_install_directory>\tools\admin\SystemInfo.bat UNIX Syntax: <blackboard_install_directory>/tools/admin/SystemInfo.sh

Page 91
Setting Up SSL
Overview
This section reviews how to use the Secure Sockets Layer (SSL) protocol to secure communication between a Blackboard Learn Web/app server and a client machine. SSL Offloading is not currently supported.
In this Section
This section includes the following topics. T opic About SSL and SSL Choice Configure SSL for IIS De s cr ip t io n This topic introduces SSL and Blackboard Learn feature, SSL Choice, that lets Administrators select which areas of the system are secured with SSL. This topic gives detailed instructions for configuring IIS to use the SSL protocol. This must be done before using the SSL Choice feature. This topic provides instructions for securing Collaboration Tool communications over SSL when the server is running Windows. This topic gives detailed instructions for configuring Apache to use the SSL protocol. This must be done before using the SSL Choice feature. This topic provides instructions for securing Collaboration Tool communications over SSL when the server is running a UNIX operating system. This topic reviews the SSL Choice feature available through the user interface.
Configure SSL for the Collaboration Tool, Windows Configure SSL for Apache
Configure SSL for the Collaboration Tool, UNIX SSL Choice
Note
If using a self-signed certificate, the certificate must be added to the list of allowed certificates on the client machine. If this is not done, the multi-upload will fail, as will a few other features which use SSL.

Page 92
About SSL and SSL Choice

Overview
Secure Sockets Layer (SSL) is a protocol for protecting Internet communications. SSL ensures that a communication is not read or changed by another entity. Blackboard Learn uses SSL to secure all or some communications between the Web server and the client machine. This feature that allows Administrators to select which areas of Blackboard Learn are secured using SSL is called SSL Choice. Note SSL may also be used to secure the connection between Blackboard Learn and a separate server for authentication (such as an Active Directory server). If SSL will be used both for connecting to an authentication server and for client sessions, SSL for the authentication server must be configured first. For more information on configuring SSL for securing with an integrated authentication server, see Authentication.
SSL Off-loading is not supported.
How Does SSL Work?

SSL works through public key encryption. Transmissions are decrypted and encrypted using certificates. The steps below outline the process for establishing a connection over SSL: 1. 2. 3. 4. Client contacts the server with a list of encryption methods. The Server returns its certificate and a public key. These initial communications are scrambled with random data. Client validates the certificate. Client creates a secret string using an encryption method recognized by both the client and the server. The string is combined with the server's public key and sent back to the server. Both the client and server create session keys based on the secret string. The client sends a message to the server that it will now use the session key to encrypt and decrypt communications. The server responds that it will also use the session key. After each side confirms, the session keys are used to encrypt and decrypt communications during the session.
5. 6. 7. 8.
Obtain a Certificate
The simplest way to obtain a certificate for use with a Web site is through a vendor known as a Certifying Authority (CA). The process, shown in the steps below, is relatively simple. 1. 2. 3. 4. Generate a certificate request. Send the request to a CA. The CA creates and registers a certificate. Make this certificate available to the Web Server (IIS or Apache).

Page 93
Certificates created in this way are usually registered and good for one year. After one year the certificate will no longer work and a new certificate must be obtained.
How Does SSL Appear to Users?

SSL works with the Hypertext Transfer Protocol (HTTP) to secure connections between Blackboard Learn Web server and the client machines. It is fairly easy to see when a Web page is using SSL to secure transmissions because an s is appended to the http at the beginning of the address. Without SSL: http://blackboard.yourinstitution.com With SSL: https://blackboard.yourinstitution.com It is important to understand that if SSL is used to secure the Web page in this example then the first URL (without SSL) is invalid and will return a 404 error.
SSL Choice
The SSL Choice feature is available in the user interface from the System Control Panel. It allows an institution to decide if all, none, or some of Blackboard Learn is secured with SSL. If SSL is to be used, it is most effective when applied to the entire Web site and not just selected areas. Note SSL must be configured on the Web Server before using the SSL Choice feature. If SSL Choice is turned on before the Web server is configured then any areas set to use SSL will be unavailable to users!

Page 94
Configure SSL for IIS

Overview
To use SSL to secure Blackboard Learn the IIS Web server must first be set to use SSL. Configuring SSL should only be done by an experienced Microsoft System Administrator. Once SSL is configured, the SSL Choice feature (accessible from the Administrator Control Panel) will function correctly. Trying to use the SSL Choice feature before configuring SSL for Apache can result in serious system errors.
Configure SSL for IIS

Follow these steps to configure SSL for the IIS Web server. 1. 2. 3. 4. 5. Open the Internet Services Manager. Right-click on the blackboard_bblearn Web site and select Properties from the menu. Click the Directory Security tab. Click Server Certificate in the Secure communications frame at the bottom of the tab. The Web Server Certificate Wizard will appear. The Status of your Web server should report that there is not a certificate installed and there are no pending requests. If anything else appears, there may be a certificate installed or a pending request already. Click Next to advance. Select Create a new certificate and click Next to advance. Select Prepare the request now, but send it later and click Next to advance. Enter a name for the certificate (the name of the Web site in IIS is the default) and select a bit length from the drop-down list. Blackboard recommends a bit length of 1024. Click Next to advance. Enter the name of your Organization and your Organizational unit in the fields. This information is important to ensure that your certificate is unique and easily identified. Click Next to advance. Enter the Common name of the Web site. The host plus the domain name works best (example: blackboard_server.yourinstitution.edu). Click Next to advance. Enter the appropriate geographical information for your institution. Click Next to advance. Enter a file name for the certificate request or click Next to select the default and advance. Click Finish to create the certificate request. Send the certificate request to a Certifying Authority. There are several commercial vendors or you can sign your own if you have the capability. The output from the Certifying Authority will be a file with the extension .cer. Once you have obtained a .cer file, return to the Web Server Certificate Server as described in Steps 1-4. Select Process the Pending Request and click Next to advance.
6. 7. 8.
9.
10. 11. 12. 13. 14.
15. 16.

Page 95
17. 18. 19. 20. 21. 22.
Enter the location of the .cer file and click Next to advance. Click Next to advance through the summary steps (be sure to review the summaries to make sure you are installing the correct certificate!). Return to the Properties box for the blackboard_bblearn Web site as described in Steps 1 and 2. If the Web Site tab is not active, select it. Enter 443 for the SSL Port in the Web Site Identification frame at the top of the tab. Restart the server to complete the process.

Page 96
Configuring SSL for the Collaboration Tool, Windows

Overview
Setting up SSL to encrypt connections to Blackboard Learn does not secure the Collaboration Tool because the Collaboration Tool uses Tomcat, not Apache or IIS, to handle user connections and serve pages. Securing the Collaboration Tool requires using a separate SSL certificate with Tomcat. Most Institutions do not need to worry about securing the Collaboration Tool because the Collaboration Tool is not used to transmit sensitive data. It should also be noted that using SSL with the Collaboration Tool slows down performance of the tool. Consider both the need for security and the performance slow down associated with applying SSL before deciding to use SSL with the Collaboration Tool. As part of the process, a keystore and a self-signed certificate are created. A keystore is a file that stores certificates. A self-signed certificate is a certificate created by you that is not submitted to a Certifying Authority. Note Macintosh users running Netscape, Internet Explorer, or Safari may use self-signed certificates to configure SSL. A pop-up warning may appear during the process; select Continue to complete the process.
If users would prefer to use a signed certificate see the Java documentation on keytools for information on obtaining a signed certificate and including it in the keystore. In most cases, taking the extra step to go through a Certifying Authority is not necessary when securing the Collaboration Tool. Certifying Authorities are used to prove to users of a Web site that the connection is secure and verified by a trusted third party. Users accessing the Collaboration Tool from your Blackboard Learn most likely do not require the validation of a third party before using the tool. The process for configuring SSL for the Collaboration Tool has two steps: 1. 2. Create a keystore. Configure Tomcat properties to use SSL encryption.
Load-Balanced Configurations
The same certificate must be used on each server. For detailed instructions on how to install the same certificate on each server please consult Microsoft Knowledge Base article 310178 at http://support.microsoft.com/default.aspx?scid=kb;en-us;310178&Product-win2000) Services on each Web/application server must be restarted after changing the SSL Choice option.

Page 97
Create the Keystore

After creation the keystore contains a self-signed SSL certificate specifically for Tomcat, <tomcat>. To create the keystore and certificate, follow these steps: 1. 2. Log on to the Web/app server as the user that runs Blackboard Learn. Run the following from the command line: %JAVA_HOME%\bin\keytool genkey -storetype pkcs12 alias tomcat keyalg RSA keystore <path_to_keystore> The keystore will be created at the <path_to_keystore>. 3. The first prompt asks for a password for the keystore. The default password that Tomcat expects is "changeit, but it is recommended that another password be used. Tomcat can be configured later to accept the new password. The next few prompts ask for information about the person creating the certificate. This information will appear to users when they first access the Collaboration Tool over SSL. Users are prompted to accept the certificate so it is important to provide accurate information so that users trust the certificate. The information recorded is: First and Last Name Organizational Unit Organization City or Locality State or Province Two-letter country code 5. The last prompt asks for the password for the <tomcat> certificate. This password must be the same as the password entered in Step 2. Simply press ENTER to confirm that the same password will be used. The keystore will be created in the specified directory.
4.
6.
Configure Tomcat to Work with the SSL Certificate

After creating the keystore and certificate, the last step is to edit the blackboard\config\bbconfig.properties file. Follow these steps to edit the file to work with SSL: 1. Make a backup of the following file: blackboard\config\bb-config.properties 2. 3. 4. Keep it safe so that the original settings can be restored. Open the bb-config.properties file in Notepad or an XML editor. Find the following lines in the file and add the appropriate values. bbconfig.collabserver.keystore.filename= bbconfig.collabserver.keystore.password= bbconfig.collabserver.portnumber.ssl.default=8443 bbconfig.collabserver.keystore.type=PKCS12 The keystore.type must be set to PKCS12. 5. Save the file.

Page 98
6. 7.
Run the PushConfigUpdates tool. Test the system. When accessing the Collaboration Tool, a prompt should appear to accept the certificate. After accepting the certificate, the Collaboration Tool will open and communications will be secured using SSL encryption.

Page 99
Configuring SSL for Apache

Overview
To use SSL to secure Blackboard Learn the Apache Web server must first be set to use SSL. Note Successful completion of this process requires that Solaris users are running Solaris 10, Solaris 9, or Solaris 8 with patch 112438-02.
Configuring SSL should only be done by an experienced System Administrator. Once SSL is configured, the SSL Choice feature (accessible from the Administrator Control Panel) will function correctly. Trying to use the SSL Choice feature before configuring SSL for Apache can result in serious system errors.
Configure SSL for Apache

The following steps detail how to configure SSL with Apache. 1. 2. Login to the Web/application server as root. Set the PATH to include the OpenSSL provided by Blackboard with the following commands: PATH=/<blackboard_install_directory>/apps/openssl/bin:$PATH export PATH 3. Test that OpenSSL is in the PATH by executing openssl. If OpenSSL is set in the PATH correctly, an OpenSSL> prompt will appear. Enter q to exit the prompt. If another instance of openssl is installed on the operating system make sure that the version supplied by Blackboard is the version that appears in the PATH. Create a directory to store certificates. Then change directories. For example: mkdir /<blackboard_install_directory>/apps/httpd/conf/certs/ cd /<blackboard_install_directory>/apps/httpd/conf/certs/ 5. Create a RSA private key: openssl genrsa out server.key 1024 where server is a variable for the file name. Typically the server name is used. 6. Backup this file and make sure that only root has read permissions on it. Make sure that the password is secure and can be recalled when necessary. (need to recall to start the server). Create a Certificate Signing Request (CSR) for the server RSA private key with the following command: openssl req new days 365 key server.key out server.csr The days option sets the expiration of the certification. Most Certifying Authorities will only sign a certificate for 1 year. At that time the certificate must be resigned.
4.
7.

Page 100
8.
View the details of the CSR with the following command: openssl req noout text in server.csr When submitting the request, it may be necessary to view the file and copy text from it for submission to the Certifying Authority (CA).
9.
Send the CSR to a Certifying Authority for signing. There are several commercial options available or you can sign your own if you have the capability. The output of either process is a server.crt file. Edit the /<blackboard_install_directory>/apps/httpd/conf/httpd.conf file to include the following directive: Include conf/ssl.conf
10.
11.
Edit the /<blackboard_install_directory>/config/bb-config.properties file by modifying the following attributes, as shown below. SSLCertificateFile /<path>/server.crt SSLCertificateKeyFile /<path>/server.key
12. 13.
Restart the server. The SSL Choice feature can now be used to select which areas of Blackboard Learn use SSL. For more information on using SSL Choice, please see SSL Choice.

Page 101
Configuring SSL for the Collaboration Tool, UNIX

Overview
Setting up SSL to encrypt connections to Blackboard Learn does not secure the Collaboration Tool because the Collaboration Tool uses Tomcat, not Apache or IIS, to handle user connections and serve pages. Securing the Collaboration Tool requires using a separate SSL certificate with Tomcat. Most Institutions do not need to worry about securing the Collaboration Tool because the Collaboration Tool is not used to transmit sensitive data. It should also be noted that using SSL with the Collaboration Tool slows down performance of the tool. Consider both the need for security and the performance slow down associated with applying SSL before deciding to use SSL with the Collaboration Tool. As part of the process, a keystore and a self-signed certificate are created. A keystore is a file that stores certificates. A self-signed certificate is a certificate created by you that is not submitted to a Certifying Authority. Macintosh users running a Netscape or Internet Explorer browser will not be able to access the Collaboration Tool if a self-signed certificate is used to configure SSL. The Safari Web browser will work with a self-signed certificate. If there are Macintosh users running Netscape or Internet Explorer browsers then use a signed certificate. If a signed certificate is preferred, see the Java documentation on keytools for information on obtaining a signed certificate and including it in the keystore. In most cases, taking the extra step to go through a Certifying Authority is not necessary when securing the Collaboration Tool and a self-signed certificate may be used. Certifying Authorities are used to prove to users of a Web site that the connection is secure and verified by a trusted third party. Users accessing the Collaboration Tool from your Blackboard Learn most likely do not require the validation of a third party before using the tool.
Configure the Collaboration Tool with a Self-signed Sertificate

The process for configuring SSL for the Collaboration Tool has two steps: 1. 2. Create a keystore. Configure Tomcat properties to use SSL encryption.
Configure the Collaboration Tool with a Signed Certificate

Clients who would like to use their existing SSL certificate should follow these steps. 1. Convert the server.key and server.crt into a PKCS12 keystore using OpenSSL. openssl pkcs12 -export -out keystore.pkcs12 -in /path/to/server.crt -inkey /path/to/server.key 2. This will prompt for a keystore password. The keystore will be created as keystore.pkcs12 in the current directory. Move this to an appropriate location.

Page 102
3.
Use the keystore and certificate in the steps below that cover editing the bbconfig.properties file so that Tomcat uses SSL.
Create the Keystore

After creation, the keystore contains a self-signed SSL certificate specifically for Tomcat, <tomcat>. To create the keystore and certificate, follow these steps: 1. 2. Log on to the Web/app server as the user that runs Blackboard Learn. Run the following from the command line: %JAVA_HOME%\bin\keytool genkey -storetype pkcs12 alias tomcat keyalg RSA keystore <path_to_keystore> The keystore will be created at the <path_to_keystore>. 3. The first prompt asks for a password for the keystore. The default password that Tomcat expects is "changeit, but it is recommended that another password be used. Tomcat can be configured later to accept the new password. The next few prompts ask for information about the person creating the certificate. This information will appear to users when they first access the Collaboration Tool over SSL. Users are prompted to accept the certificate so it is important to provide accurate information so that users trust the certificate. The information recorded is: First and Last Name Organizational Unit Organization City or Locality State or Province Two-letter country code 5. The last prompt asks for the password for the <tomcat> certificate. This password must be the same as the password entered in Step 2. Simply press ENTER to confirm that the same password will be used. The keystore will be created in the specified directory.
4.
6.
Configure Tomcat to Work with the SSL Certificate

After creating the keystore and certificate, the last step is to edit the /blackboard/config/bbconfig.properties file. Follow these steps to edit the file to work with SSL: 1. Make a backup of the following file: /blackboard/config/bb-config.properties 2. 3. Keep it safe so that the original settings can be restored. Open the bb-config.properties file in an editor.

Page 103
4.
Find the following lines in the file and add the appropriate values. bbconfig.collabserver.keystore.filename= bbconfig.collabserver.keystore.password= bbconfig.collabserver.portnumber.ssl.default=8443bbconfig.collabs erver.keystore.type=PKCS12The keystore.type must be set to PKCS12 Save the file. Run the PushConfigUpdates tool. Test the system. When accessing the Collaboration Tool, a prompt should appear to accept the certificate. After accepting the certificate, the Collaboration Tool will open and communications will be secured using SSL encryption.
5. 6. 7.

Page 104
SSL Choice
Overview
After IIS or Apache is configured to support SSL, then the communication between users and Blackboard Learn can be configured using the SSL Choice feature. SSL Choice allows Administrators to determine if none, all, or some of Blackboard Learn is secured with SSL. Note If the SSL Choice is set to use SSL before SSL is configured in IIS or Apache Blackboard Learn will not be accessible! To ensure that users can always login, configure IIS or Apache for SSL prior to changing the security options on the SSL Choice page.
If planning on using SSL, Blackboard recommends enforcing SSL on the entire system. This ensures that all proprietary data is secured. If the choice option is chosen, it is important to update SSL settings whenever a new tool is enabled or a System Extension added.
Find this Page

Click SSL Choice from the Security and Integration section of the System Control Panel.
SSL Choice Page Fields

Fie ld System-wide Disable SSL System-wide Enable SSL System-wide Enable SSL for the following areas Specific Areas Select the check box for each area that should be secured using SSL. Tools Select the check box for each tool, tab, or Course content area that should be secured using SSL. Building Block Tools Select the check box for each Building Block that should be secured using SSL. Proxy Tools Select the check box for each Proxy Tool that should be secured using SSL. Web Services Select the check box for each Web Service that should be secured using SSL. Select this option and SSL will not be used to secure any of the communication between users and Blackboard Learn. Select this option and SSL will be used to secure all of the communication between users and Blackboard Learn. Select this option to determine which areas of Blackboard Learn will be secured through SSL. Select the different areas from the check boxes on this page. De s cr ipt io n

Page 105
Setting Up SIF Integration

Overview
This section reviews how to use SIF (School Interoperability Framework) to share data between a Blackboard Learn installation and other systems using the framework.
In this Section
This section includes the following topics. T opic About SIF Configure the Blackboard SIF Agent Configure SSL for SIF Data Mapping De s cr ip t io n Describes SIF and its uses. Provides instructions for connecting to a ZIS using the Blackboard SIF Agent. Provides instructions on securing communication between the ZIS and the SIF Agent. Matches the SIF data attributes to Blackboard data attributes.

Page 106
About SIF
Exchanging and Synchronizing Data
The School Interoperability Framework (SIF) is an industry initiative to develop a scalable solution for data exchange, synchronizing data entered in one system with the data in other systems within the SIF framework. A SIF implementation is a distributed networking system that consists of a Zone Integration Server (ZIS) and one or more SIF integration agents that communicate with the ZIS, all organized into a zone. The size of the zone is flexible and could consist of a single building, a school, a small group of schools, or a district. The ZIS is responsible for all access control and routing within the system. It provides integration services to all the agents registered with it so that the agents can subscribe to data changes that occur within the zone or publish data changes out into the zone. For example, if a users phone number is changed on one of the agent systems, the agent can publish this change to the ZIS, and any other agents that have subscribed to user information data changes will then receive the new phone number from the ZIS. In SIF, an agent never talks to another agent directly. Instead, an agent communicates with the ZIS which manages the connection to the other agent. By having the ZIS manage the routing responsibilities, complex communications can occur between agents that have no direct information about each other. The ZIS acts as the trusted intermediary that brokers the data exchange.
The Blackboard SIF Agent

The Backboard SIF Agent registers with a ZIS and indicates the data Blackboard Learn can receive. ZIS tracks the data that the Blackboard SIF Agent can receive and forwards a message to the Blackboard SIF Agent if another agent has posted an applicable data change to the ZIS. The Blackboard SIF Agent conforms to SIF standards for receiving updates to user information data from the ZIS. It subscribes to data changes but does not publish data changes. SIF communication is automated. Once the Blackboard SIF Agent is configured, it automatically updates information when notification of a data change is received from the ZIS. The frequency of updates is configurable. Some important points about the Blackboard SIF Agent: The SIF Agent will not transmit information to the ZIS server, it will only receive information. The SIF Agent will add, modify, or delete user records. It will not make changes to other data. The SIF Agent is configured to listen for data from the ZIS at intervals using the Pull protocol. The ZIS server owns the data sent according to the Blackboard Learn database. Ensure that this does not conflict with established integration solutions using Snapshot or the Blackboard integration APIs.

Page 107
Configure the Blackboard SIF Agent

Overview
The Blackboard SIF agent is installed with Blackboard Learn. Configuring the SIF Agent to receive information from the ZIS is accomplished by activating the Agent in the serviceconfig.properties file and editing the Agent properties in the bb-config.properties file.
Edit the service-config.properties File

Edit /<blackboard_install_directory>/config/service-config.properties to activate the SIF Agent. Uncomment the following lines: ############################ SIF Service ################################blackboard.service.name.sifservice=blac kboard.platform.sif.SIFAgentServiceblackboard.service.impl.sifservice=b lackboard.platform.sif.SIFAgentServiceblackboard.service.sifservice.par am.config=config/bb-sif-agentconfig.xmlblackboard.service.sifservice.initlevel=17 Uncommenting these lines of code will cause the application to attempt to communicate with a ZIS server using the parameters defined in the bb-config.properties file.
Configure Settings in the bb-config.properties File

Edit /<blackboard_install_directory>/config/bb-config.properties as follows: P ro p e rt y bbconfig.sif.pull.frequency De s cr ip t io n Determines how often the SIF Agent will retrieve updates from the ZIS. This value is expressed in seconds. Identifies the zone to which the SIF Agent subscribes. Identifies the ZIS server. The port used to listen for communication from the ZIS. This must be set to HTTP for an unencrypted connection or HTTPS to use SSL to encrypt communication between the ZIS and the SIF Agent.
bbconfig.sif.zone bbconfig.sif.host bbconfig.sif.port bbconfig.sif.protocol

Page 108
P ro p e rt y bbconfig.sif.keystore
De s cr ip t io n The keystore is a certificate used to identify the SIF agent. refers to the keystore file that our agent uses to identify itself (in the handshake process of the HTTPS protocol type connection, the ZIS will read this keystore from the agent and the agent will also read the ZISs self-identifying keystore). Password for the keystore. The truststore is a certificate used to identify trusted sources. refers to the keystore file that says who our agent trusts; this keystore file is created from importing the ZISs selfidentifying certificate, so that in the handshake process our agent can match the ZISs keystore with who we say we trust in our truststore file. Password for the truststore. The SIF Authentication levels we set for bbconfig.sif.authlevel means the following to the ZIS receiving the connection message: 0- this agent is not sending a certificate to identify itself 1- this agent has a valid certificate to send to identify itself 2- this agent has a valid certificate to send to identify itself AND it got it from a source the ZIS trusts (trusted certificate authority) For level 0, the SIF Agent is not authenticating itself to the ZIS. In this instance, use the HTTP protocol to connect and do not set a keystore or a truststore. For levels 1 and 2, the HTTPS protocol must be used to connect and the keystore and truststore parameters set. When creating the keystore files, the ZIS must be configured to trust the agents certificate. This is done by importing the agents certificate into the ZISs Trusted Agent Certificates section. If the ZIS trusts the SIF Agent certificate, the agent will successfully connect to the ZIS on level 2 authentication because the selfidentifying keystore is one that the ZIS trusts. If the ZIS does not trust the agents certificate, then connection at level 2 would fail.
bbconfig.sif.keystore.password bbconfig.sif.truststore
bbconfig.sif.truststore.password bbconfig.sif.authlevel

Page 109
P ro p e rt y
De s cr ip t io n However, level 1 authentication level will still allow the agent to successfully connect to the ZIS if the ZIS were to not trust our agents certificate. This is because at level 1, the agent only needs a valid certificate to identify itselfthe certificate does not have to be one that the ZIS trusts.
Example:
##################################################################### #################### SIF configuration settings ##################### ##################################################################### bbconfig.sif.pull.frequency=30000 bbconfig.sif.zone=Bb-SIF-Test bbconfig.sif.host=ZIS_SERVER.BLACKBOARD.EDU bbconfig.sif.port=7443 bbconfig.sif.protocol=https bbconfig.sif.keystore=/<blackboard_install_directory>/config/certs/SIFa gent.ks bbconfig.sif.keystore.password=changeit bbconfig.sif.truststore=/<blackboard_install_directory>/config/certs/Tr usted.ks bbconfig.sif.truststore.password=changeit bbconfig.sif.authlevel=2 Run PushConfigUpdates and verify the connection Run the PushConfigUpdates command to apply the changes. Note The PushConfigUpdates command has been enhanced to improve system management. PushConfigUpdates automatically updates the admin data in the database by reading the value in the config.xml. It automatically pushes the changes of the database hostname and port, instance name, and externally visible Web server hostname to the database.
UNIX /<blackboard_install_directory>/tool/admin/PushConfigUpdates.sh Windows: C:\<blackboard_install_directory>\tool\admin\PushConfigUpdates The values in bb-config.properties will be written out to /<blackboard_install_directory>/config/bb-sif-agent-config.xml Check the log /<blackboard_install_directory>/logs/tomcat/sif-log.txt to verify the connection. 2009-08-12 17:29:35,833 DEBUG [ADK.Agent$Bb-SIF-Test] Polling for next message...2009-08-12 17:29:35,986 DEBUG [ADK.Agent$Bb-SIF-Test] Send SIF_SystemControl2009-08-12 17:29:35,987 DEBUG [ADK.Agent$Bb-SIF-

Page 110
Test] MsgId: 7CDD8B1AA327B2F646030FDE3B72DC5F2009-08-12 17:29:35,989 DEBUG [ADK.Agent$Bb-SIF-Test] Sending message (646 bytes)2009-08-12 17:29:36,095 DEBUG [ADK.Agent$Bb-SIF-Test] Expecting reply (489 bytes)2009-08-12 17:29:36,095 DEBUG [ADK.Agent$Bb-SIF-Test] Received reply (489 chars)2009-08-12 17:29:36,100 DEBUG [ADK.Agent$Bb-SIF-Test] Receive SIF_Ack (Status = 9; Errors = 0)2009-08-12 17:29:36,100 DEBUG [ADK.Agent$Bb-SIF-Test] MsgId: 7166CC00636B004C4A81061B23E137A7200908-12 17:29:36,100 DEBUG [ADK.Agent$Bb-SIF-Test] OrgId: 7CDD8B1AA227B2F646030FDE3B72DC5F2009-08-12 17:29:36,100 DEBUG [ADK.Agent$Bb-SIF-Test] No messages waiting in agent queue
Sample bb-sif-agent-config.xml
The example below defines the sif-agent-config.xml file. Please remember not to make any changes directly to this file, rather, edit the parameters in the bb-config.properties file and run PushConfigUpdates to make changes.  <agent-listing> <!--top level container. Multiple agents can be registered--!> <agent-entry class="blackboard.platform.sif.agent.StudentPersonalProvider" version="70"> <!--declaration of agent implementation class. Full class name must be provided Version is just meta-data--!> <connection class="blackboard.platform.sif.connect.SIFPullConnection" > <!-declaration of connection implementation class. SIFPullConnection and SIFPushConnection available--!> <property name="frequency" value ="30000" /> <!-- properties are custom per connection type. For PULL you specify the frequency the agent wakes up to do a pull--!> </connection> <zis> <!--zis represents data detailing location and means to interact with the server. --!> <zone name="Bb-SIF-Test" /> <!--SIF Zone to be used--!> <host name="10.10.107.77" port="7443"/> <!--ZIS server host and port to attach to. --!> <transport protocol="https"> <!--Actual protocol to be used. Can be either http or https if not recognized http will be used. -!> <property name="keystore" value ="C:/myURL.com/testing/siftest-app/cert/Agent.ks" /> <property name="keystorepassword" value ="mypassword" /> <property name="truststore" value ="C:/myURL.com/testing/sif-test-app/cert/Trusted.ks" /> <property name="truststorepassword" value ="changeit" /> <!--The above properties represent location of certificate stores and their corresponding passwords. --!> <property name="clientauth" value ="true" /> <!-- Controls whether the ZIS server should require SSL certificate exchange during an operation--!> <property name="authlevel" value ="2" /> </transport> </zis> </agententry> </agent-listing>

Page 111
Configure SSL for SIF

Overview
The connection between the ZIS and the SIF Agent can be secured using SSL. The settings are easily configured in the bb-config.properties, however, SSL encryption requires a keystore and possibly a truststore from the ZIS server to function properly. The instructions below explain how to create and configure a keystore as well as how to configure a truststore from the ZIS server. For more information on using SSL with SIF integration, please review the SifWorks ADK documentation available from Edustructures.
Create and Configure the Keystore

Follow these steps to create and configure a keystore. UNIX: 1. Create a directory within the blackboard directory to hold the certificate. mkdir /<blackboard_install_directory>/config/certs cd /<blackboard_install_directory>/config/certs 2. Create a keystore by running the following command and responding to the prompts: keytool -genkey -v -keystore SIFagent.ks -alias SIFagent -keyalg RSA -keysize 1024 Enter keystore password: changeit What is your first and last name? first last What is the name of your organizational unit? Product Development What is the name of your organization? Blackboard Inc What is the name of your city or locality? Washington What is the name of your state or province? DC What is the two letter country code for this unit? US Is CN=first last, OU=Product Development, O=Blackboard Inc, L=Washington, ST=DC, C=US correct? Yes Enter key password for (RETURN if same as keystore password): RETURN 3. Create a Certificate Signing Request (CSR) for the SIF agent and sign the certificate. keytool -certreq -keystore SIFagent.ks -alias SIFagent -file SIFagent.csr 4. 5. 6. Submit the CSR to a certifying authority (CA) or self-sign the certificate. Download the server certificate and the CA certificate and copy them to the ZIS server. Import the server certificate into the Blackboard server keystore. cd /<blackboard_install_directory>/config/certs keytool -import -alias NAMEcaroot -file NAME.cer -keystore SIFagent.ks keytool -import -alias SIFagent -file SIFagent.cer -keystore

Page 112
SIFagent.ks keytool -list -keystore SIFagent.ks -storepass changeit Do not forget to share the keystore with the ZIS server. Windows: 1. Run the following from the command line: %JAVA_HOME%\bin\keytool -genkey -v -keystore C:\<blackboard_install_directory>\config\certs\SIFagent.ks -alias SIFagent -keyalg RSA -keysize 1024 2. 3. The first prompt asks for a password for the keystore. The default password is "changeit. The next few prompts ask for information about the person creating the certificate. This information will appear to users when they first access the Collaboration Tool over SSL. Users are prompted to accept the certificate so it is important to provide accurate information so that users trust the certificate. The information recorded is: First and Last Name Organizational Unit Organization City or Locality State or Province Two-letter country code 4. The last prompt asks for the password for the certificate. This password must be the same as the password entered in Step 2. Simply press ENTER to confirm that the same password will be used. The keystore will be created in the specified directory. Create a Certificate Signing Request (CSR) for the SIF agent and sign the certificate. %JAVA_HOME%\bin\keytool -certreq -keystore C:\<blackboard_install_directory>\config\certs\SIFagent.ks -alias SIFagent -file SIFagent.csr 7. 8. 9. Submit the CSR to a certifying authority (CA) or self-sign the certificate. Download the server certificate and the CA certificate and copy them to the ZIS server. Import the server certificate into the Blackboard server keystore. %JAVA_HOME%\bin\keytool -import -alias NAMEcaroot -file C:\<blackboard_install_directory>\config\certs\NAME.cer -keystore C:\<blackboard_install_directory>\config\certs\SIFagent.ks keytool -import -alias SIFagent -file C:\<blackboard_install_directory>\config\certs\SIFagent.cer keystore C:\<blackboard_install_directory>\config\certs\SIFagent.ks keytool -list -keystore C:\<blackboard_install_directory>\config\certs\SIFagent.ks storepass changeit
5. 6.
Do not forget to share the keystore with the ZIS server.

Page 113
Configure TrustStore
Follow these steps to add a truststore from the ZIS server: UNIX: Import the ZIS server certificate into the SIF Agent Trusted keystore. cd /<blackboard_install_directory>/config/certs keytool -import -v -alias SIFWorks -keystore Trusted.ks -file ZIS.cer Trust this certificate? [no]: yes keytool -list -keystore Trusted.ks -storepass changeit This will create a new keystore containing the ZIS certificate, which will be trusted. Windows: Import the ZIS server certificate into the SIF Agent Trusted keystore. cd C:\<blackboard_install_directory>\config\certs %JAVA_HOME%\bin\keytool -import -v -alias SIFWorks -keystore Trusted.ks -file ZIS.cer Trust this certificate? [no]: yes %JAVA_HOME%\bin\keytool -list keystore Trusted.ks -storepass changeit This will create a new keystore containing the ZIS certificate, which will be trusted.

Page 114
Data Mapping
Overview
SIF integration passes user data from other system to the Blackboard system through the ZIS server.
Data Map
The table below outlines the data that is passed and maps the ZIS value to the corresponding Blackboard Value. SI F O b j ect Bl ac kb oa rd Us e r In f o rm at io n BATCH_UID De s cr ip t io n
RefID
Required field in Bb. Event will fail if this field cannot be populated. Max= 64. Accepts multi-byte. Required field in Bb. Event will fail if this field cannot be populated and the event is trying to create a new user. Max= 100. Accepts multi-byte. Max= 100. Accepts multi-byte. Required field in Bb. Event will fail if this field cannot be populated and the event is trying to create a new user. Max= 100. Accepts multi-byte. Max= 100. Must contain @ and . Required field in Bb. For Add Event, will be the same as BATCH_UID. Max= 50. For creating new users, since the username will be created from the BATCH_UID and the BATCH_UID allows a max of 64, if the BATCH_UID has over 50 characters, then the username cannot be created due to the limitation and the event will fail. Accepts multi-byte. Required field in Bb. For Add Event, will be the same as BATCH_UID. Max= 32 SIF M = Bb Male SIF F = Bb Female SIF U = Bb Not Disclosed Datetime field type. Max= 8
Name/FirstName
FIRSTNAME
Name/MiddleName Name/LastName
MIDDLENAME LASTNAME
Email
EMAIL USER_ID
PASSWD Demographics/Gender GENDER
Demographics/Birthdate
BIRTHDATE

Page 115
SI F O b j ect
Bl ac kb oa rd Us e r In f o rm at io n STREET_1 STREET_2 CITY STATE ZIP_CODE COUNTRY H_PHONE_1 PUBLIC_IND EMAIL_IND ADDRESS_IND WORK_IND PHONE_IND SYSTEM_ROLE INSTITUTION_ ROLE ROW_STATUS
De s cr ip t io n
StudentAddress/Address/ Street/Line1 StudentAddress/Address/ Street/Line2 StudentAddress/Address/ City StudentAddress/Address/ StatePr StudentAddress/Address/ PostalCode StudentAddress/Address/ Country PhoneNumber
Max= 100. Accepts multi-byte. Max= 100. Accepts multi-byte. Max= 50. Accepts multi-byte. Max= 50. Accepts multi-byte. Max= 50. Accepts multi-byte. Max= 50. Accepts multi-byte. Max= 50. Accepts multi-byte. Required field in Bb. For Add Events, will default to N. Required field in Bb. For Add Events, will default to N. Required field in Bb. For Add Events, will default to N. Required field in Bb. For Add Events, will default to N. Required field in Bb. For Add Events, will default to N. Required field in Bb. For Add Events, will default to None. Required field in Bb. For Add Events, will default to Student. Required field in Bb. For Add Events, will default to 0 (enabled).

Page 116

Blackboard Learn 9.1 Server Administration Guide

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Blackboard Learn 9.1 Server Administration Guide

Hochgeladen von

Copyright:

Verfügbare Formate

Release 9.

Server Administration Guide

2010 Blackboard Inc. Proprietary and Confidential

Blackboard Learn Server Administration Guide

Blackboard Learn Server Administration Guide

Blackboard Learn Server Administration Guide

Blackboard Learn Server Administration Guide

Blackboard Learn Server Administration Guide

Blackboard Learn Server Administration Guide

Blackboard Learn Server Administration Guide

About the Server Administration Guide

Other Resources for Administrators

Blackboard Learn - Basic Edition Limitations

Blackboard Learn Server Administration Guide

Blackboard Learn Server Administration Guide

Customizing Authentication Page Flow Creating and Deploying Custom Implementations

Blackboard Learn Server Administration Guide

Introduction to Blackboard Learn Authentication

Customize the Default Authentication

Return to the Default Authentication

Blackboard Learn Server Administration Guide

De s cr ip t io n Learn default authentication.

Blackboard Learn Server Administration Guide

Introduction to LDAP Authentication

Blackboard Learn Server Administration Guide

Blackboard Learn Server Administration Guide

LDAP Configuration Overview

Open LDAP UNIX Operating Systems Only

Blackboard Learn Server Administration Guide

Editing the properties file

LDAP Property Configuration

Blackboard Learn Server Administration Guide

auth.type.ldap.use_ priv_user.x auth.type.ldap.user _fdn.x auth.type.ldap.user _pwd.x auth.type.ldap.dere f_aliases.x

Blackboard Learn Server Administration Guide

P ro p e rt y auth.type.ldap.serv er_error_fatal.x auth.type.ldap.cont ext_factory.x

auth.type.ldap.refe rral_limit.x base_search_fdn

Blackboard Learn Server Administration Guide

Blackboard Learn Server Administration Guide

Debugging LDAP Authentication

Troubleshooting LDAP Authentication Properties for Windows

Blackboard Learn Server Administration Guide

7. 8. 9. 10. 11. 12. 13. 14.

Troubleshooting LDAP Authentication Properties for UNIX

Blackboard Learn Server Administration Guide

Revert to Default Authentication

Blackboard Application Log

Blackboard Learn Server Administration Guide

The LDAP SSL certificate expires

Troubleshooting LDAP with SSL

Blackboard Learn Server Administration Guide

Blackboard Learn Server Administration Guide

Blackboard Learn Server Administration Guide

Blackboard Learn Server Administration Guide

Blackboard Learn Server Administration Guide

LDAP Fail Over Considerations

Automatic Fail Over for LDAP Server Error

Blackboard Learn Server Administration Guide

Changing the Default Configuration for LDAP Server Error

For more information, see LDAP Properties.

For more information, see LDAP Properties.

Blackboard Learn Server Administration Guide

LDAP with Active Directory

Connecting via an Anonymous Bind