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); /*
* 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, 3000ms will be set by default for the Authentication and Custom Identifier clients, and 60000ms for the Signature and Organisation ID clients.
/*
* Parameter pollingTimeout controls the time interval between
* succeeding HTTP poll requests in the method
* getFinalLoginResponse.
* If the value of this parameter is less than 1000ms or
* more than 60000ms, 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 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:
- Quick Start Guide
- Initialising the Freja eID Client
- Authentication Client
- Signature Client
- Organisation ID Client
- Custom Identifier Management
- Error Handling