The Aeries API is a web-based, REST API system. The end-points for the API are documented in the knowledge base . This article focuses on the methods for authorized 3rd party vendors to directly point their users to Aeries, commonly called a "Single Sign On" solution. This is an incredibly powerful feature and needs to be appropriately secured in your system.


The security implications of this feature can not be understated. You need to critically evaluate the security and safety measures you put in place around this process before you release it to customers. A critical part of this is to not allow a user to input their own Aeries Username. If allowed to do so, they could change it to "admin" and then SSO into that account. Not good. Instead, ensure that the Aeries Username is something that only a trusted system admin has access to update.


This article is intended for use by vendors wishing to interface with the Aeries API. Interfacing with the Aeries SSO process does not in any way act as an endorsement by Aeries Software, Inc. of a product. 3rd Party Products are responsible for accurate and secure use of the Aeries SSO process.


Things To Know Before You Begin

  • Read the Aeries API Documentation document before you read this article.
  • Join the Interfacing With Aeries Google Group for updates and information about the Aeries API


The Certificate and Security Permissions

Unless you are an "Aeries Software Elite Partner"(1) and have a certificate issued directly from Aeries Software, each district will issue you a certificate that is unique for that district.


A "certificate" for purposes of interacting with the Aeries API is a 32-character string made up of the numbers 0–9 and the lowercase letters a–f.


When a district creates a certificate for a vendor, they can grant access to certain APIs and restrict access to others. It would be prudent to document the security areas that you need access to and relay that information to your customers.


It is VERY important to NEVER share or expose your district-issued certificate to end users. That includes being output to the client in Javascript or HTML. All uses of the certificate should be from your server to the district's Aeries server.



Your certificate is case-sensitive!


(1) "Aeries Software Elite Partners" are companies that have formal business relationships with Aeries Software that can involve co-marketing and sales campaigns as well as financial relationships.


Building a Request

The Aeries API is a REST API. Most end points use GET requests, and some also support POST, PUT, and DELETE. The SSO pre-authorization request described below uses GET.


Request Header

You will use the Request Header to tell the Aeries API what format you want the response (JSON or XML) and also what your certificate is.


For the response format, include the following:

XML

Accept: text/xml, text/html, application/xhtml+xml, */*


JSON

Accept: application/json, text/html, application/xhtml+xml, */*


To give the system your certificate with each request:

AERIES-CERT: [certificate here]


The certificate is case sensitive!


How to Interface With the Aeries Single-Sign-On Process

The current Aeries SSO process only works for Teachers and Staff using the Aeries system. It currently does not work for students or parents.


In your system, you will need to create some sort of button or link that triggers the following actions when the user clicks it:


Generate a random character string or GUID. This is the Temporary Authentication Token for this transaction. Next, you will take that Temporary Authentication Token and Pre-Authorize it. Generate an HTTP(s) request to the district's instance of Aeries using the following format/example:


https://aeries.mydistrict.org/api/security/SSO/Init/{UserName}/{TemporaryAuthenticationToken}

Parameters:
UserName - Aeries User Name you will SSO into.
TemporaryAuthenticationToken - the locally generated Temporary Authentication Token.

You will need to URL Encode this if the string contains characters like a dash.

Note: Don't forget the "AERIES-CERT" value in the request header!



If successful, the request will return a String value looking like this:


XML: <string xmlns="http://schemas.microsoft.com/2003/10/Serialization/">Success</string>

or

JSON: "Success"


If unsuccessful, the request still returns HTTP status 200 in most cases, with one of these strings instead of "Success": "Error - Invalid UserName", "Error - No UserName Provided", or "Error - Invalid Aeries Connections Configuration". Check for the exact value "Success" rather than relying on the status code. A 401 error is returned only if your certificate does not have the required permission, or if the request is made from a browser session that is already logged in to Aeries.


You may want to log any errors, but from the end user's perspective, you probably want to continue on to the next step no matter what is returned in the Pre-Authorization Step.


The Temporary Authentication Token can be used only once; it is cleared when the user logs in. If you pre-authorize the same user again before they log in, the new token replaces the previous one. SSO always connects to the district’s default (current) school year database.


Now direct the user to the "LoginDirect.aspx" page in Aeries. This can be done using a new browser window/tab. Caution: If you try to use JavaScript to open a new window but that JavaScript wasn't specifically run from a user's action (click), then iPads and some browsers may reject the JavaScript command to open a new window.


https://aeries.mydistrict.org/LoginDirect.aspx?AuthToken={TemporaryAuthenticationToken}&school={SchoolCode}

Parameters:
TemporaryAuthenticationToken - the above mentioned Temporary Authentication Token.
SchoolCode (Optional) - can be the Aeries School Code, the State-Defined County-District-School Code (14 digits), the State-Defined District-School Code (12 digits), or the State-Defined School Code (7 digits).

If "school" is not passed or the value passed is not valid for the user, then the user will be presented a screen to select a school to log in to. Page (Optional) - an Aeries page to open after the user logs in, added to the URL as &Page={PageName}.


Districts will also need to grant permissions inside Aeries to users who can be "SSO-ed". This is done using the Aeries Security screens, and the security area called "Single-Sign-On from 3rd Party Systems." Each user must have Read permission on that security area; otherwise they are logged out and returned to the login page. Also, the system admin who generates your certificate must give your certificate Read permission on "Single Sign On (from the 3rd party system)" on the API Security page.