Developer Platform (May 2017)

Keytool service for getting application keys

«  Managing Extensibility   ·  [   home  ·   reference  ·   community   ·  search   ·  index   ·  routing table   ·  scopes table   ]   ·  Managing Learning Service user authentication  »

Contents

To authenticate with the Brightspace APIs, a client application or service requires an Application ID-key pair. The Keytool service allows third-parties to register their applications to obtain Application ID-key pair credentials.

To learn about how Application ID-key pair credentials are used during the authentication process, see ID-key authentication.

When to register an app

We recommend that you request a new App ID-key pair for each separate release version of your application or service that you intend to distribute. This helps ensure that LMS administrators can control access to their services for each version of your application. This can be important if an LMS installation is providing a Learning Framework API version, or limited set of product components, that make their API fundamentally incompatible with your application.

Where to register an app

Brightspace 10.3 Service Pack 13 and later. For limited apps, the LMS administrator can directly create Application ID-key pairs using the Manage Extensibility tool within the LMS.

You must register Universal apps through the Keytool service.

Prior to Brightspace 10.3 Service Pack 13. You must register both limited and universal apps through the Keytool service.

Registering an app through the LMS

In environments running Brightspace 10.3 Service Pack 13 and later, the LMS administrator can directly create Application ID-key pairs for limited apps through the Manage Extensibility tool in the LMS.

Registering an app through the Keytool service

Before you start. To request an App ID-key pair, you must have a Google account; however, this does not need to be a Gmail account. We recommend that you create a generic account associated with your company or institution name to simplify verification. We also recommend that you use the email address of a distribution list for the account (for example, developer_team@myOrganziation.org) to make it easy for a team of people to manage the account.

Registration process. From your browser, go to the Keytool service home page, and then follow these steps:

  1. Click Sign In using Google.

    • If your browser is not currently logged in to a Google account, the browser proceeds to the Google login page. You will need to log in to the account that you want to authenticate with.
    • If your browser is currently logged in to a Google account, and you haven’t permanently associated that account with the Keytool, the browser proceeds to a Google page asking permission to build that association (either for just one time, or in a way that will be remembered). Click Accept to accept the association with the Keytool.
    • If your browser is currently logged in to a Google account, and the authentication association with the Keytool service is remembered, the browser proceeds to the Keytool page.
  2. If this is your first time logging in to the Keytool, you are prompted for Publisher Info.

    When users or administrators seek to grant access to your application, the back-end service uses the publisher information to identify the app wanting authentication.

    Organization Name. Type the name of your company or institution as it should appear to customers of your app (for example, MyCompany Inc.).

    Organization URL. The hostname for your organization (for example, http://appdevs.mycompany.com).

  3. On the Keytool homepage, click Register New Application.

  4. Complete the following fields:

    Name. The display name for your application that you want customers to see when your 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).

    Version. The display version for a release that a customer can use to

    differentiate a particular version of your application.

    Description. A short descriptive phrase that can help an LMS

    administrator determine the purpose or customary use of your application.

    Type. Specify the type of application key, either universal or limited.

    • Universal. A universal-scoped key is distributed to every public LMS installation that subscribes for updates to the application key list. Typically, D2L reserves these keys for distribution to partners that have Commercial Development Agreements in place.
    • Limited. A limited key is specific to the hostname for the LMS installation that the application will work with—the key only works within that particular domain, which is identified by the LMSID. A client developer should apply for a separate Application ID-key pair for each environment where the app will run (i.e., a development or test instance, versus a production instance).

    LMSID. Type the LMSID for the single LMS service that you want your application to work with. The LMSID value may be similar to the domain name for the LMS, but will not typically include http:// or www (it will only be the domain name itself). Consult with your LMS administrator to obtain the exact value for the LMSID.

    Commercialization. Specify the commercial nature of your application.

    You can request that the Keytool service create a commercial or non-commercial key. This value indicates whether users or institutions are charged for use of the application, which in turn determines the agreements you must enter into with D2L.

    D2L will approve your key request only after you’ve entered into the appropriate agreement. To help you get started with testing of your client application in deployment quickly, you may find it easiest to first apply for a non-commercial, limited key to use in a constrained environment. You can then later request a separate, commercial, registration for a commercially distributed version of the application.

    • Non-Commercial. You must accept the Non-Commercial Developer Agreement with D2L before you can proceed any further with your registration.
    • Commercial. You must seek to accept a Commercial Developer agreement with D2L. Please contact the partner program for some assistance in choosing a commercialization strategy for your application.
  5. Click Request Key to initiate the key request.

Getting the key to the LMS

Every deployed LMS regularly contacts the Keytool service to synchronize its list of application records. This happens once in every 24-hour period. In environments running Brightspace 10.2 and later, an LMS administrator can manually start the synchronization process at any time from the Manage Extensibility tool in the LMS.

When an LMS synchronizes with the Keytool service, the LMS receives an up-to-date list of

Note: Application records that have been deactivated (rejected) for some reason in the Keytool will at this stage be removed from all LMS environments that currently contain these records in their Manage Extensibility lists.

Reviewing your application records

You can review your list of application records by clicking View Registered Applications in the Keytool. The Application Records shows the information associated with each particular application you’ve registered, along with an indication of its status:

Pending application requests are still in the queue for processing. Until
the request is processed, the values in the ID and Key fields are not yet usable.

Approved application requests have been approved and granted. The values in the ID and Key fields will be usable once the registered application record has been synchronized to the target LMS back-end service(s). (Upon approval, the Keytool will begin synchronizing your application records to each LMS that should receive it.)

Rejected application requests have been denied. The values in the ID and Key fields are not usable. These application records will not be synchronized to any LMS, and can be removed from any LMS that currently has the record deployed to it. (That is, application records can be retroactively rejected for various reasons.)

Updating your app’s publisher info

To create or edit the organization information associated with your account, click Publisher Info. You can update the Organization Name and Organization URL associated with your account.

Note

Any updates you make to the publisher information will be reflected in newly registered applications. Applications that have already been registered will retain the previous publisher information.

«  Managing Extensibility   ·  [   home  ·   reference  ·   community   ·  search   ·  index   ·  routing table   ·  scopes table   ]   ·  Managing Learning Service user authentication  »