technical integration cookbook - e-box enterprise · 2020-04-17 · e-box enterprise – technical...

Technical Integration – Cookbook

DocConsumer version

Contact: [email protected]

Last update: 2018/10/03

Version 1.0

mailto:[email protected]

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.


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:


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

https://www.socialsecurity.be/site_fr/general/helpcentre/ebox/transit.htm

https://www.socialsecurity.be/site_nl/general/helpcentre/ebox/transit.htm

http://www.tousaunumerique.be/fr/index.html

http://www.samendigitaal.be/nl/index.html


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.


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

https://swagger.io/specification/v2/



DocConsumer Onboarding process

1. Onboarding request To become a new e-Box Enterprise DocConsumer, your enterprise needs to send the following

documents to [email protected].

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.



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


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.


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 [email protected]

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

[email protected]) before ordering your certificates to QuoVadis.




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

https://tools.ietf.org/html/rfc6749


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";


@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

[email protected]]

https://www.gcloud.belgium.be/rest/

https://swagger.io/specification/v2/

https://tools.ietf.org/html/rfc6749



technical integration cookbook - e-box enterprise · 2020-04-17 · e-box enterprise – technical...

Documents