Onboarding process to become a Document Consumer

You need to follow the onboarding self-service process below to integrate as a Document Consumer of the e-Box Enterprise.

Your enterprise can do some testings with the Simulation URLs to ensure that everything is OK before using e-Box as a Document Consumer in Production.

Please note that the onboarding as a Document Consumer is irreversible.

Before you can become a Document Consumer of e-Box Enterprise, you must create an account and do security settings. If you already used e-Box Enterprise, you can go directly to the section 1.2 Accepting the terms of use.

Step 1: Onboarding self-service Document Consumer

1.1 User account management

In order to become a Document Consumer, you need an Access Manager (AM) or a Co-Access Manager (Co-AM) to activate and manage your technical "Webservice" channel. Follow the Procédure pour la gestion des accès dans UMan.pdf/ Procedure voor toegangsbeheer in UMan.pdf manual to designate an AM/co-AM and manage user access.

Role EN	Role FR	Role NL
Access Manager (AM)	Gestionnaire d'Accès(GA) = Gestionnaire Local(GL)	Toegangs Beheerder (TB)= Lokale Beheerder (LB)
co-Access Manager (co-AM)	co-Gestionnaire d'Accès (co-GA) =co-Gestionnaire Local(co-GL)	co-Toegangs Beheerder (co-TB)=Lokale co-Beheerder (co-LB)

1.2 Accepting the terms of use

In order to use e-Box as a Document Consumer, your enterprise must accept the terms of use for Document Consumer in your e-Box. Go to the section Document Consumer in the menu Gestion e-Box/ Beheer e-Box.

You'll have to read the terms of use for Document Consumer, scroll to the end of the complete terms of use and accept them. Only after the acceptation can your enterprise create a technical account, which allows you to consult your messages as a Document Consumer.

1.3 Creating a Webservice REST account in ChaMan

The AM/co-AM should now create a Webservice REST account in ChaMan. To do this, follow the steps below:

1. Connect yourself to your enterprise, then click on Ajouter un compte Webservice/Een Webservice account toevoegen.
2. Choose 'REST' as type and give a name to your account.
3. Select Document Consumer e-Box Enterprise, upload your certificate and give it a name. The certificate to be used must be a X.509 certificate, and there MUST HAVE the field Key Usage.
4. Click on Valider/Bevestigen.
5. After the validation, you can find your OAuth client ID under the section Webservices Account.

Step 2: OAuth configuration

2.1 Enterprise registration in OAuth Server

The previous step involves the registration of your enterprise (identified by its CBE number) in the Social Security OAuth authorization server, thanks to which you get an OAuth client ID that is associated with your enterprise and your certificate, allowing you to generate an OAuth AccessToken which serves for consulting e-Box Enterprise's Webservice REST. The Cookbook OAuth V5 introduces OAuth and explains how a token can be retrieved.

Pay attention that there is a +-10 minutes-cache between the acceptation of terms of use and the generation of token. Therefore, please try to generate the token at minimum 10 minutes after your acceptation.

2.2 Retrieving the OAuth AccessToken via Postman

The Social Security’s Webservice REST is highly secured. Before you can access to the e-Box Enterprise's Webservice REST, you must request an OAuth AccessToken from the OAuth authorization server. You can do this via Postman by following the steps below:

1. Download the Postman Collection and import it to Postman.
2. Click on the second operation (POST), in Pre-request Script, replace the content of iss and sub by the OAuth Client ID that you've obtained via ChaMan.

3. Get the PEM of your private certificate. To do this, you should open your certificate with KeyStore, click right on the certificate=>View Details=>Private Key Details=>PEM=>Copy.
4. On Postman, in the section Environment, add a new Environment, put a new Environment variable in it with the name CLIENT_PRIVATE_KEY, put the PEM in it. It should be in both Initial Value and Current Value.

5. Return to the section Collections on Postman, run the first operation GET INIT to load the library. If you are connected to a VPN, please disconnect temporarily in order to run the operation.
6. Now you can run the second operation (POST) to get the OAuth token. Don't forget to use the environment where you've put your PEM.

As a Document Consumer, your AccessToken will contain the necessary scope to perform all possible requests concerning your e-Box:

• documentconsumer (scope:document:management:consult:ws-eboxrestentreprise:documentconsumer) to get and perform authorized actions on all messages of your e-Box.

2.3 Retrieving the OAuth AccessToken java example

You can see the get OAuth token example on Github for a java example on how to retrieve an OAuth token. The GetAccessTokenV5.getAccessToken() method is the one responsible of getting the token. If you take this example, we advise you to add the scope scope:document:management:consult:ws-eboxrestentreprise:documentconsumer as parameter in the getAccessToken() call so if the onboarding was not done properly, you will receive an error message and know that the scope is not granted before sending the requests. Both production V5 token URL and audience are https://services.socialsecurity.be/REST/oauth/v5/token .

Step 3: Testing with the Simulation URLs

3.1 Consult Provider Registry in Simulation

Once you have obtained your token, for security reasons, you can do some testings with the Simulation URLs before consulting your messages in Production as a Document Consumer. The first thing that you need to do is to consult the Provider Registry in Simulation in order to get the URL of our Document Provider in Simulation:

Environment	URL Provider Registry
Simulation	https://services-sim.socialsecurity.be/REST/ebox/enterprise/federation/documentProviderRegistry/v1/messageRegistries

In the response, you will find our Document Provider in Simulation:

Environment	Endpoint Webservice REST e-Box Enterprise
Simulation	https://services-sim.socialsecurity.be/REST/ebox/enterprise/messageRegistry/consultationIntegrationTest/v3

3.2 Consult partitions in Simulation

As a Document Consumer, it's also possible for you to consult the list of partitions of your e-Box Enterprise. To do this in Simulation, you can use the URL below:

Environment	URL Partition Consultation
Simulation	https://services-sim.socialsecurity.be/REST/ebox/enterprise/partition/v1/ebox/{enterpriseNumber}/partitions

This is useful if you want to move certain messages that you've received to another partiton of your e-Box. For example, if you have received a message related to the human resources in your partition GENERAL, and you want to move it to your specific partition named HR, you can do this:

After the operation, this message will be in the partition HR instead of the partition GENERAL.

Point of attention: when you change the partition of the message, the Simulation environment won't verify if the target partiton exists. But in the Production environment, it is verified.

You can find more information on the partition of e-Box Enterprise here.

3.3 Consult messages in Simulation

As stated in the point 3.1, you can use the endpoint of e-Box Enterprise's Webservice REST to consult the messages in Simulation. The consultation of messages is done via an HTTP GET through all the methods that start with /ebox defined in Message Registry Service API. This specification is available in .yaml format. The methods in the "publication" section are only available for the Document Sender and the Document Provider. The results of given by the Simulation URL will be reset every day at midnight.

Step 4: e-Box Enterprise consultation via REST Webservice

4.1 Consult Provider Registry

Once your test is okay in Simulation, you can then find the list of Document Providers in Production by making a GET request to the Provider Registry:

Environment	URL Provider Registry
Production	https://services.socialsecurity.be/REST/ebox/enterprise/federation/documentProviderRegistry/v1/messageRegistries

In the response, you will find our Document Provider:

Environment	Endpoint e-Box Enterprise
Production	https://services.socialsecurity.be/REST/ebox/enterprise/messageRegistry/v3

Attention that if you want to get the messages of other Document Provider, you should use thier URL instead of ours.

4.2 Consult partitions

As stated in step 3.2, you can consult the list of partitions of your e-Box Enterprise if you want to move a message from one partition to another. To do this in Production, you can use the URL below:

Environment	URL Partition Consultation
Production	https://services.socialsecurity.be/REST/ebox/enterprise/partition/v1/ebox/{enterpriseNumber}/partitions

4.3 Consult messages in your e-Box Enterprise via Webservice REST

Now that everything is okay, you can consult messages in your e-Box Enterprise via its Webservice REST in Production as a Document Consumer. :)

Some points of attention:

• To consult the messages, you should first consult the Provider Registry (step 4.1) in order to find the URLs to be used. Please don't use the URL in the step 4.2 to consult the messages.
• Messages will be considered as read when the main content has been retrieved. On the e-Box Enterprise frontend, the visual distinction is the bolding ("unread") or not ("read") of the message title.
• Messages retrieved by Document Consumer remain available in the e-Box until their expiration date.
• The e-Box Enterprise application (user interface version) is always available and must be used in case of errors with the use of technical interfaces.