Web Service Setup

Install the web service on an externally accessible Web Server. 

1. 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.

2. 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).

3. Create a keystore (a self generated certificate is OK).

Open a command prompt and type: keytool -genkey -validity 999 -keystore security/keystore (The path is relative to the web service "dist" folder and uses forward slashes)

4. Optionally create a Truststore if using SSL to connect web service to LDAP server.

Open a command prompt and type: java InstallCert your-AD-server-ipAddress-goes-here:636 (when prompted, hit return)

5. 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)

6. Open a command prompt and change directory to the "dist" folder. Start the service with the "run" command file in the dist folder. 

• providerURL: the url to the Directory Services server.
  For example:
  "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)
  -----OR----- 
  "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 "administrator@sj.k12.internal".
• 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:

1. Change the providerURL property in LdapApp.properties to use ldaps:// instead of ldap:// and change the port to 636.

2. Create a trustStore with the command: java InstallCert your-AD-server-ipAddress-goes-here: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: School Loop highly recommends that an alternate web-service is 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.)

• 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:/100.2.3.40: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 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

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:

1. From your District Admin portal, navigate to the School Site List in your Toolbox and click the Password Help Message link.

2. 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:

Q: The web service fails to run with error "Could not find the main class com.ldap.service.ldapapp".

A:  In the command prompt, change directory (CD) to the "dist" folder before running the webservice.

Q:  A "command not found" error occurs when trying to create the keystore using the keytool command.

A:  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 semi-colon 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