Authentication for CampusLink API Calls

Many calls from Anthology Student, Portal, Workflow activities, and other integrated applications rely upon a valid staff account (“APIuser”) to make CampusLink API calls. This account needs to be unique (i.e., not used for anything else). The user name and password for the account are stored in the database (SyRegistry table). The account must also exist in Active Directory (AD) or Azure Active Directory (AAD). The account details in the database and in AD/AAD need to be in sync. This can create maintenance and security issues (e.g., multifactor authentication (MFA) needs to be disabled). Therefore, the existing authentication mechanism using SyRegistry keys with user name and password will eventually be retired. For the time being, the existing logic based on a user name and password continues to work to satisfy backward compatibility requirements for integrated products.

The July 2021 releases of Anthology products introduce an alternate authentication mechanism that relies on symmetric keys. A new SyApplicationKey table stores the encrypted keys and names of the calling applications. The keys are decrypted before they are passed to the CampusLink Authentication Service.

At the time of Anthology Student 22.0 installation, a script inserts 1 record per calling application (with ApplicationKey value = NULL) into the SyApplicationKey table. The script also inserts staff users with the necessary permissions for all Anthology products that use key-based authentication and updates the corresponding AssociatedStaffId. The AssociatedStaffId is the identity that will be used for CampusLink API calls. The script makes the staff users part of the necessary staff groups to apply the necessary permissions. Institutions no longer need to manually create staff users for CampusLink API calls.

On the first CampusLink API call, the key-based authentication logic will generate a key for the product identified by the CallingApplicationName, encrypt and save the key to the SyApplicationKey table, and retrieve the decrypted key. On subsequent CampusLink API calls, the logic will retrieve the existing key and pass it on to CampusLink.

To support the key-based security, the CampusLink Authentication Service is modified by adding the following values to the in-message of the GetAuthorizationToken method:

• IsKeyBasedSecurity (bool) – set to true if using key based security instead of supplying username/password

• AppKey (string) – plain text value of app key retrieved previously (e.g., you can assign this to the variable portalApplicationKey)

• CallingAppName (string) – name of the calling application. This needs to exactly match what’s specified in the SyApplicationKey table (e.g., Anthology_Portal)

When IsKeyBasedSecurity is true and a valid AppKey is passed in, the Authentication Service validates the AppKey passed in against the CallingApplicationName and generates a token based on the AssociatedStaffId in the SyApplicationKey table. A token will be returned. Each system-generated application key will be associated with a system-generated staff user (e.g., PortalApiUser@anthology.local). This user only exists as a Staff record in the application and will not have a password or be required to be added as an AD/AAD user. As a result, this staff user will never be used to authenticate against. However, this user’s authorizations in Anthology Student are used to determine permissions for API calls that are made in the system context, using the key. The user’s Id is also used to update the database for the calls made by the client application. By default this user will have admin access. You can adjust the user’s permission based on the needs of your application.

Anthology Student 22.0 provides a form for administrators to manage the CampusLink API key information. The form is located under Settings > System > Manage Application Keys. Admin users can create a new record in the SyApplicationKey table, including generating the key. The encrypted value of the key will be stored in the ApplicationKey column. Once a new record is inserted, the plain text, decrypted key is shown in the form with a copy to clipboard option. Once the key is copied to clipboard (and shared with vendor securely), the key value is masked in the form.