Post on 07-Jul-2020
Technical Integration – Cookbook
DocConsumer version
Contact: eBoxIntegration@smals.be
Last update: 2018/10/03
Version 1.0
e-Box Enterprise – technical integration: cookbook DocConsumer v1.0 page 2
Contents
Versions history ........................................................................................................................................ 2
Introduction .................................................................................................................................................. 3
Discover e-Box Enterprise (user view) ................................................................................................. 3
The federated model of the Enterprise e-Box (technical view) ........................................................ 4
Diagram: high-level technical view .................................................................................................... 4
Glossary ..................................................................................................................................................... 5
Discover the RESTful ebox/enterprise API ....................................................................................... 6
Diagram: API discovering – access to ebox resources ................................................................... 6
DocConsumer Onboarding process .......................................................................................................... 7
1. Onboarding request ..................................................................................................................... 7
2. Configuration (OAuth) ............................................................................................................... 7
3. Technical integration ................................................................................................................... 7
DocConsumer technical integration ...................................................................................................... 8
Points of attention for DocConsumer Integration ......................................................................... 8
Annexes ....................................................................................................................................................... 10
Annex 1: X.509 certificate ..................................................................................................................... 10
Annex 2: ProviderRegistry integration ................................................................................................ 11
Technical information about the ProviderRegistry ....................................................................... 11
Annex 3: OAuth2 Authorization Server onboarding ....................................................................... 11
Technical information about the OAuth2 Authorization Server from Social Security ........... 11
Java example (JUnit Test) ................................................................................................................. 12
Annex 4: References .............................................................................................................................. 14
Versions history Version Status Date Author Changes
0.1 Draft 2018-05 Antoine MOULART First draft
0.2 Draft 2018-05-14 Antoine MOULART Peer-review avec Kevin NOPPE
0.3 Draft 2018-06 Antoine MOULART English Translation
0.4 Draft 2018-08-03 Antoine MOULART Review before final proposal
0.5 Draft 2018-08 Antoine MOULART Final first proposal
0.6 Draft 2018-08-21 Antoine MOULART Add points of attention for technical integrations
0.7 Draft 2018-09 Antoine MOULART Split onboarding processes + update after internal review
1.0 First version 2018-10-03 Antoine MOULART Info. abourt OAuth2 Authorization Server onboarding.
e-Box Enterprise – technical integration: cookbook DocConsumer v1.0 page 3
Introduction
This e-Box Enterprise cookbook is intended for technical teams who, on behalf of
their organization (user company, Institution, Partner platform...) are in charge of a technical
integration with the e-Box system.
Several types of integration are possible; this cookbook will focus on the e-Box
DocConsumer integration.
When an aspect is already described elsewhere, this cookbook will not duplicate the information,
but will indicate where exactly to find it.
Discover e-Box Enterprise (user view)
The e-Box Enterprise is the secure electronic mailbox, available for free for any company in
Belgium. The classic user-interface of the e-Box Enterprise takes the form of a Java web-
application:
The user help for the web interface of the e-Box Enterprise is not the subject of this
cookbook. For documentation about the classic web application, concerning the activation of the
e-Box and the features, we refer you to the links below:
Access to e-Box Enterprise on the Social Security Portal:
e-Box Enterprise – technical integration: cookbook DocConsumer v1.0 page 4
o FR : https://www.socialsecurity.be/site_fr/general/helpcentre/ebox/transit.htm
o NL : https://www.socialsecurity.be/site_nl/general/helpcentre/ebox/transit.htm
Information website about e-Box Enterprise:
o FR : http://www.tousaunumerique.be/fr/index.html
o NL : http://www.samendigitaal.be/nl/index.html
The federated model of the Enterprise e-Box (technical view)
The diagram below shows the high-level technical view of the federated model of the e-Box
Enterprise. The federated view indeed integrates several message sources (DocProviders), each
accessible via a MessageRegistry (WS REST) respecting the same contract (ebox / common
enterprise API).
In addition, some institutions (DocSenders) can continue to publish their messages to a
DocProvider who will make them available for the federated e-Box.
Finally, a company (DocConsumer) can directly retrieve the content of its e-Box via a technical
integration with each MessageRegistry offering this type of access. Such integration is interesting
for a (large) company that does not want to use the traditional user-interface, and wants to
automate the unloading and management of its e-Box in its internal system.
See also Glossary below.
Diagram: high-level technical view
e-Box Enterprise – technical integration: cookbook DocConsumer v1.0 page 5
Glossary
Term Definition
API Application Programming Interface, of the RESTful type in this model, which is defined as a common contract for all actors of the e-Box system.
Authorization Server
Authorization server that delivers the Tokens to the client (DocConsumer). These Tokens will then be used in order to call the different Message Registries.
DocConsumer Enterprise (private/public company) that retrieves the content of its own e-Box through a backend integration (WS call) rather than consulting the web application in a conventional way.
DocProvider Organization that hosts its documents on its own infrastructure, and makes them accessible to the Enterprise e-Box, by implementing its MessageRegistry (WS REST), that respects the common API and the required security standards.
DocSender Organization that publishes documents in a classic way to the e-Box service of the Social Security, and lets the responsibility to this DocProvider itself of storing and securing access to documents. A DocSender is in practice identified by the BCE / KBO number of its organization, and an application identifier (URN), which is typically an online service for businesses (e.g. Sigedis - DB2P application).
Message-Registry
Web service allowing access to the messages of a DocProvider. Each RESTful WS must respect the common API, and support the defined security standards.
META-API The META-API corresponds to several 'technical' operations that each DocProvider can use to describe the degree of implementation of the 'business' operations, and indicate which elements are implemented or not (example: sorting or optional query-param ...).
Provider-Registry
Technical web service that lists the different DocProviders available, with the URLs of each MessageRegistry. The ProviderRegistry is therefore seen as the directory of all accessible message sources.
e-Box Enterprise – technical integration: cookbook DocConsumer v1.0 page 6
Discover the RESTful ebox/enterprise API
The RESTful ebox/enterprise API is documented via the OpenAPI v2 Specification (OAS)
[aka Swagger] standard. This specification is available in the .yaml format. In addition to the
Swagger, the resource description is also detailed in the form of JSON-Schemas, in .json format.
The ebox/enterprise API is completed by a META-API that specifically describes the optional
elements of the API, so that each DocProvider can indicate whether or not these elements are
implemented in its MessageRegistry.
Public versions of the API and JSON-Schemas are available through the EBOX Members Area:
https://members.intranext.smals.be/projects/EBOX/default.aspx
There is also published a presentation (.pptx format) of the API with different examples and
diagrams to better visualize access to resources.
Diagram: API discovering – access to ebox resources
e-Box Enterprise – technical integration: cookbook DocConsumer v1.0 page 7
DocConsumer Onboarding process
1. Onboarding request To become a new e-Box Enterprise DocConsumer, your enterprise needs to send the following
documents to eBoxIntegration@smals.be.
The public part of the certificate you will use;
The completed document “e-Box DocConsumer request form and terms of use”, signed
by a Legal Representative of your company.
2. Configuration (OAuth) Once your request is completed and validated, the e-Box team will configure your enterprise as a
new OAuth client, to allow the recovery of your AccessToken on the OAuth2 Authorization Server
from the Social Security.
3. Technical integration You can then call the Authorization Server to get your AccessToken. With this token, you can call
the different Message Registries, listed in the Provider Registry, in order to retrieve all your e-Box data.
e-Box Enterprise – technical integration: cookbook DocConsumer v1.0 page 8
DocConsumer technical integration
Integrate the Social Security Authorization Server to obtain its AccessToken;
- Have a certificate for your enterprise (please see Annex 1!).
Call the ProviderRegistry to retrieve the list of the different MessageRegistries, for each
DocProvider.
Call each MessageRegistry to retrieve all the e-Box data for your enterprise.
Points of attention for DocConsumer Integration Certificate type you can use to integrate the Authorization Server
X.509 certificate with expected format (please see Annex 1!).
From how many documents received on average can your enterprise ask to become a DocConsumer in order to integrate the WebService?
There is no specific threshold from which it is possible to become a DocConsumer. In some enterprise, it will start to be interesting after several hundreds of documents, for others, after a few thousands…
Responsibility to consult all the documents available for your enterprise
Once your enterprise is integrated as a DocConsumer, you must be careful to regularly retrieve the contents of your e-Box, to download and process all received documents.
e-Box web application remains the official channel, in case of technical problem for example
Becoming a DocConsumer does not allow you to ignore e-Box communications in case of technical problems for example. In such a situation, the e-Box Enterprise web application remains available as the official e-Box channel, and always allows you to consult your documents.
Responsibility to manage access to
documents in your enterprise
When you retrieve your e-Box content by calling the WebService, you can consequently download all the available documents. Pay attention of dispatching the documents to the right people inside your enterprise. You’re responsible to manage the data-access in this integration type.
Responsibility about the credentials of
your enterprise (Certificate,
AccessToken…)
As a DocConsumer, your enterprise will need a certificate in order to retrieve (from the Authorization Server) the AccessToken needed to call the WS. You are responsible for both your certificate and your tokens, which are to be considered as the keys of the e-Box of your enterprise. So be careful who can use them and under which conditions.
OAuth Scopes you need to ask When requesting your AccessToken to the Authorization Server, the necessary scopes will
e-Box Enterprise – technical integration: cookbook DocConsumer v1.0 page 9
automatically be considered. As a DocConsumer, you will get the necessary scopes to perform all the possible requests to manage your e-Box:
- summary_own_ebox (to get the summary of your e-Box);
- messages_full (to get and perform authorized actions on all messages in your ebox);
- reference_data (to retrieve the details of the messageTypes, senderOrganizations, and senderApplications).
Please see the dedicated section for the Authorization Server onboarding.
Your organization has to manage several e-Box for different BCE/KBO numbers. How does the DocConsumer integration work in this case?
The e-Box of an enterprise is always identified by its BCE/KBO number. For multiple e-Box, it’s necessary to ask an e-Box client integration as DocConsumer for each BCE/KBO number.
Managing several e-Box for different BCE/KBO numbers: can you use only one certificate?
You need a distinct ‘DocConsumer OAuth client’ for each BCE/KBO number, but each client can use the same certificate. Attention, each client will have to retrieve its own AccessToken (linked to a specific BCE/KBO number thus). So it’s important to manage your different AccessTokens, in order to use the good one for the appropriate e-Box.
e-Box Enterprise – technical integration: cookbook DocConsumer v1.0 page 10
Annexes
Annex 1: X.509 certificate
Attention, you need a distinct certificate for each work environment (Acceptance,
Production).
The type of certificate requested must be a non-public trust (applicative) certificate.
o Trusted CA: QuoVadis Trust Anchor Issuing CA G2;
The order for a new certificate must be made via info.be@quovadisglobal.com
o The mail must be sent in Dutch or English.
The certificate format MUST respect the following structure:
X509
QuoVadis
Value Comment / example
C BE C = BE
O ORGANIZATIONNAME The legal name of your organization. Example:
O = SMALS
OU Belgian Federal
Government
OU = Belgian Federal Government
OU urn:be:fgov:kbo-
bce:organization:cbe-
number:xxxxxxxxxx
Example for institution with CBE 01234567689 this OU must
be
OU = urn:be:fgov:kbo-bce:organization:cbe-
number:0123456789
OU ACC Possible values {PRD, ACC, INT}. Example :
OU = ACC
CN ApplicationID-URN-from-
request-document
Example for application werkkaart/carte de travail
(RVA/Onem), CN must be
CN = employment:job-attest:werkkaart
L Brussels The city where your organization is located. Example:
L = Sint-Gillis
S Brussel-Hoofdstad The state/region where your organization is located. This
shouldn't be abbreviated. Example:
S = Brussel-Hoofdstad
If necessary, the CSR can be sent to us for validation before the application at QuoVadis.
! Do not forget to have your “e-Box DocConsumer onboarding form” validated (by
eBoxIntegration@smals.be) before ordering your certificates to QuoVadis.
e-Box Enterprise – technical integration: cookbook DocConsumer v1.0 page 11
Annex 2: ProviderRegistry integration
The ProviderRegistry is a technical web service that lists the different DocProviders available, with the
URLs of each MessageRegistry. The ProviderRegistry is therefore seen as the directory of accessible
message sources.
As a DocConsumer, you have to use the ProviderRegistry in order to retrieve the list of DocProviders,
the URLs to query and know the version of the API corresponding to each WS.
Technical information about the ProviderRegistry Not yet available
Annex 3: OAuth2 Authorization Server onboarding
This annex provides the necessary explanation to perform the OAuth 2.0 aspects of the
integration as a DocConsumer. This document will not cover the OAuth 2.0 protocol or the
onboarding procedure. You can get more information directly from the spec or from the some of
the numerous internet resources available.
As a DocConsumer you will request OAuth 2.0 tokens, in order to access secured WS in the
name of your enterprise.
Technical information about the OAuth2 Authorization Server from Social Security
In this section, you will find how to call the Authorization and the e-Box Message Registry.
1) Request your AccessToken to the Authorization Server
OAuth Authorization Server URL (ACC)
https://services-acpt.socialsecurity.be/REST/oauth/v3/token
Audience (ACC) https://oauthacc.socialsecurity.be
OAuth Authorization Server URL (PRD)
https://services.socialsecurity.be/REST/oauth/v3/token
Audience (PRD) https://oauth.socialsecurity.be
OAuth Grant Client Credentials
Your client-id See your Onboarding form
Your X.509 certificate (private-key + password)
See Annex-1 + your Onboarding form
Scopes you need to ask scope:document:management:consult:ws-eboxrestentreprise:summaryownebox
scope:document:management:consult:ws-eboxrestentreprise:messagesfull
scope:document:management:consult:ws-eboxrestentreprise:referencedata
e-Box Enterprise – technical integration: cookbook DocConsumer v1.0 page 12
2) Request your e-Box Data to the Message Registry
e-Box SocSec MessageRegistry URL (ACC)
https://services-acpt.socialsecurity.be/REST/ebox/enterprise/v1
e-Box SocSec MessageRegistry URL (PRD)
https://services.socialsecurity.be/REST/ebox/enterprise/v1
Path to your ebox resource(s)
/ebox resource protected by the scope: scope:document:management:consult:ws-eboxrestentreprise:summaryownebox /ebox/messages /ebox/messages/$messageId/ /ebox/messages/$messageId/attachments /ebox/messages/$messageId/attachments/$attachmentId/ /ebox/messages/$messageId/attachments/$attachmentId/content resources protected by the scope: scope:document:management:consult:ws-eboxrestentreprise:messagesfull
/referenceData/messageTypes /referenceData/senderOrganizations /referenceData/senderApplications resources protected by the scope: scope:document:management:consult:ws-eboxrestentreprise:referencedata
AccessToken (via Authorization Header)
Retrieved from your previous call to the Authorization Server.
Java example (JUnit Test) import java.security.KeyStore; import java.security.PrivateKey; import java.security.cert.X509Certificate; //...
public class AbstractDemoEboxPilote { //Auth.Server ACC public static final String AUDIENCE = "https://oauthacc.socialsecurity.be"; public static final String OAUTH_SERVER_URL = "https://services-acpt.socialsecurity.be/REST/oauth/v3/token"; //client_id public static final String CLIENT_ID_EBOX_PILOTE = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"; //certificate public static final String P12_FILE = “zzzzzzzzzzzzzzzzzzzzz.p12"; public static final String P12_PASSWORD = "zzzzzzzz"; public static final String ALIAS_NAME = " zzzzzzzzzzzzzzzzzzzzz "; public static final String ALIAS_PASSWORD = P12_PASSWORD; public static PrivateKey privateKey; public static X509Certificate certificate; //EBOX MessageRegistry ACC public final static String RESOURCE_SERVER_EBOX = "https://services-acpt.socialsecurity.be/REST/ebox/enterprise/v1"; //EBOX scopes public static final String SUMMARYOWNEBOX = "scope:document:management:consult:ws-eboxrestentreprise:summaryownebox"; public static final String MESSAGESFULL = "scope:document:management:consult:ws-eboxrestentreprise:messagesfull"; public static final String REFERENCEDATA = "scope:document:management:consult:ws-eboxrestentreprise:referencedata";
e-Box Enterprise – technical integration: cookbook DocConsumer v1.0 page 13
@BeforeClass public static void init() throws Exception { KeyStore keyStore = KeyStore.getInstance("PKCS12"); InputStream is = ExampleJAXRSFilter.class.getResourceAsStream(P12_FILE); keyStore.load(is, P12_PASSWORD.toCharArray()); privateKey = (PrivateKey) keyStore.getKey(ALIAS_NAME, ALIAS_PASSWORD.toCharArray()); certificate = (X509Certificate) keyStore.getCertificate(ALIAS_NAME); } }
//... import com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider; import com.nimbusds.jose.JWSAlgorithm; import com.nimbusds.jose.JWSHeader; import com.nimbusds.jose.crypto.RSASSASigner; import com.nimbusds.jwt.JWTClaimsSet; import com.nimbusds.jwt.SignedJWT; import com.nimbusds.oauth2.sdk.*; import com.nimbusds.oauth2.sdk.auth.PrivateKeyJWT; import javax.ws.rs.client.Client; import javax.ws.rs.client.ClientBuilder; import java.net.URI; import java.security.SecureRandom;
public class DocConsumerPilote extends AbstractDemoEboxPilote { @Test public void simpleDemo() throws Exception { Client client = ClientBuilder .newClient() .register(JacksonJsonProvider.class) .register(new LoggingFilter() ); ResourceDemoResponse response = client// .target(RESOURCE_SERVER_EBOX)// .path("/ebox/messages")// .request() .header("Authorization", getAuthorizationHeader())// .get(ResourceDemoResponse.class); System.out.println(response); } private String getAuthorizationHeader() throws Exception { JWSHeader jwtJwsHeader = new JWSHeader(JWSAlgorithm.RS256); JWTClaimsSet jwtClaimsSet = new JWTClaimsSet.Builder() .audience(AUDIENCE) .jwtID(getSecureID()) .issuer(CLIENT_ID_EBOX_PILOTE) .issueTime(new Date(System.currentTimeMillis())) .expirationTime(new Date(System.currentTimeMillis() + 5000L)) .subject(CLIENT_ID_EBOX_PILOTE) .build(); SignedJWT jwt = new SignedJWT(jwtJwsHeader, jwtClaimsSet); jwt.sign(new RSASSASigner(privateKey)); System.out.println("Token for authentication :" + jwt.serialize()); // create request to obtain access_token TokenRequest request = new TokenRequest( new URI(OAUTH_SERVER_URL),// new PrivateKeyJWT(jwt), //JWT signed with RSA Key new ClientCredentialsGrant(),// new Scope(SUMMARYOWNEBOX, MESSAGESFULL, REFERENCEDATA) ); TokenResponse response = TokenResponse.parse(request.toHTTPRequest().send()); if (response.indicatesSuccess()) { AccessTokenResponse successResponse = (AccessTokenResponse) response; return successResponse.getTokens().getBearerAccessToken().toAuthorizationHeader();
e-Box Enterprise – technical integration: cookbook DocConsumer v1.0 page 14 } else { // We got an error response... TokenErrorResponse errorResponse = (TokenErrorResponse) response; System.out.println(String.format("Fail with httpCode \"%s\" and error_description \"%s\"", errorResponse.getErrorObject().getHTTPStatusCode(), errorResponse.getErrorObject().getDescription())); throw new RuntimeException("Access token request failed"); } } private String getSecureID() { SecureRandom random = new SecureRandom(); byte bytes[] = new byte[20]; random.nextBytes(bytes); return Arrays.toString(bytes); } }
Annex 4: References
G-Cloud REST guidelines: https://www.gcloud.belgium.be/rest/
OpenAPI v2 Specification (OAS) [aka Swagger] standard: https://swagger.io/specification/v2/
OAuth2 specification: https://tools.ietf.org/html/rfc6749
Website with technical information about e-Box Enterprise:
https://members.intranext.smals.be/projects/EBOX/default.aspx [ask access to
eBoxIntegration@smals.be]