Overview

To access the Freja eID services, a Relying Party must use SSL with client authentication, where the client certificate is obtained from Freja eID during the onboarding process.

Initialising 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 is 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.

  
/*
* FrejaEnvironment determines which environment will be used.
* It can be Freja eID Production Environment or Test Environment, which is suitable for testing client applications.
*/
AuthenticationClientApi authenticationClient = AuthenticationClient.create(sslSettings, FrejaEnvironment.TEST).build();

SignClientApi signClient = SignClient.create(sslSettings, FrejaEnvironment.TEST).build();
												
OrganisationIdClientApi organisationIdClient = OrganisationIdClient.create(sslSettings, FrejaEnvironment.TEST).build();

CustomIdentifierClientApi customIdentifierClient = CustomIdentifierClient.create(sslSettings, FrejaEnvironment.TEST).build();

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.

/*
* Transaction context can be changed for authentication and signing client...
* 
*/
AuthenticationClientApi authenticationClient = AuthenticationClient.create(sslSettings, FrejaEnvironment.TEST)
												.setTransactionContext(TransactionContext.ORGANISATIONAL)
												.build();
SignClientApi signClient = SignClient.create(sslSettings, FrejaEnvironment.TEST)
												.setTransactionContext(TransactionContext.ORGANISATIONAL)
												.build();

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.

/*
* Connection and read timeout in milliseconds on client side. Connection timeout is time to establish
* the connection with remote host.
* Read timeout is time waiting for data after the connection was established
* (maximum time of inactivity between two data packages). 
* If value is not specified, it will be 20000 ms by default. 
*/
int connectionTimeoutInMilliseconds = 15000;
int readTimeoutInMilliseconds = 15000;
AuthenticationClientApi authenticationClient = AuthenticationClient.create(sslSettings, FrejaEnvironment.TEST)
								.setConnectionTimeout(connectionTimeoutInMilliseconds)
								.setReadTimout(readTimeoutInMilliseconds)
								.build();

Polling timeout configuration

Polling timeout can be configured through the Builder setter functions. If no other value is specified, 3000 ms will be set by default.

/*
* Parameter pollingTimeout controls the time interval between succeeding HTTP poll requests in the method getFinalLoginResponse.
* If no other value is specified for this parameter, it will be 3000 ms by default.
* If the value of this parameter is less than 1000 ms or more than 30000 ms, the builder will throw the exception. 
*/
int pollingTimeoutInMilliseconds = 5000;
AuthenticationClientApi authenticationClient = AuthenticationClient.create(sslSettings, FrejaEnvironment.TEST)
								.setPollingTimeout(pollingTimeoutInMilliseconds)
								.build();

HTTPS proxy settings

In case you are using an HTTPS proxy server to reach services and sites outside of your 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 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).

More about configuring HTTPS proxy via system variables in Java you can read here: https://docs.oracle.com/javase/8/docs/technotes/guides/net/proxies.html (section 2.2 and 2.1).

Continue to: