Remote Authentication (Enterprise)

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 log in 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.
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.

Match Users

Before you match users to your school directory, make sure you have created or imported users into your school account.

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 log in using their directory credentials. This is the URL that Schoology will query when an anonymous user visits the login page and selects your school.
A 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 in to Schoology, and data will be updated or synced.

Configuring Remote Authentication in Schoology

Animation showing the click path for remote authentication configuration.

Click Tools.
Select School Management.
Click Integration on the navigation menu.
Check Enable School Remote Authentication
Enter the Remote Authentication URL. This URL should exist on your servers, from which your users will log in 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 log out.

The Authentication tab with complete field data.

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 custom 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)?

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.

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

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:

timestamp
school_id
school_uid or username
hash

You must match either the school UID or the username between Schoology and your directory.
Once the Remote Authentication URL is set up and the Server Script is up and running, email your Remote Authentication URL to your Schoology representative to complete the process.

Possible Parameters

Parameter	Description
timestamp (required)	Timestamp 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. This timestamp must be no older than 5 minutes. Find an example of the current timestamp in the Integration area of your Schoology account.
school_id (required)	School ID Your Schoology school ID can be found in the Integration area of your Schoology account.
school_uid (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 not be used for identification.
building_id	Building ID 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.
name_first	First Name If name_first is passed, the user's first name will be updated on the Schoology system.
name_first_preferred	First Name (Preferred) If name_first_preferred is passed, the user's preferred first name will be updated on the Schoology system.
name_middle	Middle Name If name_middle is passed, the user's middle name will be updated on the Schoology system.
name_last	Last Name If name_last is passed, the user's last name will be updated on the Schoology system.
mail	Email 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 the Return URL.
username (required, see description)	Username 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. 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.
role_id	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.
hash (required)	Hash The hash is used to ensure that the information passed to Schoology is not tampered with or modified. Use the hash, SHA256, with any information that you send in the order specified by the following table. In order for Schoology to determine that the hash SHA256 is used, include the $signature_method regardless of the script language used. The following is an example in PHP: <?php $signature_method = "sha256"; $hash_msg = $private_token . $timestamp . $school_id . $school_uid . $name_first; $hash_msg .= $name_first_preferred . $name_middle . $name_last . $mail . $signature_method; $hash = hash($signature_method, $hash_msg); ?> where `$private_token` is the private token defined on the remote authentication configuration page. Your `$hash_msg` should look something like this (no variable names included): XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXJohnSmithjsmith@example.com Any information you are not passing should be omitted from the hash.

Other Parameters

Parameter

Description

destination

Login Destination
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.

$url = 'https://customdomain.acme.com/login/remote/?...&destination=courses'

Or

$url ='https://subdomain.schoology.com/login/remote/?...&destination=courses'

This parameter should not be included in the hash calculation.

Best Practices

To prevent students and teachers from logging in outside of your Remote Authentication URL, System Administrators can enable permission to Ensure user logs in using an external authentication provider.

Technical Support

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.