Org login path¶

The OrgLoginPath configuration DOME variable points at a URL that the LMS should use as the entry point for a resource to handle user authentication. With both of the simple authentication scenarios, if the user has not yet authenticated with the Learning Service then, when the user tries to open any URL provided by the Learning Service, it redirects to the URL specified in the OrgLoginPath. Likewise, when the user explicitly logs in, the service redirects the browser to the OrgLoginPath URL.

In the simple authentication scenarios, the org login path indicates a URL provided by the service itself that acts as the user-authentication entry point. By default, the D2L Brightspace integrated learning platform gets deployed with a simple login page template that serves as the index page for the service’s domain, and has the OrgLoginPath set to point to the root of your service’s domain (that is, https://devcop.brightspace.com/ for our Developer test instance or in your case, whatever the domain root is for your service).

This default login page template will generate and pass to the client’s browser a page containing a simple form to collect the user’s name and password and POST them to service’s internal web UI login route (/d2l/lp/auth/login/login.d2l). Also, by default, the login page template contains code to preserve the page the user was trying to reach when the service redirected the browser to the org login path. Deep-linkable pages in the service have code to attach their URL as a target to any redirection to the org login path; third-party links to the org login path should do the same if they want users to be directed back to them after authentication.

Accounting for deep-linking¶

If the LMS has deep-linking turned off, then it will not respect the target query parameter on any request to POST to the service’s login API route. As a result, when the service redirects a not-yet-authenticated user to the login page, the service will lose any context about where the user wanted to go originally. When the user has authenticated, the service will redirect the browser back to the user’s default home page after the user has successfully authenticated, regardless of how the user came to the org login path in the first place.

If the LMS has deep-linking turned on, then the service’s login API route will respect the target query parameter passed to it upon POST. As a result, when the service redirects a not-yet-authenticated user to the org login path, if the redirection carries a target query parameter, the service will redirect the browser back to that target after the user has successfully authenticated. If redirection to the org login path does not carry a target query parameter, the service will redirect the browser back to the user’s default home page (exactly as if the LMS had deep-linking turned off).

Managing your site’s login page template¶

The ASP page that provides the template for your Learning Service’s login page lives by default at /portal/<org_short_name>/index.asp. You can change the contents of that file to customize your site’s login page.

However, In order for your org login page to support deep-linking, it must properly handle the target query parameter that deep-linkable pages will attach to the redirection to the org login path.

<%
' See if login failed '
dim failed
failed = Request.QueryString("failed")

dim target
target = Request.QueryString("target")

dim loginUrl
loginUrl = "/d2l/lp/auth/login/login.d2l"

if (target <> "") then
  loginUrl = loginUrl & "?TARGET=" & server.URLEncode(target)
end if
%>

In particular, your login page needs to pass that target on to the resource that actually handles user authentication so that, when finished, that resource will either direct the flow to the user’s original target or pass that target on to the next link in the login chain.

How this affects the Brightspace API¶

As part of the legacy three-legged authentication system, the first step involves the calling the Brightspace API route, GET /d2l/auth/api/token and providing it with an x_target query parameter to tell the Learning Service where it should redirect the flow back to when the user has finished authenticating (and the service has tokens to hand back to the API caller). The handler for the API route will, if the user hasn’t yet authenticated, redirect through the org login path with a target parameter that captures both the Learning Service’s route tasked with passing back user tokens, and the original x_target URL:

https://learnserv.myOrg.edu/?target=%2Fd2l%2Fauth%2Fapi%2Ftoken
%3Fx_target%3D%252Fhttp%253A%252F%252FclientURLHandler.com%252Fprocess%252FuserTokens

Note that now the doubly-embedded x_target must have another level of url-encoding, so for example the url-encoded slash character (/) %2F becomes %252F.

Thus, if we assume these simple authentication scenarios (where the org login path passes through the Learning Service site’s login page template), this means that the service must preserve and carry forward the x_target parameter (originally provided to the /d2l/auth/api/token API call) through the entire authentication process:

• Because the Brightspace API depends upon deep-linking, to support applications using the API, the service must have deep-linking turned on

• Because the redirection through org login path (to authenticate the Learning Service user) passes through the login page template, that template must curate and pass forward the target parameter

Using SAML or CAS as an authentication provider¶

When the Learning Service depends on SAML or CAS to do user authentication, a typical setup configures the OrgLoginPath to point to the respective authentication method (/d2l/lp/auth/saml/login for SAML, /d2l/custom/cas for CAS), and configures the d2l.Tools.Login.LoginPageType config variable to point to External Redirect.

The active authentication provider’s configuration determines the actual URL it redirects to. For example, when using CAS, you specify the CAS Host Url here: <instance root>/d2l/custom/config/<org id>/cd56d1e9-ea4a-4242-929d-76129739ee8f

Using Shibboleth as an authentication provider¶

When the Learning Service depends on Shibboleth to do user authentication, a typical setup employs a login page for the Learning Service (just as in the simple scenarios previously described), sets the OrgLoginPath to point to this login page, but provides a mechanism from within that login page to direct to the third-party authentication service, rather than the /d2l/lp/auth/login/login.d2l route. For example, here’s a link that might appear on the Learning Service login page to direct a user off to the authentication service:

<p>To login with your OrganizationWide credentials, click <br/>
   <!-- line breaks in the URL to help readability, only -->
   <a href="https://learnserv.myOrg.edu/shibboleth.sso/Login
            ?entityID=https://shibboleth.myOrg.edu/idp/shibboleth
            &target=https%3A%2F%2Flearnserv.myOrg.edu%2Fd2l%2FshibbolethSSO%2Flogin.d2l">
     [HERE]
   </a>
</p>

The link here directs to an outgoing SSO route provided by the Learning Service (href=”https://learnserv.myOrg.edu/shibboleth.sso/Login); this route acts as the Shibboleth Service Provider. The HREF provides the Service Provider with two bits of information:

• The location of the Identity Provider (?entityID=https://shibboleth.myOrg.edu/shibboleth) to redirect to in order to request the user be authenticated

• The target URL the Identity Provider should call back to and provide the appropriate authenticated user token information (&target=https%3A%2F%2Flearnserv.myOrg.edu%2Fd2l%2FshibbolethSSO%2Flogin.d2l); notice that this target is URL-encoded to embed it within the IDP URL (value for the entityID parameter) passed to the Service Provider.

The connection points for the Learning Service here amount to two: the resource it exposes to act as the Service Provider for authentication requests from the user, and the resource it exposes to act as the Service Provider to handle incoming authentication affirmations from the Identity Provider.

Supporting deep-linking. Notice that in this Shibboleth example, the Identity Provider receives no information about the resource at the Learning Service that the un-authenticated user was trying to reach: the only contextual information passed to the Identity Provider is the location of the callback entry point at the Service Provider.

If you want to provide that information, then you need to “double embed” a target in the callback URL; for example, here’s what an attempt to visit the home page for a course with org unit ID 8083 might look like (note how the doubly-embedded target must have the percent characters url-encoded as well):

<a href="https://learnserv.myOrg.edu/shibboleth.sso/Login
         ?entityID=https://shibboleth.myOrg.edu/idp/shibboleth
         &target=https%3A%2F%2Flearnserv.myOrg.edu%2Fd2l%2FshibbolethSSO%2Flogin.d2l
             %253Ftarget%253D%252Fd2l%252Fhome%252F8083">
     [HERE]
</a>

In order to build this dynamically, if you use the D2L Learning Service’s default template page, you’ll need to a similar approach to the one described previously in Managing your site’s login page template to help preserve the incoming user-intended target resource. You will also need some assurance that your Service Provider and the Identity Provider will curate this embedded second target through to the callback to the Service Provider so that the Learning Service can pick it up and redirect the now-authenticated user to that page.

How this affects the Brightspace API. As with the simple authentication scenario, the Brightspace API client’s first step during authentication is calling /d2l/auth/api/token?x_target=https%3A%2F%2FclientURLHandler%2Ecom%2Fprocess%2FuserTokens. The Brightspace API combines the x_target parameter into the target on the request to the org login path, as described previously in the simple authentication scenario section. This entire chain of targets will need to get captured when sent to the Identity Provider so that the Service Provider’s handler coming back from the IDP knows to redirect to the API user-token issuing route:

<a href="https://learnserv.myOrg.edu/shibboleth.sso/Login
         ?entityID=https://shibboleth.myOrg.edu/idp/shibboleth
         &target=https%3A%2F%2Flearnserv.myOrg.edu%2Fd2l%2FshibbolethSSO%2Flogin.d2l
             %253Ftarget%253D%252Fd2l%252Fauth%252Fapi%252Ftoken
             %25253Fx_target%25253Dhttp%25253A%25252F%25252FclientURLHandler.com%25252Fprocess%25252FuserTokens">
     [HERE]
</a>

Note that now the triply-embedded x_target must have yet another level of url-encoding, so for example the url-encoded slash character (/) %2F becomes %25252F.

Acting as an authentication provider¶

When another service wants to use the LMS as an authentication provider, this might occur in one of two forms.

Direct API use. Some client applications need only to identify and authenticate the Learning Service user so that they can interact with the Learning Service within the permissions context of that user. This is the standard authentication model used by the Brightspace API.

LTI. Some client applications need to support more than one Learning Service user, and have access to more context than simply the authenticated user. For these situations, the client application can use LTI®, pre-configured, so that the channel between the requester and the Learning Service is already pre-assured. LTI launches from the Learning Service get sent with contextual data, allowing the client application to recognize not only the user but a variety of other contextual data.