Keytool Update: Whitelisting is here – Find out what it means to you

Authentication is one of the first tasks a developer needs to understand when using the Valence development platform. The workflow looks something like this:

  1. Register an app with Keytool to receive an active App ID\Key pair.
  2. Make the App ID and Key values available to your app, likely via one of the SDKs offered to streamline this process.
  3. Use that SDK to request User ID\Key pair from the LMS. The LMS sends the User ID and Signature back to the app via the x_a and x_b parameters, and uses the x_target parameter as the destination address.
  4. Use the user context to sign API calls made against the target LMS by your app.

Whitelisting adds an extra layer of security to the process:

  1. Register an app with Keytool – specifying your Trusted URL, which will be whitelisted to receive the User ID\Key pair on authentication - to receive an active App ID\Key pair.
  2. Make the App ID and Key values available to your app, likely via one of the SDKs offered to streamline this process.
  3. Use that SDK to request User ID\Key pair from the LMS. The LMS sends the User ID and Signature back to the app via the x_a and x_b parameters, and uses the x_target parameter as the destination address. Before sending back those tokens, the LMS will verify that the x_target value matches the Trusted URL specified. If they don’t match, the tokens will not be returned to your app.
  4. Use the user context to sign API calls made against the target LMS by your app.

Screenshot showing Trusted URL field.

Why are we adding this feature?

The whitelisting feature adds an extra layer of security to apps built to use Valence Learning Framework APIs. It ensures that User ID\Key pairs can only be sent to the pre-configured target location, and cannot be redirected to an unsecured location. The first stage in the rollout of that feature is adding the Trusted URL field to the Keytool app registration request form. The second stage of the rollout of the feature involves updating the Learning Environment to validate that the x_target passed by the app matches the Trusted URL. Learning Environment version 10.4.3 is expected to be the first version of the LMS to support this functionality.

How do I determine my Trusted URL?

The Trusted URL is simply a URL in your infrastructure that you will use to receive User ID\Key pairs. The x_target parameter that you append to your API calls must match this value in order for authentication to succeed. So you should have a good idea of where this endpoint will be at the time you register the app in Keytool, since the Trusted URL is now a required field in the app registration request form. Currently you cannot update this value once it’s specified, so be sure to verify the Trusted URL before registering your app.

Will my existing Apps continue to work without a Trusted URL?

For the time being, existing apps with an unspecified Trusted URL will continue to function. In the future, you will have an opportunity to update the Trusted URL value to enable whitelisting functionality.

Does this feature have anything to do with the new app self-registration process being previewed at FUSION?

At FUSION, D2L previewed new functionality being added to the Manage Extensibility administration tool in the Learning Environment. The new feature enables an LMS Administrator with sufficient privileges to register an app directly in the LMS, without needing to access Keytool or wait for the approval process. This feature also allows an administrator to edit some of the properties of the apps they have already registered – such as app name or version.

We are delivering the new whitelisting functionality along with this new self-registration functionality. Stay tuned for another blog post detailing that functionality and how it will impact the app registration process.

Screenshot of app registration form in the LMS.

Known Issue with Google Authentication and Keytool

As part of this update to Keytool, we’ve implemented a newer version of the Google authentication mechanism to replace the deprecated version that was previously in place. The new version of the authentication mechanism may cause the list of Application Records to appear empty when you click the View Registered Applications link. All registered apps continue to work and are stored in the database securely.

If your list appears empty when it shouldn’t, contact us via email and provide the following details:

  • The email address that you use to log in to Keytool.
  • The email address that appears in the top right corner of the Keytool interface after you log in. It should be different than the address you used to log in.

Tell us what you think!

Do you have questions or feedback about the new whitelisting feature? Join us in the ValenceUsers forum to share your thoughts with fellow community members and D2L staff.

Have you seen? Have you heard? New Brightspace Community site!

Members of the Valence Developer Community (that’s you) may be interested to know that there’s a new Brightspace Community site. The site is a gathering place for D2L clients, partners, staff – and developers, too – to access resources, share ideas and exchange information on Brightspace and other D2L products and services. Most of the resources are available for public access – which means there’s no need to log in to access product documentation, reply to discussion forums or view self-directed training videos.

Members who create an account on the site gain extra features – like the ability to initiate forum threads and create a member profile to start connecting with other members. You can check out the latest Community Updates blog post for an overview of those features and benefits.

What does this mean for the Developer Community?

The existing community resources will remain as-is. This includes this blog, the ValenceUsers forum, GitHub repos, and the Valence project site.

In the next several months, we’ll be working on a transition plan to bring together these disparate sites in a central location in the new Brightspace Community site. We’ll be sure to give ample notice of any changes – making announcements on all the related sites and by direct email where possible. We intend to provide the easiest transition process possible for Developer Community members. The end goal is to have a unified experience within the larger community site.

What should I do in the meantime?

Keep doing what you’re doing in the Developer Community – post to the ValenceUsers forum, read this blog, and access the Valence project site for documentation and links to other resources.

Join the new Brightspace Community site to access other product and community resources and start connecting with your peers.

Become a member of the Brightspace Community site to discover and connect with D2L clients, partners, users and developers.

If you have any questions or feedback about the current Developer Community resources or the transition plan, start a thread over on the ValenceUsers forum.

ICYMI: FUSION and the D2L Executive Platform Panel

It’s been quiet here on the Valence Developer blog these past few weeks, but there has certainly been a lot of activity within the Valence Developer Community. Let’s get caught up.

The key rallying point for the community this summer was FUSION – D2L’s Global User’s Conference. As we’ve shared in previous blog posts, this year’s conference boasted more extensibility and development-focused content than ever before, mostly centered in the Extensibility Lab. With this expanded developer programming, we saw a significant increase in the number of developers and people in related roles who registered to attend FUSION. This year we met with more than 60 technical folks through breakout sessions, our ever-popular Open Q&A sessions, the new Extensibility Demos event, and the first D2L Executive Platform Panel.

If you weren’t able to attend FUSION, you can get a taste of the experience by watching a recording of the D2L Executive Platform Panel hosted by Laura Brick and (yours truly) Sarah-Beth Bianchi. This panel features John Baker, Nick Oddson, Brian Cepuran and Paul Janzen addressing the topics that have been on the minds of community members since last year’s event – including strategy and roadmap questions – plus a few specific questions from the audience.

Paul Janzen, Brian Cepuran, Nick Oddson at the D2L Executive Platform Panel in the Extensibility Lab at FUSION.

Paul Janzen, Brian Cepuran, Nick Oddson at the D2L Executive Platform Panel in the Extensibility Lab at FUSION.

The activity generated from FUSION has continued in the ValenceUsers forum. We’ve seen new members, more peer support, and many great questions being asked and answered since the conference. Join the forums to start following and participating in those conversations and building on the expertise being shared.

You can also use the forum to share your feedback about your experience at FUSION, or to share your insights into why you might not have attended this year’s conference. Planning for next year’s conference is already underway, so we want to hear from you so that we can plan an event that will be attractive and valuable for community members.

API Versions and You

As D2L moves towards continuous release for its Integrated Learning Platform, the lifecycle for legacy versions of the platform becomes more explicit, and this has a concrete effect on the versions you will be able to use of the Valence Learning Framework API. This blog post provides a simple explanation for what versions of the API will be supported, to what extent, and when that support will end. You can use this information to plan your transition from one version of the Learning Framework API to another.

How the API lifecycle works

To help you understand how the API lifecycle works, it will be good to remember that the API contract provided by the release of a product component is a feature of that release. That is, when we released LE 9.4.1, the LE v1.0 APIs were a feature directly tied to that platform. The support and lifespan of that API feature, then, is directly tied to the support and lifespan of the product component that introduced it.

End of maintenance and deprecation

When the version of a product component enters a time when it gets reduced support, when it reaches “end of maintenance”, it is no longer being actively maintained by D2L. Software defects or other product related issues are not investigated or resolved. No more service packs will be released for that version of the product component.

This also applies to the API contract feature introduced with that product component. When the API contract feature reaches end of maintenance, it becomes deprecated:

  • The APIs in that contract version won’t receive prioritized support or attention by D2L: we may perform maintenance on the API routes, especially in response to critical or security-related issues, but these will get evaluated on a case-by-case basis, and we make no commitment to do the maintenance.
  • You should now put a priority on planning the transition of all your work off the deprecated API contract.

End of support and obsolescence

When the version of a product component enters a time when it gets no support at all, when it reaches “end of support”, D2L will no longer provide support services for the product compoment.

This also applies to the API contract feature introduced with that product component. When the API contract feature reaches end of support, it becomes obsolete:

  • The APIs in that contract version are eligible to have their access entirely removed from the back-end service of all in-market versions of the product component.

That point has an important implication: because the LE v1.0 API introduced on LE 9.4.1 and provided on that platform must remain the same as the LE v1.0 API also supported on LE 10.3.0, when D2L can’t make changes to the LE v1.0 API on LE v9.4.1, the consequence of that is that D2L can’t make changes to that API version anywhere.

What the next ten months looks like

Because of the transition to the continuous release model, the traditional timelines for the lifecycle of D2L’s existing in-market platforms has become accelerated. Here are the important dates you need to know:


As of this moment, both v9.4.1 and v10.0.0 of our Learning Suite are out of maintenance. All other more recent in-market releases are currently receiving full support.

That means that all the API contracts introduced by those platforms are currently deprecated. The principal contracts in question are:

  • D2LWS
  • LE v1.0, v1.1
  • LP v1.0, v1.1
  • EP v2.0, v2.1
  • LR v1.0

August 31, 2014

On August 31 of 2014, two sets of things will happen:

Firstly, v9.4.1 and v10.0.0 of our Learning Suite are out of support. This means that all the API contracts listed in the previous section move fromdeprecated to obsolete, and could get removed from all in-market releases at any time.

Secondly, v10.1.0 and v10.2.0 of our Learning Suite are out of maintenance. This means that all the API contracts that they introduced will become deprecated. The principle contracts in question there are:

  • LE v1.2, v1.3
  • LP v1.2, v1.3
  • EP v2.2, v2.3

January 4, 2015

On January 4 of 2015, the v10.1.0 and v10.2.0 versions of our Learning Suite will pass out of support. At this point, all the API contracts listed in the previous sections will become obsolete.

What this means to you

You should be planning now to move, within the next half a year, from any of these legacy API contracts up to the API contracts introduced with at leastthe v10.3.0 version of the Learning Suite.

Luckily this should not be onerous for you, thanks to D2L’s careful policies around API evolution.

API contracts strive to be supersets. Each successive API contract included, as much as possible, all the API calls from the previously released API contracts. This means that for nearly all your API calls in your integration, all you’ll need to do is increment the API version number in the call to the latest ones provided by your back-end service, and do minimal testing to look for regressions.

API contracts strive to be backwards compatible. All the Learning Framework API contracts released to this point have been minor releases and in nearly all cases have been fully backwards compatible with previous contract versions. Again, you can safely use the latest APIs provided by your back-end service, and do minimal testing to look for regressions.

There are a quite small number of APIs where fixes or improvements have introduced some backward incompatibility; however, even in these cases, the changes have been minimal. You can effectively prepare for your transition.

The Road to FUSION: Extensibility Events to Plan Your Schedule Around

If you haven’t already filled up your FUSION dance card – and even if you have – here are two sessions you’ll want to plan your schedule around.

Extensibility Demos – Tuesday @ 1:30pm – Extensibility Lab

Have you ever wondered what your peers are doing with the Valence Learning Framework APIs, LTI or customization projects at their own institutions? Do you want to pick the brains of folks who have created and used unique tools to address some of the same challenges that you’re facing? Come to this open house event to view demos, learn about the design, development and implementation process behind each solution, and get a sneak peek at the features D2L is working on to make this process even smoother in the future.

D2L Executive Platform Panel – Wednesday @ 8am – Extensibility Lab

Don’t stay out too late after the social event at the Country Music Hall of Fame on Tuesday night. You’re going to want to be in the Extensibility Lab bright and early to join CEO John Baker, VP of Product Development Nick Oddson, and Senior Director responsible for the Partners Program Mike Gruber. Moderated by Laura Brick and yours truly, these executives will address the extensibility strategy and the vision driving the development platform. Whether you’re a technology decision maker, a developer, or just curious about the D2L platform landscape, this session is a unique opportunity to hear from D2L Senior Leadership on topics that matter to you. Bring your questions to this session for an open Q&A period at the end of the panel presentation.


The Road to FUSION: D2L Partners

An important part of the extensibility of the Desire2Learn Integrated Learning Platform is the ability to integrate with wide range of solutions available through the Partner Network. At FUSION, many of these Partners will be on hand to demonstrate their solutions and meet with D2L clients – whether it be in the Solutions Central hall or through Partner-led breakout sessions. Arie Sowers of Respondus describes one such session below.

What is your name, role and institution?

Arie Sowers, Senior Product Specialist, Respondus

What is the title of your session?

Protecting the Integrity of Online Tests: LockDown Browser & Respondus Monitor

What is the main focus of your session?

The session focuses on the topics of preventing cheating and ensuring student identity in online tests within Desire2Learn. We provide an overview and live demonstration of LockDown Browser and Respondus Monitor, both of which integrate with Desire2Learn.

Who should attend your session, and how can they expect to benefit from it?

Intermediate to advanced Desire2Learn users or administrators, as well as faculty interested in deterring cheating. They will see a demo of a cost-effective tool that integrates seamlessly with Desire2Learn, learn how it can work with their programs, andhear tips and best practices. Attendees will also hear first-hand from a current user about how Respondus Monitor and LockDown Browser provide a solution for online exam integrity.

What are you most looking forward to about FUSION 2014?

We always enjoy having the chance to connect with our Desire2Learn clients.  And, it is always a great opportunity to meet Desire2Learn users who are new to Respondus.

Client side sample for authentication workflow

The Challenge

The authentication model for the Valence Learning Framework APIs requires a user to log in to the Learning Environment via a browser session. This is a smooth workflow when building a web application, allowing the user to be redirected to the LMS login screen and then back into your app in quick succession. However, if you are building a native application that doesn’t run in a browser, the workflow can feel disjointed and the process for securely retrieving the user tokens can be tricky. Getting your native app to kick off a browser session and then bring the user back to the app following authentication is an important problem to solve.

The Solution

The Client Side sample enables a native app to launch a web session, confirm successful user authentication, pass back the necessary user tokens to the app, and close off the browser session – including closing the tab on supported browsers. When added to your native app, this code shepherd’s the user through the context-switching necessary for authentication to minimize disruption of the user experience.

The Details

When your application comes to a place where user authentication is required – for example, if the app needs to pull new content from a course – the Client Side sample kicks in. The sample opens a browser session to take the user to the LMS login screen and also launches an HTTP Server to listen for the redirect that takes place after authentication is successful. Once the user logs in successfully, the HTTP Server receives the user tokens and passes them back to your application. The sample also sends a call to close the browser tab it opened. Some browsers – like Firefox – don’t allow themselves to be closed via javascript. In that case, the browser displays a message telling the user that it’s safe to close the browser tab. Once the user completes this authentication process, they return to the app and can move forward in an authenticated state.

The Sample

The sample provided is written in C#. To get it working in your environment, you’ll need to configure a few variables.

  • On line 66 of Programs.cs, update the pointer to the LMS. In the sample, it is set to which is the sample server used by the API Test Tool online sample.
  • On lines 7 and 8 of App.config, update the appId and appKey values to match the values for an app that you register. The values in the sample are the same as the ones found in the API Test Tool, and will only work against the sample LMS associated with that tool.
  • On line 24 of Program.cs, you have the option to change the port the HTTP server uses. As this HTTP Server is running on the local machine,  you won’t need to change the value unless that port is allocated to another process.

Your turn

Give this sample a try in your own client side app and share your feedback in the ValenceUsers forum. If you choose to port this sample to another language, consider contributing it back to the Valence Community so that we can host it in the Desire2Learn-Valence GitHub org.


Get every new post delivered to your Inbox.

Join 39 other followers