Table of contents
Other clients for Integrators:
Initialising SignClient as an Integrator RP
Build an instance of SignClientApi interface as shown in the examples below. Note that the SignClient has its own Builder class, which is used for instantiation of SignClient objects. This way of creating objects requires passing mandatory parameters in the Builder constructor, while the rest of parameters can be passed through the Builder setter functions.
SSL initialisation
There are two ways of establishing the SSL connection with the server and passing the client key pair and the server certificate.
The following example shows how to pass the client key pair and the server certificate using a keystore object.
HTTPS proxy settings
In case that you're using a HTTPS proxy server to reach services and sites outside of your company network you'll 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).
/* * In order to establish SSL with server, client should provide path of keystore file * where key pair with appropriate 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 SignClient with keystore parameters. */ SignClientApi signClient = new SignClient.Builder(clientKeystorePath, clientKeystorePass).build();
The next 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 SSL certificate is stored. */ /* * Creating KeyStore object * Client should provide path of keystore file, where the key pair * with appropriate 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, keystorePass.toCharArray()); TrustManagerFactory tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm()); tmf.init(keyStore); SSLContext sslContext = SSLContext.getInstance("SSL"); sslContext.init(keyManagerFactory.getKeyManagers(), tmf.getTrustManagers(), null); /* * Initialize SignClient with SSLContext object. */ SignClientApi signClient = new SignClient.Builder(sslContext).build();
Test environment
During the implementation and the testing period, you can use the Freja eID demo environment. In that case, when initialising SignClient, you need to pass the testMode parameter, set to true, like in the example below.
/* * Boolean value which indicates that RP API Client is in test mode. If this value is not set * or is set to false, RP API Client is using Freja eID production environment. Otherwise, * it is using test environment, which is suitable for testing client applications. */ SignClientApi signClient = new SignClient.Builder(sslContext) .testMode(true) .build();
Connection and read timeout configuration
Connection and read timeout can be configured through Builder setter functions. If no other value is specified, by default 20000 ms (2 minutes) will be set.
/* * 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; SignClientApi signClient = new SignClient.Builder(sslContext) .connectionTimeout(connectionTimeoutInMilliseconds) .readTimout(readTimeoutInMilliseconds ) .build();
Initialising a separate SignClient for each Integrated Relying Party
A second way of using the LoginClient library when you act as an Integrator RP is to create a LoginClient for each organisation you represent. In this case, the relyingPartyId parameter should be passed in the constructor and not in the calls, which is the case when you have just one client library for all Integrated RPs.
/* An ID of the relying party for which signing request should be initated. */ String relyingPartyId = "relying_party_id"; SignClientApi signClient = new SignClient.Builder(sslContext) .relyingPartyId(relyingPartyId) .build();
Calling a service
This section describes how to make calls to the Freja eID Signature service API and process the response.
Initiate sign
This method is used by a relying party to initiate a signing request. As opposed to authentication requests, multiple signature requests may be active at any given time, from the same or different relying parties.
Signatures can be created both in online contexts, where the access to the relying party's service or application is initiated by the end user, as in offline contexts, where the signature request is initiated by the relying party's service in its own right. Signature transactions, therefore, have configurable longevity — from the point of initiation, the user has between two minutes and 30 days to confirm the signature request.
The RP is identified through the relyingPartyId previously generated by Freja eID.
/* * Parameter relyingPartyId represents a unique ID of the relying party * for which the signing request should be initated. */ String relyingPartyId = "relying_party_id"; /* * Parameter userInfoType describes the type of user information * supplied to identify the end user. * Supported types in this version: EMAIL, PHONE and SSN. * Example: UserInfoType userInfoType = UserInfoType.EMAIL; * Example: UserInfoType userInfoType = UserInfoType.SSN; */ UserInfoType userInfoType = UserInfoType.EMAIL; /* * Parameter userInfo contains the user information that corresponds to userInfoType. * If userInfoType is either EMAIL or SSN, it's interpreted as string value of email or SSN. * Change the userInfo value (joe.black@verisec.com in the example) to match your setup. */ String userInfo = "joe.black@verisec.com"; /* * Parameter restrict, optional, describes a value that restricts the sign action only to the * Freja eID mobile application started with the same parameter. * This can be used in situations where the relying party service * is accessed through a browser or app on the same device as the Freja eID app. * By passing the same restrict value to the initSignRequest as to the start of * the mobile application, the relying party application can target the usage of * the Freja eID on the same device. * Currently, parameter restrict is not supported. */ String restrict = null; /* * Parameter minRegistrationLevel, optional, describes * minimum required registration level of a user in order to * approve/decline signing transaction. If not present, default level will be PLUS. */ RegistrationState minRegistrationLevel = RegistrationState.EXTENDED; /* * Parameter title, optional, describes the title to display in the transaction * if presented to the user on the mobile device. The title will be presented regardless of the * confidentiality setting. If not present, a system default text will be presented: * String title = "Confirm action". */ String title = "Transaction title"; /* * Parameters pushNotificationTitle and pushNotificationText, optional, describe * the title and the text of the notification sent to the mobile * device to alert the user of a signature request. * If not present, a system default title and text will be presented: * String pushNotificationTitle = "Sign", * String pushNotificationText = "You have an action to sign in Freja eID". */ String pushNotificationTitle = "Sign notification title"; String pushNotificationText = "Sign notification text"; /* * Parameter confidential, optional, determines whether the user * will be required to enter their Freja eID PIN * or, if enabled, use the handheld device's biometric authentication method * before being allowed to view the content of the transaction. * If not present, defaults to false. * Currently, parameter confidental is not supported. */ Boolean confidental = false; /* * Parameter expiry, optional, describes the time until which the relying party * is ready to wait for the user to confirm the signature request. * Expressed in milliseconds since January 1, 1970, 00:00 UTC. * Min value is current time +2 minutes, max value is current * time +30 days. If not present, defaults to current time +2 minutes. */ Long expiry = Instant.now().plus(3,ChronoUnit.MINUTES).getEpochSecond() * 1000; /* * Parameter dataToSignType describes the type of data to be signed. * Currently, only SIMPLE_UTF8_TEXT is supported. */ DataToSignType dataToSignType = DataToSignType.SIMPLE_UTF8_TEXT; /* * Parameter dataToSign is the text that will be shown in the mobile application and * signed by the end user. */ String dataToSignText = "Would you like to transfer 1000 EUR from account A to account B?”; /* * Parameter signatureType describes the type of signature that is requested. */ SignatureType signatureType = SignatureType.SIMPLE; /* * In case of Initiate sign method, response type is InitiateSignResponse. * The only data in this response is the signature transaction reference. */ InitiateSignResponse initiateSignResponse = signClientApi.initSign( userInfoType, userInfo, restrict, title, minRegistrationLevel, pushNotificationTitle,pushNotificationText, confidental, expiry, dataToSignType, dataToSignText, signatureType, relyingPartyId); String transactionReference = initiateSignResponse.getSignRef();
Get one sign result
This method is used to fetch a single result for a specified signature transaction reference (signRef returned from a call to Initiate sign method). The relyingPartyId parameter needs to be passed in this call.
/* * An ID of relying party for which signing result should be fetched. */ String relyingPartyId = "relying_party_id"; /* * A reference unique to the transaction that can be used to query the result of a transaction. */ String signRef ="reference"; /* * In case of getOneSignResult method, response type is GetOneSignResultResponse. * Response contains: signature transaction reference of the signing request, * the status of the action and details (can be used for extra validation of response). */ GetOneSignResultResponse response = signClient.getOneSignResult(signRef, relyingPartyId); String receivedSignRef = response.getSignRef(); ActionStatus status = response.getStatus(); String details = response.getDetails();
Get sign results
This method is used to fetch the results of multiple outstanding signature requests. The relyingPartyId parameter needs to be passed in this call.
/* * An ID of relying party for which signing results should be fetched. */ String relyingPartyId = "relying_party_id"; /* * Response type is GetSignResultsResponse. * The response will contain a complete list of signature requests * successfully initiated by the relying party. * The time period during which a specific signature reference is available for checking will depend on * the longevity of the signature operation (see the expiry parameter in the Initiate sign method) * and is calculated as expiry time plus 3 days. */ GetSignResultsResponse response = signClient.getSignResults(relyingPartyId); /* * As final result of getSignResults method, a list of transaction responses is received. */ List<GetOneSignResultResponse> responses = response.getSignatureResults();
Cancel sign
This method is used to cancel an initiated signature request. The relyingPartyId parameter needs to be passed in this call.
/* * A reference unique to the transaction that can be used to query the result of a transaction. */ String signRef = "reference"; /* * An ID of relying party for which signing should be cancelled. */ String relyingPartyId = "relying_party_id"; /* * Response type is EmptyFrejaResponse. * The response is empty. */ List<EmptyFrejaResponse> response = signClient.cancelSign(authRef, relyingPartyId);
Logging
Freja eID Relying Party API Client provides a logger you can include in your application. Details can be found in the Logging section.