Important Note: If you set up your school or organization's server-side script prior to October 3, 2015, click here for necessary adjustments.
What is Remote Authentication?
Remote Authentication allows a user to login to another website (e.g. school website) and then navigate to Schoology without having to login again. The Remote Authentication area allows you to configure your Single Sign-On (SSO) settings. By using this method of user authentication between your organization’s directory (e.g. LDAP, AD, or OD) and Schoology, you can:
- Manage user credentials from a centralized location.
- Login to Schoology from an outside location, e.g. your school website portal.
How Does it Work?
- The user navigates to their custom subdomain or domain alias.
- Schoology redirects the user to the Remote Authentication URL specified below (See Configure Remote Authentication).
- The script running at the Remote Authentication URL will check to see if the user is logged in. Users that are not logged in must first authenticate on the remote site.
- Using the private token and information from your database, a hash value is created.
- The user information and the hash are then sent to Schoology.
- Schoology receives the data and generates a new hash.
- If both hash values match, which ensures that the data was not modified or tampered with, the user is logged into Schoology.
Before you match users to your school directory, make sure you have created or imported users into your school account (See Import for more information).
- Either the Username or the User Unique ID field must match between your directory and Schoology in order to establish SSO.
- We recommend using the following areas to match users:
- Match the Schoology User Unique ID to the User ID in your SIS.
- Match the Schoology Username to the Username in your directory.
- The Schoology Username and Unique ID fields must be unique throughout your entire school.
- Unique ID- This ID is a unique identifier for each user (usually a School ID or SIS ID). It matches users with your data systems when you import/export.
- Username- Users are required to have a username or email address. Usernames are unique to your school.
Configure Remote Authentication
Once the information in Manage Users matches with your directory, you’re ready to set up remote authentication.
How Remote Authentication works:
- Set up a Remote Authentication URL on your servers, from which your users will login using their directory credentials. This is the URL that Schoology will query when an anonymous user visits the login page and selects your school.
- Script running at the Remote Authentication URL checks to see if the user has been authenticated against your directory
- Using the Private Token and information from your database, a hash value will be created.
- The user information and hash will be sent to Schoology.
- Schoology will receive the data and generate a new hash.
- If both hash values match, the user will be logged into Schoology and data will be updated or synced.
Configuring Remote Authentication in Schoology
- Click System Settings on the left menu of your System Admin account
- Click Integration
- Check Enable School Remote Authentication
- Enter the Remote Authentication URL. This URL should exist on your servers, from which your users will login using their directory credentials. This is the URL that Schoology will query when an anonymous user visits the login page and selects your school.
- Enter the Return URL, where users will be redirected when they logout.
Set Up the Server-Side Script
The page you specify for the Remote Authentication URL has the following two jobs:
- Identify the user. If the user is not already authenticated on your system, log the user in.
- Redirect the user to your customer domain or subdomain (for example, https://customdomain.acme.com/login/remote or https://subdomain.schoology.com/login/remote respectively). Which you use depends on your organization's Schoology DNS configuration: Do you use a Schoology subdomain (myschool.schoology.com, for example) or a custom domain (lms.myschool.com, for example)?
There is no direct communication between Schoology's servers and your servers. All communication is done through redirects and query strings. You can skip steps 1 and 2 of "How does it work?" above by linking directly to the Remote Authentication URL. Your script will be responsible for generating a current timestamp (i.e. less than five minutes old).
Note: You can download the following sample scripts that are pre-populated with your school ID and private token. To view and download these sample scripts and available parameters, navigate to the Integration area of your Schoology account.
From the SSO script, users will be passed to Schoology with the necessary parameters.
- Any parameter you include in the SSO script will update the user information in Schoology.
- Required parameters are marked:
- school_uid or username
Once the Remote Authentication URL is set up and the Server Script is up and running, email your Remote Authentication URL to your Schoology Implementation or Project Specialist to complete the process.
Note: You must match either the school uid or the username between Schoology and your directory.
Users are redirected from Schoology to the Remote authentication URL with a timestamp parameter. You can pass this timestamp back to prevent server clock synchronization issues, or generate the timestamp yourself (seconds since The Epoch). This timestamp must be no older than 5 minutes. Find an example of the current timestamp in the Integration area of your Schoology account.
Your Schoology school ID can be found in the Integration area of your Schoology account.
(required, see description)
School UID (Student ID / Teacher ID)
You must pass either this field or the username field to identify the user attempting to log in. If you use this field for identification, a user with the given school UID must first exist on the Schoology system before being remotely authenticated. If the given school UID is not found, the user is redirected to the Return URL. Also note that if you pass this field, the username field will be not be used for identification.
If building_id is passed, the user’s assigned building_id will be updated on the Schoology system. The buildings in your district can be found in the Integration area of your Schoology account.
If name_first is passed, the user’s first name will be updated on the Schoology system.
First Name (Preferred)
If name_first_preferred is passed, the user’s preferred first name will be updated on the Schoology system.
If name_middle is passed, the user’s middle name will be updated on the Schoology system.
If name_last is passed, the user’s last name will be updated on the Schoology system.
If mail is passed, the user’s email address will be updated on the Schoology system. If the new email address is already assigned to another Schoology account, the user will be redirected to theReturn URL.
(required, see description)
You must pass either this field or the school_uid field to identify the user attempting to log in. If you use this field for identification, a user with the given username must first exist on the Schoology system before being remotely authenticated. If you do not use this field for identification (i.e. by passing a significant value in the school_uid field) the user's username will be updated on the Schoology system. And, if the new username is already assigned to another Schoology account, the user will be redirected to the Return URL.
Schoology Role Id
When Enable Account Creation is checked the Schoology role id is a required field. Otherwise, this field is optional and will update the user’s role on the Schoology system. Role IDs can be found in the Integration area of your Schoology account.
The hash is used to ensure that the information passed to Schoology is not tampered with or modified. It is an MD5 hash of any information you send in the order specified by this table. The following is an example in PHP:
<?php $hash_msg = $private_token . $timestamp . $school_id . $school_uid . $name_first; $hash_msg .= $name_first_preferred . $name_middle . $name_last . $mail; $hash = md5($hash_msg); ?>where
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXJohnSmithjsmith@example.comAny information you are not passing should be omitted from the hash.
You can pass a URL encoded path without the leading "/" to direct the user to a specific page after logging on. This URL must be your custom domain subdomain (for example, https://customdomain.acme.com/login/remote or https://subdomain.schoology.com/login/remote, respectively).
Whichever redirect URL you use, be sure to use HTTPS instead of HTTP if you are set up for it. You can use HTTPS if you have requested that Schoology add your custom domain to our SSL certificates. Contact Schoology support if you would like your custom domain added to the SSL certificates.
Using HTTP will allow anyone to capture and potentially exploit sensitive login information pertaining to your organization and/or your users.
If this parameter is not specified, the user will be directed to the home page. If a user is directed from Schoology to the Remote authentication URL, Schoology will pass a destination parameter containing the path of the page that the user was trying to access.
Note: This parameter should not be included in the hash calculation.
To prevent students and teachers from logging in outside of your Remote Authentication URL, System Administrators can enable a permission to Ensure user logs in using external authentication provider.
If you encounter questions or issues while setting up the SSO script for your school or organization, submit a ticket to the Help Desk describing the issue you've encountered. The dedicated support team will work with a Schoology engineer to help provide a solution for you.