Our Directory Service Integration is available to districts using any LDAP version of Directory Services.
School Loop uses LDAP to create a secure authentication process with your directory services (for instance, Active Directory). Via a secure web service, users will log in with the username and password assigned by you. All policies and practices relating to usernames and passwords are managed through your directory services.
An added benefit is that each time a user logs in to School Loop using their Active Directory credentials, their first name, last name, email address, and login name listed in their School Loop account automatically syncs with their AD account. This syncing also occurs whenever the activate user list (discussed below) is opened.
For student accounts, there is an option to disable syncing of email addresses, which allows students to use an email address of their choosing with their School Loop account.
The secure User Web Service that is installed on a district server acts as an intermediary between School Loop and the district's Directory Services server. School Loop can query the web service for username and password authentication, and the web service will respond with "true" or "false" as to whether those login credentials are correct.
Prior to this authentication, however, Directory Service users must be "activated" in the School Loop system, via the Activate Users interface. Teacher, Student, and Staff users are activated separately, and each group of users has its own activation page.
The activation page for teachers queries the web service for all Directory Service users whose "department code" matches the school code. Each matched user's employee ID is then compared to the teacher IDs from the latest data import from your Student Information System (data importing from the SIS is a separate process known as Sloopy).
Users whose employee ID attributes match a known teacher ID are then displayed for activation. Student users are matched similarly using the student ID attribute.
No ID number is imported for any other staff, so those users are matched by username. If the username is already activated in School Loop in a staff role, that user's account is synchronized with your Directory Service; once synchronized, the user must use their Directory Service password to login (the local School Loop password will no longer work).
If the username is not active or does not exist, the user is presented with a drop-down list of roles; selecting a role and clicking submit activates the user account. If the username already exists in a non-staff role (for example a parent user), a warning message is displayed and no action is taken.
Configure Directory Services
The following configuration steps are required to connect an external Directory Services user database to the School Loop system.
- Employee IDs: Teachers and Students must have their unique district teacher ID or student ID entered as an attribute in Directory Service. By default we use the "employeeid" attribute, but any attribute can be used.
- Department Code: All Directory Service users must have a "department" value. By default we use the "department" attribute, but any attribute can be used as long as the same attribute is used consistently across the district. For school users, this code must be the district school code for the school. For district offices, this can be any unique value that is not a school code. School Loop can be configured with multiple department code values for a district office site.
Domain Names: School Loop will search a specified list of Directory Service domain names for users. If the district uses multiple domain names for users at the same school, please ensure that all user names are unique. In the case of duplicate usernames, the first user activated will receive that name, but the other user will be presented with a conflict message in the activation page.
For example, given users email@example.com and firstname.lastname@example.org at MySchool, the first activated will get the user name jsmith and the other cannot be activated since School Loop usernames must be unique at each school. (The solution would be to change one of the user names in LDAP, or register one or the other users manually with a different username, in which case their accounts would not be synchronized with Directory Service.)
- userPrincipalName: The userPrincipalName attribute contains the user name that will be used in School Loop, follow by @domainname. For example for userPrincipalName "SmithJ@district.k12.org", the resulting School Loop user name will be "smithj". (School Loop login is not case-sensitive).
Web Service Setup
Install the web service on an externally accessible Web Server.
- Make sure java JRE 5 or better is installed on the web server and the path to the java bin folder is in your system PATH variable.
- Download and unzip the Web Service distribution. This consists of a "dist" folder with all of the necessary files to configure and run the web service (download link provided by School Loop).
- Create a keystore (a self-generated certificate will suffice). Open a command prompt and type:
keytool -genkey -validity 999 -keystore security/keystore
The path at the end of that command is used to place the keystore file in the security folder which is inside the dist folder. It may be easiest to specify the full path to this location.
- Optionally, but recommended, create a Truststore if using SSL to connect web service to the LDAP server.
Open a command prompt and type: java InstallCert your-AD-server-ipAddress-goes-here:636 (when prompted, hit return).
- Edit the LdapApp.properties file in the "dist" folder to adjust the provider url, AD login, web-service port, and the keystore file as necessary (details below).
Open a command prompt and change directory to the "dist" folder. Start the service with the "run" command file in the dist folder.
Configure the LdapApp.properties File
providerURL: the url to the Directory Services server.
"ldap://10.2.2.20:3268", or for SSL, "ldaps://10.2.2.20:3269" (search Global Catalog (GC) to locate objects from any domain)
"ldap://10.2.2.20:389", or for SSL, "ldaps://10.2.2.20:636" (search for objects from local domain controller only)
adminName: the fully qualified admin name for connecting to the Directory Services server. For example "email@example.com".
adminPassword: the password for the admin user.
port: the User Web-Service port over which School Loop connects (port number listed in documentation sent to district network engineers).
keyStore: The keystore file-path for SSL connections to the web server.
keyPassword: The keystore password.
The recommended configuration is to install in a DMZ, with the Directory Services server in a secure zone. School Loop communication with the user-web service is secure, over SSL.
Therefore, it is necessary to create a keystore (if one doesn't exist) on the User Web Service server. Optionally, if secure SSL communication is desired between the Web server and the Directory Services server, a truststore needs to be created as well.
Web Service/Directory Services SSL configuration: To optionally have the Web Service use SSL for secure communication within the district's local network, the following steps are necessary:
- Change the providerURL property in LdapApp.properties to use "ldaps://" instead of "ldap://" and change the port to 636.
- Create a trustStore with the command: java InstallCert <your-AD-server-ipAddress>:636 (when prompted, hit return)
Firewall Configuration: For optimum security, the web server firewall should be configured to allow incoming traffic to the web-service's IP and port only when the traffic origin is from the School Loop system. (IP address listed in documentation sent to district network engineers).
If you are using SSL to communicate between your web-server and your AD server, you will need to make sure your web-server can communicate with your AD server port 636.
Redundancy and Restarting
Redundancy: School Loop highly recommends that an alternate web-service be installed on an additional server (or servers) so that in case one web-server is down for maintenance or due to failure, your user's login authentication will not be interrupted. School Loop’s Directory Services configuration allows any number of web-services to be running simultaneously, and will automatically try successive servers in case of connection failure.
Restarting: To further prevent interruption of user authentication, School Loop recommends that the web-service start command (the "run" bat file) be set up to automatically run on restart. This can be accomplished by adding the run command to the scheduled tasks command list (on Windows, see Start > Programs > Accessories > System Tools > Scheduled Tasks; and add the run command to the "When my computer starts" scheduled task.)
Information School Loop needs to complete configuration
District Site Codes: One or more department codes for district users.
Web Service URL: The URL to the Web Service at the district (e.g. https:/188.8.131.52:7574/ldap_service).
EmployeeID attribute name: The name of the attribute that the district has used for student and teacher IDs (default is "employeeid").
Department attribute name: The name of the attribute the district has used for the school code (default is "department").
Search Base: The domain(s) for the district users (e.g. "district.k12.org").
External web service connect error message: If you want a custom message to appear for users when the web service cannot connect to your Directory Service.
District LDAP Admin email: Web service failure alerts will be sent to this address.
Activation Options: Let us know if you want the following options turned on:
- Block Manual Student Registration
- Sync Student Email Addresses
- Activate Students Automatically
- Activate District Staff Automatically
Customizing Your Password Recovery Message
When Active Directory users request a new password, they will be presented with customized instructions to reset their Active Directory password. The instructions can include text, images and links including Mailto links. To customize your message:
- From your District Admin portal, navigate to the School Site List in your Toolbox and click the Password Help Message link.
- In the Rich Text Editor, provide instructions on how to reset the Active Directory password. It is recommended that your instructions should include:
- Specific steps and links to a password reset page.
- District requirements for a password.
- Systems where this new password will be used.
- Contact information if a district needs help resetting their password.
Below in an example of what a custom message might contain:
The web service fails to run with error "Could not find the main class com.ldap.service.ldapapp".
In the command prompt, change directory (CD) to the "dist" folder before running the web service.
A "command not found" error occurs when trying to create the keystore using the keytool command.
This likely means that that java's bin folder is not in your system's PATH variable. Either add Java to the PATH variable, or run keytool with a fully-qualified path. The keytool utility is part of the java standard edition (SE); if you only have the java runtime (JRE), you may need to download the SE. The keytool.exe utility is in the java SE's "bin" folder.
To add Java to your PATH variable, go to Control Panel > System > Advanced System Settings > Environment Variables, then look for the PATH variable under System Variables. Highlight the PATH variable and click Edit. In the Variable Value field add a semicolon at the end of the values listed and the path to Java’s bin folder on your computer. For example: C:\Program Files\Java\jre6\bin