Step 2

Topics found on this page:

• Setup ID-Rights client API
• Send Get Signature Data message
• Send Verify Signature Data message

Setup ID-Rights client API

The ID-Rights client API communicates with the ID-Rights service through XML messages. These are sent using HTTP. All XML messages to ID-Rights must be signed with a Nets issued certificate. The ID-Rights client API can be used to sign and send all XML messages.

In order to use ID-Rights client API, it should first be initialized with required details as listed below:

1. ID-Rights service URL (customer test or production).
2. PKCS12 file with Nets issued certificate.
3. JKS truststore with Nets ID-Rights server SSL certificate and its password.
4. Communication timeout.
5. MerchantID (issued by Nets for each customer, MerchantID=1587 is used for the demo app).

Sample code provided below does the initialization (detailed code is available in demo app source files). 

 MerchantContext merchantContext = new MerchantContext();

 DHCConfiguration dhcConfig = new DHCConfiguration();
 dhcConfig.setUrl("https://order.id-rights-preprod1.nets.eu/id-rights/app");
 dhcConfig.setKeyStorePath("id-rights-demo-app.p12");
 dhcConfig.setKeyStorePwd("p12-password");
 dhcConfig.setKeyStoreType("PKCS12");
 dhcConfig.setTrustStore("id-rights-trust-store.jks");
 dhcConfig.setTrustStorePwd("jks-password");
 dhcConfig.setTrustStoreType("JKS");
 dhcConfig.setSocketTimeoutOverride(10000);
			
 merchantContext.setDhcConfig(dhcConfig);
			
 PKCS12Keystore pkcs12 = new PKCS12Keystore("id-rights-demo-app.p12", "p12-password".toCharArray());

 merchantContext.setClientSSLkeystore(pkcs12);
 merchantContext.setMerchantId("1587");

 IDRightsFactory.INSTANCE.registerMerchantContext(merchantContext);

Send Get Signature Data message

Get signature data message (internally referred as getSPInfoByOrg) can be sent to ID-Rights service to get information about positions and the people that hold procuration and signature rights in an organization. A basic Get signature data XML message should contain the following:

1. Message ID (should be unique to track this message in the future)
2. Country code (Example, NO for Norway)
3. Organization number, click here for test data 

Sample code for sending a Get signature data XML message through ID-Rights client API to ID-Rights service is included below (detailed code is available in demo app source files).

The getSPInfoByOrg method (refer sample code below) from ID-Rights client API creates an XML message with the details provided, signs the XML message and sends it to ID-Rights service. 

 IDRightsFacade facade = IDRightsFactory.INSTANCE.getIDRightsFacade("1587");

 TrustB2BMessage trustB2bMessage = new TrustB2BMessage();
 TrustB2BStdHeaderType trustB2bHeader = new TrustB2BStdHeaderType();
 trustB2bHeader.setCountryCode("NO");
 trustB2bHeader.setMerchantID(1587);

 //The following message id should be unique for Nets ID-Rights service, otherwise an error will be thrown
 //Customer should generate this message ID
 trustB2bHeader.setMessageID("1587-" + System.currentTimeMillis());

 trustB2bHeader.setTraceID(null);
 trustB2bHeader.setTime(new Date());
 trustB2bMessage.setTrustB2BHeader(trustB2bHeader);
 B2BMessage b2bMessage = new B2BMessage(trustB2bMessage, null);

 GetSPInfoByOrgTypeDef getSPInfoByOrg = new GetSPInfoByOrgTypeDef();
 getSPInfoByOrg.setOrganizationNumber("org-number");
 b2bMessage.getTrustB2BMessage().setGetSPInfoByOrg(getSPInfoByOrg);

 B2BMessage b2bResponse = facade.getSPInfoByOrg(b2bMessage);

On receiving the signed XML message, ID-Rights service validates the signature in the incoming message and authenticates the customer. On successful authentication, the XML message is taken for further processing.

Send Verify Signature Data message

Verify signature data message (internally referred as verifySPInfo) can be sent to ID-Rights service to verify the signature rights of a person in an organization. A basic Verify signature data XML message should contain the following:

1. Message ID (should be unique to track this message in the future)
2. Country code (Example, NO for Norway)
3. Organization number (see page about test data)
4. SSN or Personal number (see page about test data)

Sample code for sending a Verify signature data XML message through ID-Rights client API to ID-Rights service is included below (detailed code is available in demo app source files).

The verifySignatureAndProcuration method (refer sample code below) from ID-Rights client API creates an XML message with the details provided, signs the XML message and sends it to ID-Rights service.  

 IDRightsFacade facade = IDRightsFactory.INSTANCE.getIDRightsFacade("1587");

 TrustB2BMessage trustB2bMessage = new TrustB2BMessage();
 TrustB2BStdHeaderType trustB2bHeader = new TrustB2BStdHeaderType();
 trustB2bHeader.setCountryCode("NO");
 trustB2bHeader.setMerchantID(1587);

 //The following message id should be unique for ID-Rights service, otherwise an error will be thrown
 //Customer should generate this message ID
 trustB2bHeader.setMessageID("1587-" + System.currentTimeMillis());

 trustB2bHeader.setTraceID(null);
 trustB2bHeader.setTime(new Date());
 trustB2bMessage.setTrustB2BHeader(trustB2bHeader);
 B2BMessage b2bMessage = new B2BMessage(trustB2bMessage, null);


 VerifySignatureAndProcurationTypeDef verifySignatureAndProcuration = new VerifySignatureAndProcurationTypeDef();
 verifySignatureAndProcuration.setOrganizationNumber("org-number");
 verifySignatureAndProcuration.setPersonIDList(new PersonIDList());

 PersonIDTypeDef personId = new PersonIDTypeDef();
 personId.setSocialSecurityNumber("personal-number|ssn");
 verifySignatureAndProcuration.getPersonIDList().getPersonID().add(personId);
 b2bMessage.getTrustB2BMessage().setVerifySignatureAndProcuration(verifySignatureAndProcuration);

 B2BMessage b2bResponse = facade.verifySignatureAndProcuration(b2bMessage);

Continue to Step 3 >