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 configuration file (under the WEB-INF/conf/ directory), as shown below.


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


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.

(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.


(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()
String key = "mysecretkey";
String userId = "joestudent";
// Calculate a digest md
// 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.
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
  = ""
  + "ekp/servlet/ekp/authenticationTokenVerifier"
  + "?userId="
  +, "UTF-8")
  + "&digest="
  +, "UTF-8");

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.


Rully Noviandri said...

Hi Rob, i want to ask something. Let say I have an independent user database in another environment with dbo.user as user table (Username,Password). Can I integrate this user table
to EKP Authentication?

Robert Lowe said...

Rully, yes, absolutely. You would just need to create a page (.aspx, .jsp, .php etc.) that uses your database table to authenticate the user instead of hard-coding the userId as in my example.

Anonymous said...

Dear Rob could you help me about my issue using PHP?

i have a portal named SitePortal and i need to do an integration if my user have an account through EKP then i need to allow him to access EKP site without authentication.

1. PHP code to check if the user have a permission
2. EKP Configuration

Please help me with full code :)


Robert Lowe said...

Anonymous, you should start with the PHP sample authentication service.

Ravie said...

thanks Robert,

i have checked the url that you have been sent, i did the same steps but should i set the external authentication = YES ?

Robert Lowe said...

Ravie, it doesn't matter, that setting has no effect when using delegated authentication. (It's only used when a user logs in via Talent Suite's standard login page.)

Ravie said...

thanks again rob, but what is the needed code should be implemented to let me see that myuser is authenticated and can access Net Diminsion Account ?

Robert Lowe said...

Ravie, I'm not sure I understand what you are trying to accomplish?

Typically, authentication would happen within your portal, after which you would redirect the user to Talent Suite with the appropriate parameters. Assuming all is well, the user will then be signed into Talent Suite. After that, there would not normally be any redirects back to your portal.

So it's not clear to me at what point you would that check to occur, or why you think authentication might fail?

Ravie said...

Dear Ravie,
Thank you, but after using the call back service url and redirect user, i got the below error / warrning

"Authentication Request

A site identifying as attempted to discover your identity.

The attempt was blocked because the site is not permitted to access this information."

Please help me

Robert Lowe said...

You need to configure as a trusted relying party.

Ravie said...

Could you please provided me about the needed steps to do that ?

"You need to configure as a trusted relying party."

assume my portal is ""

Robert Lowe said...

Ravie, my previous comment included a link to the documentation on how to configure a trusted relying party. Here it is again: