Brightspace’s developer platform authentication requires you to make every API request in a calling context from which the back-end service can determine
- What client application makes the call
- What logged-in user is employing the client app to make the call
In the calling context, you provide these identifications with a set of authentication tokens. To get started, you need to follow these four general steps to gather all the resources you’ll need to be able to provide those authentication tokens with each API call your app will make.
By using D2L’s Keytool service, we can provide your application with an Application ID-key pair. Your app will use its Application ID as a public “name” to uniquely identify itself to back-end LMS instances. It will use the associated Application Key to create authentication signatures on all its API requests, so that the back-end LMS instance (which also knows this Application Key) can verify that a request actually comes from your application.
See Keytool Service For Getting Application Keys for information on how to register your app to obtain an Application ID-key pair.
Every Brightspace API call happens within a calling user context, and the LMS will limit the functionality it extends to your call depending upon the permissions that user would have logged in to the LMS and using through the standard browser interface.
Accordingly, you should ensure you have an appropriate range of LMS user accounts available to you for testing.
- If your app will be used only by students, then you only need to have one or more student-role accounts to test with.
- If your app will be used by instructors, you’ll need instructor-role accounts as well.
- If your app’s functionality is special purpose or administrative in nature (perhaps as an automated server maintenance process or the like), then we recommend that you create an LMS “service” account to pair precisely with your application, and grant that service account the exact set of permissions your app will require. (Use the standard deployed user roles permission sets as guides to which permissions your app may need.)
You will need to know the username and password for all the accounts you want to test with (in order to go through the authentication process that prompts the LMS to send you back the appropriate authentication tokens for each user).
We provide SDK packages for a number of different language bindings. We have attempted to provide packages to meet several broad types of needs (compiled versus interpreted languages, server-side versus client-side, mobile versus desktop).
The foundational piece for each SDK is a small library, module, or set of classes you can use to ease the process of creating API URLs that are appropriate decorated with authentication tokens for your calling context.
As Brightspace’s developer platform is primarily an open-source effort, the community may have contributed language binding support for other languages as well.
The calling context for each API call provides five bits of information, built
over two phases. In the first phase, your application uses three tokens with a
special Brightspace API call to
request the User ID-key pair:
- The Application ID provided to you by D2L
- An Application Signature your code must generate, using the Application ID-key pair provided to you be D2L
- A timestamp your code must generate
In response to your request for a User ID-key pair, the service will first ask the user to authenticate, to confirm granting access to your application, and then provide you with a User ID-key pair for the authenticated user: this pair will be specific to your application’s request; it is not transferable to another Application ID.
The second phase consists of all other Brightspace API calls that do require a specific calling user context. In addition to the previous three tokens, your calls must now also provide:
- The User ID provided to you by the back-end LMS service in phase one
- A User Signature your code must generate, using the User ID-key pair provided to you by the back-end LMS service in phase one
If you’d like more detailed information on the end-to-end ID-key Auth process, you can read our authentication topic.
All our client library SDK packages provide you with a simple library, module, or set of classes that assist you with generating these authentication tokens: you can refer to their source code, and to their use in our companion getting started samples for more information on how the ID-key Auth process works, as well.