Initialising the Freja eID Client

Overview

To access Freja eID Services, you will get an SSL/TLS certificate from us during the onboarding process. More information on obtaining an SSL certificate can be found here.

Initialising the Client

Build an instance of client interface as shown in the examples below. Note that every client has its own Builder class, which is used for instantiation of client objects. This way of creating objects requires passing mandatory parameters in the Builder constructor, while the rest of the parameters can be passed through the Builder setter functions.

SSL Initialisation

There are three ways of establishing the SSL connection with the server and passing the client key pair and the server certificate to the library.

The following example shows how to pass the client key pair using a keystore object and the server certificate separately.

/*
* In order to establish SSL with server, client should provide path of  
* keystore file where key pair is stored. 
* Change the path (C:\\keystore.ks in the example) to match your setup.
*/

String clientKeystorePath  = "C:\\keystore.ks";

/*
* The password of client keystore. Change the password (123123 in the
* example) to match your setup.   
*/

String clientKeystorePass = "123123";

/*
* The server certificate. Change the path (C:\\certificate.cer in the
* example) to match your setup.   
*/

String serverCertificatePath = "C:\\certificate.cer";

/*
* Initialize SslSettings with keystore parameters.
*/

SslSettings sslSettings = SslSettings
    .create(clientKeystorePath, clientKeystorePass, serverCertificatePath);

The following example shows how to pass the client key pair and the server certificate using a keystore object.

/*
* In order to establish SSL with server, client should provide path of
* keystore file where key pair, with appropriate server SSL certificate,
* is stored.  
* Change the path(C:\\keystore.ks in the example) to match your setup. */

String clientKeystorePath  = "C:\\keystore.ks";

/*
* The password of client keystore. Change the password (123123 in the
* example) to match your setup.   
*/

String clientKeystorePass = "123123";

/*
* Initialize SslSettings with keystore parameters.
*/

SslSettings sslSettings = SslSettings
    .create(clientKeystorePath, clientKeystorePass);

The following example shows a more advanced way of SSL initialisation, where the key pair and the server certificate are passed using the SSLContext object.

/*
* In order to establish SSL with server, client should provide SSLContext 
* object from javax.net.ssl package, created using keystore file where
* key pair, with appropriate server SSL certificate, is stored.
*/
/*
* Creating KeyStore object
* Client should provide path of keystore file, where the key pair
* with appropriate server SSL certificate is stored.
* Change the path(C:\\keystore.ks in the example) to match your setup.
*/

String clientKeystorePath  = "C:\\keystore.ks";

/*
* The password of client keystore. Change the password (123123 in the
* example) to match your setup.
*/

String clientKeystorePass = "123123";
try (InputStream keyStoreStream = 
      new FileInputStream(clientKeystorePath  )) {
  KeyStore keyStore = KeyStore
      .getInstance(KeyStore.getDefaultType());
  keyStore.load(keyStoreStream, clientKeystorePass.toCharArray());
} catch (Exception ex) {
      Log.error(ex,"failed to create keystore object!");
}
KeyManagerFactory keyManagerFactory = KeyManagerFactory
      .getInstance(KeyManagerFactory.getDefaultAlgorithm());
keyManagerFactory
      .init(keyStore, clientKeystorePass.toCharArray());
TrustManagerFactory tmf = TrustManagerFactory
      .getInstance(TrustManagerFactory.getDefaultAlgorithm());
tmf.init(keyStore);
SSLContext sslContext = SSLContext.getInstance("SSL");
sslContext.init(keyManagerFactory.getKeyManagers(), 
    tmf.getTrustManagers(), null);

/*
* Initialize SslSettings with SSLContext object.
*/

SslSettings sslSettings = SslSettings.create(sslContext);

Using the Test Environment

During the implementation and the testing period, you can use the Freja eID Test Environment. In that case, when initialising any client, you need to pass the test environment as the preferred one, like in the example below.

Transaction Context Configuration

Transaction context can be configured through the Builder setter functions. For Authentication, Signature and Custom Identifier clients, the default value of the transaction context is PERSONAL, while for the Organisation ID client it is ORGANISATIONAL.

Connection and Read Timeout Configuration

Connection and read timeout can be configured through the Builder setter functions. If no other value is specified, 20000 ms will be set by default.

Polling timeout configuration

Polling timeout can be configured through the Builder setter functions. If no other value is specified, 3000ms will be set by default for the Authentication and Custom Identifier clients, and 60000ms for the Signature and Organisation ID clients.

HTTPS Proxy Settings

In case you are using an HTTPS proxy server to reach services and sites outside of tour company network, you will have to provide details about the proxy server host and port to the library.

The library uses a standard Java mechanism for configuring the HTTPS proxy which assumes setting system properties https.proxyHost and https.proxyPort to provide the hostname and port of the proxy server (optionally, a system property http.nonProxyHosts can be set if you need to provide a list of hosts for which you don’t need a proxy).

Read more about configuring HTTPS proxy via system variables in Java here (sections 2.1 and 2.2)

Go to: