LON-CAPA: Customizing Institutional User Information Integration, Study notes of Communication

Download LON-CAPA: Customizing Institutional User Information Integration and more Study notes Communication in PDF only on Docsity!

Learning Online Network with CAPA

Domain Coordination Tutorial And Manual

February 27, 2022

LON-CAPA Group

Michigan State University

Contents

1 INTRODUCTION 4

1 Introduction

The Domain Coordination Manual includes both a description of tasks which require stan- dard LON-CAPA interaction via a web browser, with the Domain Coordinator role active, but also tasks which require command line access to the primary library server in a domain. In some cases one individual may complete both these types of task, whereas in others a separate Systems Administrator may need to be called upon for tasks completed from the command line. With the Domain Coordinator role active, the Main Menu provides a Domain Coordina- tor with access to the functionality needed to complete the routine tasks which a Domain Coordinator carries out, including creation of courses, approval of course requests, and as- signment of author roles. Courses can be created interactively by completing a web form or can be created in batch mode by uploading a file containing course specifications for one or more courses. The right to submit course requests via a web form may also be granted to groups of users, and requests can be set to be processed automatically, or require Domain Coordinator approval. Addition of users/roles can similarly be carried out interactively, or by uploading a text file of users. The Domain Coordinator may also periodically need to modify domain settings via the Domain Configuration menu. LON-CAPA provides hooks to permit integration with institutional information systems to support the following procedures:

• Authentication via an institutional authentication service (e.g., LDAP)
• Automatic updates of classlists
• Automatic updates of user information
• Automatic processing of validated course requests for “official” courses.
• Retrieval of institutional user information for individual users
• Searches for users at the institution
• Automatic import of student photos from an institutional repository

There are three perl modules included in LON-CAPA (localauth.pm localenroll.pm, and localstudentphoto.pm all located in /home/httpd/lib/perl ) which need to be customized to provide integration with institutional systems. Although customization and testing will involve a systems administrator, and program- mer(s) at an institution, a Domain Coordinator is likely to be involved in the design and testing phases of the integration, if not in the actual implementation. Set-up of a standalone LON-CAPA instance on a separate server is advised for the purposes of implementing and testing institutional integration, before enabling the new functionality on the production system. Besides the integration described above, customization of localenroll.pm is also needed (at present) to define the titles used for official course categories (e.g., Year, Semester, Department, Number) which can be used as filters when searching the Course/Community Catalog.

LON-CAPA installation and/or update will provide unmodifed copies of the three cus- tomizable files in /home/httpd/lib/perl, each with -std appended, i.e., localauth-std.pm, localenroll-std.pm, and localstudentphoto-std.pm. These files receive updates when ./UP- DATE is run to update a LON-CAPA installation to a newer version, while their customized equivalents will be left untouched. If you have previously customized localenroll.pm it is recommended that you compare the contents of localenroll.pm and localenroll-std.pm after an update to see if there are new subroutines (which exist as stubs in localenroll-std.pm) which can be copied to your custom localenroll.pm and later customized, should you wish to use that functionality.

2 Domain Configuration

2.1 Log-in Screen Customization

Log-in Service If your domain has more than one server you have the option to configure whether any of the servers will redirect to another server whenever the log-in page is requested. This can be useful if you maintain a portal or “Load Balancer” server which forms your institution’s gateway to LON-CAPA. You can specify the path to which the user should be redirected, and also whether log-in page requests from specific IP addresses should be exempt from the redirection. The exemption is useful if you run a monitoring script which tests log-in, course display, and logout periodically for each of your LON-CAPA servers.

Log-in Page Items If your domain only has one LON-CAPA server, or you have multiple servers and will display their log-in pages, their appearance can be customized as follows:

• upload of custom image files
• changes to colors of text, links or backgrounds
• enabled/disabled display of specific links

Note: logos displayed in the login page configuration panel are scaled down from the full size used in the log-in page itself.

The following elements are configurable:

• Header image at the top of the page
• Main Logo centered in the upper part of the main panel
• Domain logo in the lower left corner of the main panel
• Header above the login panel - can also be set to use text “Login” instead of an image.
• Background colors for the page itself, the main panel, and the left (side) panel.

For a LON-CAPA node configured to support Single Sign On (SSO), e.g., by operating as a Shibboleth SP, entries in Apache config files (loncapa apache.conf, if Shibboleth) will cause display of an SSO login page whenever a user accesses /adm/roles without a cookie for an unexpired LON-CAPA session. If it is preferred instead to display /adm/login configured to offer dual SSO log-in (e.g., Shibboleth), and non-SSO login (i.e., LON-CAPA), that will be set via the “Dual login: SSO and non-SSO options” section. Check the “Yes” radio button for each of the domain’s servers which will offer dual login and then set:

• SSO: Text, Image, Alt Text, URL, Tool Tip
• non-SSO: Text

The value in the URL field will be /adm/sso for Shibboleth, and an uploaded image file will provide the button to be clicked to load /adm/sso (i.e., to prompt an SSO login). The alt and title attributes for the button can also be set. With this in effect the LON-CAPA login page /adm/login will display the following:

• Log-in type: Immediately followed by the text for either SSO, or non-SSO login, as set via the “Dual login: SSO and non-SSO options” textboxes for SSO and non-SSO.
• Change? A link below the “Login type:” line which can be used to toggle between the SSO and non-SSO logins
• Button (SSO) or Log-in box (non-SSO)
  • SSO - an image (i.e., clickable button) which was uploaded in the SSO option item, with alt text, and a tool tip shown when hovering over the button.
  • Non-SSO - standard LON-CAPA login box for username, password, domain and ”Log In” button.

If the SSO service is something other than Shibboleth (e.g., CAS or Sentinel) and the PerlVar lonOtherAuthenUrl has been set to a preferred URL (e.g., /adm/sentinel), then the URL item in the SSO entry in the dual login options should be set to that same preferred URL. Note: if the original page request by an unauthenticated user included a query string containing role and symb (i.e., the unique resource instance identifier) then they will be stored in a token file on the server, for access later to support deep-linking.

2.2 Setting E-mail Addresses for Administrators and Support

LON-CAPA will send automatic e-mail to administrators/support staff under certain cir- cumstances. The contact information data table can be used to provide e-mail addresses for receipt of these e-mails and to configure which types of e-mail should be sent to each address. The types of e-mail are:

• Error reports - whenever a server encounters a 500 error (Internal Server Error), Apache will handle that event by displaying an error report form which the affected user can complete and submit. The submission, which contains session information besides any information provided by the user, will be sent as an e-mail.
• Package update alerts - the CHECKRPMS script run three times a week (on Mon- day, Thursday, and Sunday) will generate e-mail if it detects that package updates are needed.
• Module integrity alerts and new LON-CAPA releases - a nightly process com- pares checksums for LON-CAPA modules installed for your current release with the expected values for that release retrieved from one of the Academic Consortium servers (if your server is part of the LON-CAPA network). An alert is sent if checksums or versions don’t match, or if a new LON-CAPA release has been announced.
• LON-CAPA server status A nightly run of the /home/httpd/perl/loncron script will generate an e-mail if the weighted total of notices, warnings, and errors exceeds a specified threshold. The script checks load average, disk usage, and recent entries in the log files for the lond and lonc LON-CAPA daemons, as well as the difference between the number of delayed “critical” transactions and the number of such trans- actions subsequently completed when connection was re-established, (as recorded in the permanent log file: /home/httpd/perl/logs/lonnet.perm.log). If an e-mail is sent the message body contains the same HTML as in the /lon-status/ page on each LON- CAPA server, for which access is configured using the “Display Detailed Report” item in the domain configuration for “Access to server status pages”;
• Alerts for users sharing the same student/employee ID - a script is run every other night to check for use of the same student/employee ID by multiple users in your domain. In LON-CAPA, a username must be unique, and it is also recommended that student/employee IDs are unique.

Definition of the default Admin e-mail address and the default Support e-mail address saved from the “Contact Information” screen supercede any definitions made when ./UPDATE is run to update to a new version of LON-CAPA. Addresses entered the first time ./UPDATE was run on the primary library server for the domain (i.e., when LON-CAPA was first installed) will continue to apply until the first “Save” of the Contact Information settings has occurred in the domain. Three additional settings allow you to specify:

1. Whether error reports submitted by users should be sent to the core developer group at Michigan State University (as well as to the recipients selected in your domain).
2. Whether an e-mail reporting a completed upgrade to a new LON-CAPA version should be sent to the core developer group.
3. Whether an e-mail containing the nightly status report generated by loncron should be sent to the core developer group if the total error count exceeds a specified threshold.

• Optional added text A text string can automatically be added to each e-mail, either prepended to the subject, or to the body of the message. Extra helpdesk form fields The user’s e-mail address, and the message subject and description are always required fields in the web form. The following are additional fields which can be set to be one of: optional or not shown.
• Name
• Phone
• Username and domain
• Course Details
• Section
• Cc e-mail
• File upload In the case of Name and Phone, the fields may also be set to required, and in the case of CC e-mail and File upload, those are only shown when the helpdesk web form is accessed by a user logged into LON-CAPA. If the File upload field is to be displayed, the allowed size of the upload can be specified (the default is 1.0 MB).

2.3 Default Color Schemes

Default color schemes can be set for the domain for four types of user context:

• Student
• Course Coordinator
• Author/Co-author/Assistant Author
• Domain roles (Domain Coordinator)

In each case the following can be set or modified:

• Header image displayed in place of the inline navigation controls when the page is viewed with the Remote Control active.
• Color used for text in the LON-CAPA interface
• Background colors used for the page itself, and the inline navigation (if shown) and the page header below it, and a border to the header (not used).
• Default colors for links in the page, depending on status: either active, visited or default (if neither apply).

Individual users can override any default settings you establish for the domain via the “Change Color Scheme” link in their individual Preferences screen. In the absence of individ- ual preferences, any domain defaults you set will be used whenever users from your domain are using LON-CAPA, regardless of which domain owns the server hosting the session.

2.4 Setting Domain Defaults: Authentication, Language, Time

Zone, Portal and User Types

Prior to LON-CAPA 2.7, default language and authentication type/argument were defined in the domain’s entry in the domain.tab file. Those settings will continue to be used by servers in your domain until you have displayed and saved the Default authentication, language, timezone data table. Once that has been done, whenever values need to be determined for these settings in the domain they will be retrieved from the configuration.db file on the primary library server in your domain, which is where information saved from the “Domain Configuration” data tables is stored. Any information in the domain.tab file will no longer be consulted, except by servers running pre-2.7 versions of LON-CAPA. Default domain configurations can be assigned for:

• default language used by users in your domain, unless overridden by a user preference
• default authentication type for new users in the domain. You will need to set the default authentication if you intend to allow a user to create a LON-CAPA account if the user successfully authenticated via a central service at your institution (e.g., Kerberos), but is without a LON-CAPA account. The default authentication is also the default offered when Course Coordinators or Authors create new accounts, assuming user creation is permitted in these contexts.
• default timezone - this will be the timezone used when showing any times in your domain, unless overridden at a course level, by a course-wide timezone. The time- zones available are mostly in the form Continent/City, although for the USA there are some in the form America/State/City as well as EST5EDT, CST6CDT, MST7MDT, PST8PDT and HST (for Eastern, Central, Mountain, Pacific and Hawaii Timezones, which adjust for daylight savings as appropriate). If no default timezone is set times will be displayed according to the timezone of the server hosting the user’s LON-CAPA session.
• portal/default URL - starting with LON-CAPA 2.10, a default URL can be specified. This URL will be included in e-mail sent to confirm self-enrollment etc. and might be for a load-balancer LON-CAPA server, or in the case of a multi-domain server, for a specific alias used for the domain.

Institutional user types can also be defined for the domain via the same screen. Prior to LON-CAPA 2.11, institutional user types were defined in the &inst usertypes subroutine in localenroll.pm, which would be customized for consistency with types defined in institutional data feeds. Setting of user types via the Domain Configuration web GUI supersedes use of localenroll::inst usertypes(). Items that can be set are:

• Internal ID (e.g., faculty)
• Name Displayed (e.g., Faculty/Academic Staff)
• Order (Listing order, 1 through N, when the type is to be selected from a list).

on the log-in page. If the information submitted via the web form matches that stored in LON-CAPA for that user (and the user’s authentication type is “internal”), then an e-mail will be sent to the user’s e-mail address, containing a time-limited link, which when followed will display a second web form, in which the user enters e-mail address, username, e-mail address, and a new password. Starting with LON-CAPA 2.11.3 this procedure can be customized in the following ways:

• Type of Captcha (for robot suppression) to use with the initial web form.
• Expiration time of the time-limited link in the generated e-mail.
• Whether checking of username and/or e-mail address is/are case-sensitive.
• Whether just username, or just e-mail address or both are submitted in the first form.
• Whether information besides the new password is required in the second form.
• Which e-mail address(es) stored for a user in LON-CAPA may be used in the password reset.
• Whether custom text should be used as a preamble for the initial web form.

If “Institutional Types” (e.g., faculty, student etc.) have been defined for a domain then some of the customizations can be made dependent on a user’s institutional type. Encryption of Stored Passwords

• Encryption cost for bcrypt (positive integer). Starting with 2.11.2 bcrypt is used to encrypt the password for an internally authenticated user. The complexity of the en- cryption is determined by the bcrypt cost value. A higher value means more complexity (and more time to validate a user’s password). The cost needs to be a positive integer. If no value is set in a domain, a default of 10 will be used.
• Check bcrypt cost if authenticated. When an internally authenticated user logins and the credentials are validated, the bcrypt cost used for the original encryption can be compared with the current domain default. If the cost for the stored encryption is less than the current domain setting, there are two options - either allow login and update the stored encryption using the higher cost, or disallow login. The default is not to compare the original cost with the current domain setting.
• Existing crypt-based switched to bcrypt if authenticated. When an internally authenti- cated user logs-in and the credentials are validated, if the stored credentials are cur- rently encrypted with crypt, there is an option to update the stored encryption to use bcrypt, with or without backing-up the existing passwd file to a passwd.bak file. The default is not to update the stored passwd file, so existing users who have crypt-based stored passwords will continue to do so until such time as they change their password.

Rules for LON-CAPA Passwords

Starting with LON-CAPA 2.11.3 requirements can be set for password length, whether special characters or mixed case are required, and how many (if any) previous passwords to save for a user (disallow reuse). Course Owner Changing Student Passwords Starting with LON-CAPA 2.11.3 a domain can be configured to allow a course owner to change a student’s password, if the following conditions are met:

• same domain is used by owner, course, and student,
• student has no active or future roles besides student role in courses owned by the course owner making the change,
• course container is not a Community.
• owner is course coordinator in the course,
• setting to disable this action has not been set for the specific course.

If “Institutional Types” (e.g., faculty, staff, student etc.) have been defined for a domain then which course owners may change student passwords can be restricted to specific types. In addition, which students may have their passwords changed can also be restricted to specific types. The default is to not allow Course owners to change a student’s password.

2.6 Setting Domain Defaults: Blogs, Portfolios, Personal Infor-

mation Pages, WebDAV, and Quotas

By default, each user in your domain can create blogs, a personal information page, and store files in an individual portfolio space. Students can submit items from their portfolio to meet the requirements of assignments in their courses. You can choose to disable personal information pages, blogs and/or portfolios for different groups of users defined for your domain (e.g., Faculty, Adjunct, Staff, Student). If the “Modify User” utility in User Management is used to explicitly set availability of these tools for a particular user, that will override the corresponding settings determined by the user’s affiliation. If you choose to enable portfolios, default quotas (in MB) can similarly be set to vary by institutional affiliation. If a user is affiliated with more than one group, whichever default quota is largest for the different groups is the one which applies. Institutional types are defined in the “Institutional user types” section on the “Default authentication, language, timezone, portal, types” screen. If no types have been defined, then a single default quota will apply for all users from the domain. Default portfolio quotas which can be set for users in your domain will be overridden by any quota you set for an individual user via: the “Modify User” utility. Additional options for authoring spaces can be set for the various user types: (a) whether webDAV is active, and (b) the default quota for Authoring Space. These only come into effect for a particular user, when an author and/or one or more co-author roles have been assigned to a user to provide access to one or more Authoring Spaces.

2.7 Setting IP-based access control for specific Courses and IP

Ranges

To accommodate use of LON-CAPA within a dedicated Computer Based Testing Facility (CBTF), a domain configuration is available to set IP-based restrictions on availability of student roles in course(s) and access to LON-CAPA tools used for communication and col- laboration. This complements domain settings in the “Blogs, personal web pages, webDAV/quotas, portfolios” section 2.6 which apply by default, regardless of a user’s IP address, to specific types of user (e.g., Student, Staff etc.). IP-based access controls set at a domain level also complement time-limited blocks a Course Cordinator can set in a course via Settings > Content Settings > Blocking Communication/Resource Access, some of which can impact functionality in other courses, e.g.,, Chat, Messaging, Portfolio and Blogs. Configuration of IP-based access control in a domain supports multiple access control items, and each item in use will be assigned the following:

• Location(s) An identifier, typically the name of the location where IP-based access control is needed, e.g., CBTF.
• IP Range(s) The IP address(es) of users’ web browsers from which access to specific courses is allowed, while blocked for all other course roles, and also for which communication blocking will be in effect. Each set of IP addresses should either be in the format: IP netblock/prefix (i.e., A.B.C.D/N) or a hyphen-separated IP range (i.e., A.B.C.D- E.F.G.H). If multiple sets apply for a single location, each set should be separated by a comma from other set(s). Range(s) will be stored in LON-CAPA as IP netblock(s) in CIDR notation (comma separated).
• Functionality Blocked? Choose communication and/or collaboration functions in LON-CAPA to block for non- privileged users, i.e., users without the “Evade communication blocking” (evb) privilege (Domain Coordinators, Course Coordinators and Instructors). For functions subject to blocking, a “Communication blocked” link will be shown, which when followed will pop-up open a window to explain the cause of the block. If IP-based blocking of “Messaging” is in effect, the only LON-CAPA messages a non- privileged user can display are “Critical Messages” sent by course personnel or by a Domain Coordinator. If ”Blocking” is in effect, one of two buttons: (a) “Move to Inbox” or (b) “Confirm Receipt” will be displayed below each new critical message, but their equivalents with the reply option will not be. Users will also be unable to send regular LON-CAPA messages, except via “Send Feedback” (in course context) to send questions to an instructor or other designated course personnel. If “Send Feedback” is used within a session subject to IP-based blocking, subject and content originally sent will be replaced in the sender’s “Sent Messages” Folder with the text: ”Not shown

due to IP block”. Lastly, if the “Ask helpdesk form settings” for the domain include the“Cc e-mail” field as an optional field, that will not apply in the case where IP- based blocking of “Messaging” is in effect for a logged-in user who is completing the help form.

• Courses/Communities allowed Choose which course(s) and/or communities should be exclusively selectable by stu- dents when accessing LON-CAPA from a web browser with an IP address which falls within the IP range(s) designated for the particular location. Those same courses will be unavailable for selection from other locations, unless another access control item in the domain is in effect for IP address(es) elsewhere. Users with the ‘evb’ privilege are exempt from restrictions on role selections in a course, unless selecting a student role. As a user may potentially have been assigned roles in different LON-CAPA domains it is important to understand that IP-based access control rules on a course will only apply to users who meet at least one of the following conditions: - User’s domain and course’s domain are the same - User’s domain is one of the current server’s domain(s) - User’s domain is one of the institution’s domain(s)

Accordingly, either the domain should be configured so LON-CAPA sessions for the domain’s users may only be hosted on the institution’s own server(s), see the “User session hosting/offloading” section 2.25, or web browsers in the location (or local net- work) should be ”locked down” such that the only LON-CAPA servers which may be contacted by browsers in the location are servers in the institution’s domain(s).

2.8 Web Application Firewall/Reverse Proxy

A LON-CAPA server requires a static IP address, and the hostname included in the hosts.tab entry for the server should resolve to that IP address. If the server is part of the LON-CAPA network, the server will need to support connections from other servers for both “internal” communication via the dedicated LON-CAPA port as well as requests to standard web ports when replicating content. Consequently, in order to run LON-CAPA server(s) behind a Web Application Firewall (WAF), or Reverse Proxy, different hostname(s), or alias(es) to the default hostname in /home/httpd/lonTabs/hosts.tab must be requested by users’ web browsers when accessing LON-CAPA pages from a domain’s server(s) via a WAF.

1. Alias for WAF/Reverse Proxy The “Web Application Firewall/Reverse Proxy” domain configuration is used to indi- cate if a WAF is in use, and if so, to provide the alias assigned to each LON-CAPA server which will use the WAF. For each one there is also an option to indicate whether a node supporting Single Sign On, will use the alias when redirecting to the URL used to trigger SSO authentication: default is /adm/sso, but can be set in an Apache config file using: PerlSetVar lonOtherAuthenUrl

• Access via regular hostname (no WAF)
• Access via aliased hostname (WAF)

If VPN users will not use WAF, but other users will, then the following are needed:

• IP Range for backend WAF connections
• Internal IP Range(s) for VPN sessions

5. Forwarding http and https requests If using WAF select one of:

• WAF forwards both http and https requests to https
• WAF forwards http requests to http and https to https

2.9 Identity Management: Searching for Users in an Institutional

Directory

LON-CAPA provides a mechanism to search for users by complete username, last name, or last name,first name (or fragments of each). Accounts within the LON-CAPA domain itself can be searched, or alternatively, an institutional directory may be searched, if you are able to implement a conduit to directory information to support such searches. This will be done by customizing the &get userinfo() routine in localenroll.pm. This routine has a dual role in LON-CAPA. Not only will it support searches where the user is not excatly known, but it can also be used to retrieve institutional records for a specific username or student/employee ID. This latter mode of use is appropriate when adding a new user to LON-CAPA. Settings for directory searches apply either to institutional directory searches or to LON- CAPA domain searches.

1. Institutional Directory searches
   • Set institutional directory searches as available or unavailable in the domain
   • Set whether users from other LON-CAPA domains can use the institutional di- rectory search to search for users.
   • For searches by users within your domain, you can limit the users who can use institutional directory search based on institutional status
   • Set which types of search method - username, last name or last name,first name are allowed for institutional searches
   • Set which types of search latitude - exact match, begins with or contains - are allowed.
2. LON-CAPA Domain searches

• Set whether accounts within the LON-CAPA domain itself can be searched by users with privileges to add users to a course, or as co-authors, or to a domain. All types of search method and all types of search latitude will be available for LON-CAPA domain searches.
• Set whether users from other domains can search within a LON-CAPA domain.

In the case of a “contains” type search at least three characters must be entered by the user as the search term. Searches are case insensitive.

2.10 Identity Management: Creating New Users

Identity management in a LON-CAPA domain is dependent on settings made for user cre- ation and user modification. Of particular concern is the potential for assignment of user- names in a format used by your institution when the username does not yet exist. In such a case, authentication is likely to be set to be “internal”, and should a real user be created in the future, and be enrolled in a course by auto-enrollment, the user would either be unable to authenticate (using LON-CAPA log-in page), or would be authenticated by SSO, and have access to the original user’s roles and associated information. It is important therefore to establish format rules for new usernames so the only users created with institutional-type usernames are the real users themselves with the appropriate authentication type (Kerberos or localauth). Even without format rules, the Domain Coor- dinator can set who can create new users, and the authentication types that may be set in different context. The domain-wide options available for user creation are:

• Activate/deactivate operation of format rule(s) for usernames
• Activate/deactivate operation of format rule(s) for student/employee IDs
• Control which types of username (official or non-official) may be used when creating new users in course or author context
• Control which types of authentication may be used when assigning authentication to new users in author, course or domain context

The format rules themselves are defined by customizing the following routines in localen- roll.pm:

• usernames: &username rules() and &username check()
• IDs: &id rules() and &id check()

When enforced the user name and ID rules require that if a username and/or ID which matches the format for an active rule is to be used in LON-CAPA, they must exist in the institutional directory. If they exist, the corresponding user information (first name, middle name, last name, e-mail address) will be used when creating the new user account. If they do not exist, account creation will not occur.