Table of Contents

Getting started (**Deprecated**)

  1. Install Security Server and setup Trust Services:
    1. - AUTH Certificate for Security Server
    2. - SIGN Certificate for each Subsystem behind it
  2. Connect Security Server with your information system (Adapter development (Java, .NET, PHP etc.))
  3. Configure data access settings (in Security Server)
  4. Exchange data with your business partners

Tips:

Information system owner view of architecture

RoksNet utilizes the X-Road components for secure data transfer. The illustration below shows the main components and interfaces of the RoksNet.

Important (to get a unique Member/User Code for RoksNet Development environment)

Before setting up your Security Server, please provide the following information to us:

The fields in bold text are required. Please send the following information to support@roksnet.com and we'll send you a 8-digit Member/User Code, that will be needed later to RoksNet setup process.

DOWNLOAD

STEP 1 (required) - Setting up a Security Server and Trust Services

System requirements

Requirements Explanation
Ubuntu 14.04 LTS x86-64 Operating system
2 GB RAM, 10 GB disk space Minimum system requirements
http://x-road.eu/packages X-Road package repository
http://x-road.eu/packages/xroad_repo.gpg The repository key
TCP 5500 Port inbound & outbound for message exchange between security servers
TCP 5577 Port inbound & outbound for querying OCSP responses between security servers
TCP 4001 Port outbound for communication with the roksnet registry
TCP 80 Port outbound for downloading global configuration
TCP 443 Port outbound for OCSP and TSA services
TCP 4000 Port inbound for access to user interface (local network)
TCP 80, 443 Ports inbound as information system access points (local network or external via https)

REQUIREMENTS FOR THE SECURITY SERVER

Minimum recommended hardware parameters:

Requirements to software and settings:

Installing the Security Server

PREPARING THE OS

1. Add system user whom all roles in the user interface are granted to: 

sudo adduser username

2. Set operating system locale. Add the following line to /etc/environment: 

LC_ALL=en_US.UTF-8

INSTALLATION

3. Add the address of the X-Road package repository and the nginx repository to to /etc/apt/sources.list.d/xroad.list: 

deb http://x-road.eu/packages trusty main
deb http://ppa.launchpad.net/nginx/stable/ubuntu trusty main
deb http://ppa.launchpad.net/openjdk-r/ppa/ubuntu trusty main

4. Add X-Road's repository's signing key to the list of trusted keys: 

curl http://x-road.eu/packages/xroad_repo.gpg | sudo apt-key add -
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys 00A6F0A3C300EE8C
sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys EB9B1D8886F44E2A

5. Install the security server software: 

sudo apt-get update
sudo apt-get install openjdk-8-jre-headless
sudo apt-get install xroad-securityserver

6. During the installation you will be asked to specify the username (added at step 1.) that will be granted the rights to perform all activities in the user interface.

7. The other questions can be answered with their default values as they are detected from the OS.

POST INSTALLATION CHECKS

8. Check if all the processes started. The following services should be running. 

sudo initctl list | grep "^xroad-"
xroad-jetty start/running, process 19796
xroad-confclient start/running, process 19563
xroad-signer start/running, process 19393
xroad-proxy start/running, process 19580

9. Ensure that the Security Server user interface at https://SECURITYSERVER:4000/ can be opened in a web browser. To log in, use the account name chosen during the installation. While the user interface is still starting up, the web browser may display the “502 Bad Gateway” error.

Configuring the Security Server

1. To perform the initial configuration, open the address https://SECURITYSERVER:4000/ in a web browser. To log in, use the account name chosen during the installation.

2. The system will ask for a global configuration anchor file. RoksNet's development environment's anchor can be downloaded from http://apt.roksnet.com/xroad6-debs/configuration_anchor.xml. The hash value for verification is 

Hash (SHA-224): 71:3B:88:8C:6B:59:73:29:57:D2:06:8D:BE:A0:FF:F4:E4:E8:E1:D9:3A:A6:8A:75:E3:02:E7:FB

3. If the configuration is successfully downloaded, the system asks for the following information:

Example (values in the picture are for demostration purposes):

4. The system will prompt a warning. This is fine, as we'll register the member status later.

5. Enter softtoken PIN in the Keys and Certificates view (chosen in step 3.)

6. Add a TSA in System Parameters view

7. Generate keys and certificate requests in the Keys and Certificates view

Security Servers use 2 types of certificates

Generate 2 keys by selecting the SoftToken-0 and press GENERATE KEY. Give the key a label and press OK. Your keys should now look similar to this:

Next, generate a CSR for a SIGN certificate by choosing a key and selecting GENERATE CSR. Make sure the Usage: SIGN is selected. If the Common Name (CN) field is empty, please use the Member/User Name in that field.

Then generate a CSR for an AUTH certificate. Make sure the Usage: AUTH is selected. If the Common Name (CN) field is empty, please use the Member/User Name in that field.

Send the downloaded CSR-s to us at support@roksnet.com with the following details:

We will use the CSR-s to issue you certificates.

Once you have received the certificates you should be able to import them in the “Keys and Certificates” view. After importing them, select the AUTH certificate and press “ACTIVATE” and “REGISTER”. Your keys and certificates should now look like this:

Once we have accepted the registration request in the RoksNet User Registry, the OCSP response and status of the AUTH certificate will change to “good, registered”.

The next step would be registering a Subsystem. Select “ADD CLIENT” in the Security Server Clients view.

Select “CONFIRM” in the next prompt.

Once we have accepted the registration request in the RoksNet User Registry, you'll be ready to Consume or Provide User Content Services on RoksNet's Development Environment.

STEP 2 (optional) - Setting up RoksNet Portal

RoksNet Portal is a universal client application that's easy to set up and makes it easy to consume Content Services without the need to develop one's own information system. It's also a good developers tool, as it makes testing your services easy.

System requirements

Requirements Explanation
Ubuntu 14.04 64-bit, 4 GB RAM Recommended system requirements
http://apt.roksnet.com/roksnet-portal RoksNet Portal repository
TCP 80, 443 outbound For communicating with the security server (HTTPS if over public internet
TCP 443 inbound For access to the web interface

Requirements to software and settings:

Installing RoksNet Portal

1. All activities during installation are performed as root user, so 

sudo -i

2. Configure RoksNet Portal and JDK-8 repositories. To do that, add the following lines to /etc/apt/sources.list.d/roksnet-portal.list 

deb [arch=amd64] http://apt.roksnet.com/roksnet-portal trusty main
deb http://ppa.launchpad.net/openjdk-r/ppa/ubuntu trusty main

3. Download signing key for JDK-8 

apt-key adv --keyserver keyserver.ubuntu.com --recv-keys EB9B1D8886F44E2A

4. Update package lists 

apt-get update

Ignore the following error for now: 

W: GPG error: http://www.aktors.ee trusty Release: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY 671B319BE775D097

5. Install RoksNet Portal keyring

Install roksnet-keyring package: 

apt-get install roksnet-keyring

When asked, choose “y” as an answer: 

Install these packages without verification [y/N]?

Update the package lists again: 

apt-get update

6. Install postgreSQL

For ubuntu 16.04 LTS 

vi /etc/apt/sources.list.d/pgdg.list

add line: 

deb http://apt.postgresql.org/pub/repos/apt/ precise-pgdg main

Add key 

wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
apt-get update
apt-get install postgresql-9.3

For ubuntu 14.04 LTS 

apt-get install postgresql-9.3

7. Edit the file /etc/postgresql/9.3/main/pg_hba.conf so that postgres user's authenticaton method would be “trust”. It should look like this: 

# Database administrative login by Unix domain socket
local   all             postgres                                trust

8. Restart PostgreSQL 

service postgresql restart

9. Install RoksNet Portal database package 

apt-get install roksnet-postgresql

For testing purposes questions prompted during installation can be answered with default values.

10. Install Java JDK 8 

apt-get install openjdk-8-jdk

11. Add JAVA_HOME variable 

export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64

12. Install RoksNet Portal application 

apt-get install roksnet-application

Quite a few questions will be asked during this installation.

13. Edit the file /var/lib/tomcat7/webapps/ROOT/WEB-INF/classes/config.cfg with the following content:

You can change the country code: 

#If no suitable countries are defined, then uses system default locale country
countries = [ISO code of your country, e.g. "GB"]

14. Edit /etc/apache2/sites-available/ssl.conf with your IP aadress to gain access to the admin interface. It should look like this: 

    <Location "/*/admin/*">
        Order deny,allow
        Deny from all
        Allow from 127.0.0.1 192.168.1.90
    </Location>

15. Restart apache2. 

service apache2 restart

Configuring RoksNet Portal from the web interface

1. You should now be able to log into RoksNet Portals's admin interface at https://server_ip/admin. Use the administrator account you created during installation to log in.

2. When logged in, under Portal management, select “Add new”

3. Fill out the forms with the following information:

After filling out the forms, hit “Save portal configuration”.

4. Select “Add new manager”.

5. Fill out the forms and hit “Add new person as manager”. For password authentication, check the “change password” checkbox to see the new password fields.

6. Choose “Exit” at upper right corner.

7. Log in with the user you just created at https://server_ip/

The username must be enter as [countrycode+serialnumber].

8. Select “All producers” → “Refresh producers”, check the following boxes and hit “Save active producers”.

9. Select a producer, hit Refresh services → From security server (allowed).

This will send a metaquery from RoksNet Portal to your Security Server, which will proxy it the the Producer's Security Server. As a response, the Producer's Security Server will send a list of allowed methods for your Subsystem.

10. Check all Services and hit Refresh XForms descriptions of selected Services → Generate from Security Server.

This will generate XForms based on the services WSDL-s.

11. Hit the play button on a Service to test it.

You're now able to consume Content Services via RoksNet Portal :)

12. The following demo Content Services are available in RoksNet Development Environment:

NB! In most of demo Content Services you can use % symbol as input parameter and you will receive a list of persons or companies. Take some person or company code from the list and use it in another demo queries. The successful result shows that you received a demo data from another RoksNet User.

STEP 3 (optional) - User Content Services development and own application integration with RoksNet

Developer documentation

RoksNet User Content Services are based on SOAP. Information about X-road specific requirements are in the following documents:

Python example

Source code of example: https://github.com/Roksnet/Python-adapter-example The example contains library and two examples. Installation instructions are in included in the package.

To create a new service in the SOAP server:

To create SOAP client:

Java adapter example

GitHub link: https://github.com/vrk-kpa/xrd4j

All of the related documentation is on the GitHub page

Since the example is not created by Roksnet, we do not guarantee the operation of the example with the Roksnet Portal.

C# example with X-tee.NET

Tool and examples can be downloaded from http://xtee.codeplex.com/

How to use X-tee.NET tool

  1. Get WSDL (if you plan to consume existing services) or write WSDL (if you plan to provide services).
  2. Use generator to generate code based on WSDL.
  3. Use generated code in your project to implement SOAP client or server.

Using generator

Execute the generator program Xtee.Gen.exe and fill the form with necessary data. User interface is in Estonian only. The fields in the form have following meaning:

Fill the gaps and press button „Genereeri“. If generation is successful, you will get generated code in the output directories. Based on this code, you can create and compile a new class library for using in your project.

Implementation of SOAP client

Add generated class library, Xtee.Code.dll and log4net.dll into your application.

Write client code to consume the services: 

using Calculator.Xroad.Eu;
using Xtee.XteeClient.Calc;
namespace Client
{
    class Program
    {
        static void Main(string[] args)
        {
            var client = new CalcAdapter();
            // ID of authenticated end user
            client.XteeCommand.Configuration.UserId = "EE30101010007";
            // call the service
            decimal result = client.Add(new Variables(3, 4)).Result.Value;
            Console.WriteLine(result); 
        }
    }
}

This code creates a SOAP client instance using the class name which was entered into the generator. Each call must include actual user ID who has been authenticated by your application. Finally, we will call the service – in this example, service name is Add and it’s parameters are numbers 3 and 4.

Add <xtee.configuration> element to the configuration file of you project: 

<configSections>
    <section name="xtee.configuration"                   
             type="Xtee.Core.Client.Config.ClientConfigurationSection, Xtee.Core"/>
</configSections>
<xtee.configuration proxyURL="http://my_security_server/cgi-bin/consumer_proxy"
      xRoadInstance="roksnet-dev"
      memberClass="COM"
      memberCode="12998179"
      subSystemCode="roksnet-consumer"
      objectType="SERVICE">
    <xteeTypeAssemblies>
      <clear/>
      <add assemblyName="Name_of_generated_DTO_DLL"/>
      <add assemblyName="Name_of_generated_serializers_DLL"/>
    </xteeTypeAssemblies>
</xtee.configuration>

Replace attributes of <xtee.configuration> with your own data (according to the certificate issued to your security server). Possible attributes are:

Attribute values may be set within the client code as well.

Implementation of SOAP server

Add generated class library, Xtee.Code.dll and log4net.dll into your application.

To provide a service, create service class, inheriting it from the generated interface of the service, and implement ProcessRequest method: 

namespace Server.Services
{ 
    public class ServiceMultiply : MultiplyServiceHandler
    {
        public MultiplyResponse ProcessRequest(MultiplyRequest input, MultiplyInputHeader header)
        {
            return new MultiplyResponse(input.Request, new Result(input.Request.VarX * input.Request.VarY));
        }
    }
}

The configuration file of your application must include <adapter.configuration> element: 

<configSections>
    <section name="adapter.configuration" type="Xtee.Core.Adapter.Service.Config.AdapterServiceConfigurationSection, Xtee.Core"/>
</configSections>
<adapter.configuration storagePath="stored_messages" storeMessages="true">
    <services>
      <clear/>
      <!—- Bind each service to the handler class which will serve it -->
      <add objectType="SERVICE" xRoadInstance="roksnet-dev" memberClass="COM" memberCode="12998179" subSystemCode="Calc" serviceCode="Add" version="v1" servicehandler="Server.Services.ServiceAdd,Server"/>
    </services>
    <xteeTypeAssemblies>
      <clear/>
              <add assemblyName="Name_of_generated_DTO_DLL"/>
      <add assemblyName="Name_of_generated_serializers_DLL"/>
    </xteeTypeAssemblies>
</adapter.configuration>

Replace attributes of <adapter.configuration> with your own data (according to the certificate issued to your security server). Possible attributes are:

Since the example is not created by Roksnet, we do not guarantee the operation of the example with the Roksnet Portal.