Key Based authentication is an alternate method for authentication within CampusLink based on Symmetric Keys. This method helps you to avoid the challenge of maintaining the API Username and Password entered in SyRegistry when your Institution uses Active Directory (AD) or Azure Active Directory (AAD) based authentication.
Prior to Anthology Student version 22.0, many calls from Student Web Client, Portal and Workflow Activities relied upon a valid staff account to make CampusLink API calls. In AD and AAD environment, this staff account must exist in either Active Directory or in Azure Active Directory. When such an account is stored for making CampusLink API calls, it creates few issues related to security and maintenance.
Thus, we are providing an alternate and more secure option in the form of Application API keys. The staff credentials based method of getting the token (supplying UserName and Password in the request) for CampusLink Authentication service’s GetAuthorizationToken web method will continue to work. However, it is recommended that all existing integrations that use CampusLink Authentication Service calls, especially those that use the user identity stored in SyRegistry for regkeys APIUserName and APIUserPassword, be refactored to use key based security instead as the keys, are deprecated and will be removed in a future release.
In Anthology Student version 23.3, to complete the transition to the use of application keys to manage API access, Anthology has removed the use of APIUSER as a username in the system. To facilitate this change, Anthology has replaced the existing APIUSER with a new secure username apiadmin@anthology.local. This name is, by default, part of the System Admin staff group but institutions may need to update workflows and task or document policies for this replacement secure user as they move to this release.
Add Application API Keys for Third-Party Application Integration
To allow the Key Based authentication for third-party application integrations using CampusLink APIs, the application keys must be generated and stored using the new settings menu, Application API Keys (Select the Settings tile > locate System in the tree > select Application API Keys.) in the Standard Interface.
Application API Keys menu is added to help staff members to generate or regenerate and store the API keys for the third-party application that wants to use CampusLink APIs. The integrating application is expected to use the Calling application and Application key while calling the Authentication webservice’s GetAuthorizationToken web method, setting IsKeyBasedSecurity to true. A token is returned from this call as before and this token be used for any down the line CampusLink API calls.
The identity assigned to the generated token is the user assigned to the key in Student (SyApplicationKey.AssociatedStaffId). Any audit records generated by the API calls with this token, will use this user’s information and any API authorization checks will also be done against this user. So, ensure that this staff member has the necessary permissions and staff group memberships.
Changes on Authentication Service
In Key Based authentication, CampusLink’s GetAuthorizationToken web method uses three new field.
| Name | Required | Type | Description |
|---|---|---|---|
| IsKeyBasedSecurity | No | Boolean | Set to true if you are using the key based security instead of supplying username/password |
| AppKey | No | String | Plain text value of application key. Conditionally required when the IsKeyBasedSecurity = True |
| CallingAppName | No | String | Name of the calling application. This needs to exactly match the string specified in the SyApplicationKey table (for example, Anthology_Portal). Conditionally required when the IsKeyBasedSecurity = True |
The API validates whether the key passed in against the calling App and then generates a token based on the staff ID present in the SyApplicationKey table.
Sample Code to Get the Application Key for Your Product
string portalApplicationKey = _applicationKeyManager.GetApplicationKey(new GetApplicationKeyArgs { CallingApplicationName = "Vendor1_Attendance_Integration", ConnectionStringName = "dbConnection" });
This will retrieve or if this is the first call, it will generate a key for your product, encrypt and save to the SyApplicationKey table and retrieve the decrypted key. You will pass on what is in portalApplicationKey to CampusLink.
Ensure you do not log the App key in your application.
You do not have to set the Username and Password fields in the Request, if you set IsKeyBasedSecurity to true. Instead you will pass in the AppKey and CallingAppName as specified above.
The staff member for your App will be a system user who is assigned to the record (SyApplicationKey.AssociatedStaffId). A token is returned and the identity assigned to it will be this system staff user. (Example: PortalApiUser@anthology.local)
You can use this token while making other CampusLink calls in your application.
Key Storage
A new table called SyApplicationKey is added which holds the application API keys generated.
The key generated is encrypted and is saved to the database table. The application key unique is to each calling application.
Records will be inserted (with ApplicationKey value = null) into the above table during install time of Anthology Student for 22.0 installation. There will be 1 record per product. The AddedBySystem bit will be set for these initial records added through the script.This will be done for all the Anthology products using the Campuslink APIs internally.
The script will also insert system users with the necessary permissions for all the internal products that may use this new key based authentication. The corresponding LinkedStaffId will be updated. This will be the identity that will be used for the calls, so that the API user has the necessary authorizations. Script will also make the user a part of the necessary staff groups so that the user has admin permissions.
For example, LinkedStaffId 24 for portal above is a user with code PortalApiUser@anthology.local.
These systaff records will have SystemCode = 1, indicating that they are system generated users.
