Original post: http://fabriccontroller.net/blog/the-belgian-eid-in-windows-azure-part-1-authentication-and-identification

 

You might have noticed that I'm really into the Belgian eID. Needless to say I had to look at how we can use the Belgian eID in Windows Azure. In this series I'll show you how you can integrate it with your existing or future cloud projects.

 

We'll start by taking a look at the eID Identity Provider (or eID IdP), an open source project hosted on code.google.com: http://code.google.com/p/eid-idp/. The IdP runs in JBoss and uses a relational database (like MySQL, PostgreSQL, ...). To keep things simple, we won't be looking at how you can install the IdP. Besides running the eID IdP yourself, you can also use the hosted version on the e-Contract website (managed by Frank Cornelis, one of the contributors of the eID IdP project). The following page shows the supported protocols: https://www.e-contract.be/eid-idp/main

 

Since we're going to use Windows Identity Foundation, these metadata endpoints seem to be the most appropriate:

If you look at the claims offered by the WS-Federation Authentication and Identification endpoint, it seems we can get access to some useful information:

schemas.xmlsoap.org/ws/2005/05/identity/claims/name
schemas.microsoft.com/ws/2008/06/identity/claims/role
schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier
schemas.xmlsoap.org/ws/2005/05/identity/claims/streetaddress
schemas.xmlsoap.org/ws/2005/05/identity/claims/locality
schemas.xmlsoap.org/ws/2005/05/identity/claims/postalcode
schemas.xmlsoap.org/ws/2005/05/identity/claims/gender
schemas.xmlsoap.org/ws/2005/05/identity/claims/dateofbirth
be:fedict:eid:idp:nationality
be:fedict:eid:idp:pob
be:fedict:eid:idp:photo
be:fedict:eid:idp:age

 

Enough chitchat, show me some code!

We're going to build a webrole that will use the eID IdP for authentication and identification. To build this application you'll need the Azure SDK, ASP.NET MVC3, the WIF SDK and the WIF runtime:

Create a new Windows Azure project, add an ASP.NET MVC 3 web role and choose the Internet Application template. Now if you run the application and you'll see that you can view the application without having to login, but this isn't what we want. We would like to have an application that requires you to login using the eID IdP. This way we'll know the user is authenticated without having to do the management of usernames, passwords, security, ... And we're actually externalizing the authentication.

 

Now right click the webrole and choose Add STS reference, fill in the application URI (in our case this is http://127.0.0.1 - this is the address that was assigned by the devfabric). Choose to use an existing STS: https://www.e-contract.be/eid-idp/endpoints/ws-federation/metadata/auth-ident-metadata.xml, this endpoint will authenticate you (by asking your pincode) and identify you (get your information). To get things working you'll need to disable the request validation mode (see my previous post):

<httpRuntime requestValidationMode="2.0"/>

Before we can run the application we'll write some code to make everything go well and to display the claims we received from the eID IdP. It's important to know that this IdP uses the realm URI as the return URL after a successful login. This means if you used http://127.0.0.1 as realm, you'll be redirected here. But this isn't what we want...

 

What we want is that the user gets redirected to an action like /Account/Display after a successful login (to show the user's claims). To achieve this you'll need to add the following code in the Global.asax file:

 

protected void Application_Start()
{
    ...
    FederatedAuthentication.ServiceConfigurationCreated += OnServiceConfigurationCreated;
}
 
private void OnServiceConfigurationCreated(object sender, ServiceConfigurationCreatedEventArgs e)
{
    FederatedAuthentication.WSFederationAuthenticationModule.SignedIn += new EventHandler(WSFederationAuthenticationModule_SignedIn);
}
 
private void WSFederationAuthenticationModule_SignedIn(object sender, EventArgs e)
{
    HttpContext.Current.Response.Redirect("/Account/Display");
}

 

Ok this is a good starting point. Now, after a successful login, the user will be redirected to /Account/Display. This means we'll need to write the required code in the AccountController. Let's start with some helper functions that will allow us to get all the claims available for the current identity and an other function that will help us read the value for a specific claim:

private ClaimCollection GetClaims()
{
    var claimsPrincipal = Thread.CurrentPrincipal as IClaimsPrincipal;
    var claimsIdentity = (IClaimsIdentity)claimsPrincipal.Identity;
    return claimsIdentity.Claims;
}
 
private string GetClaimValue(ClaimCollection claims, string claim)
{
    var claimRecord = claims.FirstOrDefault(o => o.ClaimType == claim);
    if (claimRecord != null)
        return claimRecord.Value;
    else
        return null;
}

Now with this code it will become very easy to write the required actions: Display and Photo. This Display action maps the claims to the UserInfo model and displays it in the view:

public ActionResult Display()
{
    var claims = GetClaims();
 
    var user = new UserInfo();
    user.NameIdentifier = GetClaimValue(claims, "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier");
    user.Name = GetClaimValue(claims, "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name");
    user.StreetAddress = GetClaimValue(claims, "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/streetaddress");
    user.Nationality = GetClaimValue(claims, "be:fedict:eid:idp:nationality");
    user.POB = GetClaimValue(claims, "be:fedict:eid:idp:pob");
    user.Locality = GetClaimValue(claims, "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/locality");
    user.Surname = GetClaimValue(claims, "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname");
    user.Gender = GetClaimValue(claims, "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/gender") == "1" ? "Male" : "Female";
    user.GivenName = GetClaimValue(claims, "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname");
    user.DateOfBirth = GetClaimValue(claims, "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/dateofbirth");
    user.PostalCode = GetClaimValue(claims, "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/postalcode");
    user.Age = GetClaimValue(claims, "be:fedict:eid:idp:age");
    user.AuthenticationMethod = GetClaimValue(claims, "http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod");
    return View(user);
}

 

In the Display view we'll simply show all properties of the model, but we'll also show something else...

<img style="float: right;" src="/Account/Photo" alt="" width="140" height="200" />

Yes... that's right. We'll show the user's photo. One of the claims is the be:fedict:eid:idp:photo claim. This claim contains your picture encoded using standard Base64 encoding. And knowing this makes it very easy to build the Photo action:

public ActionResult Photo()
{
    var photo = GetClaims().FirstOrDefault(o => o.ClaimType == "be:fedict:eid:idp:photo");
    if (photo != null)
    {
        var stream = new MemoryStream(Convert.FromBase64String(photo.Value));
        return new FileStreamResult(stream, "image/jpg");
    }
    else
    {
        return new EmptyResult();
    }
}

When you start the application, you'll be redirected to the eID IdP:  

 

 

After entering the PIN code the Java applet will start reading the eID and the eID IdP will redirect to the realm URI (in this case 127.0.0.1). Since we made that small change in the Global.asax file we'll be redirected to /Account/Display after a successful login:

 

 

 

Download the code: WebRoleWitheIDIdP.zip

Or try it yourself (will stay online for a few days): http://eid-idp-demo.cloudapp.net

 

Enjoy!

Dynamics CRM 2011 allows you to manage all kinds of data (xRM) but when you start working with actual people it might come in handy to work with eID cards. Especially in healthcare, education, ... where the end user has to work with a lot of people during the day. Instead of manually entering the data over and over again you could use the eID card to automate this process. That's what we'll build today!

 

Before we get started there are some prerequisites:

Note: This post will explain how to do this in a regular deployment. For IFD I'll write a post in some time explaining how to do this with Windows Azure. 

Sigh... Java. I never thought I'de mention this in one of my posts but yes... we'll be using Java. On code.google.com you'll find a project named eid-javascript-lib. This project allows you to use the eID Java Applet to make the connection between your websites using Javascript and the Belgian eID. And since Dynamics CRM 2011 relies heavily on Javascript this is the perfect match.

This is how the solution will look like:

 

In CRM 2011 you are able to add some web resources, but the system only allows a few types like HTML, CSS, JS, XML, PNG, ... You might think, why not change the extension to one of these types... but this won't work since the MIME type used to serve the Java applets will not be the right one (like application/x-java-jnlp-file for example, more on this later). That's why we'll need a seperate site to host the Java specific stuff.

Before we can dive into Dynamics CRM 2011 we need to host the required Javascript and Java files. Remember that this is only suited for regular deployments, the guide to host this in an IFD will follow soon.

 

First we'll create an IIS website that will contain all the data. If your CRM deployment is https be sure to also make the IIS website an https website. If you don't do this, you'll get some nasty popups saying only the secure parts of the page are displayed etc...

 

So I've created a website in IIS with HTTPS binding (https://localhost:100/). In this website I'll be hosting 3 types of files: *.js, *.jar and *.jnlp. If you want these to work correctly you'll need to check if the MIME Types have been configured in your IIS website. Go to your website and open the MIME Types option:

 

 

Be sure the following MIME Types exist: 

 

 

Now the site is ready to host our files. I assume you installed the Belgian eID SDK (see prerequisites). If you did, you should have a directory like this: 'C:\Documents and Settings\<user>\My Documents\Belgium Identity Card SDK\beidlib\Java\bin'. This directory should contain the following files:

Copy these files to the directory of your newly created website. Now go to the download page of the eid-javascript-lib (http://code.google.com/p/eid-javascript-lib/downloads/list) and download the following files (also in the website's directory):

Modify both *.jnlp files, the codebase (2nd. line) should contain the address of the IIS website containing all these files. Here is an example of the beid.jnlp file:

 

<?xml version="1.0" encoding="utf-8"?>
<jnlp codebase="https://localhost:100/" href="beid.jnlp">
  <information>
    <title>Java Binding to Belgium eID Middleware 3.5</title>
    <vendor>Fedict</vendor>
    <offline-allowed/>
  </information>
  <security>
      <all-permissions/>
  </security>
  <resources os="Windows">
      <nativelib href = "beid35JavaWrapper-win.jar" />
    </resources>
    <resources os="Linux">
      <nativelib href = "beid35JavaWrapper-linux.jar" />
    </resources>
    <resources os="Mac OS X">
      <nativelib href = "beid35JavaWrapper-mac.jar" />
    </resources>
  <component-desc />
</jnlp>

 

Finally create a new file in your website called web.config containing the following (this will make sure the Java Applets are hosted correctly):

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <staticContent>
            <mimeMap fileExtension=".jnlp" mimeType="application/x-java-jnlp-file" />
        </staticContent>
    </system.webServer>
</configuration>

This should be the end result:

 

Now that we've done the heavy lifting it's time to do some work in CRM 2011. I've started by adding a new button in the Ribbon of the contact page. Since this post is focused on the eID I will not explain how to modify the Ribbon. Take a look at http://msdn.microsoft.com/en-us/library/gg309639.aspx to get started with Ribbon modifications.

This is my button on the contact page:

 

 

Now the goal is that the user clicks the button and a dialog opens. In this dialog the user will be able to read the eID card and if required store the information in the current contact. First we'll write the code for the dialog. The dialog is actually very simple. We'll just write some HTML to display the form and some Javascript to interact with it:

 

<html>
<head>
	<title>eID: Read</title>
	<script type="text/javascript" src="https://localhost:100/be_belgium_eid.js"></script>
	<script language="javascript" type="text/javascript">
	    // Initialize the reader.
	    var cardReader = new be.belgium.eid.CardReader();

	    // Bind error events.
	    function noCardPresentHandler() { window.alert("No card present!"); }
	    cardReader.setNoCardPresentHandler(noCardPresentHandler);
	    function noReaderDetectedHandler() { window.alert("No reader detected!"); }
	    cardReader.setNoReaderDetectedHandler(noReaderDetectedHandler);
	    function appletNotFoundHandler() { window.alert("Applet not found!"); }
	    cardReader.setAppletNotFoundHandler(appletNotFoundHandler);
	    function appletExceptionHandler(e) { window.alert("Error reading card!\r\nException: " + e + "\r\nPlease try again."); }
	    cardReader.setAppletExceptionHandler(appletExceptionHandler);

	    // Read the card.
	    function readCard() {
	        document.getElementById("content").value = "Please wait ...";
	        window.card = cardReader.read();
	        if (window.card != null) {
	            document.getElementById("content").value = window.card.toString();
	        } else {
	            document.getElementById("content").value = "No card returned.";
	        }
	    }

	    // Save the card to contact.
	    function saveCard() {
	        var data = { firstName: card.getFirstName1().toString(),
	            lastName: card.getSurname().toString(),
	            street: card.getStreet().toString(),
	            streetNumber: card.getStreetNumber().toString(),
	            zipCode: card.getZipCode().toString(),
	            country: card.getCountry().toString(),
	            municipality: card.getMunicipality().toString()
	        };
	        self.opener.onUpdateContact(data);
	        self.close();
	    }
	</script>
</head>
<body style='background-color: rgb(233, 237, 241)'>
<table>
	<tr>
	<td valign='top'>
		<applet code="org.jdesktop.applet.util.JNLPAppletLauncher" codebase="https://localhost:100" 
                width="140" height="200" name="BEIDAppletLauncher" id="BEIDAppletLauncher" archive="applet-launcher.jar,beid35libJava.jar,BEID_Applet.jar">
			<param name="codebase_lookup" value="false">
			<param name="subapplet.classname" value="be.belgium.beid.BEID_Applet">
			<param name="progressbar" value="true">
			<param name="jnlpNumExtensions" value="1">
			<param name="jnlpExtension1" value= "https://localhost:100/beid.jnlp">
			<param name="debug" value="false"/>
			<param name="Reader" value=""/>
			<param name="OCSP" value="-1"/>
			<param name="CRL" value="-1"/>
			<param name="jnlp_href" value="https://localhost:100/beid_java_plugin.jnlp" />
		</applet>
	</td>
	<td valign='top'>
		<textarea id='content' wrap='virtual' cols='80' rows='20'> </textarea>
		<br>
		<input title="Read Card" onclick=javascript:readCard() value="Read Card" type=button> 
		<input title="Save" onclick=javascript:saveCard() value="Save" type=button> 
	</td>
	</tr>
</table>
</body>
</html>

There isn't actually that much to it:

That's it for the dialog. I've saved the HTML page as a Web Resource and called it contacteid_page (write this down, you'll need this later on).

 

Now we still need to write some code for the Ribbon button and for updating entity. I've created a new Web Resource holding this code.

// Open the card reader page.
function readCard() {
  window.open ("https://crm2011.some.url//WebResources/new_contacteid_page", 'ReadEid', 'width=850, height=450'); 
}

// Update the contact based on the eID data.
function onUpdateContact(data)
{
   Xrm.Page.getAttribute("firstname").setValue(data.firstName);
   Xrm.Page.getAttribute("lastname").setValue(data.lastName);
   Xrm.Page.getAttribute("address1_line1").setValue(data.street + ' ' + data.streetNumber);
   Xrm.Page.getAttribute("address1_city").setValue(data.municipality);
   Xrm.Page.getAttribute("address1_postalcode").setValue(data.zipCode);
   Xrm.Page.getAttribute("address1_country").setValue(data.country);
   Xrm.Page.getAttribute("address1_stateorprovince").setValue('');
};

Again this code is pretty straightforward:

First I've opened my contact list:

 

 

Now I've opened the contact Cathan Cook and pressed the Connect eID button:

 

 

If all goes well you should see a security warning. Press Run to continue:

 

 

To read the card I press the Read button and this is the result:

 

 

To update the CRM contact press Save and you'll see that the dialog will close and your contact will be updated:

 

 

That wasn't so hard was it?

We're working with 2 websites, Javascript, Java Applets, ... and this can sometimes be a pain to troubleshoot. Here are some quick tips!

 

 

When saving the dialog to the entity you might bump into a Permission Denied error caused by the same origin policy (http://en.wikipedia.org/wiki/Same_origin_policy). To fix this issue, make sure the hostname of the dialog's URL is the same as the hostname of the CRM server. In my example I had the following URLs:

Do you see the difference? One link has 'api' in the hostname and the other one doesn't.

The following issue took me a while to troubleshoot... when pressing the Read Card button I suddenly got an Error reading card! error. And a few minutes before everything just worked!

 

 

After investigating a bit I stumbled upon the following:

<TD vAlign=top><APPLET id=BEIDAppletLauncher name=BEIDAppletLauncher archive=applet-launcher.jar,beid35libJava.jar,BEID_Applet.jar codeBase="https://localhost:100" code=org.jdesktop.applet.util.JNLPAppletLauncher width=140 height=200><PARAM NAME="_cx" VALUE="3704"><PARAM NAME="_cy" VALUE="5291"></APPLET> </TD>
<TD vAlign=top><TEXTAREA id=content wrap=virtual cols=80 rows=20> </TEXTAREA> <BR><INPUT title="Read Card" onclick=javascript:readCard() value="Read Card" type=button> <INPUT title=Save onclick=javascript:saveCard() value=Save type=button> </TD></TR></TBODY></TABLE></BODY></HTML>

It looked like the code of my HTML page (for the dialog) suddenly changed. Everything was wrapped on two lines and some parts were actually missing. The reason why this happened was because I modified the file using the Text Editor in the Web Resource page. Don't use the Text Editor because it will change your page! Always modify the file locally and upload it using the browse button.

With a bit of magic you can now use the Belgian eID in Dynamics CRM 2011. Think about the possibilities here... this is great for all healthcare, education, ... projects. Projects where you'll want the users to sign in visitors, register people, ...

Enjoy!