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 Integrator 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 Integrator 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 as an Integrator RP

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();

Initialising a separate UserManagementClient for each Integrated Relying Party

A second way of using the UserManagementClient library when you act as an Integrator RP is to create a UserManagementClient for each organisation you represent (Integrated RP). 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";
UserManagementClientApi userManagementClient = new UserManagementClient.Builder(sslContext)
                                                    .relyingPartyId(relyingPartyId)
                                                    .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. 

Please note that examples below are intended for Integrator RPs which have decided to build just one client library and pass the relyingPartyId of an Integrated RP in each call. If you, however, wish to build a client library for each Integrated RP, the mentioned parameter should be passed in the constructor, as explained in the section above. Calls are then initiated in a regular way, as described in Custom Identifier Management API Client (DEPRECATED), i.e. without the parameter relyingPartyId included in calls.

Set custom identifier

This method is used by a relying party 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. The RP is identified through the relyingPartyId previously generated by Freja eID.

/*
* An ID of relying party for which custom identifier should be set.
*/
String relyingPartyId = "relying_party_id"; 
 
/*
* Describes the type of user information supplied to identify the end user. 
* Supported types in this version: EMAIL, PHONE and SSN.   
* See example below; 
*/
UserInfoType userInfoType = UserInfoType.EMAIL 
/*
* If user info type 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";
/*
* 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, relyingPartyId);


Delete custom identifier

This method is used by a relying party to delete a custom identifier for a specific user. The relyingPartyId also needs to be passed in this call.

/*
* An ID of relying party for which custom identifier should be deleted.
*/
String relyingPartyId = "relying_party_id"; 
 
/*
* 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, 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.