This document is a high-level technical document which provides a guidance on the installation process of the Loqate Address Lookup extension on the SAP Commerce.
The expected audience for this document is technical specialists who will be involved in Loqate integration into SAP Commerce Cloud. These specialists are expected to be familiar with the SAP Commerce Cloud platform and installing extensions/add-ons for it.
This add-on is designed and tested with B2C version 1905 of SAP Commerce Cloud.
Extension for Loqate integration supports the address Lookup feature. The extension is designed utilizing the SAP integration patterns offered on the platform and tested against the standard B2C accelerator offered by SAP.
This document is split largely into two sections – the first explaining the installation process and the second demonstrating how to use the Loqate Address Lookup extension. There’s also a short final section detailing some mitigation steps for Log4j2 vulnerabilities.
If this is your first time working through this guide then we recommend you start at the beginning and take it step by step, to make sure you cover everything. If you want to look for a specific section however, you can use the links below:
List of files that are changed as a part of Loqate extension will be available in OOB folder in hybris/config/customize/modules folder.
The following OOB extensions need to be modified for the Loqate feature:
Storefront Changes
OOB yacceleratorstorefront is used as the template storefront for Loqate add-on development. Below files are updated for Loqate Address lookup capture and verification. If merchant application is using any custom files, update the same with the changes for Loqate from below file list.
yacceleratorstorefront files:
acceleratorstorefrontcommons files:
commercefacades files:
acceleratorservices files:
Update the system
If you have already performed full initialization, then you need to update your Hybris system as follows:
In order to get started, we need to create an account in Loqate: https://account.loqate.com/en-gb/
Once your account is created, you need to create services which can be configured to SAP Hybris forms associated to MyAccount, Shipping and Billing pages.
These services are split up into two groupings:
Address Validation
Follow these steps to set up address validation on both your Shipping and Billing pages in SAP Hybris.
Shipping page
Once you’ve done that, you will see this page:
You will also see the following error message – don’t worry, this is fine.
This will now navigate to the Shipping page of your SAP Hybris application, where you will see the Loqate widget on the right-hand side of the screen. This will automatically detect your Hybris fields and allow you to map them to Loqate fields.
You have two options for adding a new service – you can either select one of the services shown on the right-hand side and click Configure, or scroll to the bottom of the page on the right-hand side, select the Add another service drop-down and choose a service.
Click on Address Validation to configure lookup feature.
Billing page
Like the Shipping page, services need to be created and configuration needs to be applied for the Billing page. Repeat the process, using the URL of your Billing page.
Here’s an example of what that might look like:
Email and Cell phone validation
Next you need to configure Email and Cell phone validation, using essentially the same process.
From the in-page setup screen, you can select the Email validation and Cell phone validation options, again either from the drop-down at the bottom of the page or the individual service options:
NOTE
Altogether there are four services which need configuring. Please make sure that you don’t create any additional services/API keys apart from what is required.
If you do create any additional services, you can delete them via the Dashboard page in your Loqate account (https://account.loqate.com/account#/Dashboard/).
There are some configurations that need to be applied through HAC. Details can be configured in local.properties.
Sample local.properties is available in the config folder.
The following properties should all be present in local.properties:
Property Key: |
sop.post.url |
Description: |
OOB Payment Mock URL |
Property Value: |
https://electronics.local:9002/acceleratorservices/sop-mock/process |
Property Key: |
loqate.script |
Description: |
Loqate Script which need to be included in forms |
Property Value: |
(function(n,t,i,r){var u,f;n[i]=n[i]||{},n[i].initial={accountCode:"CMPNYXXXXX",host:"CMPNYXXXXX.pcapredict.com"},n[i].on=n[i].on||function(){(n[i].onq=n[i].onq||[]).push(arguments)},u=t.createElement("script"),u.async=!0,u.src=r,f=t.getElementsByTagName("script")[0],f.parentNode.insertBefore(u,f)})(window,document,"pca","//CMPNYXXXXX.pcapredict.com/js/sensor.js") |
Property Key: |
geolocation.api |
Description: |
API details of Geolocation |
Property Value: |
/capture/getLocation |
Property Key: |
loqate.find.api |
Description: |
API details of Find |
Property Value: |
https://api.addressy.com/Capture/Interactive/Find/v1.10/json3.ws |
Property Key: |
loqate.retrieve.api |
Description: |
API details of Retrieve |
Property Value: |
https://api.addressy.com/Capture/Interactive/Retrieve/v1.00/json3.ws |
Property Key: |
loqate.verify.api |
Description: |
Loqate Verify API |
Property Value: |
https://api.addressy.com/Cleansing/International/Batch/v1.00/json4.ws |
Property Key: |
geolocation.enabled |
Description: |
Switch to enable/disable Geolocation |
Property Value: |
false |
Property Key: |
hybris.loqate.countrymap |
Description: |
Other configuration |
Property Value: |
"US-USA,CA-CAN,GB-GBR,AL-ALB,AD-AND,AT-AUT,BY-BLR,BE-BEL,BA-BIH,BG-BGR,CN-CHN,HR-HRV,CY-CYP,CZ-CZE,DK-DNK,EE-EST,FO-FRO,FI-FIN,FR-FRA,DE-DEU,GI-GIB,GR-GRC,GL-GRL,GG-GGY,VA-VAT,HK-HKG,HU-HUN,IS-ISL,IE-IRL,IM-IMN,IT-ITA,JP-JPN,JE-JEY,KR-KOR,LV-LVA,LI-LIE,LT-LTU,LU-LUX,MO-MAC,MK-MKD,MT-MLT,MD-MDA,MC-MCO,ME-MNE,NL-NLD,NO-NOR,PL-POL,PT-PRT,RO-ROU,RU-RUS,SM-SMR,RS-SRB,SK-SVK,SI-SVN,ES-ESP,SE-SWE,CH-CHE,TW-TWN,TR-TUR,UA-UKR,VN-VNM" |
Property Key: |
geolocation.key |
Description: |
Geolocation key |
Property Value: |
XXXX-XXXX-XXXX-XXXX |
Property Key: |
country.phonecode.map |
Description: |
Other configuration |
Property Value: |
"US-1,CA-1,GB-44,AL-355,AD-376,AT-43,BY-375,BE-32,BA-387,BG-359,CN-86,HR-385,CY-357,CZ-420,DK-45,EE-372,FO-298,FI-358,FR-33,DE-49,GI-350,GR-30,GL-299,GG-44-1481,VA-379,HK-852,HU-36,IS-354,IE-353,IM-44-1624,IT-39,JP-81,JE-44-1534,KR-82,LV-371,LI-423,LT-370,LU-352,MO-853,MK-389,MT-356,MD-373,MC-377,ME-382,NL-31,NO-47,PL-48,PT-351,RO-40,RU-7,SM-378,RS-381,SK-421,SI-386,ES-34,SE-46,CH-41,TW-886,TR-90,UA-380,VN-84" |
Property Key: |
loqate.verify.enabled |
Description: |
Switch to enable/disable Verify Logic |
Property Value: |
true |
Property Key: |
countrycode.phonenumber.map |
Description: |
Other configuration |
Property Value: |
"Select CountryCode,AL-Albania,AD-Andorra,AT-Austria,BY-Belarus,BE-Belgium,BA-Bosnia and Herzegovina,BG-Bulgaria,CA-Canada,CN-China,HR-Croatia,CY-Cyprus,CZ-Czech Republic,DK-Denmark,EE-Estonia,FO-Faroe Islands,FI-Finland,FR-France,DE-Germany,GI-Gibraltar,GR-Greece,GL-Greenland,GG-Guernsey,VA-Holy See (Vatican City State),HK-Hong Kong, China,HU-Hungary,IS-Iceland,IE-Ireland,IM-Isle of Man,IT-Italy,JP-Japan,JE-Jersey,KP-Korea, Democratic People's Republic of,KR-Korea, Republic of,LV-Latvia,LI-Liechtenstein,LT-Lithuania,LU-Luxembourg,MO-Macao, China,MK-Macedonia,MT-Malta,MD-Moldova,MC-Monaco,ME-Montenegro,NL-Netherlands,NO-Norway,PL-Poland,PT-Portugal,RO-Romania,RU-Russian Federation,SM-San Marino,RS-Serbia,SK-Slovakia,SI-Slovenia,ES-Spain,SE-Sweden,CH-Switzerland,TW-Taiwan, China,TR-Turkey,UA-Ukraine,GB-United Kingdom,US-UnitedStates,VN-Viet Nam" |
Property Key: |
countrycode.phonenumber.map1 |
Description: |
Other configuration |
Property Value: |
"Select PhoneCode,+355-Albania,+376-Andorra,+43-Austria,+375-Belarus,+32-Belgium,+387-Bosnia and Herzegovina,+359-Bulgaria,+1-Canada,+86-China,+385-Croatia,+357-Cyprus,+420-Czech Republic,+45-Denmark,+372-Estonia,+298-Faroe Islands,+358-Finland,+33-France,+49-Germany,+350-Gibraltar,+30-Greece,+299-Greenland,+44-1481-Guernsey,+379-Holy See (Vatican City State),+852-Hong Kong, China,+36-Hungary,+354-Iceland,+353-Ireland,+44-1624-Isle of Man,+39-Italy,+81-Japan,+44-1534-Jersey,+82-Korea, Democratic People's Republic of,+82-Korea, Republic of,+371-Latvia,+423-Liechtenstein,+423-Lithuania,+352-Luxembourg,+853-Macao, China,+389-Macedonia,+356-Malta,+373-Moldova,+377-Monaco,+382-Montenegro,+31-Netherlands,+47-Norway,+48-Poland,+351-Portugal,+40-Romania,+7-Russian Federation,+378-San Marino,+381-Serbia,+421-Slovakia,+386-Slovenia,+34-Spain,+46-Sweden,+41-Switzerland,+886-Taiwan, China,+90-Turkey,+380-Ukraine,+44-United Kingdom,+1-UnitedStates,+84-Viet Nam" |
Property Key: |
prod.envirnoment.enabled = false |
Description: |
Geolocation related attribute |
Property Value: |
false |
Also, the project.properties of loqateaddon should have the following configurations:
The following steps are optional and only required if you configure the Find Address feature using the Geolocation attributes like latitude and longitude.
To enable the Geolocation search, you need to turn on the geolocation.enabled flag through HAC (as mentioned in the previous step). By default, this feature is turned off, and the latitude and longitude search will not be displayed in forms.
Configurations related to Geolocation
Attribute details and descriptions
Attribute | Description |
Loqate Environment | This will have either value as Test or Live |
accountcode | The Loqate account code value for the particular environment |
accountHost | The Loqate account host value for the particular environment |
accountURL | The Loqate account URL value for the particular environment |
geolocationAPIUrl | The Loqate Geolocation API URL for the particular environment |
geolocationAPIKey | The Loqate Geolocation API Key value for the particular environment |
Implementing a phone number - country flag integration on the Shipping, Billing and My Address pages requires a third-party open-source JavaScript/jQuery plugin called International Telephone Input (a plugin for entering and validating international telephone numbers). This adds a flag dropdown to any input, displays a relevant placeholder, and provides formatting/validation methods. It is also widely known as intl-tel-input.
Files associated |
intlTelInput.css |
intlTelInput.js |
Flags.png |
Flags@2x.png |
ere we will demonstrate how Loqate functionality works on the Shipping page, starting with UK addresses before moving on to US addresses.
UK addresses
Navigate to the Shipping page and select UNITED KINGDOM from the COUNTRY/REGION drop-down. This will load the address form related to the UK:
US addresses
If a user selects UNITED STATES from the COUNTRY/REGION drop-down, this will change the form to display US-specific fields.
The PHONE NUMBER field contains a country flag and country code, which by default will be loaded based on the country selected from the COUNTRY/REGION drop-down list. Here’s how that looks for the US, and the UK:
The Loqate email validation tool will clearly show whether an entered email is valid or not.
Address validation for the Shipping page
If the loqate.verify.enabled flag is set to TRUE, the Loqate Address Verification tool will be enabled, and will call the Loqate Verify API to validate the user’s address:
This occurs when user submits the Shipping page. The ADDRESS LINE 1, ADDRESS LINE 2, CITY and ZIP/POSTAL CODE (or POST CODE in the UK) fields will be populated based on the response of the Verify API, and this will be submitted to Backend for further processing.
Geolocation [Optional: recommended on Demo to leave this feature off]
To enable this option, navigate to HAC and search for the geolocation.enabled flag. By default, the value is set to false.
By default, when a user navigates to Billing page, the USE MY DELIVERY ADDRESS checkbox is checked, and any data that was entered in the Shipping page is carried over to the Payment page.
However, a user can uncheck this option if they want and enter a different billing address.
If this is the case, the user can complete the form on the Billing page in exactly the same way as on the Shipping page (see above for full details).
This page allows users to save addresses to their accounts. This follows many of the same steps as the previous pages.
On Dec 9, 2021 a very serious vulnerability in the popular Java-based logging package Log4j was disclosed. This vulnerability allows an attacker to execute code on a remote server - a so-called Remote Code Execution (RCE). Because of the widespread use of Java and Log4j this is likely one of the most serious vulnerabilities on the Internet. It is CVE-2021-44228 and affects version 2 of Log4j between versions 2.0-beta-9 and 2.14.1. It is patched in 2.15.0.
How to mitigate CVE-2021-44228
The change is not specific to the Loqate cartridge, and the jar comes with the OOB Sap Commerce package. This change does not have any custom code change specific to Loqate.
You can check the following in case you haven’t already handled any mitigation steps for CVE-2021-44228.
NOTE: Please note that the below version was recommended earlier and might change to handle some of the other log4j CVE’s. However, the steps remain the same. Details regarding this are mentioned in the section below.
Temporary Mitigation
If you are using Log4j v2.10 or above, and cannot upgrade, then set the property:
Additionally, you can set an environment variable for these same affected versions:
Or remove the JndiLookup class from the classpath. For example, you can run a command like this to remove the class from the log4j-core:
PatternLayout patterns can be modified to specify the message converter as %m{nolookups} instead of just %m.
Hybris Commerce Package comes with log4j versions 2.13.3 in its latest version (2105/2011) and 2.9.1 version in older version (1905)
Permanent mitigation
When the following steps are applied, you can verify whether this solution has worked by checking that there are no issues in start-up after updating the log4j jars.
Here are the repo locations from where you can download the log4j related jars:
Here are some external articles which provide useful additional information on this issue:
Other Log4j CVEs
While CVE-2021-44228 is the most notable Log4j vulnerability, there are a few others that you should be aware of.
Log4j Vulnerability CVE-2021-44832
A medium severity vulnerability which lets an attacker with control over the Log4j configuration set a malicious data source for the JDBC appender.
The data source refers to an attacker-controlled JNDI URI that will execute arbitrary code on the application using Log4j.
Although this is a Code Execution attack, it demands a crucial precondition: the attacker must have permissions to modify the log4j.xml file, which should only be available to a highly privileged actor. Alternatively, it requires an attacker to spoof a remote server from which the application imports the log4j.xml file, only if the application uses a remote log4j.xml file in the first place, and if it imports the file using an insecure connection (HTTP).
Since there is a very low chance of all these conditions coming together to allow an attack, the vulnerability was given a medium vulnerability score, which rates it as a Highly Complex attack, with High Privileges needed.
Mitigation: if you are using the Log4j 2.17.x branch for Java 8 and later, upgrade to 2.17.1.
Log4j Vulnerability CVE-2021-45105 (16 Dec)
Fixed in Log4j 2.17.0, 2.12.3 and 2.3.1
Apache Log4j2 versions 2.0-alpha1 through 2.16.0 (excluding 2.12.3) did not protect from uncontrolled recursion from self-referential lookups.
When the logging configuration uses a non-default Pattern Layout with a Context Lookup (for example, $${ctx:loginId}), attackers with control over Thread Context Map (MDC) input data can craft malicious input data that contains a recursive lookup, resulting in a StackOverflowError (runtime error that cannot be caught by an application.
StackOverflowError indicates that the application stack is exhausted, and is usually caused by deep or infinite recursion that will terminate the process. This is also known as a DOS (Denial of Service) attack.
Mitigation: upgrade to Log4j 2.3.1 (for Java 6), 2.12.3 (for Java 7), or 2.17.0 (for Java 8 and later).
Log4j Vulnerability CVE-2021-45046 (14 Dec)
Fixed in Log4j 2.16.0 (Java 8) and 2.12.2 (Java 7)
It was found that the fix to address CVE-2021-44228 in Apache Log4j 2.15.0 was incomplete in certain non-default configurations.
When the logging configuration uses a non-default Pattern Layout with a Context Lookup (for example, $${ctx:loginId}), attackers with control over Thread Context Map (MDC) input data can craft malicious input data using a JNDI Lookup pattern, resulting in an information leak, remote code execution in some environments and local code execution in all environments.
Mitigation: upgrade to Log4j 2.3.1 (for Java 6), 2.12.3 (for Java 7), or 2.17.0 (for Java 8 and later).
Additional resources: