Showing posts with label Coding. Show all posts
Showing posts with label Coding. Show all posts

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.

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

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)

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);

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.