D2L’s Learning Management System provides a few points of administration to manage access to its extensibility features.
Note
The authentication-related information in this topic applies to Brightspace API client applications using the legacy ID-Key authorization method.
System overview¶
Extensibility to third party applications and services relies on Application ID-key pairs provided to registering third-parties, and then synchronized from a central Keytool service out to the global network of active LMS instances. The service limits the distribution of Application keys (as one level of the security system); only the third party associated with a specific key, and D2L’s own software installations, ever receive an Application ID-key. Availability of the application keys is controlled by the central Keytool service and provided to specific, registered LMS instances; therefore, each LMS organization should ensure their instance has Application Key Synchronization turned on to support extensibility for third-party applications and services.
The nearby diagram shows you the general process and overview of how application keys control access to an LMS. The lettered dots indicate the general order of the process, with events leading into the D2L Key Tool Service happening before that service’s responses.
A. When the provider of third-party app or service wants to make it available, the provider must register with the Keytool service to request an ID-key pair for the application. You should request a different ID-key pair for each “released version” of your application or service. After approval, the Keytool lets you see your new ID-key pair, so you can copy these credentials and build them into your application and use it for signing.
When the Keytool assigns an application an ID-key pair, it adds the record to its principal list, with any appropriate limiting information required (for example, most applications will only need to be operable in conjunction with a specific LMS deployment).
Note
As of Brightspace 10.3 Service Pack 13, LMS administrators can register limited apps directly through the Manage Extensibility tool in the LMS.
B. Each LMS deployment that supports extensibility to third-party applications and services must be configured upon deployment to synchronize application record data with the Keytool service. Deployments by default should have this synchronization activated.
Regularly, the Keytool service prepares and dispatches a domain-appropriate list of application records to every deployed LMS in the field. Each LMS will receive two types of application records: Universal ID-key pairs (those not limited to a single LMS domain), and the Limited ID-key pairs keys appropriate for its specific domain.
The deployed LMS will have received application records made available for administration through the Manage Extensibility tool. By default, a deployed LMS will automatically make new applications active: that is, it will allow access to the Brightspace APIs from “known” applications (those whose records appear in its active list).
C. Once an organization’s deployed LMS has a third-party’s application record in its active list, the third-party application can sign Brightspace API requests with its application key, and expect to have the LMS receive those requests, recognize that the request comes from a valid client, and take the appropriate action and send back appropriate data.
If a third-party application tries to use one of the Brightspace API routes and cannot sign the request with a key the LMS recognizes as valid and active, the LMS will reject the request.
Administration tools¶
As mentioned, when D2L deployed the LMS to your organization, the deployment will have activated synchronization between your LMS and our central Keytool service. This means that your LMS should already have a list of all the domain-appropriate application keys available for you. However, the default handling of that key list will depend upon when and how we deployed your LMS.
In either case, you would use the Manage Extensibility tool and the Config Variable settings to administer third-party application’s access to your LMS Brightspace APIs.
Note
To properly manage your LMS’s provision of Brightspace API access, you must be a user with sufficient privileges to both (a) use the Manage Extensibility tool and (b) view and make changes to your deployment’s Security settings.
Manage Extensibility tool¶
You can find the Manage Extensibility tool from your home page, in the Organization Related section of the Admin Tools widget.
The Manage Extensibility tool allows you to:
View all available applications that are deployed to your LMS, including the application’s name, version number, and publisher name.
Enable or disable applications for your LMS.
Register new applications for your LMS (as of 10.3 SP13).
An enabled application can make API requests to your LMS, provided the application signs the request with the valid App ID/Key.
To disable or enable all applications in the currently visible list. Click the Select All check box to select all the applications in the list of records. Then click the Enable or Disable buttons to quickly enable access for all known applications, or quickly turn access off for all applications.
To disable or enable one or more applications. Click the check boxes next to the application records that you want to enable/disable. Then click the Enable or Disable buttons to set their state.
To enable all applications by default. If you want to grant access to all new applications as their records get synchronized to you from the Keytool service, then you should verify your Config Variable settings (see the next section).
Note
An application will almost certainly have a different entry in the list for each released version. If you want to support an application at all, then you should strongly consider supporting all of its released versions (unless you have a specific reason not to; for example, if you know that a particular version is incompatible with the version of Learning Framework APIs supported by your LMS).
To register a new application. With Learning Suite 10.3 Service Pack 13 and later, you can register applications that are specific to your LMS (also referred to as “limited” apps). Prior to 10.3 Service Pack 13, limited apps had to be registered through the Keytool.
Click Register an App.
Complete the following fields:
Application name. The display name for the application that you want users to see when the application requests authentication.
Trusted URL. The URL that the app returns to after the user has been authenticated. This URL must match the x_target query parameter that’s used during the login process (
GET /d2l/auth/api/token). Consult with the application developer to obtain this URL.Major Version and Minor Version. The release version of the application.
Description. A short description of the purpose of the application.
Click the Enable this application check box to enable the application for the LMS.
After reading and accepting the Non-Commercial Developer Agreement, click the I accept the Non-Commercial Developer Agreement check box.
Click Register Application.
Config Variable settings¶
You can find config variables in the following location:
Admin Tools > Config Variable Browser (v10.3.0 and later)
Admin Tools > DOME > Config Variable Browser (v10.2.0 and earlier)
After you open the Config Variable Browser, go to the API variable settings inside the Security group:
All Variables > Security > Api
To automatically enable new applications as you receive their records. Your LMS can automatically make active each application as it arrives in its list. The ApplicationsAvailableAsPublished variable controls this feature. You must ensure its value is On. On some (recent) deployments, this will be turned on by default.
Note that turning this feature on only affects your LMS’ behaviour with respect to new application records that arrive. If you have records in your list that are not active, turning this feature on will not affect the state of those applications.
To manually review and manage access to all applications. You should ensure that the ApplicationsAvailableAsPublished variable has a value of Off.
Note that turning this feature off only affects your LMS’ behaviour with respect to new application records that arrive. If you have records in your list that are active, turning this feature off will not affect the state of those applications.
Troubleshooting¶
If your environment is not operating as you expect it should, you can use this section to help identify potential configuration changes.
If you require further assistance with your deployment, please contact D2L through your organization’s Approved Support Contact.
If you have development-related questions, please use the Brightspace developer support channel.
Empty key list¶
If your Manage Extensibility tool has no application records listed, then this means that your deployed LMS has not been successful in registering with the Keytool service to synchronize it’s list of applications. You should contact your deployment support contact to assist you in properly configuring your LMS instance.
Empty app login screen¶
If a third-party application is attempting to log in to your LMS, and all the client sees is a blank screen, then this likely means that that application’s record has not yet been made active within your LMS.
You should first verify with the client the precise application, publisher, and application version used.
Then, you should use the Manage Extensibility tool to verify that you have enabled (made active) the application record for that specific combination of application, publisher, and version.
Please be aware that a third-party application vendor may have released a new version of their software, and thus your client may be attempting to use an application ID/Key pair in a record that you have not yet activated. This can occur particularly if you have not configured your LMS to automatically enable new applications as you receive application records with the ApplicationsAvailableAsPublished variable.