How to establish connection and make API calls to Brightspace (to create a user and enroll the...

Siva.Karthik.Narisetty174

How to establish connection and make API calls to Brightspace (to create a user and enroll the user to a specific course) ?
 

I have a web application that handles user authentication. Once the user is logged in, his/her eligibility for a course is checked (internal logic). If user is eligible for a course, I would like to make API call to enroll this user to the course and generate a link that can be used by the user to start course learning (without entering his/her credentials because user is already authenticated).

 

I am trying to achieve this using C# or JavaScript. I tried valance authentication (with App ID and App Key), I am able to call WhoAmI() method, but I had to enter the credentials when Valance Authentication redirected me to login page.  

 

I also tried to follow SSO documentation is Brightspace community site, but I am finding it hard to understand the process. 

 

Could you direct me to the right solution, please? I would appreciate if you could share a sample in C# or JavaScript that uses SSO authentication. 

 

 

 

 

 

Sergio.Sepúlveda3681

Is your Learning Environment acting like a Service or IdentityProvider?, you can see more here: http://docs.valence.desire2learn.com/admin/lmsauth.html, in my opinion IdentityProvider is the ideal situation, but if you have a legacy system or are implementing a SIS (Student information system) things get more complicated.

 

 

Siva.Karthik.Narisetty174

Hi Sergio,

 

I just realized the user authentication API is different from the Data API. In my case, the user authentication will be done by SSO so that user doesn't have to enter the credentials.

 

My question now is, how do I make API calls to enroll the user to a specific course (given that I have OrgUnitID, UserID and RoleID). Let's say there is a button on my portal that reads "Enroll User to Course" on clicking which an API call is made to brightspace to do the enrollment. I see from the documentation that the route is /d2l/api/lp/(version)/enrollments/ and JSON parameters are OrgUnitID, UserID and RoleID.

 

I am familiar with passing Authorization: Basic <GUID> in the request header so that request is authorized. So I tried passing Authorization: Basic Base64(userID:Password) along with the POST request header, but with no luck. I tried it in API Test tool and Fiddler as well.

 

It would be great if you could share a sample request to achieve this.

 

Regards,

Siva

 

 

 

Sergio.Sepúlveda3681

Valence API uses what is called "the three-legged system", more info about authentication process here: http://docs.valence.desire2learn.com/basic/auth.html. Look at step 11, you can see the format for API calls is like this: GET https://{service}/d2l/api/{route}/x_a={appID}&x_b={userID}&x_c={appKey}&x_d={userKey}&x_t={time}, so if you want to perform an enrollment your full endpoint url would be something like this:

POST https://www.mylms.com/d2l/api/lp/1.20/enrollments/x_a={appID}&x_b={userID}&x_c={appKey}&x_d={userKey}&x_t={time}

 

You don't build this URL manually, you should use some open source SDK (https://github.com/Brightspace?&q=sdk) to build valid endpoint, so the library build this for you. AppId/AppKey pair is given to you when you register your application in Learning Environment (using Manage Extensibility menu), and UserId/UserKey pair is given after user is logged in Learning Environment (see step 7).

 

My understanding is your are implementing a non-interactive workflow (your backend is doing enrollment on behalf of portal administrator for learners), so in this case UserId/UserKey is also needed but its expiration timeout is very long. This page describes the process: https://community.brightspace.com/s/article/API-Cookbook-Headless-Non-Interactive-Web-Service-Workflow

 

I recommend to download ApiTest tool (https://github.com/Brightspace/util-api-test-tool), run it in your computer, change trusted URL (in Manage Extensibility menu) to point to http://localhost and write some debug messages to learn more about authentication process.

 

Best regards,

Sergio

 

 

Siva.Karthik.Narisetty174

Hi Sergio,

 

Thank you for your help. I am almost there.

 

Yes, its a non-interactive workflow which will be auto-triggered to enroll the user to a course when user satisfies the eligibility check. I am using Valance SDK for .NET where I don't see a way to include UserID and User Key.

 

When I use the API test tool, the User ID and Key are auto-populated when I hit "Authenticate" after entering App ID , Key. But from web application, I can create the App Context by passing App ID, Key.

 

var appFactory = new D2LAppContextFactory();

m_valenceAppContext = appFactory.Create(m_appId, m_appKey);

 

Then generate URL For authentication:

 

var returnUrl = Url.Action("AuthReturn", null, null, Request.Url.Scheme);

var authUrl = m_valenceAppContext.CreateUrlForAuthentication(m_valenceHost, new Uri(returnUrl));

 

But as soon as I redirect app to this authUrl ( return Redirect(authUrl) ), I am redirected to Brightspace login page. If I enter my credentials correctly, user context is created and then the API call is success.

 

Am I missing anything while generating the URL for authentication ? like passing the User ID and Key?

 

Regards,

Siva Karthik Narisetty

Sergio.Sepúlveda3681

Hi Siva,

I'have looked into C# SDK, and you can either build UserContext by:

 

1)Using full redirect URL given to your application in step 7 of autenthication workflow (http://docs.valence.desire2learn.com/basic/auth.html), the method is this: https://github.com/Brightspace/valence-sdk-dotnet/blob/master/lib/D2L.Extensibility.AuthSdk/Impl/D2LAppContext.cs#L17

 

2) Or, by extranctring x_a and x_b (UserId and UserKey respectively) by yourself from the full redirect URL and calling this method: https://github.com/Brightspace/valence-sdk-dotnet/blob/master/lib/D2L.Extensibility.AuthSdk/Impl/D2LAppContext.cs#L29. This method is also useful if you already have acquired UserId and UserKey previously and don't want you application perform authentication cycle again, for instance, at starting time. It's also useful if you authenticate using ApiTest tool and just want your application use this credential set (appId/Key and userId/Key) like they where "multi compound" Json WebToken . Take in account expiration parameter (d2l.Security.Api.TokenTimeout) for production operation.

 

Best regards,

Sergio

 

 

 

 

Siva.Karthik.Narisetty174

Hi Sergio,

 

I am able to authenticate the request by extracting User ID, Key from the API test tool and creating the app context with the second overload method of CreateUserContext(UserID, Key, Host) . I had to do some workaround by adjusting the Trusted URL property of registered the application.

 

Thanks a lot for all valuable suggestions.

 

 

Regards,

Siva

Siva.Karthik.Narisetty174

Hi Sergio,

 

The WhoAmI API call is success by following the above approach. But I am still not able to enroll a user to a course, this could probably the C# code I wrote. The response has a 400 error status with message "Request has missing or invalid parameters" eventhough I am sending the three parameters mentioned in Enrollment.

CreateEnrollmentData (http://docs.valence.desire2learn.com/res/enroll.html)

 

The same method is success if ran from API Test Tool.

 

Here is the method that enrolls user:

 

private void EnrollUserToCourse()

    {

      var client = new RestClient("https://" + LMS_URL);

      var authenticator = new ValenceAuthenticator(m_valenceUserContext);

      var request = new RestRequest(Enrollment_ROUTE ,Method.POST);

       

      request.AddParameter(new Parameter { Name = "OrgUnitId", Value = 6639, Type=ParameterType.RequestBody });

      request.AddParameter(new Parameter { Name = "UserId", Value = 203, Type = ParameterType.RequestBody });

      request.AddParameter(new Parameter { Name = "RoleId", Value = 103, Type = ParameterType.RequestBody });

 

      authenticator.Authenticate(client, request);

      var response = client.Execute(request);

    }

     

Error Message:

{"type":"http://docs.valence.desire2learn.com/res/apiprop.html#invalid-parameters","title":"Invalid Parameters","status":400,"detail":"Request has missing or invalid parameters."}

 

Am I missing any other required parameter in the Request ?

 

 

Regards,

Siva

Sergio.Sepúlveda3681

Hi Siva,

I'm not an expert nor I'm working with C# right now, but I think samples use RestSharp library, so check out this userEnrollUser() method:

https://github.com/dalejohnson/UWValence/blob/master/Valence/Biz/Valence.cs#L180

 

Project (https://github.com/dalejohnson) is also worth to look in if you are working with C#, in my opinion Valence is a low level API so for large project you'll have to build something similar or even better: colaborate with OSS.

 

Best regards,

Sergio

Siva.Karthik.Narisetty174

Hi Sergio,

 

You are awesome! this is exactly what I was looking for and your example helped me alot. I am now able to enroll user plus I can see the project structure of a C# application.

 

Thanks alot.

 

Regards,

Siva

Genny.Doss7787

I have also tried this but due to the Lenovo Error Code 1802 in my device I have been facing a lot of issues in this. Is there any other way with which I can get rid of such issues that I am facing with this?