Originally posted on 6/11/2014 on the Valence Developer Blog by Sarah-Beth Bianchi.
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 lms.valence.desire2learn.com 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 forums. 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 Brightspace GitHub org.