EidIf you ever have to implement the eID for a website, you will quickly realize that there is little to no information to be found on the Fedict website itself. Especially if you want to integrate eID in ASP.NET MVC. This means you’re on the brink of a giant quest for information! This is why  this blog-post can help, so you don’t have to wander around the internet for days and days to gather the little information you can find. Or even worse, to wait endlessly for a reply to your emails from the Fedict helpdesk.

The easiest way of implementing the eID would be to use the services of econtract.be. This, however, is not free if you exceed a certain limit of requests. When the company you work for wants to roll its own requests, a different approach is needed.

This post will contain directions to do a simple implementation of a fedlet with which you can log in and/or out using your (Belgian) eID. This blog post does not deal with the paperwork needed prior to the implementation of the application.

First of all, you need to know that Fedict is running an OpenAM version through which the authentication runs. You will need a .NET Fedlet so that your application can take the necessary steps to make a connection with the Fedict server. The fedlet that is used in this project can be downloaded through this link. The download contains the fedlet and a sample app, which will already get you far. However, in order to achieve a successful implementation you will need to thoroughly study the example requests contained in this document.


To reduce clutter in this post,  a sample application (EIDMVCSample) with the Fedict specifics included has been made. You can download the sample here. Please bear in mind that, after you have made the correct configuration changes, this sample app will never work on localhost since Fedict will try to send a response to a user defined url, which is all part of the login/logout process. This makes debugging a little harder. Luckily, when you deploy the sample app on a server, you can find useful information in the event viewer, such as the requests made and the responses received.

To let the sample app work for you, all you need to do is make changes to the configuration files present in the app_data folder. (Note: when working with regular asp.net and aspx files, the app_data folder should be on the same level as the pages where you create and receive your requests and responses.)

The xml files in this folder contain all of the configuration fields necessary to establish a communication with the Fedict server. You should consider the following parameters and update them with the information you have received from Fedict when you applied for a subscription. So look through all the xml and cot files in the app_data folder in my sample app and replace these dummy values with the correct ones.

FEDLET_COT The name of the Circle Of Trust that Fedict gave to you. This is most likely the same as the FEDLET_ENTITY_ID.
IDP_ENTITY_ID The name of the identity provider issued by the government:
Integration: https://idp.iamfas.int.belgium.be/fas
Production: https://idp.iamfas.belgium.be/fas
FEDLET_ENTITY_ID The name of the service provider (your own application).
FEDLET_DEPLOY_URI The root url of your application.
FEDLET_CERTIFICATE_NAME The ‘Friendly name’ of the certificate installed on the server on which your application will be hosted.
FEDLET_CERTIFICATE The value you see when you open the *.crt file in notepad or some other text editor. (Without the begin and end tags of course)

Please be advised that production and integration values are different!


There are some Fedict specific fields that are different/extra than the ForgeRock sample app. We’ll discuss these below.

Idp.xml

You will not find this xml file in the sample provided by ForgeRock. This is because this file should be generated one time by the identity provider. You can acquire this file through the following links:

Integration: https://idp.iamfas.int.belgium.be/fas/saml2/jsp/exportmetadata.jsp
Production: https://idp.iamfas.belgium.be/fas/saml2/jsp/exportmetadata.jsp

idp-extended.xml

Here you will find an attribute called ‘wantlogoutRequestSigned’. This has to be set to true.

<Attribute name="wantLogoutRequestSigned">
<Value>true</Value>
</Attribute>

sp.xml

To be able to sign the logoutrequest, the sp.xml has to be adjusted so the certificate key is contained in the .xml like this:

<EntityDescriptor entityID="FEDLET_ENTITY_ID" mlns="urn:oasis:names:tc:SAML:2.0:metadata">
<SPSSODescriptor AuthnRequestsSigned="false" WantAssertionsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol"> <KeyDescriptor use="signing">
<ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#"> <ds:X509Data> <ds:X509Certificate>
<TODO: Replace with the key of the certificate installed on your server.></TODO>
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</KeyDescriptor>
...

sp-extended.xml

To sign the logout request, the attribute ‘wantLogoutRequestSigned’ has to be set to true

<Attribute name="wantLogoutRequestSigned">
<Value>true</Value>
</Attribute>

Code adjustments compared to the ForgeRock sample app

TIP: A handy tool to view the SAML requests originating from your application is the SAML Tracer plugin for firefox.

Login (AuthenticationController.Login)

To create a correct login request, the following parameters need to be added:

// Store parameters for initializing SSO NameValueCollection parameters = Saml2Utils.GetRequestParameters(System.Web.HttpContext.Current.Request); //Binding could also be HttpArtifactProtocolBinding or HttpSoapProtocolBindin.
parameters[Saml2Constants.Binding] = Saml2Constants.HttpPostProtocolBinding;
parameters[Saml2Constants.AllowCreate] = "true";
parameters[Saml2Constants.AuthnContextClassRef] = "urn:be:fedict:iam:fas:citizen:eid";
parameters[Saml2Constants.IdpEntityId] = "https://idp.iamfas.int.belgium.be/fas";

Logout (AuthenticationController.LogOff)

Following parameters are important for the logout request:

NameValueCollection parameters = new NameValueCollection();
parameters[Saml2Constants.AllowCreate] = "true";
parameters[Saml2Constants.AuthnContextClassRef] = "urn:be:fedict:iam:fas:citizen:eid";
parameters[Saml2Constants.SessionIndex] = Session[Constants.SessionIndex].ToString();
parameters[Saml2Constants.SubjectNameId] = Session[Constants.SubjectNameId].ToString();
parameters[Saml2Constants.Binding] = Saml2Constants.HttpPostProtocolBinding;
parameters[Saml2Constants.RelayState] = "http://localhost/Home/Index";

The SessionIndex and the SubjectNameId are two parameters that you will find in the response when logging in. You need to store these in the session or something similar so you can construct the correct logout request. (you will find the sample implementation in the controller action ‘SingleSignIn’ )

The RelayState is the redirect url to which your own code can redirect you after you process the logout response received from Fedict (See controller action ‘SingleSignOut’)

Some Pitfalls

Requests

Problems I encountered were mainly malformed requests. With the above code, all should be fine. If you still encounter problems, you can send an email to the Fedict helpdesk. Be sure to include your request, which you can copy from the SAML tracer, in your message. Provided some patience they will always come up with an answer.

Certificate

The certificate on the server should be installed as ‘local computer’. It is important that this certificate is imported through the MMC console. If you do this through IIS, the installation of the certificate will not be 100% complete which will result in errors when sending a request or receiving a response. You should also make sure that the network_service user has sufficient access rights for the certificate. An indication for this particular scenario is the “Key not found” error message.

Download the sample app here.