Showing posts with label API. Show all posts
Showing posts with label API. Show all posts

Wednesday, May 26, 2010

Can I delegate authentication by embedding an EKP login form directly in my portal?

Portals developed using the EKP Portal Toolkit typically use a process called delegated authentication that makes it possible for EKP to authenticate the user on behalf of the portal and thus avoid the problem of multiple logins.

In such cases, NetDimensions recommends including a Sign In link in the upper right corner of each portal page. Clicking the link initiates the delegated authentication process, which involves redirecting the user to EKP. If, as is typical, the user is not signed into EKP, he or she will be presented with the EKP login page, and will need to log into EKP before being redirected back to the portal with an appropriate authentication token. However, it is possible that the user might already be signed into EKP, in which case he or she will be immediately and transparently redirected back to the portal with the authentication token. This could happen for a number of reasons: the user's portal session might have timed out while his or her EKP session has not (which could happen if the session timeout for the portal is shorter than the session timeout for EKP); the user might previously have logged into EKP directly; or the user might already have signed into another portal running against the same EKP site.

The above is the approach followed in our code samples and by our portal demo sites.

Portal developers sometimes ask us if they can embed an EKP login form directly in their portal instead of using the sign-in link as described above. While this is possible, it creates a suboptimal user experience because it will in some cases force users to enter their user ID and password unnecessarily. This is because the only way for the portal to determine whether the user is already signed into EKP (which would allow them to bypass the login process as described above) is to redirect the user to EKP. However if the login form is embedded in the portal then this redirect does not occur until after the credentials have been entered. In other words, by the time we can determine whether the user's credentials are required, they will already have been entered, perhaps unnecessarily.

This situation might be acceptable if there is only a single portal, and if users of the portal site are unlikely to also access EKP directly. It becomes increasingly undesirable as the number of portals increases.

With the above caveats, here is an outline of how an embedded login form could be implemented if desired.

First, create a login form with the following fields:

  • A hidden field named TX with value VERIFY;
  • A text field named UID for the user ID;
  • A password field named PWD for the user's password; and
  • A hidden field named target, the value of which should be the absolute URL of a “post-login” callback page that is part of the portal, the purpose of which is described below.
Be sure that the form uses the POST method to ensure that the password is not included in the URL when the form is submitted. Note that there is no need to include the delegated authentication nonce or callback parameters in this form, since the handler will not use them.

Assuming that the base URL of the EKP site is https://www.example.com/ekp/ and the URL of the callback page is http://portal.example.com/post_login.php, this login form might look as shown below.

<form method="post" action="https://www.example.com/ekp/servlet/ekp">
 <input type="hidden" name="TX" value="VERIFY">
 <p><label>User ID: <input type="text" name="UID"></label></p>
 <p><label>Password: <input type="password" name="PWD"></label></p>
 <input type="hidden" name="target" value="http://portal.example.com/post_login.php">
 <p><input type="submit" value="Sign In"></p>
</form>

When the user submits the login form (and assuming he or she entered a valid user ID and password), he or she will be signed into EKP and then redirected to the “post-login” portal page. (If the user entered an incorrect user ID or password EKP will display the standard login page so that he or she can retry.) At this point, though, the portal has not validated that the login was successful. (The fact that the user has been redirected to the post-login page is not itself sufficient, since the portal can't reliably determine that the user didn't navigate to this page manually.)

At this point, the portal should initiate the delegated authentication process in the normal way, i.e. by generating a random nonce value, storing it in the session, and then redirecting the user to https://www.example.com/ekp/servlet/ekp/authenticate?nonce={nonce-value}&callback={callback-value}. Note that, since the user is already signed into EKP, he or she will not be shown the login page but will instead immediately be redirected to the callback URL with the authentication token, which the portal can then use to validate the login. In other words, this second step should be completely transparent to the user but allows the portal to verify that the login was successful.

Friday, April 23, 2010

What's New in the EKP 6.1 API

Although there are no major new areas of functionality in the EKP 6.1 API, there are several useful enhancements, listed herewith.

  • News feeds can now be filtered by category. Both api/publicNews and api/userNews now support an optional categoryId parameter. Why this is useful: If you are creating a topical portal, you can now restrict the articles shown to those that are relevant to the subject of the portal; for example, an onboarding portal can show articles targeted to the user, with the further restriction that only articles related to onboarding are shown.
  • api/module returns additional information. Specifically, module attributes are now returned, as are prices (currency and amount) for module sessions. (Since module attributes are not always intended for learners, they will be returned only if you authenticate as a System Administrator.) Why this is useful: Price information is essential for e-commerce portals, while module attributes can be used to retrieve implementation-specific data such as a product code to be passed to a payment gateway (if this is not the same as the EKP course ID).
  • Images specified via the Picture URL field are now available in news feeds. (Note that you can always include inline images in your articles using the HTML <img> tag.) Why this is useful: Images add impact to news articles, and being able to include those images on your portal sites will make those sites more engaging.

We hope these enhancements will make the API significantly more useful in EKP 6.1.

Monday, April 5, 2010

Images in News Feeds

EKP's API provides two functions for retrieving feeds of news articles in either RSS 2.0 or Atom 1.0 format. publicNews returns a feed of public news articles (the same articles that would appear on the login page), while userNews returns the personalized news feed for a specific user.

Previously, these feeds did not include any values for the Picture URL field configured for the articles (although they would include images included directly in the text of the articles using HTML markup). However, starting from build 6.0.0.127, these values will be included in feeds when using either the rssfull or atom format. (Picture URL values are not included when using the rssteasers format.)

Since neither RSS nor Atom include a distinct field for images, the value is included as an entity-escaped HTML img element inside the description element (for rssfull) or the content element (for atom). The unescaped img element would look similar to the example below.

<img alt='My Article'
     class='news-image'
     src='/ekp/nd/fresco/repository/myimage.jpg'>

When the img element is entity-escaped and included in a description element (for the rssfull format), the result would look as shown below.

<description>&lt;img alt='My Article' class='news-image'
src='/ekp/nd/fresco/repository/myimage.jpg'&gt; This is the text of the
article.</description>

The equivalent content element for the atom format is shown below.

<content type="html">&lt;img alt='My Article' class='news-image'
src='/ekp/nd/fresco/repository/myimage.jpg'&gt; This is the text of the
article.</description>

Note that the img element includes an attribute class='news-image', which you can take advantage of to apply special styling to these images using CSS if you are including the article text in your own Web pages. For example, the rule below ensures that all such images are floated to the right of the article text.

img.news-image {float: right;}

The rule below ensures that the images are not displayed.

img.news-image {display: none;}

If you want to use the image URL in a way that can't easily be accomplished using CSS, you could extract the URL, for example by parsing the article text into its own DOM and then applying the following XPath expression.

//img[@class="news-image"]/@src

We know that images can add significant impact to your content, and we hope that this change makes it easier for you to use news article images in your portal pages.

Monday, March 8, 2010

Creating a custom sign-up form using PHP

EKP provides a built-in sign-up (self-registration) function for new users. However, there are situations in which you might want to provide a custom sign-up form, particularly if users are accessing EKP's functionality via a portal.

  • A custom sign-up form provides you with complete control of the “look and feel” of your sign-up page.
  • A custom sign-up form enables you to control what happens at the end of the sign-up process. For example, instead of directing users to a standard EKP start page, you can direct them to a page within a learning portal.

This post outlines how you might go about creating a custom sign-up page using PHP.

The first step is to create the sign-up form itself. This might reside in a file named signup.php for example.

<form action="handlesignup.php" method="POST">
    User ID: <input name="userid" type="text" maxlength="85">
    <br>
    Password: <input name="password" type="password">
    <br>
    Family Name: <input name="familyname" type="text" maxlength="85">
    <br>
    Given Name: <input name="givenname" type="text" maxlength="85">
    <br>
    <input type="submit" value="Sign Up">
</form>

When user submits this form, the browser will send an HTTP POST request to another PHP script named handlesignup.php. The example below shows what the code in this file might look like.

<?php

// defines $ekp_base, $auth_key
require 'config.php';

// Grab the parameters from the request
$user_id = $_POST['userid'];
$password = $_POST['password'];
$family_name = $_POST['familyname'];
$given_name = $_POST['givenname'];
// Other fields as needed...

// Format as CSV for the contentHandler/usersCsv API function
// CSV data consists of two lines: one for headers, and one for data
// Full list of permitted fields is same as for User Data Loader
// Note that almost all fields are optional
$data = '"Action","UserID","Password","FamilyName","GivenName"' . "\r\n"
      . '"A","' . $user_id . '","' . $password . '","' . $family_name . '","'
      . $given_name . '"';

// Use cURL to POST the CSV data to EKP
// Note that the profile parameter is optional
$ch = curl_init($ekp_base . 'contentHandler/usersCsv?profile=signupprofile');
curl_setopt($ch, CURLOPT_POST, TRUE);
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type: text/csv"));

// Although EKP ignores the user name, a non-empty value must be used
// otherwise cURL will not include the authentication header
$user_name = "dummy";
curl_setopt($ch, CURLOPT_USERPWD, $user_name . ":" . $auth_key);

curl_setopt($ch, CURLOPT_POSTFIELDS, $data);
$result = curl_exec($ch);

curl_close($ch);

// Now show a confirmation page to the user, or redirect him or her to an
// appropriate page.

?>

<html>
    <head>
        <title>Sign-Up Completed</title>
    </head>
    <body>
        <h1>Thanks for signing up!</h1>
    </body>
</html>

Known issues

  • The code above does not attempt to escape the double quotation mark character ("), which has a special meaning in CSV, when it occurs in field values. In order to guard against possible data-injection attacks, the code should really replace each occurrence of this character with two instances of the character.
  • The code does not perform any validation of the input. A more robust example would validate the user input before calling the API function.
  • As a special case of the above, it is common on sign-up forms to ask the user to re-type his or her password, since a mistyped password might prevent the user from accessing his or her account. The example code shown here does not do this.

Wednesday, June 17, 2009

Publishing a podcast using the News Manager

EKP 5.6 provides RSS feeds both for public news on the login page and for personalized news on a learner's home page. (Note: RSS feeds are available only if your license includes API access.)

RSS feed link on Home Page

In EKP 5.6.0.129 we have added support for RSS enclosures. Roughly speaking, RSS enclosures serve the same purpose as email attachments—they make is possible to attach a file of arbitrary type to a text message. Probably the most interesting consequence of this change is that it's now possible to use the News Manager to publish a podcast. Here's how.

  1. Record a podcast episode, edit it as necessary, and save as an appropriate media file (audio or video). There are many tools available for recording, editing and encoding media files. For audio, we suggest Audacity for recording and editing, with the LAME MP3 encoder to generate MP3 files.

  2. Upload your media file to the Repository Manager.

    Uploading an MP3 file to the Repository Manager
  3. Create a news article in the News Manager. For the File Attachment URL field, select the media file you uploaded in the previous step. Make sure the article is targeted to the appropriate audience, and publish as usual.

    Creating a news article with attached MP3 file
  4. A listener/viewer can subscribe to an appropriate RSS feed using a “podcatcher” such as Apple's iTunes. The podcatcher will download new podcast episodes as they are made available. The episodes can then be played offline, and can also be synchronized to devices such as portable MP3 players and phones.

    Subscribed podcast in iTunes

Friday, June 5, 2009

The API Explorer

EKP provides an application programming interface (API) that enables other applications and Web sites to interact with EKP—for example, to create user accounts and enrollments, and to obtain information about courses, catalogs, enrollments and training records.

We've always provided API documentation as part of the EKP distribution. However, in working with software developers, we've identified a couple of ways in which the documentation could be improved.

Firstly, the API changes between releases as new API functions are added. This means it's important to work with the correct version of the documentation for the EKP version you're developing for. However, keeping track of different document versions is a hassle.

Secondly, most developers learn more easily if they are able to call API functions interactively and generate actual responses, rather than simply reading dry documentation. However, calling API functions generally involves writing code.

With these points in mind, in EKP 5.6 we introduced the API Explorer. The API Explorer serves two purposes: it is both an online reference for the API functions, and a tool that enables developers to learn about the API by calling its functions interactively.

Enterprise Knowledge Platform API

The API Explorer lists the API functions available. For each function, it provides information about how to invoke the function, including the URL and the expected HTTP method, parameters and authentication scheme. Where possible, it provides one or more HTML forms that can be used to call the API function directly from the browser. (Note: some API functions cannot be invoked from a browser.)

userNews API function

The API Explorer can be accessed by appending api/ to the base URL of your EKP site. For example, if your site is located at http://www.example.com/ekp/, then the API Explorer for the site can be accessed at http://www.example.com/ekp/api/. At the time of writing, an instance of the API Explorer is available at http://utest2.netdimensions.com/utest/api/.

Note: If you do not see the API Explorer at the expected URL, your Web server (e.g. Apache or IIS) might not be forwarding the requests to Tomcat. In the case of Apache, you can fix this by adding a directive like the one below to httpd.conf.

JkMount /ekp/api/* ajp13

Thursday, October 2, 2008

PENS authentication

I've written before about how to use a PENS-conformant authoring tool or LCMS with EKP. However, in that post I didn't fully explain the intricacies of how EKP handles authentication of PENS requests.

EKP actually provides two PENS endpoints, which differ only in how they handle authentication. Assuming your installation uses the default /ekp/ path prefix, the endpoint URLs are as follows.

/ekp/pens
/ekp/servlet/ekp/pens

The first of these endpoints handles authentication exactly as described in the PENS specification. That is, the PENS request is expected to include parameters named system-user-id and system-password, the values of which should correspond with, respectively, the user ID and password of an EKP account with permission to create courses. (In fact, this endpoint will also accept credentials supplied as an HTTP basic authentication header. This is allowed primarily for consistency with other EKP web services. However, the request parameters always take precedence when supplied.)

The second endpoint ignores the PENS authentication request parameters and HTTP basic authentication headers, and instead uses EKP's standard login sessions for authentication. While this is strictly outside the scope of the PENS specification, it is convenient in situations where the PENS request originates directly from a browser. Since the user is likely to have already logged into EKP at the time at which the PENS request is sent, this approach avoids the need for the user to re-enter his or her credentials every he or she initiates the PENS publishing process.

Monday, May 26, 2008

Code samples: invoking APIs using C#

I've previously posted sample code that demonstrates how to invoke EKP's APIs using Java and Visual Basic. Herewith, equivalent code using C#.

As with modern Visual Basic, C# is a .NET-based language. It's therefore fairly straightforward to translate our previous Visual Basic sample code into C#. As with the Visual Basic code, we will use an instance of System.Net.WebClient to make the API calls.

System.Net.WebClient client = new System.Net.WebClient();

Again, we need to set the credentials that WebClient will use for the HTTP basic authentication process. We must set the user name to a non-empty value to ensure that WebClient sends the authentication header, but the exact value doesn't matter since EKP ignores it. The password must match the value of the authentication.key property configured in the file WEB-INF/conf/ekp.properties.

String userName = "dummy";
String key = "mysecretkey";
client.Credentials = new System.Net.NetworkCredential(userName, key);

To create a user account, we send an HTTP POST request to /ekp/contentHandler/usersCsv, including CSV-formatted data in the body of the request.

String data1 = "Action,UserID,Password,FamilyName,GivenName\r\n"
             + "A,joestudent,dummypass,Student,Joe\r\n";
client.UploadString("https://ekp.example.com/ekp/contentHandler/usersCsv",
                    data1);

Similarly, we can enroll the user in a course with ID Derivatives_101 by sending an HTTP POST request to /ekp/enrollmentHandler, again including appropriately-formatted CSV data in the body of the request.

String data2 = "USERID,LEARNINGID\r\n"
             + "joestudent,Derivatives_101\r\n";
client.UploadString("https://ekp.example.com/ekp/enrollmentHandler", data2);

Sunday, May 25, 2008

Code samples: invoking APIs using Visual Basic

I've previously posted sample Java code that demonstrates how to invoke EKP's APIs. Herewith, equivalent code using Visual Basic .NET.

The .NET platform provides a couple of classes for sending HTTP requests, specifically System.Net.HttpWebRequest and System.Net.WebClient. Either will do the job. However, WebClient is a little simpler to work with, so that's what we'll use.

Dim client As Net.WebClient = New Net.WebClient()

API requests must include an HTTP basic authentication header. Fortunately, both WebClient and HttpWebRequest have built-in support for HTTP basic authentication, so this is straightforward. The user name is ignored by EKP; however, we must set the user name to a non-empty value, otherwise WebClient won't send the authentication header. The password must match the value of the authentication.key property configured in the file WEB-INF/conf/ekp.properties.

Dim userName As String = "dummy"    ' any non-empty value is okay
Dim password As String = "mysecretkey"
client.Credentials = New Net.NetworkCredential(userName, password)

To create a user account, we send an HTTP POST request to /ekp/contentHandler/usersCsv, including CSV-formatted data in the body of the request.

Dim data1 As String _
        = "Action,UserID,Password,FamilyName,GivenName" & ControlChars.CrLf _
        & "A,joestudent,dummypass,Student,Joe" & ControlChars.CrLf
client.UploadString("https://ekp.example.com/ekp/contentHandler/usersCsv", _
                    data1)

Similarly, we can enroll the user in a course with ID Derivatives_101 by sending an HTTP POST request to /ekp/enrollmentHandler, again including appropriately-formatted CSV data in the body of the request.

Dim data2 As String = "USERID,LEARNINGID" & ControlChars.CrLf _
                    & "joestudent,Derivatives_101" & ControlChars.CrLf
client.UploadString("https://ekp.example.com/ekp/enrollmentHandler", data2)

Tuesday, March 25, 2008

Pragmatic API design

In a comment on a previous post, Carfield Yim suggests an alternative style for API requests. We could dub this the URL-encoded style, since the content type associated with the request format is application/x-www-form-urlencoded. (Carfield's example involves updating a user's name, so the hypothetical service ought to require that the request be submitted using HTTP POST method rather than GET, since the action is unsafe.)

There is eternal debate in the software and web communities on the question of what APIs should look like, involving an acronym soup of terms such as SOAP, REST, SOA, POX and ROA. Without invoking too many buzzwords, we can observe that the following are both desirable properties of real-world APIs.

  1. Support for invoking an operation, and viewing the response, directly in a browser. Typically the requests would need to be submitted using an HTML form. This can be very useful to a developer trying to make use of the API, since it becomes incredibly easy to test its behavior. Learning by experiment is often easier and more effective than reading a specification.
  2. Reuse of existing data formats. For example, one of the examples in the original post was concerned with creating a user account in EKP. The body of the request message contained CSV data in the format EKP expects for files uploaded using the User Data Loader. Hence, if an organization has already written code to generate data in that format (extracted from their HR system for example), it needs relatively little work to switch between either generating files for manual upload, or submitting the data directly using the API. On the other hand, the application/x-www-form-urlencoded content type isn't normally used outside of HTTP requests.

(In passing, it's worth noting that SOAP does not satisfy either of these requirements particularly well. It fails completely with the first. As for the second, it's reasonably easy to reuse an existing format if it is XML-based and literal encoding is used rather than SOAP encoding. On the other hand, using a format that is not XML-based—because it predates XML for example—typically requires sending the data as some kind of SOAP attachment, which raises a whole other set of issues.)

In some cases, support for batch operations might also be a requirement. For example, if I need to update 1,000 user records, this will be considerably more efficient if the data can be sent in a single request. If 1,000 separate requests are required, then network latency will become a serious concern. (However, HTTP pipelining could help if supported.)

As I see it, the URL-encoded request style meets the first requirement (it supports invocation from a browser), but fails to meet the second (it fails to reuse an existing data format for the request) and third (it is not well suited to batch operations). On the other hand, the CSV request style described in the original post fails to meet the first requirement, but meets the second and third. This seems like a reasonable trade-off in this case. However, the URL-encoded style seems like a reasonable approach in cases where support for large batch updates isn't a critical requirement, and there isn't an existing data format that obviously matches the desired content of the request message.

Thursday, March 20, 2008

Code samples: invoking APIs using Java

Following on from my previous post, I thought it might be useful to post some sample code that demonstrates how to invoke EKP's APIs, in this case using Java.

Every API request must include an HTTP basic authentication header. If you are using Java's built-in HttpURLConnection class, you would need to construct and add this header manually. This is not hard, and the EKP APIs and Web Services Overview explains how to do it. However, it's even easier to use a library that supports HTTP basic authentication directly.

One such library is Jakarta Commons HttpClient. HttpClient is free, open source, and distributed under version 2.0 of the Apache License, meaning that it can be used with minimal obligations in software that is not itself open source. (Note that HttpClient has dependencies on both Commons Logging and Commons Codec, so you will also need both of those to run this sample code.)

import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.UsernamePasswordCredentials;
import org.apache.commons.httpclient.auth.AuthScope;
import org.apache.commons.httpclient.methods.PostMethod;
import org.apache.commons.httpclient.methods.StringRequestEntity;

We begin by creating an instance of HttpClient, which is straightforward.

HttpClient httpClient = new HttpClient();

We need to initialize the HttpClient object with the appropriate user name and password. The user name is ignored by EKP, so we simply use the empty string. The password must match the value of the authentication.key property configured in the file WEB-INF/conf/ekp.properties.

String userName = "";
String key = "mysecretkey";
httpClient.getParams().setAuthenticationPreemptive(true);
httpClient.getState().setCredentials(AuthScope.ANY,
        new UsernamePasswordCredentials(userName, key));

As described in the previous post, we can create a user account (here, joestudent) by sending an HTTP POST request to /ekp/contentHandler/usersCsv, and including CSV-formatted data in the body of the request.

PostMethod postMethod1 = new PostMethod(
        "https://ekp.example.com/ekp/contentHandler/usersCsv");
String content1 = "Action,UserID,Password,FamilyName,GivenName\r\n"
                + "A,joestudent,dummypass,Student,Joe\r\n";
postMethod1.setRequestEntity(new StringRequestEntity(content1,
        "text/plain", "UTF-8"));
httpClient.executeMethod(postMethod1);

Similarly, we can enroll joestudent in a course with ID Derivatives_101 by sending an HTTP POST request to /ekp/enrollmentHandler, again with appropriately-formatted CSV data in the body of the request.

PostMethod postMethod2 = new PostMethod(
        "https://ekp.example.com/ekp/enrollmentHandler");
String content2 = "USERID,LEARNINGID\r\n"
                + "joestudent,Derivatives_101\r\n";
postMethod2.setRequestEntity(new StringRequestEntity(content2,
        "text/plain", "UTF-8"));
httpClient.executeMethod(postMethod2);

API 101

We just finished a fairly intensive training session here in Hong Kong with a couple of partners. The subject was ostensibly our customization toolkit, but we also spent quite a bit of time discussing APIs and how EKP can be integrated with existing web sites, portals and applications. Every time we conduct these training sessions, this topic expands.

Here's an outline of what we covered, with links to the relevant documentation.

  1. The first step in seamlessly combining EKP functionality with an existing site is understanding how to implement web-based single sign-on.
  2. With a single sign-on mechanism in place, it's possible to have external pages link directly to specific pages in EKP, and, in particular, to launch courses directly from external pages. (See also: How can I link directly to a page in EKP without losing the navigation frames?)
  3. Data can be manipulated in, or extracted from, EKP using the APIs described in the EKP APIs and Web Services Overview. Examples:
    • To ensure that EKP has a user account for a specific user ID (as part of the single sign-on process for example), have the external site send a direct server-to-server HTTP POST request to /ekp/contentHandler/usersCsv, with CSV-formatted data (following the User Data Loader format) in the body of the request. Note that most of the columns are optional when the User Data Loader format is used, so the following is valid for example:
      Action,UserID,Password,FamilyName,GivenName
      A,joestudent,mypassword,Student,Joe
    • To ensure that a specific user is enrolled in a specific course (prior to launching the course for example), have the external site send a direct server-to-server HTTP POST request to /ekp/enrollmentHandler with CSV-formatted data in the body of the request. For example:
      USERID,LEARNINGID
      joestudent,Derivatives_101
    • To retrieve a complete training history, in XML format, for user joestudent (to display within an external page for example), have the external site send a direct server-to-server HTTP GET request to /ekp/contentGenerator/trainingHistoryXml?userId=joestudent.

Update: I posted Java code samples for creating a user account and enrolling a user in a course.

Update 2: Musings on the invocation style of the API operations discussed above, prompted by Carfield's comment.

Sunday, March 16, 2008

Directory services and hosted EKP sites

Consider the following scenario, which is not uncommon. An organization wishes to make use of an EKP site that is hosted outside of their network. The organization has already implemented a directory service (Active Directory for example) that is most likely accessible via LDAP. Naturally, the organization would like their users to be able to access EKP using the usernames and passwords stored in the directory service. Below are three ways in which this could be accomplished.

  1. Usernames and passwords could be exported from the directory service (using a tool such as CSVDE for Active Directory for example) and imported into EKP. The import could be performed manually using EKP's CSV User Data Loader, or it could be automated using EKP's APIs or import scheduler. Users would log into EKP using EKP's standard login page.
  2. The EKP site could be configured to connect directly to the organization's directory service using LDAP to perform authentication. Again, users would log into EKP using EKP's standard login page.
  3. A login page could be created on a web server in the organization's DMZ that connects to the organization's directory service and implements an authentication service for EKP as described in this previous post.

The first approach has a few disadvantages.

  • It is not real-time. For example, a password change in the directory service will not take effect on the EKP site until the next time the usernames and passwords are synchronized.
  • For extra security, systems that support password-based authentication might store a cryptographic hash of a password, from which it is infeasible to recover the original password, instead of storing the original password. (In fact EKP does exactly this, which is why it is not possible to export passwords from EKP.) Thus, it might not be possible to export passwords from the directory service.
  • Even if it is technically possible to export passwords from the directory service, replicating passwords on a system outside of the organization's network might violate the organization's security policies.

The second approach avoids these problems. However, it does require that the organization's directory service be accessible from outside the organization's network, which often will not be the case. (This would of course be the preferred approach if the EKP site was hosted inside of the organization's network.)

The third approach has several advantages.

  • It is real-time. For example, when a password is changed in the directory service, the new password will immediately be effective for accessing EKP.
  • It does not require passwords to be exported from the directory service or replicated outside of the organization's network.
  • It does not require that the directory service be accessible outside of the organization's network via LDAP.
  • In cases where the organization already has a web site or portal that authenticates against the directory service, the authentication service for EKP can be combined with the existing site, thus providing single sign-on between the existing site and EKP.

This third approach should be the preferred approach in most cases where the EKP site is hosted outside of the organization's network.

Thursday, July 26, 2007

Can I launch courses directly from a portal so that learners don't have to log into EKP, but still have EKP track the learners' progress?

In order to link to a course so that the course launches immediately, and is tracked by EKP, you can link to the launchByCourseId transaction, e.g.:

/ekp/servlet/ekp/launchByCourseId?courseId=My_Course

(Note that this requires that the learner already be enrolled in My_Course, so you might want to pre-enroll learners using a Group Enroll or Auto-Enroll.)

If you link directly to the URL above, and the learner does not yet have a session with EKP, she will be prompted to log in as normal. In order to achieve “transparent login”, you can use one of the two mechanisms described below.

  1. Implement the "external authentication service" mechanism. To implement this, the portal would need to be modified to generate “authentication tokens” (cryptographic hashes) when requested by EKP. Then, EKP's configuration is modified so that, when it needs to authenticate a user, it redirects to the portal to request an authentication token instead of showing the standard login page.

    Note that this mechanism has the significant advantage that it is not required that users' passwords be synchronized in the two systems. In fact, when using this mechanism, the passwords stored in EKP's database are never used.
  2. Use the standard verify transaction. This is the transaction that is used to validate a user ID and password submitted using the normal login page. It is possible to add a target parameter to specify the page to which the user should be redirected after a successful login (instead of the normal home page). In particular, if you want to start a course after login, you can specify the launchByCourseId transaction (with appropriate courseId parameter value) as the value of the target parameter. E.g.:
    /ekp/servlet/ekp?TX=VERIFY&UID=joestudent&PWD=password&target=%2Fekp%2Fservlet%2Fekp%2FlaunchByCourseId%3FcourseId%3DMy_Course
    Note that the value of the target parameter has been percent-encoded.

    The above example includes the parameters in the query string—however, for security reasons you should avoid including the user ID and password in the URL—therefore, the portal should be coded to use the POST method rather than GET to invoke the verify transaction.

Note that, unlike method 1, method 2 requires passwords to be synchronized between the two systems, which could be difficult to achieve if passwords are changed regularly (a good security practice). (This problem can be avoided by configuring both systems to use the same directory server, i.e. Active Directory or LDAP.) In addition, method 2 requires embedding the user's password in an HTML page (or HTTP redirect header), which might be cached. For these reasons, we recommend using method 1 if possible.

Thursday, June 28, 2007

Can I use an external authentication service so that users don't need to log into EKP directly?

(Note: this post contains technical details that will likely be of most interest to developers.)

In a typical organization, EKP will be one of many applications that employees or other stakeholders use on a regular basis. In this situation, it's typically desirable to provide some kind of single (or reduced) sign on, so that users don't have to perform separate logins to different applications.

EKP provides a number of mechanisms to help solve this problem. Some of those most commonly-used are listed below.

  • Support for LDAP and Active Directory services: Use of an LDAP or Active Directory service avoids the needs to store and update users' passwords in EKP's database, because users' credentials are checked against the centralized directory service when they log in. This works even if the user is accessing EKP over the internet. However, it does not actually eliminate the need for the user to perform a login to access EKP. (For details of LDAP- and Active Directory-based authentication, see the LDAP Authentication Integration Configuration Guide and the Active Directory Authentication Integration Configuration Guide respectively.)
  • Support for Integrated Windows Authentication: Use of Integrated Windows Authentication avoids not only the need to store and update users' passwords in EKP's database, but also the need for users to explicitly log into EKP, because their identity is automatically propagated to EKP based on their Windows login. However, Integrated Windows Authentication typically only works within a Windows-based intranet; it typically will not work for access over the internet. (For details on using Integrated Windows Authentication with EKP, see the Single Sign-On Integration with Windows document.)

However, it's often desirable to provide an integrated authentication mechanism that will work over the internet, even if the authentication service is not physically co-located with EKP. This post describes such a mechanism.

For the sake of example, let's suppose that you are running a company portal alongside EKP, and that you want your portal users to be able to access EKP. However, you do not want users to have to log into EKP separately; rather, you want all authentication to occur via the portal, with users' identities being propagated to EKP once they have authenticated through the portal.

In order to enable the integrated authentication mechanism, it's necessary to define a couple of properties in the ekp.properties configuration file (under the WEB-INF/conf/ directory), as shown below.

authentication.key=mysecretkey
authentication.service.url=http://portal.abc.com/login.asp

The significance of these properties and their values is explained below. In addition, another optional property may be specified, as shown below.

authentication.digestAlgorithm=SHA

The value of this property specifies the cryptographic hash function that will be used as part of the authentication process, as explained below. Permitted values are MD5 and SHA. If this property is not specified, a default value of MD5 is assumed.

Normally, when an unauthenticated user tries to access a page in EKP that requires authentication, she will be redirected to EKP's standard login page. With the integrated authentication mechanism enabled, she will instead be redirected to the URL specified by the value of the authentication.service.url property. (Note that it does not matter how the user came to access the EKP page. She might have accessed the page by following a link from the portal, but that's not necessary for the mechanism to work.)

EKP will also append a query string parameter named salt to the URL that is the target of the redirect. The value of this parameter is a random sequence of bytes, converted to characters using Base64 encoding. The purpose of the salt value is to prevent replay attacks—which is to say that if an attacker was able to intercept the URL generated by the portal as described below, they would not be able to reuse it authenticate against EKP after the salt value expired.

An example of a possible redirect target URL is shown below.

http://portal.abc.com/login.asp?salt=OqQ1uao%3D

(N.B. In this example, the raw Base64-encoded salt value is the character string OqQ1uao=. However, the equals character “=” has special meaning when used in URLs, so the value has been URL-encoded as OqQ1uao%3D.)

On receiving the request from the redirected client, the portal needs to perform the following steps.

  • Recover the original bytes of the salt by Base64-decoding the URL parameter value.
  • Authenticate the user if she does not already have a session with the portal.
  • Using the function configured as described previously, calculate a cryptographic hash of the user ID, secret key (this is the value of the authentication.key property described above) and salt value.
  • Convert the bytes of the cryptographic hash to a character string using Base64.
  • Redirect the client back to EKP's authenticationTokenVerifier transaction, passing both the user ID and the Base64-encoded cryptographic hash as query string parameters.

For example, assuming that the user is authenticated by the portal as joestudent, and the secret key is mysecretkey, then the MD5 cryptographic hash (after Base64 encoding) would be vf1nZ7R2YSoso+g+BLLVog==, and the EKP URL to which the portal would redirect the client would look as shown below.

/ekp/servlet/ekp/authenticationTokenVerifier?userId=joestudent&digest=vf1nZ7R2YSoso%2Bg%2BBLLVog%3D%3D

(Note that the value of the digest parameter is the URL-encoded cryptographic hash.)

On receiving the request from the redirected client, EKP will perform its own computation of the cryptographic hash and compare it with the value passed by the portal. If the values match, this is accepted as proof that the redirect was actually generated by the portal and was not “spoofed”. EKP then considers the client to be authenticated and establishes a session with the client.

The following sample code provides an outline of how the mechanism described above might be implemented as a Java servlet.

String saltStr = req.getParameter("salt");
byte[] salt
  = new sun.misc.BASE64Decoder()
      .decodeBuffer(saltStr);
  
String key = "mysecretkey";
String userId = "joestudent";
  
// Calculate a digest
java.security.MessageDigest md
  = java.security.MessageDigest.getInstance("MD5");
  
// Convert user ID and key to bytes--need to
// specify a character encoding here in case the
// default encodings are different on the two
// systems.
md.update(userId.getBytes("UTF-8"));
md.update(key.getBytes("UTF-8"));
md.update(salt);
byte[] digest = md.digest();
  
// Use Base64 encoding to turn the digest into a
// string, so we can pass it in the URL.
String digestStr
  = new sun.misc.BASE64Encoder().encode(digest);
  
// Encode the digest again using URL encoding to
// escape any special characters.
String url
  = "http://ekp.abc.com/"
  + "ekp/servlet/ekp/authenticationTokenVerifier"
  + "?userId="
  + java.net.URLEncoder.encode(userId, "UTF-8")
  + "&digest="
  + java.net.URLEncoder.encode(digestStr, "UTF-8");
  
response.sendRedirect(url);

The mechanism described in this post works in EKP 4.6 Gold build 116 or higher, and in EKP 4.7 Gold build 52 or higher.

Wednesday, February 28, 2007

How can I link directly to a page in EKP without losing the navigation frames?

Sometimes it's convenient to link directly to pages in EKP from external systems. For example, if you have a course with ID MY_COURSE, you could link to the course catalog page from a page on your company intranet by using a URL like the one below.

/ekp/servlet/ekp?TX=FORMAT1&CID=MY_COURSE

However, if you create a link in this way then the visitor will see only the course catalog page, not the usual EKP navigation frames, so she will not be able to explore EKP, or even log out.

With a little more work, it's possible to create a URL that will let you link to the same page in such a way that it's displayed with the standard navigation frames. You do this by using a URL that follows the pattern shown below.

/ekp/servlet/ekp/pageLayout?mainSrc={URL-of-target-page}

You need to replace {URL-of-target-page} with the actual URL of the target page. However, this URL needs to be URL-encoded. It's beyond the scope of this blog post to fully explain how URL-encoding works, but basically it involves replacing special characters with an encoded form that consists of a percentage symbol (%) followed by two letters or digits. For example, the slash character (/) is replaced by the percentage symbol followed by the digit 2 and the letter F. Here is a more detailed explanation of URL-encoding.

To return to our original catalog page example, the URL-encoded form of the target URL is as shown below.

%2Fekp%2Fservlet%2Fekp%3FTX%3DFORMAT1%26CID%3DMY_COURSE

Once this is substituted into the URL that displays the navigation frames, the final full URL is as shown below.

/ekp/servlet/ekp/pageLayout?mainSrc=%2Fekp%2Fservlet%2Fekp%3FTX%3DFORMAT1%26CID%3DMY_COURSE

The same technique can be used for any internal EKP page that can be linked to directly.