COMPETITIVENESS AND INNOVATION FRAMEWORK PROGRAMME
ICT Policy Support Programme (ICT PSP)
Project acronym: e-SENS
Project full title: Electronic Simple European Networked Services
ICT PSP call identifier: CIP-ICT-PSP-2012-6
ICT PSP main theme identifier: CIP-ICT-PSP-2012-6-4.1 Basic Cross Sector Services
Grant agreement n°: 325211
Integration of e-SENS LARMS functionality into Web Applications
Version :
Status :
Dissemination Level :
Work Package :
1.0
Final
Confidential in Commerce
5.2
Organisation name of lead partner for this deliverable
Author(s):
FhGFOKUS
Abstract:
Provides a detailed description of how to use the features provided by the Local Attribute Retrieval and
Mapping Service (LARMS) plugin inside of Web Applications.
WP5.2 –Use of LARMS functionality within Web Applications
1
1. Introduction
The e-SENS Local Attribute Retrieval and Mapping Service (LARMS) is an e-SENS plugin to the FutureID
Client software that provides client side functionality to access identity attributes stored on different
kinds of smartcards (e.g. eIDs or electronic health cards). This enables the integration of locally
processed smartcard functionality (here: attribute retrieval and mapping) into arbitrary locally running
applications including web applications executed by the user’s browser.
The following document provides a brief overview of how to use the plugin’s functionality with
arbitrary web applications. A short overview about the general architecture is given as well as some
code snippets that allow for a fast integration.
1.1. Future ID Overview
The FutureID Client and its plugins offer - as a part of a bigger identity management infrastructure smartcard related services running on the PC’s localhost interface. Each plugin provides a set of certain
functionality that can be accessed via a predefined URL. It is NOT usable through external network
interfaces.
PC
Future ID Client
Application
(e.g. Web
Browser)
localhost
eth
...
X
X
Figure 1: Use of FutureID Client functionality through the localhost interface
The functionality provided by the client plugins may vary in complexity, starting from rather simple
(e.g. list of supported smartcards) to more advanced tasks (e.g. retrieval and mapping of identity
attributes from different smartcards, support of electronic signatures through an OASIS DSS compliant
interface).
Remember: The content of this document only refers to the functionality of the Future ID Client
provided through the LARMS plugin (Local Attribute Retrieval and Mapping). Other functionalities
(e.g. digital signature service) will be discussed in separate documents.
The FutureID Client is a Java Application that can be executed through the means of Java Web Start.
Therefore an integration into Web Applications should be straight forward.
WP5.2 –Use of LARMS functionality within Web Applications
2
2. LARMS Architecture
The Local Attribute Retrieval and Mapping Service provides a generic interface that enables its user to
retrieve identity attributes from different smartcards in a consistent way and format without the need
to further investigate on token specific aspects.
Portugal
Client Middleware
(e.g. Cartão de
Cidadão )
(e.g FutureID client)
Authentication
Italy
(e.g. Carta Nazion ale
dei Servizi )
Identity Attribute List
Attribute Mapping
(e.g. SAML Assertion, JSON Web
Token)
Austria
Signature
(e.g. Bürgerkarte )
Cardinfo
Cardinfo
Cardinfo
files
files
files
...
Mapping
Cardinfo
Cardinfo
Instructions
files
files
Figure 2: Support for different smartcards
Specific mappings are defined for each of the supported cards. These describe which information to
retrieve from what EF (Elementary File) and how to map or convert it consistently onto a common set
of predefined attributes. An overview for the currently supported cards is given in Appendix A.
ATTRIBUTE RETRIEVAL AND MAPPING EXAMPLE
Datasource
compresses format
read
Smartcard
EF
decompress
Binary Data
(gzipped)
read
EF
EF
Attributes in
native format
native format
parse
XML
encoded data
ASN.1
encoded data
(e.g. X.509 Cert)
read
map
Identity
map
Identity
parse
map
Identity
Attribute
embed
Normalized
embed
Identity
Attributes
Attributes
Attributes
Attributes
Attributes
Attributes
BCD
encoded data
Normalized
Identity
Attributes
Attributes
Attributes
Attributes
Attributes
Attributes
parse
Attributes in
SAML or JWT
format
Attributes in
pivot format
Normalized
Identity
Attribute
SAML
Assertion /
JSON W eb
Token
embed
Figure 3: Retrieval and mapping methodology
At this time LARMS supports two different output formats that share some common properties:
1. SAML-Token
2. JASON Web Token (JWT)
The following sections will provide examples for the supported output formats.
WP5.2 –Use of LARMS functionality within Web Applications
3
2.1.SAML Token
Figure 4: Example - Belgium eID – Output Format = SAML Token
2.2.
JASON Web Token
Figure 5: Example - Belgian eID - Output Format = JWT (JWT payload decoded)
2.3.
Service Interface
The http GET based LARMS interface consist of a single operation with only one optional parameter
(format) that is used to define the required output format (saml token vs. jwt). If no parameter is
contained within the request “jwt” (Jason Web Token) is selected as the default output format. The
service listens on port 24727:
http://localhost:24727/larms/getAttributes[?format=saml|jwt]
WP5.2 –Use of LARMS functionality within Web Applications
4
3. Web Application Integration
As the functionality provided by the LARMS plugin uses common and widespread web technology (e.g.
protocols like http and formats like jwt) it is quite simple and straightforward to integrate it into
arbitrary web applications that can benefit from its presence. Nevertheless, the integration should
consider different aspects/steps that have to be coped with. These two aspects are closely related and
will often be covered together:
1. FutureID Client Presence - Check whether the FutureID client is already up and running. If
not, provide the user with some information on what it is, were to get it and how to use it.
2. UI Integration – Provide an easy to use interface to integrate the functionality into your Web
Application with minimal or hopefully no interference regarding application workflow and
layout.
The following sections will describe one possible integration option where those aspects are
considered. An online demonstration can be found under: http://jnlp.fokus.fraunhofer.de.
3.1.Example Integration
Remember: The described integration option makes use of JavaScript functionality. Therefore, it is
necessary to activate in the user’s web browser. In addition an external JavaScript library (jQuery) is
needed to support the integration.
Step 1 – Check whether the FutureID Client is up and running
Figure 6: FutureID Client not active
Figure 7: FutureID Client active
WP5.2 –Use of LARMS functionality within Web Applications
5
The left figure shows a simplified web application that could not discover an active FutureID Client.
Therefore, it provides a link, from where the user can download and start the software.
This behaviour is integrated by using a simple JavaScript Code Snippet that checks for the presence of
the client every 5 seconds.
setInterval(function() {
$.ajax({
type: 'GET',
url: "http://127.0.0.1:24727/",
crossDomain: true,
success: function(responseData, textStatus, jqXHR){
$("#sc_link").hide();
$("#sc_button").show();
},
error: function (responseData, textStatus, errorThrown){
$("#sc_button").hide();
$("#sc_link").show();
},
timeout: 3000
});
}, 5000);
The code issues an HTTP GET request to http://127.0.0.1:24727/. If a HTTP status code 200 (OK) is
received the download link (figure 6) is hidden and the form button (figure 7) displayed, if not the
other way around.
Step 2 – Integrate the functionality with your UI
The actual integration of the LARMS functionality into the web application works in a quite similar way
as the discovery of the FutureID Client. This time a HTTP GET request is issued to
http://127.0.0.1:24727/larms/getAttributes. This triggers the LARMS plugin to actually discover a
supported smartcard and retrieve/map the contained identity attributes.
function readAttributes() {
// empty form data
$("input[id='given_name_input']").attr("value", "");
$("input[id='surname_input']").attr("value", "");
var result = $.ajax({
url: 'http://localhost:24727/larms/getAttributes',
type: 'GET',
success: function(response) {
// clear old logging messages
$('#log').html('');
// split the JWT into header and payload
var res = response.split('.', 2);
var header = $.parseJSON(atob(res[0]));
var payload = $.parseJSON(atob(res[1]));
// set form input fields
$("input[id='given_name_input']").attr("value",
payload['http://www.stork.gov.eu/1.0/givenName']);
$("input[id='surname_input']").attr("value", payload['http://www.stork.gov.eu/1.0/surname']);
},
error: function(responseData, status, text) {
$('#log').html('');
if (responseData.status == 400) {
$('#log').append('Invalid request (e.g. wrong operation, unknown parameter)');
WP5.2 –Use of LARMS functionality within Web Applications
6
} else if (responseData.status == 500) {
$('#log').append('Problems processing the request (e.g. unknown card-type, no card
inserted)');
} else
$('#log').append('Unknown error. FutureID client could not be reached.');
}
})
}
Remember: A complete Listing of the sample web site is provided in Annex B.
When
Figure 8: Attributes retrieved from an Italian eID (Carta Regionale dei Servizi)
WP5.2 –Use of LARMS functionality within Web Applications
7
4. Appendix A
Remember: Some of the listed attributes might be subject to minor changes as no official review of the
developed mapping policies was carried out so far.
4.1.Austria – Austrian ecard
http://www.futureid.eu/attributes/common/cardIssuerCountry
http://www.futureid.eu/attributes/common/cardType
http://www.stork.gov.eu/1.0/givenName
http://www.stork.gov.eu/1.0/surname
http://www.stork.gov.eu/1.0/dateOfBirth
http://www.futureid.eu/attributes/common/healthInsuranceId
http://www.futureid.eu/attributes/common/ehicId
http://www.futureid.eu/attributes/common/ehicValidity
http://www.stork.gov.eu/1.0/gender
http://www.futureid.eu/attributes/common/healthInsuranceCompanyId
4.2.
Belgium – Belgian eID
http://www.futureid.eu/attributes/common/cardIssuerCountry
http://www.futureid.eu/attributes/common/cardType
http://www.futureid.eu/attributes/common/cardId
http://www.futureid.eu/attributes/common/cardValidFrom
http://www.futureid.eu/attributes/common/cardValidTo
http://www.stork.gov.eu/1.0/givenName
http://www.stork.gov.eu/1.0/surname
http://www.stork.gov.eu/1.0/dateOfBirth
http://www.futureid.eu/attributes/common/healthInsuranceId ???
http://www.stork.gov.eu/1.0/gender
4.3.
Germany – German Electronic Health Card
http://www.futureid.eu/attributes/common/cardIssuerCountry
http://www.futureid.eu/attributes/common/cardType
http://www.futureid.eu/attributes/common/cardId
http://www.stork.gov.eu/1.0/givenName
http://www.stork.gov.eu/1.0/surname
http://www.stork.gov.eu/1.0/dateOfBirth
http://www.futureid.eu/attributes/common/healthInsuranceId
http://www.stork.gov.eu/1.0/gender
http://www.stork.gov.eu/1.0/title
http://www.stork.gov.eu/1.0/canonicalResidenceAddress/streetName
http://www.stork.gov.eu/1.0/canonicalResidenceAddress/streetNumber
http://www.stork.gov.eu/1.0/canonicalResidenceAddress/postalCode
http://www.stork.gov.eu/1.0/canonicalResidenceAddress/town
http://www.stork.gov.eu/1.0/canonicalResidenceAddress/countryCodeAddress
WP5.2 –Use of LARMS functionality within Web Applications
8
http://www.stork.gov.eu/1.0/textResidenceAddress
http://www.futureid.eu/attributes/common/healthInsuranceCompanyId
4.4.
Italy - Carta Regional dei Servizi
http://www.futureid.eu/attributes/common/cardIssuerCountry
http://www.futureid.eu/attributes/common/cardType
http://www.stork.gov.eu/1.0/givenName
http://www.stork.gov.eu/1.0/surname
http://www.stork.gov.eu/1.0/dateOfBirth
http://www.futureid.eu/attributes/common/healthInsuranceId ???
http://www.stork.gov.eu/1.0/gender
http://www.stork.gov.eu/1.0/fiscalNumber
http://www.futureid.eu/attributes/common/healthInsuranceCompanyName
http://www.futureid.eu/attributes/common/healthInsuranceCompanyId
WP5.2 –Use of LARMS functionality within Web Applications
9
5. Annex B
<!DOCTYPE html>
<html>
<head>
<title>Search Patient</title>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<link rel="stylesheet" href="css/bootstrap.min.css"/>
<script src="js/jquery-1.10.2.js"></script>
<script type="text/javascript">
$(document).ready(function() {
// Hide download link and retrieve button until the status of the FutureID Client is discovered
$("#sc_button").hide();
$("#sc_link").hide();
getStatus();
});
setInterval(function() {
getStatus();
}, 5000);
function getStatus() {
$.ajax({
type: 'GET',
url: "http://127.0.0.1:24727/",
crossDomain: true,
success: function(responseData, textStatus, jqXHR) {
// clear logging information and show form button
$('#log').html('');
$("#sc_link").hide();
$("#sc_button").show();
},
error: function(responseData, textStatus, errorThrown) {
// clear logging information and show download link
$('#log').html('');
$("#sc_button").hide();
$("#sc_link").show();
// handle request errors
if (responseData.status == 400) {
$('#log').append('Invalid request (e.g. wrong operation, unknown parameter)');
} else if (responseData.status == 500) {
$('#log').append('Problems processing the request.');
} else
// will be executed if no FutureID Client listens on the port
$('#log').append('The FutureID Client seems not to be active! The retrieval of smartcard
identity attributes is therefore not possible. Please download and start the client using the above link.');
},
timeout: 3000
});
}
function readAttributes() {
// empty form data
$("input[id='given_name_input']").attr("value", "");
$("input[id='surname_input']").attr("value", "");
$("input[id='street_input']").attr("value", "");
$("input[id='id_input']").attr("value", "");
$("input[id='city_input']").attr("value", "");
$("input[id='zip_input']").attr("value", "");
$("input[id='sex_input']").attr("value", "");
$("input[id='birthdate_input']").attr("value", "");
$("input[id='fc_input']").attr("value", "");
var result = $.ajax({
url: 'http://localhost:24727/larms/getAttributes',
type: 'GET',
success: function(response) {
// clear old logging messages
$('#log').html('');
WP5.2 –Use of LARMS functionality within Web Applications
10
// split the JWT into header and payload
var res = response.split('.', 2);
var header = $.parseJSON(atob(res[0]));
var payload = $.parseJSON(atob(res[1]));
$("input[id='given_name_input']").attr("value",
payload['http://www.stork.gov.eu/1.0/givenName']);
$("input[id='surname_input']").attr("value", payload['http://www.stork.gov.eu/1.0/surname']);
var streetName = payload['http://www.stork.gov.eu/1.0/canonicalResidenceAddress/streetName']
var
streetNumber
=
payload['http://www.stork.gov.eu/1.0/canonicalResidenceAddress/streetNumber'];
if (typeof streetName != 'undefined') {
var street = streetName + " " + streetNumber;
} else {
var street = "";
}
$("input[id='street_input']").attr("value", street);
$("input[id='zip_input']").attr("value",
payload['http://www.stork.gov.eu/1.0/canonicalResidenceAddress/zipcode']);
$("input[id='city_input']").attr("value",
payload['http://www.stork.gov.eu/1.0/canonicalResidenceAddress/town']);
$("input[id='sex_input']").attr("value", payload['http://www.stork.gov.eu/1.0/gender']);
$("input[id='fc_input']").attr("value", payload['http://www.stork.gov.eu/1.0/fiscalNumber']);
var identifier = payload['http://www.futureid.eu/attributes/common/healthInsuranceId'];
var selector = Object.keys(identifier)[0];
var short_selector = selector.split(":")[2];
var request = "input[title='" + short_selector + "']";
$("input[id='id_input']").attr("value", identifier[selector]);
$(request).attr("value", identifier[selector]);
var date = payload['http://www.stork.gov.eu/1.0/dateOfBirth'];
$("input[id='birthdate_input']").attr("value",
date.slice(0,
date.slice(8, 10));
4)
+
date.slice(5,
7)
+
},
error: function(responseData, status, text) {
$('#log').html('');
if (responseData.status == 400) {
$('#log').append('Invalid request (e.g. wrong operation, unknown parameter)');
} else if (responseData.status == 500) {
$('#log').append('Problems processing the request (e.g. unknown card-type,
no
card
inserted)');
} else
$('#log').append('Unknown error. FutureID client could not be reached.');
}
})
}
</script>
</head>
<body>
<div class="container">
<div class="row">
<div class="col-lg-4 col-md-6 col-sm-8 col-xs-12 col-lg-offset-4 col-md-offset-3 col-smoffset-2" style="margin-top: 20px">
<a href="http://www.fokus.fraunhofer.de/ehealth">
<img src="img/fokus.png" alt="Fraunhofer FOKUS">
</a>
<div class="panel panel-default" style="margin-top: 20px">
<div class="panel-heading"><b>Smartcard information</b> <br/>(currently supported:
de_egk_g1, at_ecard_g3, it_cns/crs, be_eid)</div>
<div class="panel-body">
<div id="search_form_div">
<div class="form-group">
<label>ID</label>
<input class="form-control" id="id_input" type="text"/>
</div>
<div class="form-group">
<label>Surname</label>
<input class="form-control" id="surname_input" type="text"/>
</div>
<div class="form-group">
<label>Given name</label>
WP5.2 –Use of LARMS functionality within Web Applications
11
<input class="form-control" id="given_name_input" type="text"/>
</div>
<div class="form-group">
<label>Street name & number</label>
<input class="form-control" id="street_input" type="text"/>
</div>
<div class="form-group">
<label>ZIP</label>
<input class="form-control" id="zip_input" type="text"/>
</div>
<div class="form-group">
<label>City</label>
<input class="form-control" id="city_input" type="text"/>
</div>
<div class="form-group">
<label>Birthdate</label>
<input class="form-control" id="birthdate_input" type="text"/>
</div>
<div class="form-group">
<label>Gender</label>
<input class="form-control" id="sex_input" type="text"/>
</div>
<div class="form-group">
<label>Fiscal code</label>
<input class="form-control" id="fc_input" type="text"/>
</div>
<button
class="btn
btn-default"
id="sc_button"
onclick="readAttributes()">Read from smartcard</button>
<a
id="sc_link"
target="_blank"
href="http://jnlp.fokus.fraunhofer.de/openecard.jnlp">Download Future ID Client</a>
</div>
</div>
</div>
</div>
</div>
<div class="row">
<div class="col-lg-4 col-md-6 col-sm-8 col-xs-12 col-lg-offset-4 col-md-offset-3 col-smoffset-2" style="color: red" id="log"><!-- log area --></div>
</div>
</div>
</body>
</html>
WP5.2 –Use of LARMS functionality within Web Applications
12