Integrating Tegrity with Sakai using AAIRS Custom Connectors
How to Setup Tegrity / Sakai Integration for Authentication, Authorization and Single Sign On
This help article provides the information necessary to deploy and configure Sakai integration with Tegrity AAIRS. The following elements are covered:
- Configuration of Sakai web services to permit user-context data to pass from Sakai to Tegrity
- Configuration of Link Tool to enable SSO from Sakai to Tegrity
- Configuration of Tegrity AAIRS Sakai integration connectors to enable authentication and authorization from Sakai
Overview
To integrate Tegrity with Sakai, both services must be configured to permit integration communication, thus enabling a high quality user experience for students and instructors. The Tegrity / Sakai AAIRS-based integration ensures that Tegrity always has up to date information about users, courses, and course enrollments (including each user’s role in each course).
Firewall Exceptions
In order for the Tegrity / Sakai integration to function, please enable firewall exceptions to allow inbound TCP port 80 and 443 for Tegrity services to your institution’s Sakai instance.
- Tegrity Services FQDNs:
- aairs.tegrity.com
- mhaairs.tegrity.com
- aairs-connectors.tegrity.com
- FQDN for your institution’s Tegrity instance
Check here for more information on Firewall Requirements
Sakai Configuration
Configuration of Sakai to support Tegrity integration consists of the following:
- Web Services Configuration
- API User Creation
- Link Tool Creation
Each is described below.
Sakai Web Services Configuration
The Sakai webservices will permit Tegrity to execute API commands that request user context data such as the User’s first and last name, the courses a specific user is associated with, and what role they have in each course. To enable the Sakai web services for Tegrity, “sakai.properties” must be configured to include:
- webservices.allowlogin=true
- webservices.allow=.*
- linktool.enabled=true
Important Note: “webservices.allow=.*” is very broad, and should not be configured this way in production. This setup is only advisable for test configurations.
Sakai API User Creation
A Sakai user with the authority to run API commands is required to support the Tegrity / Sakai integration. The API user account must be provisioned within Sakai as an internal account with “superuser” status, and with the following permissions:
- roster.viewallmembers
- roster.viewenrollmentstatus
- roster.viewgroup
- roster.viewhidden
- roster.viewprofile
- site.upd
- site.viewRoster
- usermembership.view
Notes:
- Use an obvious name for the Sakai API user (e.g., “tegrityapiuser” or “apiuser”).
- “Superuser” means that the user is part of the “/site/!admin” realm and also has some minimum admin permissions.
- Tegrity recommends that a special role in the “/site/!admin” realm be created just for this required Tegrity user.
Sakai Link Tool Creation
A link to Tegrity is required in each course to enable single-sign-on (SSO) from Sakai to Tegrity. In Sakai, create a Link Tool for Tegrity. The URL field should include the following value:
http://aairs-connectors.tegrity.com/sso/sakai/default.aspx?customer=XXXX-XXXX-XXXX
or
https://aairs-connectors.tegrity.com/sso/sakai/default.aspx?customer=XXXX-XXXX-XXXX
Where the XXXX-XXXX-XXXX value is replaced with the Tegrity “Customer Number” that was provided to you by Tegrity. A Tegrity Customer Number is unique for each Tegrity instance.
Test Page
A test page has been set up to enable troubleshooting during the configuration process. To use the test page, create a Link Tool for Tegrity Test. The URL field should include the following value:
https://aairs-connectors.tegrity.com/linktooltest.v001/Default.aspx
When the Tegrity Test Link Tool is accessed, the Tegrity Test page will open and run the tests. At the bottom of the test page, you should see “verifysign:true” if the tests are successful. If the tests are not successful, then connectivity is being interrupted (for example, by firewall restrictions).
Tegrity AAIRS Configuration
Configuration of Tegrity to support Sakai integration consists of the following:
- Authentication Connector Configuration
- Authorization Connector Configuration
Each is described below.
Note: This document assumes that Sakai will be used for both authentication and authorization integration. If Sakai will be used for only authorization integration, ignore the authentication section.
Tegrity Connector Configuration
To configure the Tegrity Sakai authentication connector, perform the following:
1. Log into your Tegrity instance as an Administrator.
2. On the Admin Dashboard, select “Manage AAIRS” in the Integration section.
Tegrity Authentication Connector Configuration
The Tegrity Authentication Connector allows users to login directly with their Sakai user ID and password (instead of accessing Tegrity via Sakai Tegrity SSO link) and be authenticated by Sakai.
3. On the Manage AAIRS page, select “Edit” in the Authentication section.
4. In “Available Connectors” section, click and drag the Custom (not Sakai) connector from the right to the left and drop it into the Currently Used Connectors area. Move it to the top.
5. Fill in the fields as appropriate:
- Title: Descriptive label for this connector
- Service URL: http://aairs-connectors.tegrity.com/sakai.001/Service1.asmx
- Extended Properties field:
customer_number={XXXX-XXXX-XXXX};server={name:port};protocol={http/https};app_user={ApiUserID};app_user_password={ApiUserPassword}
Where:
- {XXXX-XXXX-XXXX} is the Customer Number for this Tegrity instance}
- {name:port} is the DNS name (or IP address) of the Sakai server and optionally the communications port
- {http/https} is the protocol used by the Sakai server
- {ApiUserID} is the user ID of the Sakai API user created above
- {ApiUserPassword} is the password for the Sakai API user identified above
6. Click the “Save” button for this Authentication connector.
Tegrity Authorization Connector Configuration
The Tegrity Authorization Connector allows Tegrity to query Sakai for each user’s course enrollments and course role based on the user’s Sakai user ID.
7. On the Manage AAIRS page, select “Edit” in the Authorization section.
8. In “Available Connectors” section, click and drag the Custom (not Sakai) connector from the right to the left and drop it into the Currently Used Connectors area. Move it to the top.
9. Fill in the fields as appropriate:
- Title: Descriptive label for this connector
- Service URL: https://aairs-connectors.tegrity.com/csv.000/Service1.asmx
- Extended Properties field:
data_url=https://aairs-connectors.tegrity.com/context-storage/;customer={XXXX-XXXX-XXXX}
Where: {XXXX-XXXX-XXXX} is the Customer Number for this Tegrity instance
10. Click the “Save” button for this Authorization connector.
11. Click the “Save and Continue” button at the top or the bottom of the Manage AAIRS page.
Tegrity Connector Testing
Each Sakai connector can be tested individually as follows:
On the Admin Dashboard, select “Manage AAIRS” in the Integration section.
Click “edit” in either the Authentication or Authorization section.
Click the “Test” button for the Sakai connector.
Enter the required test parameters:
- Authentiation: Login Username & Password
- Authorization: Login Username
The Login username is the user ID associated with any valid Sakai user (i.e., instructor or student).
Note: Tegrity recommends that in Sakai the following are created: test instructor user, test student user, and test course. The test users should be enrolled in the test course with the appropriate roles.
Click the “Test” button on the Test Connector window.
- If the Authentication test is successful, the test results will display the word “Success”
- If the Authorization test is successful, the test results will display the course and enrollment information for each user in XML format.
Updated: May 2015