Table of contents
Other clients:
Overview
Freja eID allows Relying parties (RP) to manage a single, RP-specific attribute, through the Custom Identifier Management Service. A custom identifier must be unique within the requesting relying party system inside the Freja eID service. In other words, Freja eID does not allow two identical custom attributes to be set by the same RP.
In order to set a custom identifier for a user, the RP needs to obtain the existing user information for that user in the Freja eID system (e.g. the email address the user has connected to Freja eID, their phone number or, if the user is on the Extended or Plus level, their Social Security Number) and pass it in the call to Freja eID services. Once the custom identifier is set for a user, the RP can ask for that additional information about the user to be returned when initialising an authentication request.
For more detailed information about the Custom Identifier Management, please refer to Freja eID Relying Party Developers' Documentation.
Initialising UserManagementClient
Build an instance of the UserManagementClientApi interface as shown in the examples below. Note that the UserManagementClient has its own Builder class, which is used for instantiation of UserManagementClient 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 to the library.
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 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 UserManagementClient with keystore parameters. */ UserManagementClientApi userManagementClient = new UserManagementClient.Builder(clientKeystorePath, clientKeystorePass).build();
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 UserManagementClient with SSLContext object. */ UserManagementClientApi userManagementClient = new UserManagementClient.Builder(sslContext).build();
Using the test environment
During the implementation and the testing period, you can use the Freja eID demo environment. In that case, when initialising LoginClient, you need to pass a 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. */ UserManagementClientApi userManagementClient = new UserManagementClient.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; UserManagementClientApi userManagementClient = new UserManagementClient.Builder(sslContext) .connectionTimeout(connectionTimeoutInMilliseconds) .readTimout(readTimeoutInMilliseconds ) .build();
Calling a service
This section describes how to make calls to the Freja eID API in order to set or delete a custom identifier.
Set custom identifier
This method is used to set a custom identifier for a specific user. As said before, the existing user information for that user in the Freja eID system must be passed as a parameter of this method.
/* * 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; */ UserInfoType userInfoType = UserInfoType.EMAIL /* * Change the userInfo value (joe.black@verisec.com in the example) to match your setup. * If user info type is EMAIL, PHONE or Swedish SSN, it's interpreted as their string value. * e.g. in case of UserInfoType.PHONE, userInfo = "+467123456789", * in case of UserInfoType.EMAIL, userInfo = "example@test.com", * in case of UserInfoType.INFERRED userInfo must be explicitly set to "N/A", * in case of UserInfoType.SSN for Swedish SSN, userInfo = "198511170040". * In case of UserInfoType.SSN for non-Swedish SSN, information about the user shall be packed in a SsnUserInfo object that contains the country code and SSN itself like * SsnUserInfo ssnUserInfo = new SsnUserInfo("NO", "31019411411") */ String userInfo = "joe.black@verisec.com"; /* * The custom attribute to be set for the end user, it's interpreted as string value. * Must be unique within the requesting relying party system inside the Freja eID service. */ String customIdentifier = "joeblack"; /* * As final result of setCustomIdentifier method, custom identifier is * set for user. No additional information is returned. */ userManagementClient.setCustomIdentifier(userInfoType, userInfo, customIdentifier);
Delete custom identifier
This method is used to delete a custom identifier for a specific user.
/* * The custom attribute to be deleted for the end user, it's interpreted as string value. * Must exist within the requesting relying party system inside the Freja eID service. */ String customIdentifier = "joeblack"; /* * As final result of deleteCustomIdentifier method, custom identifier is * deleted for user within requesting relying party system. No additional information is returned. */ userManagementClient.deleteCustomIdentifier(customIdentifier);
Logging
Freja eID Relying Party API Client provides a logger you can include in your application. Details can be found in the Logging section.