NIST SPECIAL PUBLICATION 1800-17C
Multifactor Authentication for E-Commerce¶
Risk-Based, FIDO Universal Second Factor Implementations for Purchasers
Volume C:
How-To Guides
William Newhouse
Information Technology Laboratory
National Institute of Standards and Technology
Brian Johnson
Sarah Kinling
Jason Kuruvilla
Blaine Mulugeta
Kenneth Sandlin
The MITRE Corporation
McLean, VA
July 2019
This publication is available free of charge from https://doi.org/10.6028/NIST.SP.1800-17
The first draft of this publication is available free of charge from https://www.nccoe.nist.gov/sites/default/files/library/sp1800/cr-mfa-nist-sp1800-17.pdf
DISCLAIMER
Certain commercial entities, equipment, products, or materials may be identified by name or company logo or other insignia in order to acknowledge their participation in this collaboration or to describe an experimental procedure or concept adequately. Such identification is not intended to imply special status or relationship with NIST or recommendation or endorsement by NIST or NCCoE; neither is it intended to imply that the entities, equipment, products, or materials are necessarily the best available for the purpose.
National Institute of Standards and Technology Special Publication 1800-17C, Natl. Inst. Stand. Technol. Spec. Publ. 1800-17C, 165 pages, (July 2019), CODEN: NSPUE2
FEEDBACK
As a public-private partnership, we are always seeking feedback on our practice guides. We are particularly interested in seeing how businesses apply NCCoE reference designs in the real world. If you have implemented the reference design, or have a question about applying it in your environment, please email us at consumer-nccoe@nist.gov.
NATIONAL CYBERSECURITY CENTER OF EXCELLENCE
The National Cybersecurity Center of Excellence (NCCoE), a part of the National Institute of Standards and Technology (NIST), is a collaborative hub where industry organizations, government agencies, and academic institutions work together to address businesses’ most pressing cybersecurity issues. This public-private partnership enables the creation of practical cybersecurity solutions for specific industries, as well as for broad, cross-sector technology challenges. Through consortia under Cooperative Research and Development Agreements (CRADAs), including technology partners—from Fortune 50 market leaders to smaller companies specializing in information technology security—the NCCoE applies standards and best practices to develop modular, easily adaptable example cybersecurity solutions using commercially available technology. The NCCoE documents these example solutions in the NIST Special Publication 1800 series, which maps capabilities to the NIST Cybersecur ity Framework and details the steps needed for another entity to re-create the example solution. The NCCoE was established in 2012 by NIST in partnership with the State of Maryland and Montgomery County, Maryland.
To learn more about the NCCoE, visit https://www.nccoe.nist.gov/. To learn more about NIST, visit https://www.nist.gov.
NIST CYBERSECURITY PRACTICE GUIDES
NIST Cybersecurity Practice Guides (Special Publication 1800 series) target specific cybersecurity challenges in the public and private sectors. They are practical, user-friendly guides that facilitate the adoption of standards-based approaches to cybersecurity. They show members of the information security community how to implement example solutions that help them align more easily with relevant standards and best practices, and provide users with the materials lists, configuration files, and other information they need to implement a similar approach.
The documents in this series describe example implementations of cybersecurity practices that businesses and other organizations may voluntarily adopt. These documents do not describe regulations or mandatory practices, nor do they carry statutory authority.
ABSTRACT
As retailers in the United States have adopted chip-and-signature and chip-and-PIN (personal identification number) point-of-sale (POS) security measures, there have been increases in fraudulent online card-not-present electronic commerce (e-commerce) transactions. The risk of increased fraudulent online shopping became more widely known following the adoption of chip-and-PIN technology that increased security at the POS in Europe.
The NCCoE at NIST built a laboratory environment to explore methods to implement multifactor authentication (MFA) for online retail environments for the consumer and the e-commerce platform administrator. The NCCoE also implemented logging and reporting to display authentication-related system activity.
This NIST Cybersecurity Practice Guide demonstrates to online retailers that it is possible to implement open standards-based technologies to enable Universal Second Factor (U2F) authentication at the time of purchase when risk thresholds are exceeded.
The example implementations outlined in this guide encourage online retailers to adopt effective MFA implementations by using standard components and custom applications that are composed of open-source and commercially available components.
KEYWORDS
electronic commerce (e-commerce) security; internet shopping security; multifactor authentication (MFA)
ACKNOWLEDGMENTS
We are grateful to the following individuals for their generous contributions of expertise and time.
Name | Organization |
---|---|
Greg Dicovitsky | RSA |
Leonardo Andrade | RSA |
Adam Cohn | Splunk |
Arshad Noor | StrongKey |
Kamil Kreiser | TokenOne |
Derek Hanson | Yubico |
David Coley | Dominion Tea |
Brian Abe | The MITRE Corporation |
Lorrayne Auld | The MITRE Corporation |
Lura Danley | The MITRE Corporation |
Sallie Edwards | The MITRE Corporation |
Charles Jones, Jr. | The MITRE Corporation |
Joshua Klosterman | The MITRE Corporation |
Jay Vora | The MITRE Corporation |
Mary Yang | The MITRE Corporation |
The Technology Partners/Collaborators who participated in this build submitted their capabilities in response to a notice in the Federal Register. Respondents with relevant capabilities or product components were invited to sign a Cooperative Research and Development Agreement (CRADA) with NIST, allowing them to participate in a consortium to build these example implementations. We worked with:
Technology Partner/Collaborator | Build Involvement |
---|---|
RSA | RSA Adaptive Authentication (Cloud) Version 13.1 |
Splunk |
|
StrongKey |
|
TokenOne | TokenOne cloud-based Authentication Version 2.8.5 |
Yubico | Yubico YubiKey NEO Security Key |
List of Figures
Figure 1-1 MFA for E-Commerce High-Level Cost Threshold Reference Architecture
Figure 1-2 MFA for E-Commerce High-Level Risk Engine Reference Architecture
Figure 1-3 MFA for E-Commerce Lab Network Architecture
Figure 2-1 StrongKey CryptoEngine Components
Figure 2-2 Magento Open Source E-Commerce Platform Components
Figure 2-3 StrongKey magfido Module Components
Figure 2-4 RSA Adaptive Authentication Components
Figure 2-5 TokenOne Authentication Components
Figure 2-6 Splunk Enterprise Components
Figure A-1 Browser Display Without Any Security Keys Registered 149
Figure A-2 Browser Display with Two Security Keys Registered 150
Figure A-3 Display Function Part of the FIDO Registration Process 151
Figure A-4 Preregistration Part of the FIDO Registration Process 152
Figure A-5 Third and Final Step of the FIDO Registration Process 153
Figure A-6 Magento Checkout Workflow 154
Figure A-7 Overview of the FIDO Authentication Process 156
List of Tables
Table 1-1 Cost Threshold Architecture List of Components
Table 1-2 Risk Engine Architecture List of Components
Table 1-3 MFA Example Lab Build Network Details
Table 1-4 Lab Network Host Record Information
Table 2-1 Network Ports to Be Enabled
1. Introduction¶
The following volume of this guide shows information technology (IT) professionals and security engineers how we implemented the two example implementations. We cover all of the products employed in these reference designs. We do not re-create the product manufacturers’ documentation, which is presumed to be widely available. Rather, this volume shows how we incorporated the products together in our environment.
Note: These are not comprehensive tutorials. There are many possible service and security configurations for these products that are out of scope for these reference designs.
1.1. Practice Guide Structure¶
This National Institute of Standards and Technology (NIST) Cybersecurity Practice Guide demonstrates standards-based reference designs and provides retailers with the information they need to replicate the multifactor authentication (MFA) for electronic commerce (e-commerce) example implementations. These reference designs are modular and can be deployed in whole or in parts.
This guide contains three volumes:
- NIST SP 1800-17A: Executive Summary
- NIST SP 1800-17B: Approach, Architecture, and Security Characteristics – what we built and why
- NIST SP 1800-17C: How-To Guides – instructions for building the example implementations (you are here)
Depending on your role in your organization, you might use this guide in different ways:
Business decision makers, including chief security and technology officers, will be interested in the Executive Summary, NIST SP 1800-17A, which describes the following topics:
- challenges that enterprises face in implementing MFA to reduce online fraud
- example implementations built at the NCCoE
- benefits of adopting one or more of these example implementations
Technology or security program managers who are concerned with how to identify, understand, assess, and mitigate risk will be interested in NIST SP 1800-17B, which describes what we did and why. The following sections of Volume B will be of particular interest:
- Section 3.4, Risk Assessment, provides a description of the risk analysis we performed.
- Appendix A, Mapping to Cybersecurity Framework, maps NIST and consensus security references to the Cybersecurity Framework Subcategories that are addressed in this practice guide. Additionally, work roles in NIST SP 800-181, National Initiative for Cybersecurity Education (NICE) Cybersecurity Workforce Framework that perform the tasks necessary to implement those cybersecurity Functions and Subcategories were identified.
You might share the Executive Summary, NIST SP 1800-17A, with your leadership team members to help them understand the importance of adopting standards-based solutions when implementing MFA that can increase assurance of who is using the purchaser’s credit card and account information.
IT professionals who want to implement approaches like these will find the whole practice guide useful. You can use the How-To portion of the guide, NIST SP 1800-17C, to replicate all or parts of the build created in our lab. This How-To portion of the guide provides specific product installation, configuration, and integration instructions for deploying the example implementations. We do not recreate the product manufacturers’ documentation, which is generally widely available. Rather, we show how we incorporated the products together in our environment to create example implementations.
This guide assumes that IT professionals have experience implementing security products within the enterprise. While we have used a suite of commercial products to address this challenge, this guide does not endorse these particular products. Your organization can adopt these example implementations or one that adheres to these guidelines in whole, or you can use this guide as a starting point for tailoring and implementing parts of these e-commerce fraud-reducing capabilities. Your organization’s security experts should identify the products that will best integrate with your existing tools and IT system infrastructure. We hope that you will seek products that are congruent with applicable standards and best practices. Volume B, Section 3.5, Technologies, lists the products that we used and maps them to the cybersecurity controls provided by the reference implementations.
1.2. Example Builds Overview¶
The NCCoE at NIST built two example laboratory environments to explore MFA options available to online retailers, which are described in this section.
1.2.1. Usage Scenarios¶
The example implementations fulfill the use cases of a returning purchaser with established login account credentials with the retailer, and who possesses a Fast IDentity Online (FIDO) Universal Second Factor (U2F) authenticator [1], [2]. The purchaser’s U2F authenticator is used when the retailer system requests additional authentication. This gives the retailer additional assurance that the purchaser is a returning customer when the checkout process occurs in circumstances that exceed the retailer’s risk thresholds. In these NCCoE reference architectures, the risk thresholds that initiate MFA requests are based on the total cost of the shopping-cart transaction or upon input received from the risk engine.
The NCCoE worked with members of the NCCoE Retail Community of Interest to develop a set of use case scenarios to help design and test the reference implementations. For a detailed description of the example builds’ architectures and the use cases that they are based upon, reference Sections 4 and 5 in Volume B.
1.2.2. Architectural Overview¶
The MFA for e-commerce high-level reference architectures illustrated in Figure 1-1 and Figure 1-2 show the cost threshold and risk engine example implementations, respectively. The high-level reference architectures display the data communication among the returning purchaser, retailer e-commerce platform, risk assessment/MFA module and risk engine, MFA mechanisms, and logging and reporting dashboard.
The cost threshold example implementation uses a predetermined shopping-cart price threshold to require use of MFA by the returning purchaser. The risk engine example implementation uses analytics to determine when MFA is required by the returning purchaser. The two example implementations include e-commerce platform capabilities, risk assessment and MFA, and logging and display capabilities.
The example implementations were constructed on the NCCoE’s VMware vSphere virtualization operating environment. Internet access was used to connect to remote cloud-based components, while software components were installed as virtual servers within the vSphere environment.
TokenOne’s authentication capability authenticates the Magento e-commerce platform administrator before any administration modifications are made to the e-commerce platform. It is based upon TokenOne’s cloud-based authentication infrastructure and a smartphone application on either an Android or iPhone device. This helps secure the overall e-commerce organization’s infrastructure.
The lab network that was used to build and configure the example implementations is not connected to the NIST enterprise network.
Figure 1-1 MFA for E-Commerce High-Level Cost Threshold Reference Architecture
The cost threshold example build illustrated in Figure 1-1 uses the components listed in Table 1-1.
Table 1-1 Cost Threshold Architecture List of Components
Components | Installation Guidance |
---|---|
StrongKey CryptoEngine (SKCE) FIDO U2F server and CryptoEngine plug-in | Section 2.1 |
Magento Open Source e-commerce platform | Section 2.2 |
StrongKey Magento magfido risk assessment module | Section 2.3 |
TokenOne Authentication | Section 2.5 |
Splunk Enterprise logging/reporting dashboard | Section 2.6 |
Yubico YubiKey NEO Security Key | Section 2.7 |
Figure 1-2 MFA for E-Commerce High-Level Risk Engine Reference Architecture
The risk engine example build illustrated in Figure 1-2 uses the components listed in Table 1-2. The Risk Engine Adaptive Authentication component is highlighted in yellow within the green box.
Table 1-2 Risk Engine Architecture List of Components
Components | Installation Guidance |
---|---|
SKCE FIDO U2F server and CryptoEngine plug-in | Section 2.1 |
Magento Open Source e-commerce platform | Section 2.2 |
RSA Adaptive Authentication | Section 2.4 |
TokenOne Authentication | Section 2.5 |
Splunk Enterprise logging/reporting dashboard | Section 2.6 |
Yubico YubiKey NEO Security Key | Section 2.7 |
1.2.3. General Infrastructure Details and Requirements¶
The lab network architecture is shown in Figure 1-3, where the relationship among the MFA example implementation components, firewalls, and network design are illustrated. The installation and configuration for many of the components shown in Figure 1-3 will be referenced in this volume of the guide.
Figure 1-3 MFA for E-Commerce Lab Network Architecture
Table 1-3 lists the MFA example lab build’s network internet protocol (IP) address range, system, and associated IP addresses. These network addresses were used in the example implementation builds and will be modified to reflect actual network architectures when deployed into a retailer’s information system network.
Table 1-3 MFA Example Lab Build Network Details
Network | System | IP Address |
---|---|---|
192.168.1.0/24 | Splunk Enterprise server logging and reporting | 192.168.1.10 |
192.168.2.0/24 | domain name system (DNS) common services | 192.168.2.10 |
192.168.3.0/24 | SKCE FIDO U2F server authentication services | 192.168.3.30 |
192.168.3.0/24 | RSA Adaptive Authentication connectivity, TokenOne, Magento Open Source authentication services and retailer e-commerce platform | 192.168.3.155 |
192.168.5.0/24 | Optional future services for vendor network | As assigned |
There are both prerequisite infrastructure and example implementation components, whose installation and configuration are described below.
1.2.3.1. Domain Name System¶
DNS was configured within the lab to facilitate data communication among the example implementation components. The domain names and IP address ranges will be modified to reflect actual network architectures when deployed into an online retailer’s information system network.
The name of the domain used for this example build is mfa.local. Create the following host records in the mfa.local forward lookup zone by using the host names, fully qualified domain names (FQDNs), and IP addresses listed in Table 1-4.
Table 1-4 Lab Network Host Record Information
Host Name | FQDN | IP Address |
---|---|---|
Splunk | Splunk.mfa.local | 192.168.1.10 |
DNS | DNS.mfa.local | 192.168.2.10 |
Magento | Magento.mfa.local | 192.168.3.30 |
Magento2 | Magento2.mfa.local | 192.168.3.155 |
The network adapter configuration for the DNS server is as follows:
Network Configuration (Interface 1)
- IPv4 Manual
- IPv6 Disabled
- IP Address: 192.168.2.10
- Netmask: 255.255.255.0
- Gateway: 192.168.2.1
- DNS Name Servers: 192.168.2.10
DNS-Search Domains: mfa.local
1.3. Typographic Conventions¶
The following table presents typographic conventions used in this volume.
Typeface/Symbol | Meaning | Example |
---|---|---|
Italics | file names and path names; references to documents that are not hyperlinks; new terms; and placeholders |
For detailed definitions of terms, see the NCCoE Glossary. |
Bold | names of menus, options, command buttons, and fields | Choose File > Edit. |
Monospace | command-line input, onscreen computer output, sample code examples, and status codes | mkdir |
Monospace Bold | command-line user input contrasted with computer output | service sshd start |
blue text | link to other parts of the document, a web URL, or an email address | All publications from NIST’s NCCoE are available at https://www.nccoe.nist.gov. |
2. How to Install and Configure¶
This section of the practice guide contains detailed instructions for installing and configuring the products used to build the example implementations.
2.1. StrongKey CryptoEngine FIDO U2F Server¶
This section of the guide provides installation and configuration guidance for the SKCE, which provides FIDO authentication services.
2.1.1. StrongKey CryptoEngine Overview¶
The SKCE 2.0 Build 163 from StrongKey [3] performs the FIDO U2F [1], [2] server functionality in the build architecture.
SKCE is provided in the StrongKey Key Appliance, but the company also distributes some of its software under the Lesser General Public License, published by the Free Software Foundation. SKCE was downloaded from the StrongKey repository on SourceForge and was used in this build.
The CryptoEngine plug-in enables Magento to communicate with the SKCE when the returning purchasers require MFA.
Both the cost threshold and risk engine example implementations use the SKCE’s capabilities. The components that are installed by using the instructions in this section are illustrated in Figure 2-1 and are highlighted in yellow within the green boxes.
Figure 2-1 StrongKey CryptoEngine Components
Installation instructions and the product download site for StrongKeyʼs FIDO U2F server, SKCE, can be found at https://sourceforge.net/projects/skce/. For this example implementation, we installed and configured a local copy of SKCE by using the SKCE installation instructions documented below in Section 2.1.2.
2.1.2. SKCE Requirements¶
The following subsections document the software, hardware, and network requirements for SKCE Version 2.0.
2.1.2.1. SKCE Software Requirements¶
For this build, SKCE was installed on a Community Enterprise Operating System (CentOS) 7.4 64-bit server.
Because SKCE is a Java application, it is compatible with operating systems that support a compatible version of Java and the other required software. The application was built with the Oracle Java Development Kit (JDK) Version 8, Update 72. Instructions for obtaining Oracle JDK and the other necessary components are provided in this section.
SKCE can be installed manually or with an installation script included in the download. SKCE depends on other software components, including a Structured Query Language (SQL) database, a lightweight directory access protocol (LDAP) directory server, and the Glassfish Java application server. By default, the script will install MariaDB, OpenDJ, and Glassfish all on a single server.
For this build, the scripted installation was used with the default software components. The required software components listed below must be downloaded prior to running the installation script:
- Glassfish 4.1 2010
- Java Cryptography Extension Unlimited Strength Jurisdiction Policy Files 8 2011
- JDK 8, Update 121 2012
- OpenDJ 3.0.0 2013
- MariaDB 10.1.22 2014
- MariaDB Java Client 2015
Reference StrongKey’s scripted installation instructions for details and preinstallation software download links (StrongKey, n.d.).
Note: To download OpenDJ, the user must register for a free account for ForgeRock BackStage.
2.1.2.2. Hardware Requirements¶
StrongKey recommends installing SKCE on a server with at least 10 gigabytes (GB) of available disk space and 4 GB of random access memory (RAM).
2.1.2.3. Network Requirements¶
The SKCE application programming interface (API) uses transmission control protocol (TCP) Port 8181 (Table 2-1). Any applications that request U2F registration, authentication, or deregistration actions from the SKCE need to be able to connect on this port. Glassfish runs a hypertext transfer protocol secure (https) service on this port. Use firewall-cmd, iptables, or any other system utility for manipulating the firewall to open this port.
Table 2-1 Network Ports to Be Enabled
Port | Use |
---|---|
TCP 8181 | U2F Application Access |
Other network services listen on the ports listed in Table 2-2. For the scripted installation, where all of these services are installed on a single server, there is no need to adjust firewall rules for these services when they are only accessed from localhost.
Table 2-2 Local Ports
Port | Use |
---|---|
TCP 3306 | MariaDB listener |
TCP 4848 | Glassfish administrative console |
TCP 1389 | OpenDJ LDAP service |
2.1.3. Install SKCE, the FIDO U2F Authentication Server¶
The installation procedure consists of the following steps:
- Download the software dependencies to the server where SKCE will be installed.
- Make any required changes to the installation script.
- Run the script as root/administrator.
- Perform post-installation configuration.
- Reference StrongKey’s scripted installation instructions for details and preinstallation software download links (StrongKey, n.d.).
The installation script creates a “strongauth” Linux user and installs all software under /usr/local/strongauth. Rather than reproduce the installation steps here, this section provides some notes on the installation procedure:
- Download the software. Download and unzip the SKCE build to a directory on the server where SKCE is being installed. Download all installers as directed in the SKCE instructions to the same directory.
- Change software versions as required in the installation script. If different versions of any of the software dependencies were downloaded, update the file names in the installation script (install-skce.sh). Using different versions of the dependencies, apart from minor point-release versions, is not recommended. For the lab build, JDK Version 8u151 was used instead of the version referenced in the instructions. This required updating the JDK and JDKVER settings in the file.
- Change passwords in the installation script. Changing the default passwords in the delivered script is strongly recommended. The defaults are readily discoverable, as they are distributed with the software. Passwords should be stored in a password vault or other agency-approved secure storage. Once the installation script has been run successfully, the script should be deleted or sanitized to remove passwords. The following lines in the installation script contain passwords:
LINUX_PASSWORD=ShaZam123 # For 'strongauth' account
GLASSFISH_PASSWORD=adminadmin # Glassfish Admin password
MYSQL_ROOT_PASSWORD=BigKahuna # MySQL 'root' password
MYSQL_PASSWORD=AbracaDabra # MySQL 'skles' password
SKCE_SERVICE_PASS=Abcd1234! # Webservice user 'service-cc-ce' password
SAKA_PASS=Abcd1234!
SERVICE_LDAP_BIND_PASS=Abcd1234!
SEARCH_LDAP_BIND_PASS=Abcd1234!
Set the App ID (identifier) uniform resource locator (URL): The App ID setting in install-skce.sh should point to a URL that will be accessible to clients where the app.json file can be downloaded. The default location is a URL on the SKCE server, but the SKCE would not be exposed to mobile clients in a typical production deployment. In the lab, app.json was hosted on the following SKCE server:
/usr/local/strongauth/payara41/glassfish/domains/domain1/docroot/app.json
This enables the file to be accessed by clients at the following URL: https://magento.mfa.local:8181/app.json.
Run the script. install-skce.sh must be run as the root user. If the installation script terminates with an error, then troubleshoot and correct any problems before continuing.
(For CentOS 7) create the firewall rule. The installation script attempts to open the required port by using iptables, which does not work on CentOS 7. In that case, the following commands will open the port:
**# firewall-cmd --permanent --add-port 8181/tcp**
success
**# firewall-cmd --reload**
success
Restart Glassfish. On CentOS 7, run the following command:
$ sudo systemctl restart glassfishd
Complete Step 3b in the SKCE installation instructions to activate the cryptographic module.
Complete Step 3c in the SKCE installation instructions to create the domain signing key. When prompted for the App ID, use the URL referenced above in the App ID setting of the install-skce.sh script.
Complete Step 4 in the SKCE installation instructions if secondary SKCE instances are being installed; this was not done for this build but is recommended for a production installation.
Test the FIDO Engine. Follow the testing instructions under Step D at the following URL: https://sourceforge.net/p/skce/wiki/Test%20SKCE%202.0%20Using%20a%20Client%20Program%20%28Build%20163%29/.
There are additional tests on that web page to test the other cryptographic functions of the SKCE; however, only the FIDO Engine tests are critical for this build.
2.2. Magento Open Source Electronic Commerce Platform¶
This section provides installation and configuration guidance for the Magento Open Source e-commerce platform. The Magento platform provides connectivity to most of the example implementations’ components. Both example implementation builds use Magento. The location of the Magento components that are installed using the instructions in this section are illustrated in Figure 2-2 and are highlighted in yellow within the green boxes.
Figure 2-2 Magento Open Source E-Commerce Platform Components
2.2.1. Magento Overview¶
Magento is an e-commerce platform that offers on-premises and cloud solutions to retailers. For this lab implementation, we leveraged the Magento Open Source version of this platform, which was hosted on-premises. This section describes how to install and configure Magento Open Source [4], [5] and how to configure it with StrongKey’s SKCE FIDO U2F server capabilities. For the e-commerce platform, Magento Open Source Version 2.1.8 was used in the example implementation.
The installation procedure consists of the following steps:
- Download the Magento software to the server where it will be installed.
- Download the software dependencies to the server where Magento will be installed.
- Execute commands as root/administrator.
- Perform post-installation configuration.
2.2.2. Magento Requirements¶
The following subsections document the software, hardware, and network requirements for Magento Open Source 2.1.X.
2.2.2.1. Software Requirements¶
For this implementation, Magento was installed on a CentOS 7.0 server.
Magento Open Source developer’s documentation states that Magento can operate on Linux operating systems, such as these:
- Red Hat Enterprise Linux
- CentOS
- Ubuntu
- Debian
Magento Open Source 2.1.X requires the following installations:
- Web Server: Apache 2.2 or 2.4 or NGINX 1.X
- Database: MySQL 5.6, MariaDB, Percona, or other binary-compatible MySQL technologies
- Hypertext Preprocessor (PHP): 7.0.2, 7.0.4, 7.0.6-7.0.X, or 7.1.X
- Secure Sockets Layer (SSL)
- Mail Server: Redis 3.0, Varnish 3.5, memcached
See Magento’s developer’s documentation for additional details and download links: https://devdocs.magento.com/guides/v2.1/install-gde/system-requirements-tech.html.
2.2.2.2. Hardware Requirements¶
Magento requires installing Magento Open Source on a server with at least 2 GB of RAM.
2.2.3. Magento Preinstallation¶
Magento requires the Linux, Apache, MySQL, PHP (LAMP) software stack. This section describes the process of installing and configuring the LAMP software stack that uses versions compatible with Magento.
Open a terminal window, and enter the following command to log in as root:
sudo su
- After entering the command, you will be prompted to enter the password for the current user.
To install wget from the terminal, enter the following command:
yum install wget
Download the Extra Packages for Enterprise Linux repository by entering the following command:
wget https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
Download the Remi repository by entering the following command:
wget http://rpms.remirepo.net/enterprise/remi-release-7.rpm
Add the two repositories—so that Yellowdog Updater Modified (YUM) can locate them when needed—by entering the following command:
rpm -Uvh remi-release-7.rpm epel-release-latest-7.noarch.rpm
Install the Apache server by entering the following command:
yum install httpd
Install Transport Layer Security (TLS)/SSL support for Hypertext Transfer Protocol Daemon (HTTPD) by entering the following command:
yum install mod_ssl
8. Install PHP by entering the following command:
yum install --enablerepo=remi-php70 php php-opcache php-xml php-mcrypt php-gd php-devel php-mysql php-mbstring php-zip phpcommon php-ldap php-soap php-intl
Create a file named Maria.repo in the /etc/yum.repos.d by entering the following command:
vim /etc/yum.repos.d/Maria.repo
- In the text editor, enter the following contents:
[mariadb]
name = MariaDB
baseurl = http://yum.mariadb.org/10.2/centos7-amd64
gpgkey = https://yum.mariadb.org/RPM-GPG-KEY-MariaDB
gpgcheck = 1
- Save the file, and exit by entering the following command:
:wq!
- Install MariaDB by entering the following command:
yum install mariadb-server mariadb-client
- Restart the computer system by entering the following command:
init 6
- Open a terminal window, and enter the following command to log in as root:
sudo su
- Log in to MariaDB as root by entering the following command (Note: Even though the MariaDB relational database is being used, it uses the same tools as the MySQL database.):
mysql -u root
- Create the Magento database by entering the following SQL command:
create database magento2;
- Create the Magento user by entering the following command, replacing parameters in <> with values appropriate for your installation:
GRANT ALL PRIVILEGES ON magento2.\* TO magento@localhost IDENTIFIED BY '<db password>';
- Flush the database privileges by entering the following SQL command:
flush privileges;
- Exit the MariaDB shell by entering the following command:
exit
- Open httpd.conf to modify Apache settings by entering the following command:
vim /etc/httpd/conf/httpd.conf
- Locate the
<Directory “/var/www/html”>
section, and change“AllowOverride None”
to“AllowOverride All”
.
- Save, and exit by entering the following command:
:wq!
- Open php.ini to modify PHP settings by entering the following command:
vim /etc/php.ini
- Uncomment the line containing
date.timezone
by removing the “;” character preceding the text, and enter your time zone as shown below (this example is for the eastern United States).
date.timezone = America/New_York
- Uncomment the line containing
memory_limit
by removing the “;” character preceding the text, and enter 2G as the value, as shown below.
memory_limit = 2G
- Open 10-opcache.ini to modify PHP settings by entering the following command:
vim /etc/php.d/10-opcache.ini
- Uncomment the line containing
opcache.save_comments
by removing the ”;“ character preceding the text. The line should then read as shown below.
opcache.save_comments=1
2.2.4. Magento Installation¶
For the e-commerce platform, Magento Open Source Version 2.1.8 [5] was used in the example implementation.
To download the open-source copy of Magento, navigate to the site: https://magento.com/products/open-source.
When redirected to the resource page, specify the download format. In the example implementation, we installed Magento on CentOS by selecting a file that ends
in .gz
, as shown in the example below.
Magento-Community-Edition-2.1.8.tar.gz
Create a Magento directory inside HTTPDʼs DocumentRoot folder by entering the following command:
mkdir /var/www/html/magento
Move the Magento-CE-2.1.8.tar.gz into the Magento directory with the following command:
mv <download location>/Magento-CE-2.1.8-2017-08-09-96-91-21.tar.gz /var/www/html/magento
Change the directory to the Magento directory by entering the following command (all commands following this step should be run from this directory):
cd /var/www/html/magento
Extract the Magento distribution from Magento-CE-2.1.8.tar.gz by entering the following command:
tar zxvf Magento-CE-2.1.8-2017-08-09-96-91-21.tar.gz
Change ownership of the extracted files to the Apache user by entering the following command:
chown -R apache:apache /var/www/html/magento
- Change file permissions by entering the following command (Note: This is a single command that must be executed on a single line.):
find var vendor pub/static pub/media app/etc -type f -exec chmod u+w {} \\; && find var vendor pub/static pub/media app/etc -type d -exec chmod u+w {} \\; &&
chmod u+x bin/magento
Change the Security-Enhanced Linux (SELinux) context permissions to allow the Apache user to have read/write access to specific directories within the Magento directory by entering the following command:
chcon -R --type httpd_sys_rw_content_t app/etc var pub/media pub/static
- Open the web browser to log in to https://marketplace.magento.com and access your account. Click Access Keys.
- In the Magento tab, click Create A New Access Key.
- Enter a name for your new access key, and click OK.
- The new access keys will be displayed in the menu with the Status of Enabled.
- Install Magentoʼs sample data by entering the following command and then providing <public key> when a Username is requested and <private key> as the Password when prompted:
php bin/magento sampledata:deploy
- Install the Magento software distribution by issuing the following command, replacing parameters in <> with values appropriate for your installation (Note: This is a single command that must be executed on a single line.):
php bin/magento setup:install --admin-firstname=<First Name> --admin-lastname=<Last Name> --admin-email=<email> --admin-user=strongauth
--admin-password=<password> --base-url=https://<fully-qualified-domainname>/magento/ --db-host=127.0.01 --db-name=magento2 --db-user=magento
--db-password=<db password> --use-secure-admin=1
- Modify compiled file permissions by issuing the following command:
chmod -R u-w app/etc
- Modify compiled file permissions by issuing the following command:
chown -R apache:apache /var/www/html/magento && find var vendor pub/static pub/media -type f -exec chmod u+w {} \\; && find var vendor pub/static pub/media
-type d -exec chmod u+w {} \\; && chmod u+x bin/magento
- Modify SELinux permissions, to enable HTTPD to access the database, by executing the following commands:
service httpd stop
setsebool -P httpd_can_network_connect 1
setsebool -P httpd_can_network_connect_db 1
service httpd start
service mysql restart
- Verify the installation by navigating in the browser to the store URL, which was set up in Section 2.2.4, Step 13 (https://magento2.mfa.local/magento).
2.2.5. Configuring the Magento Account Lockout Feature¶
This section describes the steps required to configure account lockouts after a specified number of failed login attempts. For our example implementation, we specified five as the maximum number of login-attempt failures before temporarily disabling the account, and 20 minutes as the lockout time. These parameters can be adjusted, and the administrator of the Magento site has the information system privileges to set these values based on the implementer’s preference.
Determine the admin uniform resource identifier (URI) by running the following command:
php bin/magento info:adminuri
- Navigate to the admin URI identified in Section 2.2.5, Step 1, and sign in with the Magento Username and Password created in Section 2.2.4, Step 13 (the example implementation URI is https://magento2.mfa.local/admin_14mzl4).
- Proceed to the Configuration page: STORES > Configuration.
- Click the CUSTOMERS drop-down from the menu in the Configuration page, and select Customer Configuration.
- Click the Password Options drop-down.
- Uncheck the Use system value fields for the Maximum Login Failures to Lockout Account and Lockout Time (minutes) to modify the settings for the Password Options.
- Click Save Config to save the changes made.
- The following pop-up will appear, notifying you to refresh Cache Types. Click the Cache Management link in the message.
- You will be redirected to the Cache Management page. Click Flush Magento Cache to resolve the INVALIDATED Cache Types.
- Upon completion of the flush, the page will reflect the changes.
2.2.6. Disabling Magento Guest Checkout¶
This section describes steps to disable Magento’s guest checkout feature to ensure that purchasers cannot choose to check out as a guest.
- Navigate to the admin URI identified in Section 2.2.5, Step 1 (https://magento2.mfa.local/admin_14mzl4), and sign in with the Username and Password created in Section 2.2.4, Step 13.
- Proceed to the Configuration page: STORES > Configuration.
- Click the SALES drop-down from the menu on the Configuration page, select Checkout, and expand the Checkout Options.
- Uncheck the Use system value fields for the Allow Guest Checkout setting, and modify the settings to No for the Checkout Options.
- Click Save Config.
- The following pop-up will appear, notifying you to refresh Cache Types. Click the Cache Management link in the message.
- You will be redirected to the Cache Management page. Click Flush Magento Cache to resolve the INVALIDATED Cache Types.
- Upon completion of the flush, the page will reflect the changes.
2.3. StrongKey magfido Module¶
This section of the guide provides installation and configuration guidance for the StrongKey magfido FIDOU2FAuthenticator module [6]. While the core feature of the magfido module is to enable U2F authentication, the magfido module also allows registration of FIDO U2F Security Keys. Additional information on magfido and how the registration feature works can be found in Appendix A.
2.3.1. StrongKey magfido Overview¶
The magfido module is used in the cost threshold example implementation build to examine the shopping cartʼs characteristics and to recommend whether MFA is required for the returning purchaser. The magfido module will modify the default behavior of Magento to register FIDOU2FAuthenticators, also known as FIDO Security Keys, and for FIDO authentication on purchases that exceed a total of $25. The StrongKey magfido components that are installed by using the instructions in this section are illustrated in Figure 2-3 and are highlighted in yellow within the green boxes.
Figure 2-3 StrongKey magfido Module Components
2.3.2. StrongKey magfido Installation and Configuration¶
The installation procedure consists of the following steps.
- Download the software module to the Magento server where magfido will be installed.
- Execute commands as root/administrator.
- Perform post-installation configuration.
Navigate to the following site, and proceed to download the code: https://sourceforge.net/projects/magfido/.
Create a code directory inside Magentoʼs app folder by entering the following command:
mkdir /var/www/html/magento/app/code
Change your current directory to the Downloads directory by entering the following command:
cd /home/magento/Downloads/
Unzip the magfido-code-3-trunk.zip by entering the following command:
unzip magfido-code-3-trunk.zip
Move the StrongAuth_FIDOU2FAuthenticator module to the code directory by entering the following command:
cp -r home/magento/Downloads/magfido-code-3-trunk/StrongAuth /var/www/html/magento/app/code
Change directories to the Magento directory by entering the following command:
cd /var/www/html/magento
Enable the StrongAuth_FIDOU2FAuthenticator module by entering the following command:
php bin/magento module:enable StrongAuth_FIDOU2FAuthenticator
Register the StrongAuth_FIDOU2FAuthenticator module by entering the following command:
php bin/magento setup:upgrade
Recompile dependencies by entering the following command:
php bin/magento setup:di:compile
- Adjust the compiled file permissions by entering the following command:
chown -R apache:apache /var/www/html/magento && find var vendor pub/static pub/media -type f -exec chmod u+w {} \\; && find var vendor pub/static pub/media
-type d -exec chmod u+w {} \\; && chmod u+x bin/magento
Configure the locally installed SKCE with the following steps:
- Open FidoService.php by entering the following command:
Vim /var/www/html/magento/app/code/StrongAuth/FIDOU2FAuthenticator/Model/FidoService.php
- Modify the file to include the following information:
- The DID parameter is the Domain ID of SKCE.
- The SVCUSERNAME parameter is the SKCE user responsible for authorizing requests to the FIDO server.
- The SVCPASSWORD parameter is the password of the SKCE user.
- The PROTOCOL, VERSION, and LOCATION are parameters used for reference for the FIDO server. They should be left as is.
- The WSDL (Web Services Description Language) parameter specifies the web service end point with which the Magento server will communicate to send web-service requests to the FIDO server. The default SKCE install will have the WSDL as “https://<fully-qualified-domainname>:8181/skfe/soap?wsdl.”
- Retrieve a copy of the FIDO serverʼs TLS digital certificate by entering the following command (Note: This is a single command that must be executed on a single line.):
openssl s_client -servername <fully-qualified-domain-name> -connect <fully-qualified-domain-name>:8181 </dev/null \| sed -ne '/BEGIN CERTIFICATE-/,/-END
CERTIFICATE-/p' > <FQDN>.crt
Add the certificate to the list of trusted certificates by entering the following command:
cat <fully-qualified-domain-name>.crt >> /etc/pki/tls/cert.pem
- Open the Chrome browser and navigate to https://magento.mfa.local:8181/app.json.
- A warning will appear, stating that “Your connection is not private.”
- Click HIDE ADVANCED.
- Click Proceed to <fully-qualified-domain-name> (unsafe).
On your SKCE machine, edit the app.json file by entering the following command:
vim usr/local/strongauth/payara41/glassfish/domains/domain1/docroot/app.json
- Add the FQDN of the machine hosting the Magento application in the ids array, and save the file.
2.4. RSA Adaptive Authentication¶
This section of the guide provides installation and configuration guidance for the RSA Adaptive Authentication risk engine. The RSA Adaptive Authentication product performs a risk analysis and then prompts the returning user to provide an MFA authenticator when required for the risk engine example implementation build. The purpose of the RSA Adaptive Authentication is to minimize fraud with a low-friction consumer experience. This example implementation uses the RSA Adaptive Authentication cloud offering. The components that integrate Magento with RSA Adaptive Authentication are installed by using the instructions in this section. The components are illustrated in Figure 2-4 and are highlighted in yellow within the green box.
Figure 2-4 RSA Adaptive Authentication Components
2.4.1. RSA Overview¶
RSA [7] offers an Adaptive Authentication [8] capability, which is part of the risk engine example implementation.
The installation procedure consists of the following steps:
Preinstallation:
- Download the RSA Project Library.
- Configure Magento to accept additional extension attributes.
Installation and configuration:
- Integrate RSA files into Magento.
- Create policy in RSA Back Office.
2.4.2. RSA Preinstallation Steps¶
Before beginning installation, perform the following steps.
- Contact your RSA representative regarding access to RSA project library files (RSA.zip) and RSA.php files. Download these files to the /home/magento/Downloads directory.
- Configure Magento to accept additional extension attributes as outlined below.
This section will discuss how to add extension attributes to Magento to pass necessary information to RSA Adaptive Authentication.
- Open a terminal window.
To edit the file containing Magento’s extension attributes, issue the following commands:
vim /var/www/html/magento/app/code/StrongAuth/FIDOU2FAuthenticator/etc/extension_attributes.xml
- Press
**i**
to enter insertion mode.
- Following Line 53, which contains
<attribute code=”signature” type=”string” />
, insert the following lines (shown in the picture below):
<attribute code=”email” type=”string”/>
<attribute code=”deviceprint” type=”string”/>
<attribute code=”cookie” type=”string”/>
<attribute code=”httplang” type=”string”/>
<attribute code=”useragent” type=”string”/>
<attribute code=”httpref” type=”string”/>
Press the Esc key to exit insert mode.
Save changes, and exit by entering the following command:
:wq
.Return to the terminal window.
Change to the Magento folder by entering the following command:
cd /var/www/html/magento
To recompile Magento to reflect the changes made to the extension attributes file, issue the following commands:
php bin/magento module:disable StrongAuth_FIDOU2FAuthenticator
php -f bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento module:enable StrongAuth_FIDOU2FAuthenticator
php bin/magento setup:di:compile
2.4.3. Adaptive Authentication Installation and Configuration¶
This section provides a step-by-step installation guide for integrating RSA Adaptive Authentication. Before you begin, make sure that you have received your RSA project libraries from your RSA representative.
- Open a terminal window.
Create a new directory by entering the following command:
Mkdir /var/www/html/RSA
Obtain the RSA zip file from your RSA representative.
Change to the Downloads directory by entering the following command:
cd /home/magento/Downloads
Unzip the RSA directory by entering the following command:
unzip RSA.zip
Change to the newly unzipped directory by entering the following command:
cd aaWsdlTake3/
Copy the contents of the API runtime directory to the RSA directory, which was created in Step 2, by entering the following command:
cp resources/aa13/aa70api-runtime/* /var/www/html/RSA/
Copy the contents of the aaWsdlTake3 directory to the StrongAuth model directory by entering the following command:
cp -R ./* /var/www/html/magento/app/code/StrongAuth/FIDOU2FAuthenticator/Model/
Change to the generated RSA API runtime folder by entering the following command:
cd /var/www/html/magento/app/code/StrongAuth/FIDOU2FAuthenticator/Model/generated/aa13/aa70api-runtime/
Edit the Adaptive Authentication file by entering the following command:
vim AdaptiveAuthentication.php
Make edits in the Adaptive Authentication file by pressing the i key to enter insert mode.
Change Line 297 of the document to the following line:
$wsdl = ‘http://magento2.mfa.local/RSA/AdaptiveAuthentication.wsdl’;
- Press the Esc key to exit insert mode.
- Save changes, and exit by entering the following command:
:wq.
- Edit the RSA Risk Assessor File by entering the following command:
vim /var/www/html/magento/app/code/StrongAuth/FIDOU2FAuthenticator/Model/RiskAssessor.php
- Press the i key to enter editor mode.
- Make the following changes to the RiskAssessor.php file:
- After Line 41, add the following two lines:
use RSA;
require_once(‘RSA.php’);
- Change Line 55 to the following line:
Public function isFidoNeeded($cartId, $email, $deviceprint, $cookie, $httplan, $useragent, $httpref)
- After Line 65, edit the following lines:
$test = new RSA;
$amount = $test->rsaAACall($cartId, $email, $deviceprint, $cookie, $httplan, $useragent, $httpref);
return $amount;
- Press the Esc key to exit insert mode.
- Save changes, and exit by entering the following command:
:wq.
- Open the PIMOverrideFidoAuthenticate.php file in the vim editor by entering the following command:
vim /var/www/html/magento/app/code/StrongAuth/FIDOU2FAuthenticator/Model/PIMOverrideFidoAuthenticate.php
- Press the i key to enter editor mode.
- Make the following changes to the PIMOverrideFidoAuthenticate.php file:
- Between Lines 68 and 72, edit the following lines:
extData = $paymentMethod->getExtensionAttributes();
if($this->riskAssessorFactory->create()->isFidoNeeded($cartId,$extData->getEmail(),$extData->getDeviceprint(),$extData->getCookie,$extData->getHttplang(),$extData->getUseragent,$extData->getHttpref()))
{
- Press the Esc key to exit insert mode.
- Save changes, and exit by entering the following command:
:wq.
- Open the RSA RiskAssessor Controller file by entering the following command:
vim /var/www/html/magento/StrongAuth/FIDOU2FAuthenticator/Controller/Index/Riskassessor.php
- Press the i key to enter editor mode.
- Make the following changes to the RiskAssessor.php file:
- Change Line 60 to the following line:
$result = $this->riskAssessorFactory->create()->isFidoNeeded($params[‘cartId’], $params[‘email’], $params[‘deviceprint’], $params[‘cookie’],
$params[‘httplang’], $params[‘useragent’], $params[‘httpref’]);
- Press the Esc key to exit insert mode.
- Save changes, and exit by entering the following command:
:wq.
- Open the RSA JavaScript Override file by entering the following command:
vim /var/www/html/magento/StrongAuth/FIDOU2FAuthenticator/view/frontend/web/js/default-payment-override.js
- Press the i key to enter editor mode.
- Make the following changes to the default-payment-override.js file:
- Add the following two lines after Line 57:
‘StrongAuth_FIDOU2FAuthenticator/js/lib/hashtable’,
‘StrongAuth_FIDOU2FAuthenticator/js/lib/rsa’
- Change Line 83 to the following line:
Data: {cartId: quote.getQuoteId(), email : window.customerData.email, deviceprint : encode_deviceprint(), cookie: document.cookie, httplang :
window.navigator.language, useragent : navigator.userAgent, httpref : document.referrer},
- Change Line 95 to the following line:
self.getPlaceOrderDeferredObjectOverride(null)
- After Line 268, add the following lines:
Data[‘extension_attributes’][‘email’] = window.customerData.email;
Data[‘extension_attributes’][‘deviceprint’] = encode_deviceprint();
Data[‘extension_attributes’][‘cookie’] = document.cookie;
Data[‘extension_attributes’][‘httplang’] = window.navigator.language;
Data[‘extension_attributes’][‘useragent’] = navigator.userAgent;
Data[‘extension_attributes’][‘httpref’] = document.referrer;
- Press the Esc key to exit insert mode.
- Save changes, and exit by entering the following command:
:wq.
- Download the RSA JavaScript files from your RSA representative.
- Make the following change to the Downloads directory:
cd /home/magento/Downloads
- Unzip the contents of the RSA JavaScript folder by entering the following command:
unzip RSA_Scripts.zip
- Move to the newly unzipped scripts folder by entering the following command:
cd scripts/
- Copy the rsa.js and hashtable.js files to StrongAuth front-end JavaScript directory by entering the following commands:
cp rsa.js /var/www/html/magento/app/code/StrongAuth/FIDOU2FAuthenticator/view/frontend/web/js/lib/
cp hashtable.js /var/www/html/magento/app/code/StrongAuth/FIDOU2FAuthenticator/view/frontend/web/js/lib/
- Open the StrongAuth JavaScript required file by entering the following command:
vim
/var/www/html/magento/app/code/StrongAuth/FIDOU2FAuthenticator/view/frontendrequirejs-config.js
- Press the i key to enter editor mode.
- Make the following edits to the requirejs-config.js file:
- After Line 41, insert the following lines:
“hashtable” : “StrongAuth_FIDOU2FAuthenticator/js/lib/hastables”,
“rsa” : “StrongAuth_FIDOU2FAuthenticator/js/lib/rsa
- Press the Esc key to exit insert mode.
- Save changes, and exit by entering the following command:
:wq.
- To create Adaptive Authentication policies, follow the product configuration instructions provided by your RSA representative.
2.5. TokenOne¶
This section provides installation and configuration guidance for TokenOneʼs authentication capability [9]. TokenOneʼs authentication product is used by the retailer e-commerce platform administrator when they are managing the Magento e-commerce platform. TokenOne developed a Magento connector that both the cost threshold and risk engine example implementations use. The TokenOne authentication components that are installed and configured in this section are illustrated in Figure 2-5 and are highlighted in yellow within the green box.
Figure 2-5 TokenOne Authentication Components
2.5.1. TokenOne Overview¶
TokenOne allows software-based authentication through a onetime personal identification number (PIN). The Magento Admin URI portal has been configured to use Second Factor Authentication with TokenOne. When accessing Magento with TokenOne’s authentication capability, the user’s numeric PIN is not entered, transmitted, or stored, but the corresponding letter code—which is entered when accessing Magento—is different every time that the user accesses the system. The TokenOne smartphone application is not push-button. The user always enters the code in the Magento administration interface.
The installation procedure consists of the following steps:
Preinstallation:
- Download the TokenOne application.
- Download the TokenOne module.
Installation and configuration:
- Integrate the TokenOne module into Magento.
- Test connectivity and authentication.
2.5.2. Preinstallation Steps¶
Before beginning installation, ensure that the following steps are completed:
- Download and install the TokenOne mobile application from either the Apple App Store or the Google Play Store.
- Speak with your TokenOne representative to receive the TokenOne10.zip file.
- Download the TokenOne10.zip file to the /home/magento/Downloads directory.
2.5.3. TokenOne Installation and Configuration¶
To begin installation, perform the following steps:
- Open a terminal window.
Change to the Downloads directory by entering the following command:
cd /home/magento/Downloads
- Move the Tokenone10.zip file to the Magento application code directory by entering the following command:
mv Tokenone10.zip /var/www/html/magento/app/code/
Change to the Magento application directory by entering the following command:
cd /var/www/html/magento/app/code/
Unzip the TokenOne zip file by entering the following command:
unzip Tokenone10.zip
Remove the zip file from the code directory by entering the following command:
rm Tokenone10.zip
Change to the Magento web server directory by entering the following command:
cd /var/www/html/magento/
Enable the TokenOne module by entering the following command:
php bin/magento module:enable Tokenone_TwoFactorAuth
To upgrade Magento to reflect the newly enabled module, enter the following command:
php bin/magento setup:upgrade
Recompile Magento to reflect the changes by entering the following command:
php bin/magento setup:di:compile
To find the Magento admin URI, enter the following command:
php bin/magento info:adminuri
Note the URI that is output from the command. It will be used for TokenOne provisioning.
2.5.4. TokenOne Provisioning¶
Once TokenOne has been installed, administrators will be required to use TokenOne to log in to the administration portal. The first time that an administrator logs into the portal, they will be required to provision and link their TokenOne authenticator with the system by using the following steps:
- Open a web browser and navigate to https://magento2.mfa.local/magento/admin_14mzl4.
- Sign in to the admin portal.
- Once the administrator has signed in to the Magento admin portal, a TokenOne splash screen will appear with steps to create an account.
- Open the TokenOne mobile application and click LINK A NEW SERVICE.
- Click SCAN QR CODE.
- Capture the Quick Response (QR) code that is displayed on the Magento site.
- Upon scanning the QR code, the phone will then be profiled and registered.
- Follow the prompts on the smartphone to complete the registration.
- Click NEXT.
- Create a recovery password for the account.
- Click NEXT. Once the phone has been profiled and the account provisioned, you will be prompted to set your user PIN.
- Click SET PIN on the phone, and click Confirm on your computer.
- Use the KeyMap on the phone screen to encode your user PIN into a letter code. A KeyMap is simply a sheet of 10 letters, each with a corresponding number (0 to 9). Match the numbers of your PIN to the corresponding letters. This is your onetime letter code. For example, if your PIN is 2610, then your onetime letter code is HVXK.
- Enter the letters corresponding to your PIN into the Magento admin panel, and click Submit. Repeat the process to confirm your PIN.
- Do not turn off your phone during this process. Wait until the smartphone application indicates that the account has been registered.
2.5.5. Administrator Login with TokenOne Authentication¶
To log in to the Magento administration portal by using TokenOne authentication, perform the following steps:
- Open a web browser and navigate to https://magento2.mfa.local/magento/admin_14mzl4.
- Sign in to the admin portal.
- Magento will prompt for the TokenOne CODE.
- Open the TokenOne mobile application on your smartphone.
- An In standby… screen will appear while the service verifies that you are using the correct registered device.
- Once your device is verified, a unique KeyMap will appear.
- Match the numbers of your PIN to the corresponding letters. This is your onetime letter code. For example, if your PIN is 2610, then your onetime letter code is MGYB.
- Enter the letter code into the administration panel, and click Confirm.
2.6. Splunk Enterprise¶
This section provides installation and configuration guidance for Splunkʼs Enterprise product. Splunk Enterprise is used in both the cost threshold and risk engine example implementation builds to process and display authentication logging information. In addition to installing and configuring Splunk Enterprise and its supporting components, this section also provides step-by-step guidance on developing dashboard displays of the logged information. The locations of the Splunk components that are installed by using the instructions in this section are illustrated in Figure 2-6 and are highlighted in yellow within the green box.
Figure 2-6 Splunk Enterprise Components
2.6.1. Splunk Technologies Overview¶
Splunk [10] technologies enable computer log and data collection, parsing, and display. Splunk Enterprise [11], along with two enabling capabilities, was used in both example implementations:
- Splunk Enterprise [11], where data was collected, parsed, and displayed by using dashboards
- Splunk Universal Forwarder [12], which was installed on systems from which we collected data, forwarding the information to Splunk Enterprise
- Splunk DB Connect [13], which was used to import structured data for analysis, indexing, and visualization into Splunk Enterprise in the example implementation
2.6.2. Splunk Enterprise¶
2.6.2.1. Overview¶
Splunk Enterprise [11] enables the monitoring and analyzing of data from multiple sources. Splunk Enterprise can receive data from many sources and then respond to data queries and provide dashboard displays of the data that has been provided to it.
For both example implementations, we used Splunk Enterprise to ingest a variety of log types from the retail e-commerce platform server. Once the data was collected by Splunk Enterprise, it could then be parsed and displayed by using prebuilt rules or custom criteria. For both example implementations, we displayed information as described in Section 2.6.5.
2.6.2.2. Splunk Enterprise: Requirements¶
System requirements required to support the use of Splunk Enterprise can be found here: http://docs.splunk.com/Documentation/Splunk/6.6.1/Installation/Systemrequirements.
2.6.2.3. Splunk Enterprise: Prepare for Installation¶
To prepare your environment for an on-premises installation, follow this guidance:
2.6.2.4. Splunk Enterprise: Installation¶
You will need a Splunk account to download Splunk Enterprise. The account is free and can be set up at https://www.splunk.com/page/sign_up.
Download Splunk Enterprise from https://www.splunk.com/en_us/download/splunk-enterprise.html. Splunk Enterprise was installed on a Windows instance. The installation instructions can be found here: http://docs.splunk.com/Documentation/Splunk/6.6.1/Installation/InstallonWindows.
2.6.3. Splunk Universal Forwarder¶
2.6.3.1. Splunk Universal Forwarder: Overview¶
The Splunk Universal Forwarder collects data to be used by Splunk Enterprise. Splunk Universal Forwarder allows Splunk Enterprise to collect data from remote sources and send it for indexing. To use this capability, Splunk Universal Forwarder must be installed on each system from which you want to collect data.
We used Splunk Universal Forwarder to collect data from Magento and forward it to Splunk Enterprise. Once the data was delivered to Splunk Enterprise, the data provided by the Splunk Universal Forwarder was used to analyze purchaser authentication trends and to populate the dashboard displays.
2.6.3.2. Splunk Universal Forwarder: Requirements¶
System requirements required to support the use of Splunk Universal Forwarder can be found here: http://docs.splunk.com/Documentation/Forwarder/6.6.1/Forwarder/Systemrequirements.
2.6.3.3. Splunk Universal Forwarder: Prepare for Installation¶
Before you can forward data to Splunk Enterprise, you must enable forwarding and receiving on Splunk Enterprise. Instructions can be found here: http://docs.splunk.com/Documentation/Forwarder/6.6.1/Forwarder/EnableaReceiver.
2.6.3.4. Splunk Universal Forwarder: Installation¶
The Splunk Universal Forwarder can be installed on different operating system platforms. The following subsections provide instructions for installing the Splunk Universal Forwarder on both Linux and Windows.
2.6.3.4.1. Installing Splunk Universal Forwarder on Linux¶
Detailed Splunk Universal Forwarder installation instructions can be found here: http://docs.splunk.com/Documentation/Forwarder/6.6.1/Forwarder/Installanixuniversalforwarder#Install_the_universal_forwarder_on_Linux.
The following steps are an abridged version of the preceding installation link:
You will need a splunk.com account to download the Splunk Universal Forwarder on Linux. Account setup is free and can be done here: https://www.splunk.com/page/sign_up.
Once you have an account, the Splunk Universal Forwarder for Linux is free and can be downloaded from here: http://www.splunk.com/en_us/download/universal-forwarder.html.
Having the latest operating system version is recommended for installations. For both example implementations, we used the latest CentOS version 2.6+ kernel Linux distributions (64-bit). For the example implementation, we installed on CentOS by selecting the file that ends in .tgz and placed it on the target Linux machine. This is an example:
splunkforwader-7.0.1-2b5b15c4ee89-linux-x86_64.tgz
Untar the file downloaded to the opt/ directory:
tar zxvf <splunk_package_name.tgz> -C /opt
Change to the /opt/splunkforwarder/bin directory:
cd /opt/splunkforwarder/bin
Start the universal forwarder:
./splunk start
Enable boot start of the universal forwarder:
./splunk enable boot-start
2.6.3.4.2. Configure Splunk Forwarder on Linux¶
More information about adding a forwarder can be found at http://docs.splunk.com/Documentation/Forwarder/6.6.1/Forwarder/Configuretheuniversalforwarder.
Change to the /opt/splunkforwarder/bin directory:
cd /opt/splunkforwarder/bin
Run script to configure the forwarder to connect to the Splunk Enterprise server:
./splunk add forward-server loghost:7777 -auth admin:change
2.6.3.4.3. Installing Splunk Universal Forwarder on Windows¶
You will need a splunk.com account to download the Splunk Universal Forwarder on Windows. An account is free and can be set up here: https://www.splunk.com/page/sign_up.
Once you have an account, the Splunk Universal Forwarder for Windows is free and can be downloaded from here: http://www.splunk.com/en_us/download/universal-forwarder.html.
You want the latest version for operating system version Windows (64-bit). Because this download will be installed on Windows, select the file that ends in .msi and follow the instructions for installation and configuration. This is an example of the file name that will be downloaded:
spunkforwarder-7.0.0-00f5bb3fa822-x64-release.msi
2.6.4. Splunk DB Connect¶
Splunk DB Connect facilitates database information imports, exports, lookups, and multiple data source combinations [13], [14].
2.6.4.1. Overview¶
Splunk DB Connect provides a solution for integrating database information with Splunk Enterprise queries and reports. It allows for structured data-collection from databases, which can be leveraged in analysis.
Splunk DB Connect was used to import structured data from Magento’s MySQL database instance. This enabled us to leverage information in the database within the Splunk Enterprise deployment.
2.6.4.2. Splunk DB Connect Requirements¶
Splunk DB Connect requires that the Java Runtime Environment (JRE) is installed on the Splunk Enterprise search head. The JRE can be installed from here: http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html.
You must install a driver for the database that you are planning to connect to the Splunk DB Connect application. Splunk DB Connect supports a list of drivers that can define other databases. MariaDB is not included in the list of predefined databases. As MariaDB is a branch of MySQL, we downloaded the MySQL Java Connector from the following location (Section 2.6.4.4, Step 6 provides installation directions for the Java Connector.): https://dev.mysql.com/downloads/connector/j/.
2.6.4.3. Splunk DB Connect Installation¶
This section describes the steps required to install the Splunk DB Connect application onto your single-instance deployment of Splunk. Additional guidance can be found here: https://docs.splunk.com/Documentation/DBX/3.1.2/DeployDBX/AboutSplunkDBConnect.
- Navigate to the Splunk Enterprise home page, and click the Splunk Apps icon.
- Type “db connect” into the search bar to locate the Splunk DB Connect application.
- Once the Splunk DB Connect application is located, click Install.
- Log in and accept the terms and conditions by using your splunk.com user account and credentials (not the Splunk Enterprise instance credentials) and then by clicking Login and Install.
- Click Restart Now.
- Log in after reboot with the Splunk Enterprise instance credentials that were created during installation of Splunk Enterprise.
2.6.4.4. Setup¶
This section describes the initial setup process that will follow installation of Splunk DB Connect.
- On the home page, navigate to Splunk DB Connect in the Apps sidebar.
- Select whether to send Splunk information about your use of Splunk DB Connect.
- Click Setup to begin the configuration process.
- Specify the JRE Installation Path (JAVA_HOME).
- Click Save to confirm general configurations.
- Task server restart will occur.
- Once the restart completes, click OK.
- Proceed to set up drivers for the database in the Drivers tab: Configuration > Settings > Drivers.
- Search for the database that you are using.
If your driver is not installed, Splunk DB Connect will show No for Installed. If that is the case, perform Step i below to move the connector into a new directory to enable configuring Splunk DB Connect.
- Move the MySQL Java Connector downloaded in Section 2.6.4.2 to the following directory:
C:\Program Files\Splunk\etc\apps\splunk_app_db_connect\drivers
- To specify a database that is not predefined, follow the Splunk documentation located here: https://docs.splunk.com/Documentation/DBX/3.1.2/DeployDBX/AboutSplunkDBConnect.
- Click Reload. The status of the driver should reflect that it was installed.
2.6.4.5. Creating Identities¶
Before connecting Splunk DB Connect to your database, an identity is needed to establish the connection. This section details creating an identity that leverages database credentials, which will be used by Splunk DB Connect to access your database.
- Navigate to the Identities tab: Configuration > Databases > Identities.
- Click New Identity.
- Configure the Settings for your New Identity.
- Specify a unique Identity Name.
- Enter the Username and Password that are used to access your database.
- Click Save.
- You will now see the new identity that you created, listed in the table of identities.
2.6.4.6. Creating Connections¶
This section details how to create a database connection for Splunk DB Connect to use. This provides the information that the software needs to connect to your remote database.
- Navigate to the Connections tab: Configuration > Databases > Connections.
- Click New Connection.
- Configure the Settings for your New Connection.
- Uniquely name your connection in the Connection Name field.
- Select the Identity created in Section 2.6.4.5.
- In the Connection Type field, select the type of database being connected.
- Specify the Timezone.
- Configure the JDBC URL Settings.
Enter the database’s host name in the Host field.
Specify the Port that your database uses for remote connections.
Specify the Default Database to be used.
Click Save.
Note: If you receive an error when attempting to save the connection, be sure to check that the database to which you are attempting to connect is configured for remote connections.
- You will now see the new connection that you created, listed in the table of connections.
2.6.4.7. Creating Inputs¶
This section details how to ingest data from your database by using inputs. We demonstrated creation of an input that pulled customer account information from the Magento database.
- Navigate to the Inputs tab: Data Lab > Inputs.
- Click New Input.
- Choose the table for your New Input.
- Select the Connection created in Section 2.6.4.6.
- Select the Default Database created in Section 2.6.4.6, Step 4c, as the Catalog.
- Search for and select the Table from which input is to pull data. We selected the Customer_entity table.
- Preview the data.
- Click Execute SQL to review the results of the query.
- Select the Input Type.
Batch or Rising: Batch indexes all of the table’s data every time that it runs, whereas Rising uses a checkpoint to update the data that it collects from the table. We selected Rising.
- Configure the settings for the Rising input type.
- Specify the column of your table to be used as the Rising Column. We selected entity_id.
- Enter the Checkpoint Value of the entry where you want your Rising Input to begin updating. This will dynamically update as the query is executed over time. We entered 0 to begin input at the first entity created.
- Select the Timestamp for Splunk to index this data. We selected Current Index Time.
- Query Timeout: Enter the number of seconds to wait for the query to complete. We entered 30.
- Click Next.
- Set Properties for the New Input.
- Enter a unique Name for the input. We named our instance magento_customer_entity.
- Enter a Description for the type of data being input from the table.
- Select the Application context. We selected Splunk DB Connect.
- Enter the Max Rows to Retrieve with each query. We entered the default, 0.
- Enter the Fetch Size. This specifies the number of rows to be returned with each input query. We entered the default, 300.
- Enter the Execution Frequency. This specifies how frequently, in seconds, to execute the query for this input. We entered 30.
- Enter a Source Type for the data being queried by this input. Note: This can be predefined, or a new type can be created in this field. We entered the predefined mysqld-5.
- Select the Index field, and enter main.
- Click Finish.
- The following screen will appear upon completion. Click Back to List.
- You will now see the new input that you created, listed in the table of inputs.
2.6.4.8. Creating Database Lookups¶
This section describes creating a new database lookup. Database lookups allow you to extend the data being input from your external database into the Splunk Search Processing Language (SPL) queries. It allows events gathered from logs to be correlated with the information pulled from your database. This example correlates the entity_id returned in SPL queries to user emails stored in the database.
- Navigate to the Lookups tab: Data Lab > Lookups.
- Click New Lookup.
- Navigate to Set Reference Search, and select the field of interest to be mapped to the lookup.
- We entered a new Search.
- Click Next.
- Navigate to Set Lookup SQL.
- Specify a Connection by using information from the connection, which was created in Section 2.6.4.6.
- Specify the Catalog.
- Enter the Table.
- Click Execute SQL to view the results of the query created.
- Click Next.
- Navigate to Field Mapping.
- Click Add Search Field.
- Select the Search Fields to be mapped to the database. We selected entity_id.
- Select the Table Columns to which the field maps in the database. We selected entity_id.
- Click Add Column.
- Select the Table Columns to be returned as Splunk fields. We selected email.
- Enter an Alias for the field. We chose to leave the name of the field as email.
- Click Next.
- Navigate to Set Properties.
Enter a unique Name for the lookup. We named our instance Magento_Customer_Mapping.
Enter a Description for the type of new lookup being created.
Select the Application context. We selected Splunk DB Connect.
The Summary contains the command to be appended to your SPL searches to leverage the lookup:
| dbxlookup lookup=“Magento_Customer_Mapping”
Click Finish.
- The following screen will appear upon completion. Click Back to List.
- You will now see the new lookup that you created, listed in the table of lookups.
2.6.5. Splunk Enterprise Queries and Dashboards¶
Splunk Enterprise reports, alerts, and dashboards are powered by queries written in the Splunk SPL. These queries are used to perform the analytics responsible for capturing events, identifying trends, and detecting anomalies. Once a query is written, it can be saved as a report, an alert, or a dashboard panel. The following queries were developed for both example implementations and were also saved as Splunk Enterprise dashboards to provide a central viewing location.
2.6.5.1. Query: Total Attempted Single-Factor Authentications¶
The following search query traverses the logs aggregated from the Magento server. The query uses multiple data sources relating to the same access log to detect when access to a customer account is attempted via single-factor credentials. The output of the query shows the total events per hour.
host="magento.mfa.local" source ="/var/log/httpd/*" sourcetype=access_common 302 "/fidodemo/customer/account/loginPost" earliest=1 latest=now \| stats count
by date_hour
2.6.5.2. Query: Failed Single-Factor Authentications Within Past Five Minutes¶
The following search query traverses the logs aggregated from the Magento server, specifically the database logs. This log returns information, including failed login attempts per entity ID. With the database lookup created in Section 2.6.4.8, the query below maps the entity ID to the respective email address reporting when a customer account has failed to be logged in via single-factor credentials. The output of the query shows failed logins, per email address, within a five-minute interval.
source="/usr/local/strongauth/mariadb-10.1.22/log/mysqld.log" failures_num!="'0'" \| rex field=entity_id "\'?(?<entity_id>[\d\.]+)\'?" \| dbxlookup
lookup="Magento_Customer_Mapping" earliest=-5m latest=now \| eventstats \| stats count by email
2.6.5.3. Query: Attempted Single-Factor Authentications in Past Five Minutes¶
The following search query traverses the logs aggregated from the Magento server. The query uses multiple data sources relating to the same access log to detect when access to a customer account is attempted via single-factor credentials. The output of the query shows the failed login, per IP address, within a five-minute interval.
host="magento.mfa.local" source ="/var/log/httpd/*" sourcetype=access_common 302 "/fidodemo/customer/account/loginPost" earliest=-5m latest=now \| stats count
by IP
2.7. Testing FIDO Key Registration and Checkout¶
Once installed and configured, the example implementation can configure accounts, and the build can be tested. To test the implementation, an example customer account was created. Example processes for customer account creation, FIDO key registration, and FIDO checkout are detailed in the following subsections.
2.7.1. Creating an Example Magento Customer Account¶
This section outlines how to create example customer accounts. The accounts are created using a web browser interface.
- To begin, open a web browser and navigate to https://magento.mfa.local/fidodemo.
Click Create an Account.
Fill out the form as shown in the example below.
- First Name: John
- Last Name: Doe
- Email: jdoe@mfa.test.com
- Password: <password>
- After entering the required information, click Create an Account.
- Upon successful account creation, you will be taken to the Account Dashboard page, where details of the account that was created are visible.
2.7.2. FIDO Key Registration¶
This section provides information for associating the FIDO key with the purchaser’s account that was created in Section 2.7.1. The account holder will need their FIDO key to complete the registration process.
To begin, open a web browser and navigate to https://magento.mfa.local/fidodemo.
Note: You need to have already created a Magento Example Customer Account. If you have not done so, please refer to Section 2.7.1.
Click Sign In.
- Fill out the Email and Password for the example customer account that was created in Section 2.7.1.
- Email: jdoe@mfa.test.com
- Password: <password>
- Click Sign In.
- On the Account Dashboard page, click Register FIDO Security Key.
- The FIDO Authentication Engine will prompt “Please confirm user presence NOW.”
2.7.3. Testing Customer Checkout¶
This section provides information for testing that the FIDO server is prompting for a second form of authentication for purchases above $25. This section assumes that an example customer account has been created with a registered FIDO Security Key (Section 2.7.1 and Section 2.7.2).
Open a web browser and navigate to https://magento.mfa.local/fidodemo.
If not already logged in to an example customer account, select Sign In from the Magento home page and log in with the following credentials:
- Email: jdoe@mfa.test.com
- Password: <password>
You will be taken to the Account Dashboard page.
From there, navigate back to https://magento.mfa.local/fidodemo.
Scroll down the page and select any item over $25. For our demonstration, we have selected the Fusion Backpack.
- Click Add to Cart.
- Click the shopping-basket icon, and then click Go to Checkout.
- Under Shipping Methods, select the Fixed–Flat Rate radio bubble.
- Click Next.
- On the following page, select Place Order.
- The FIDO Authentication Engine will prompt “Please confirm user presence NOW.”
- Insert the Yubico YubiKey NEO Security Key into an available USB slot on the computer, and then place a finger on the gold contact pad.
- Successfully activating the FIDO token will result in the order confirmation page.
Appendix A FIDO U2F Security Key Registration
Fast IDentity Online (FIDO) authentication requires registering one or more FIDOU2FAuthenticators, also known as FIDO Universal Second Factor (U2F) Security Keys, or security keys. Security keys can be used for authentication on multiple information systems or websites. If the purchaser already has a U2F, then they can use that same U2F as their multifactor authenticator for the electronic commerce (e-commerce) example implementations depicted in this guide.
FIDO authentication in these example implementations is accomplished by using the magfido FIDOU2FAuthenticator module created by StrongKey for the Magento Open Source platform. When deploying the example implementations, there are three parts to the process. While these three parts all execute in sequence without the purchaser being aware of each part, it is helpful to explain each part so that developers understand the workflow.
A.1 Display Function
In this part of the process, the Magento layout file customer_account_index.xml loads code from the fido_register.phtml file on the server side to perform these two functions:
- Generate Hypertext Markup Language (HTML) that displays FIDO registration purchaser-interface components in the browser, along with summary information of the number of security keys that a purchaser may have registered. The summary information on registered keys is shown above the Recent (Magento) Orders section, which normally appears at the top of the dashboard.
- Execute the FIDO registration process to register a new FIDO Security Key, using JavaScript embedded in the fido_register.phtml file.
If a purchaser has not yet registered a FIDO Security Key within Magento, then the HTML displays a zero (0) value for the number of registered keys, and a button to register a new security key (Figure A-1).
Figure A-1 Browser Display Without Any Security Keys Registered
If a purchaser has registered one or more security keys to their account—which the FIDO U2F protocol allows—then the FIDOU2FAuthenticator module displays the number of security keys registered by the purchaser. Otherwise, it displays 0. The HTML display for such a purchaser’s registered keys resembles the depiction shown in Figure A-2.
Figure A-2 Browser Display with Two Security Keys Registered
To determine the number of FIDO Security Keys registered by a purchaser within their account, the server code in fido_register.phtml calls the “block” file, Register.php. This Hypertext Preprocessor (PHP) file, in turn, invokes FidoService.php to call a web service (also sometimes known as “consume a web service”) on a previously configured FIDO U2F server (implemented in StrongKey CryptoEngine [SKCE]) known to the Magento instance. The web-service request retrieves security-key-related information for the specific purchaser from the FIDO server.
FidoService.php parses the retrieved number of registered keys and returns the value to Register.php, which, in turn, returns the number to fido_register.phtml that generates HTML for the browser to display.
Note: In this example implementation, Register.php is executed only when the purchaser navigates to their purchaser-dashboard page. If a new security key is registered while on that page, then the page is automatically refreshed upon completion of the transaction to display the correct number of registered security keys.
An overview diagram of the first part of the registration process—that displays the current number of registered security keys, if any—is shown in Figure A-3.
Figure A-3 Display Function Part of the FIDO Registration Process
A.2 Preregister Function
The second part of the FIDO registration process acquires a challenge from the FIDO U2F server (SKCE) for processing within the purchaser’s FIDO Security Key (Figure A-4).
When the Register FIDO Security Key button on the browser is clicked by the purchaser, JavaScript that was loaded earlier in the web page (by fido_register.phtml) makes an Asynchronous JavaScript and XML (Extensible Markup Language) (AJAX) call to Preregistration.php on the Magento server, which, in turn, invokes FidoService.php to call the preregister web-service operation on the SKCE. SKCE returns a nonce, along with a list of previously registered FIDO Security Keys, if any. If this is the first security key being registered, then this list is empty.
Note: In the FIDO U2F protocol, currently registered security keys, if any, are returned by the FIDO server to safeguard that security keys do not attempt to generate a duplicate key for purchasers on the same device. This implies that manufacturers of FIDO Security Keys must implement logic to ensure that they check for an existing key pair for a purchaser for the specific website. A FIDO Certified Authenticator will always have this logic implemented because it is part of the protocol-conformance testing to achieve the FIDO Certified label.
Figure A-4 Preregistration Part of the FIDO Registration Process
Upon receiving the challenge, the browser and the security key interact with each other by using the u2f-api.js library to perform FIDO U2F-specified protocol functions. If the security key does not already have a cryptographic key pair for this specific website domain, then it requires the purchaser to perform an action to prove their presence in front of the computer. Upon the purchaser doing so, it generates a new Elliptic Curve Digital Signature Algorithm (ECDSA) key pair.
The “purchaser action” may be something chosen by the manufacturer of the security key, such as these actions:
- touching a metallic component or pressing a button that has a blinking light-emitting diode
- removing and reinserting a USB-based security key
- bringing a near field communication (NFC)-based security key near the NFC-enabled computer/mobile device
- scanning their finger or iris on a mobile device enabled with biometric capabilities
- additional manufacturer choices
FIDO protocols do not mandate any specific user/purchaser action for testing human presence. Manufacturers are at liberty to choose whatever complies with the protocol.
A.3 Register Function
The third and last part of the FIDO registration process generates a new key pair for the purchaser for the specific website domain on the purchaser’s FIDO Security Key, digitally signs the challenge from the FIDO U2F server (SKCE), and then submits a package of the response to SKCE for processing.
When the purchaser has “activated” their FIDO Security Key by using the mechanism that the manufacturer designed into the process, the security key generates a new ECDSA key pair, uses the newly generated private key from the key pair to digitally sign the nonce, and assembles a package of information to return to the browser. The browser sends the package to Registration.php, which, in turn, sends the package to FidoService.php, which finally calls the register web-service operation on SKCE to register the newly generated public key with the FIDO server.
During this process, fido_register.phtml displays a modal dialogue to notify purchasers of progress and/or error messages, should something go wrong. Any interaction with the modal dialogue, such as closing it, does not affect the operation. The operation continues until it succeeds or fails.
This last step of the registration process is shown in Figure A-5 .
Figure A-5 Third and Final Step of the FIDO Registration Process
A.3.1 The Checkout Process
The FIDOU2FAuthenticator module must integrate with Magento’s default checkout workflow.
Before describing the FIDO authentication process, a brief background of the default checkout workflow is presented below.
- Purchasers browse the e-commerce website to purchase one or more items.
- Purchasers place and remove items in and out of their shopping cart until they decide to purchase the items in their shopping cart.
- Purchasers click Proceed to Checkout.
- At this point, the checkout process requires the purchaser to fill out billing and shipping information and then to click Place Order.
- This causes the browser to run JavaScript code, which makes an AJAX call to submit the shopping cart, billing address, and payment information to the Magento server.
- The Magento server processes the information and saves it to its database—or returns an error if there is an exception—confirming the conclusion of the transaction.
The checkout workflow is displayed in Figure A-6.
Figure A-6 Magento Checkout Workflow
Note: In Figure A-6, * placeOrder is in Magento_Checkout::view/frontend/web/js/view/payment/default.js # savePaymentInformationAndPlaceOrder is in Magento_Checkout::PaymentInformationManagement
By understanding the above Magento default checkout workflow, you can better understand how the example implementations’ FIDO authentication flow is implemented.
A.3.2 The FIDO Authentication Flow for the Example Implementations
The FIDOU2FAuthenticator module, when installed, will inject itself into the workflow described above. The primary modification that FIDO authentication makes to the checkout process is to override the placeOrder function of Magento_Checkout/view/payment/default.js.
- The new placeOrder function makes an AJAX call to the RiskAssessor.php on the Magento server to determine whether FIDO authentication is required (based on this example implementation’s rule to check whether the total order is greater than $25).
- If the total is $25 or less, then the checkout data is sent to the Magento server to be persisted directly without any FIDO actions. However, if the order total exceeds $25, then another AJAX call is made to FidoService.php to request a FIDO challenge from SKCE. This is accomplished by FidoService.php making a preauthenticate web-service request to SKCE, the FIDO U2F server. FidoService.php returns the challenge nonce to the calling JavaScript in the customer’s browser.
- Upon receiving the challenge, the browser interacts with u2f-api.js to prompt the customer to digitally sign the challenge by using their FIDO Security Key.
- Once the challenge nonce has been signed by using the FIDO Security Key, the digital signature is appended to checkout data that is normally sent to the Magento server.
- On the server, where the Magento_Checkout/Model/PaymentInformationManagement savePaymentInformationAndPlaceOrder function has been overridden, Magento receives the checkout data and checks again if FIDO authentication is required. This is to ensure that web-service requests to the back-end services are not manipulated to bypass FIDO strong authentication.
- If FIDO strong authentication is not required, then Magento goes through the standard checkout flow and persists the transaction. If FIDO strong authentication is required, then the overridden code in PIMOverrideFidoAuthenticate.php checks for the digital signature bytes appended to the checkout data.
- If the signature bytes are present, then PIMOverrideFidoAuthenticate.php calls the authenticate web-service operation (by using FidoService.php) on SKCE with the signature bytes.
- If the authenticate web service returns successfully, then PIMOverrideFidoAuthenticate.php continues with the checkout process, persists transaction data to the database, and confirms the transaction to the customer. A failed response to the authenticate web service returns an error to the customer, and the checkout fails.
In the browser, a modal dialogue provides status messages on the FIDO strong-authentication process executing in the background (if FIDO strong authentication is determined to be necessary); otherwise, the FIDO dialogue does not display itself. As in the FIDO registration workflow, closing the modal dialogue does not stop the FIDO authentication process, and interacting with the browser window in any way does not change the behavior.
Figure A-7 provides an overview of the FIDO authentication process at a high level.
Figure A-7 Overview of the FIDO Authentication Process
A.3.3 Information About the magfido Files and Directories
This section provides additional information regarding files referenced and/or modified by StrongKey to implement FIDO U2F MFA for these example implementations. If you are familiar with Magento, then you may skip this section; others may find this section to be helpful in understanding what must be done to integrate FIDO U2F into their Magento instance in a production environment.
Magento includes several boilerplate/configuration files: composer.json and registration.php are those that must be included in every Magento module because they identify the module to the Magento system.
The etc folder contains configuration files:
- module.xml is a boilerplate file.
- di.xml tells Magento to override the default PaymentInformationManagement.php file with StrongKeyʼs custom version (named PIMOverrideFidoAuthenticate.php).
- extension_attributes.xml tells Magento that purchase-transaction data sent to the server may have signature data appended to it, which can be identified by the attribute name signature.
- etc/frontend/di.xml adds an AdditionalConfigProvider that supplies the MFA modal dialogue with the file name loading.gif.
- routes.xml tells Magento that this module defines controllers that will handle uniform resource locator (URL) requests to fidou2fauthenticator.
The api folder contains interface files describing valid functions of the models FidoService and RiskAssessor. The interface files are named FidoServiceInterface.php and RiskAssessorInterface.php.
The block folder contains server-side logic to generate views displayed by the browser. Specifically, it contains the file Register.php that provides the base URL for AJAX calls in the registration workflow and returns the number of security keys registered to the online customer.
The controller folder contains controllers to handle AJAX calls from the browser. The controllers map to SKCE web services, such as preregistration, registration, and preauthentication. Because FIDO authentication is part of the checkout process and is performed in conjunction with payment data, an explicit controller for FIDO authentication is not defined here but is included as part of PIMOverrideFidoAuthentication. It also contains the RiskAssessor.php controller to call the RiskAssessor.php code in the model folder (see below), which performs the actual risk assessment.
The model folder contains the following server-side logic files:
- AdditionalConfigProvider.php retrieves the static URL of the loading.gif image and adds it to variables for the browser client to deliver a better user experience.
- FidoService.php makes the actual web-service calls to the FIDO U2F server, SKCE.
- RiskAssessor.php makes the risk decision in this example implementation—to check if the order’s total value is greater than $25—and returns a Boolean value indicating if FIDO multifactor authentication (MFA) is necessary.
- PIMOverrideFidoAuthentication.php implements the server-side logic to check, once again, if FIDO MFA is necessary, checking if signature bytes are appended to payment data, verifying if the supplied digital signature is valid (through FidoService.php), and persisting the order transaction.
The view folder contains the client-side logic. Because all FIDO-related workflows in this example implementation are intended for customer interaction only, there is a frontend folder inside the view folder (as opposed to an adminhtml folder, which would normally define views for administrators). Within the frontend folder, there are four groups of files:
- The first group contains files related to the registration workflow: layout/customer_account_index.xml directs Magento to load templates/fido_register.phtml above the Recent Orders section of the Customer dashboard in the browser. fido_register.phtml coordinates the entire FIDO registration workflow.
- The second group contains files related to the modal dialogue: layout/checkout_index_index.xml appends JavaScript from web/js/view/checkout-modal.js to JavaScript normally loaded on checkout pages. checkout-modal.js, in turn, loads web/template/checkout-modal.html with HTML that is rendered on the checkout page.
- The third group of files provides client-side logic to perform FIDO authentication. requirejs-config.js is a configuration file to load JavaScript libraries found in web/js/lib—including u2f.js and common.js, which are part of the standard distribution for FIDO U2F from Google for use with the Chrome browser—and overrides the default JavaScript in Magento_Checkout/js/view/payment/default.js with web/js/default-override.js. The latter file—default-override.js—provides client-side logic, including requesting the challenge nonce, getting the challenge nonce digitally signed by the FIDO Security Key, returning the digital signature, and updating the modal dialogue with progress information.
- The last group of files found in the view/frontend folder contains image files found in web/images/.
A.3.4 Solutions to Common Challenges When Configuring Magento and magfido
The following subsections provide solutions to common challenges when the magfido module is configured with Magento.
A.3.4.1 Code Was Modified but Change Did Not Take Effect
The most common reason for this issue is that Magentoʼs cache was not cleared. Clear the browser cache from the browser’s admin console, or open a terminal, change to the Magento directory (/var/www/html/fidodemo), and run this command:
php bin/magento cache:flush
A.3.4.2 Magento Is Unable to Read the WSDL of the FIDO Server
Possible reasons for Magento being unable to read the FIDO server’s Web Services Description Language (WSDL), and thus being unable to complete the action, are explained below.
- The Fully Qualified Domain Name of the FIDO server was defined incorrectly. This can be fixed by modifying the WSDL constant in StrongAuth_FidoValidator/Model/FidoService.php.
- The FIDO server has a self-signed certificate that Hypertext Transfer Protocol Daemon (HTTPD) does not trust. This can be fixed by adding the self-signed certificate to the trusted certificate store located in /etc/pki/tls/certs/ca-bundle.crt.
- The Security-Enhanced Linux (SELinux) security policy is blocking the outbound port used by HTTPD to connect to the FIDO server. This can be fixed by disabling SELinux for testing purposes. In production environments, it is recommended that SELinux rules be modified to permit HTTPD to connect to the FIDO server.
A.3.4.3 Error 500 When Attempting to Access the Home Page
This is not a FIDO-related issue but can manifest itself as a Magento-HTTPD misconfiguration. While there are many possible ways that this error can occur, the most common reason is incorrect file permissions. For testing purposes, running the following command should fix the problem to make the Magento home page accessible:
cd /var/www/html/fidodemo && find var vendor pub/static pub/media app/etc -type f -exec chmod 777 {} \\; && find var vendor pub/static pub/media app/etc -type d
-exec chmod 777 {} \\; && chmod 777 bin/magento
In production environments, consider the security ramifications before adjusting permissions to the directory structure and files, and before making modifications. Please note that the command shown above is a concatenation of multiple commands executed as a single command, so either execute them in a single command (as shown above) or execute them as multiple commands in sequence:
cd /var/www/html/fidodemo
find var vendor pub/static pub/media app/etc -type f -exec chmod 777 {} \\;
find var vendor pub/static pub/media app/etc -type d -exec chmod 777 {} \\;
chmod 777 bin/magento
Appendix B List of Acronyms
AJAX | Asynchronous JavaScript and XML |
API | Application Programming Interface |
CentOS | Community Enterprise Operating System |
DNS | Domain Name System |
ECDSA | Elliptic Curve Digital Signature Algorithm |
e-commerce | Electronic Commerce |
FIDO | Fast IDentity Online |
FQDN | Fully Qualified Domain Name |
GB | Gigabyte(s) |
HTML | Hypertext Markup Language |
HTTPD | Hypertext Transfer Protocol Daemon |
HTTPS | Hypertext Transfer Protocol Secure |
ID | Identifier |
IP | Internet Protocol |
IT | Information Technology |
JDK | Java Development Kit |
JRE | Java Runtime Environment |
LAMP | Linux, Apache, MySQL, PHP |
LDAP | Lightweight Directory Access Protocol |
MFA | Multifactor Authentication |
NCCoE | National Cybersecurity Center of Excellence |
NFC | Near Field Communication |
NIST | National Institute of Standards and Technology |
PHP | Hypertext Preprocessor |
PIN | Personal Identification Number |
QR | Quick Response |
RAM | Random Access Memory |
SELinux | Security-Enhanced Linux |
SKCE | StrongKey CryptoEngine |
SP | Special Publication |
SPL | Splunk Search Processing Language |
SQL | Structured Query Language |
SSL | Secure Sockets Layer |
TCP | Transmission Control Protocol |
TLS | Transport Layer Security |
U2F | Universal Second Factor |
URI | Uniform Resource Identifier |
URL | Uniform Resource Locator |
USB | Universal Serial Bus |
WSDL | Web Services Description Language |
XML | Extensible Markup Language |
YUM | Yellowdog Updater Modified |
Appendix C Glossary
Authentication | Verifying the identity of a user, process, or device, often as a prerequisite to allowing access to a system’s resources [17] |
Authenticator | Something the claimant possesses and controls (typically a cryptographic module or password) that is used to authenticate the claimant’s identity [17] |
Credential | An object or data structure that authoritatively binds an identity–via an identifier or identifiers–and (optionally) additional attributes to at least one authenticator possessed and controlled by a subscriber While common usage often assumes that the subscriber maintains the credential, these guidelines also use the term to refer to electronic records maintained by the Credential Service Providers that establish binding between the subscriber’s authenticator(s) and identity [17]. |
Credential Service Provider | A trusted entity that issues or registers subscriber authenticators and issues electronic credentials to subscribers. A Credential Service Provider may be an independent third party or issue credentials for its own use [17]. |
Identity | An attribute, or set of attributes, that uniquely describes a subject within a given context [17] |
Multifactor | A characteristic of an authentication system or an authenticator that requires more than one distinct authentication factor for successful authentication. MFA can be performed by using a single authenticator that provides more than one factor or by using a combination of authenticators that provide different factors. The three authentication factors are something you know, something you have, and something you are [17]. |
Multifactor Authentication (MFA) | An authentication system that requires more than one distinct authentication factor for successful authentication. Multifactor authentication can be performed by using a multifactor authenticator or by using a combination of authenticators that provide different factors. The three authentication factors are something you know, something you have, and something you are [17]. |
Personal Identification Number | A memorized secret typically consisting of only decimal digits [17] |
Private Key | The secret part of an asymmetric key pair that is used to digitally sign or decrypt data [17] |
Public Key | The public part of an asymmetric key pair that is used to verify signatures or encrypt data [17] |
Public Key Certificate | A digital document issued and digitally signed by the private key of a certificate authority that binds an identifier to a subscriber to a public key. The certificate indicates that the subscriber identified in the certificate has sole control and access to the private key. See also RFC 5280 [17]. |
Relying Party | An entity that relies upon the subscriber’s authenticator(s) and credentials or a verifier’s assertion of a claimant’s identity, typically to process a transaction or grant access to information or a system [17] |
Risk | The level of impact on organizational operations (including mission, functions, image, or reputation), organizational assets, or individuals resulting from the operation of an information system, given the potential effect of a threat and the likelihood of that threat occurring [18] |
Session | A persistent interaction between a subscriber and an endpoint, either a relying party or a Credential Service Provider. A session begins with an authentication event and ends with a session termination event. A session is bound by use of a session secret that the subscriber’s software (a browser, application, or OS) can present to the relying party or the Credential Service Provider, in lieu of the subscriber’s authentication credentials [17]. |
Single Factor | A characteristic of an authentication system or an authenticator that requires only one authentication factor (something you know, something you have, or something you are) for successful authentication [17] |
Subscriber | A party who has received a credential or authenticator from a Credential Service Provider [17] |
Token | See Authenticator [17]. |
Transaction | A discrete event between a user and a system that supports a business or programmatic purpose. A government digital system may have multiple categories or types of transactions, which may require separate analysis within the overall digital identity risk assessment [17]. |
Appendix D References
[1] | (1, 2) FIDO Alliance. (n.d.). Specifications Overview [Online]. Available: https://fidoalliance.org/specifications/overview/. |
[2] | (1, 2) FIDO Alliance. (n.d.). FIDO Alliance [Online]. Available: https://fidoalliance.org/. |
[3] | StrongKey. (n.d.). Home–StrongKey [Online]. Available: https://www.strongkey.com/. |
[4] | Magento, Inc. (n.d.). eCommerce Platform|Best eCommerce Software for Selling Online [Online]. Available: https://magento.com/. |
[5] | (1, 2) Magento, Inc. (n.d.). Magento Open Source [Online]. Available: https://magento.com/products/open-source. |
[6] | A. Noor and A. de Leon. (Feb. 20, 2018). FIDO U2F Integration for Magento 2 [Online]. Available: https://sourceforge.net/projects/magfido/?source=navbar. |
[7] | RSA. (n.d.). RSA|Security Solutions to Address Cyber Threats [Online]. Available: https://www.rsa.com/. |
[8] | RSA Security LLC. (n.d.). Adaptive Authentication|Fraud Detection–RSA [Online]. Available: https://www.rsa.com/en-us/products/fraud-prevention/secure-consumer-access. |
[9] | TokenOne. (n.d.). TokenOne|Secure Authentication|Sydney [Online]. Available: https://www.tokenone.com. |
[10] | Splunk Inc. (n.d.). Splunk [Online]. Available: https://www.splunk.com/. |
[11] | (1, 2, 3) Splunk Inc. (n.d.). Splunk® Enterprise [Online]. Available: https://www.splunk.com/en_us/products/splunk-enterprise.html. |
[12] | Splunk Inc. (n.d.). Splunk® Universal Forwarder: Forwarder Manual [Online]. Available: http://docs.splunk.com/Documentation/Forwarder/7.0.2/Forwarder/Abouttheuniversalforwarder. |
[13] | (1, 2) Splunk Inc. (n.d.). Splunk DB Connect [Online]. Available: https://splunkbase.splunk.com/app/2686/. |
[14] | Splunk Inc. (n.d.). Splunk DB Connect Details [Online]. Available: https://splunkbase.splunk.com/app/2686/#/details. |
[15] | Yubico. (n.d.). Yubico NEO [Online]. Available: https://www.yubico.com/products/yubikey-hardware/. |
[16] | Yubico. (n.d.). Yubico|YubiKey Strong Two Factor Authentication for Business and Individual Use [Online]. Available: https://www.yubico.com/. |
[17] | (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17) National Institute of Standards and Technology (NIST) Special Publication 800-63-3, Digital Identity Guidelines. (June 2017). [Online]. Available: https://pages.nist.gov/800-63-3/. |
[18] | NIST Interagency/Internal Report 7298, Rev. 2, Glossary of Key Information Security Terms. (May 2013). [Online]. Available: https://www.nist.gov/publications/glossary-key-information-security-terms-1. |