Develop Desktop Applications with Amazon SP-API

Overview

This document describes the requirements for building hybrid applications (web applications that have a desktop client) using the Amazon Selling Partner API (SP-API). This document focuses on the acceptable authorization model and best practices for data security. Guidance is provided to assist with compliance of the Acceptable Use Policy (AUP) and the Data Protection Policy (DPP).

In MWS, Amazon defined a desktop application as software that is installed on a single computer. In SP-API, only hybrid applications are supported. Here are the two common types of desktop applications:

• Native desktop applications are downloaded by a user onto their computer and
  have no connection to the application developer's systems. This is not acceptable per Amazon policies.

• Hybrid applications run on a remote host owned by the developer. Hybrid
  applications use both a web-browser interface and a desktop component
  downloaded to the user’s computer. Acceptable per Amazon policies.

Requirements for building hybrid Amazon SP-API applications

Here are the requirements for developing a hybrid (web applications that have a desktop client) in Amazon SP-API:

• The correct authorization model. In the Grant authorization model, sellers provide the SP-API authentication token, thus giving the developer the ability to make calls to Amazon SP-API on the seller’s behalf.

• The required data encryption controls. Ensure Amazon information is encrypted through all network channels and at rest in your application. Amazon customer personally identifiable information (PII) data must always be encrypted. All communication channels in the application must be protected using firewalls or security groups.

• Secure logging and monitoring solutions. Ensure logs are captured securely in your application and passed back to your systems over a protected network. Implement automated alarms and monitoring for all facets of the application.

• Develop your application with software updates and security patches that are easily accessible. It is important that your web and desktop application are up to date with the latest software updates and security patches. It is also important to architect applications to protect against viruses, malware, and hacks to reduce the likelihood of a security breach.

The following sections discuss special considerations for each of these requirements when building desktop applications.

Authorization model

This section explains the Grant Authorization model. The benefit of the Grant Authorization is that no application credentials are exchanged or stored. Instead, an access token with a limited expiration time is generated.

Use the website authorization workflow to get authorization from the seller, and then make the Login with Amazon call to get the refresh token to make the SP-API call. Due to the OAuth workflow, the call can only originate from your server.

Grant authorization model

The grant authorization model is the only approved authentication method to use with an Amazon SP-API application. In this model, sellers authorize the SP-API application using the OAuth workflow, which generates a long-term refresh token (valid for one year). This gives you the ability to exchange the refresh token, along with your SP-API application credentials, for an access token that is valid for one hour, to make calls to Amazon SP-API on the seller’s behalf. Because the access token is only valid for a short time, a purely native desktop application is not an accepted model.

You must build your application so that you are able to make the Login with Amazon call to get a new access token every hour. All SP-API calls must originate from the developer's server and the response should also be received by the developer. The developer is responsible for securing all data retrieved from Amazon. The grant model enables you to control and manage Amazon information with DPP controls. You can securely store a seller’s authentication token in your database for later use, for as long the seller is your customer.

Figure 1: Grant Authorization model implementation

Unacceptable authorization models

Authorization models that share SP-API application credentials are a violation of the Acceptable Use Policy and are not permitted by Amazon. This can happen when the seller or developer shares application credentials. Unacceptable authorization models are reviewed by Amazon's security team.

Seller shared credentials

It is a violation of Amazon policy for a seller to share any credentials. As shown in Figure 2, the seller enters their own Amazon SP-API application credentials into your application’s interface to make the Amazon SP-API call. This violates the Acceptable Use Policy (AUP) clause never ask for or accept a seller's Secret Keys for any purpose. Even if the application client_id and client_secret are not accessible to you, the security of Amazon customer PII data is at risk. Sellers might not have the knowledge or the tools to ensure that the data is secured and encrypted through all channels on your application.

Risks of the seller shared credentials model:

• The SP-API application credentials are shared across multiple instances of your application or public repository. This presents a risk of breach, giving access to Amazon information for all of your sellers.

• Amazon information is stored in your desktop application on the seller's computer. This means you don't have the ability to control and secure the Amazon information.

Developer shared credentials

It is a violation of Amazon policy for a developer to share credentials. In Figure 3, the SP-API application client_id and client_secret are hardcoded, or embedded, into the desktop component of the application or shared on a public repository such as GitHub. This leaves Amazon SP-API application credentials exposed on the seller’s device or on a public repository. This violates the AUP clause never share keys or passwords.

Risks of the developer shared credentials model:

• The SP-API application credentials are shared across multiple instances of your application or public repository. This presents a risk of breach, giving all of your sellers access to Amazon information.
• Amazon information is stored on the seller's computer in the desktop application you developed. This means you don't have the ability to control and secure the Amazon information.

Data encryption and retention

All Amazon SP-API developers must comply with the Data Protection Policy (DPP), regardless of application type. Amazon holds developers responsible for protection of Amazon information on their applications.

Applications must comply with the following:

• Encrypt data in transit
• Encrypt data at rest
• Automate data retention and lifecycle policies

Encrypting data in transit

Data in transit is any data that gets transmitted from one system to another. This includes communication between resources within your environment as well as communication between native desktop components installed on a seller’s device. By providing the appropriate level of protection for data in transit, you preserve the confidentiality and integrity of Amazon information.

Selecting secure protocols such as Transport Layer Security (TLS), SSH File Transfer Protocol (SFTP) is a common best practice. For example, AWS services provide HTTPS endpoints using TLS for communication, that provide encryption in transit when communicating with AWS APIs. Server-side encryption and client-side encryption protocols also allow you to protect data using a Secure Sockets Layer (SSL) or by encrypting data on the client-side and uploading the encrypted data to your data store.

Encrypting data at rest

Data at rest is any data that you persist for any duration. This includes block storage, object storage, databases, and any other storage medium on which data is persisted. Protecting your data at rest with encryption and access controls reduces the risk of unauthorized access. If your client based applications allow Amazon PII data to be downloaded locally on a seller’s device, these downloads must be encrypted and must have access controls as defined in the DPP.

Message-level data encryption should be considered when data is persisted through multiple channels. For example, you should consider encrypting data at the attribute level in a database, on a web-server, and on a desktop app on a seller’s computer. Encrypting data at the attribute level removes any dependency on the data store to encrypt the data.

Automated data retention and lifecycle policies

Your application must meet data retention requirements. According to the AUP, "developers will retain PII only for, and as long as is necessary to fulfill orders (no longer than 30 days after order shipment), ... this archived storage should be cold or offline...". Amazon recommends that no Amazon PII data is stored on the seller's device. If desktop applications allow the persistence of Amazon PII data, you must implement an automated data deletion mechanism at the end of the retention period.

You should develop a verification mechanism for your desktop application to ensure the deletion of data after the retention period has expired. For example, Amazon S3 allows you to set up a retain until date for an object version and protects the object version until the retention period expires.

Logging and monitoring

Application logging

Configure logging throughout your application stack, including application, service, and resource logs. All logs should be collected centrally and automatically analyzed to detect anomalies and indicators of malicious activity or compromise. For desktop applications you can use agent-based tools to collect logs. For example, you can use Amazon CloudWatch in hybrid architecture by using the CloudWatch agent or API to aggregate log files from your resources and monitor your desktop applications. Implement detailed logging that contains important content, such as Amazon PII data access and changes. Automatic logging of changes to your environment allows you to audit, and quickly identify actions, that might have impacted reliability.

Implement a logging to file mechanism where you ask sellers to retrieve logs and send the log files back to your environment when there is an issue. Securely logging directly to your operating system event log is another fast and reliable way to log for a desktop application. Implement an automated mechanism to recognize an exception or crash, and send exception log file details securely, to a designated server. Decouple your alerting from your systems as much as possible.

Monitoring and alarming

Monitoring is critical to ensure that you are meeting availability requirements. Monitor all of your external endpoints from remote locations to ensure that they are independent of your base implementation. Monitor all instances of your desktop application. We have seen improvements in time-to-detection of problems with the use of user canary applications. These can be implemented in both desktop and web applications.

Canary deployment is the practice of directing a small number of your customers to the new version and scrutinizing any behavior changes or errors that are generated. You can remove traffic from the canary deployment and send your sellers to the previous version if you have critical problems. Select these deployment tasks carefully and complete them within a very short time, so that the application is not overloaded. The reason to use tasks with short durations is so you can run tests over a short period of time. This enables you to detect a problem before it is visible to users.

Software updates and security patches

It is important to keep software up-to-date. Software updates are released to address security issues when they occur, address minor technical issues discovered in the application, improve operation of hardware or peripherals, and to add support to new computer models. Security updates are common operating system updates that are issued to protect your computer against vulnerabilities that might be exploited by hackers and viruses.

It is important to install security updates when they are released to ensure that your system is as protected as possible against constantly changing threats. If desktop applications aren’t always connected to the internet, preventing mandatory updates, it is possible that the application will remain outdated without an enforcement mechanism. A web application might never face this issue, but a downloaded desktop application can still have old versions installed.

You can enforce patching if you own the host on which the application runs. For desktop applications that run on a seller’s computer, a case by case effort is necessary to install software updates on each instance. There should be a validation check on the desktop application to ensure that the software is the latest version. For example, when AWS Systems Manager Patch Manager is installed on an operating system, security-related patches are updated on servers by default.

Additional resources

• Acceptable Use Policy
• Amazon Data Protection Policy
• AWS Well-Architected Framework
• Resource Data Token (RDT)
• AWS Security Pillar

Notices

Amazon sellers and developers are responsible for making their own independent assessment of the information in this document. This document: (a) is for informational purposes only, (b) represents current practices, which are subject to change without notice, and (c) does not create any commitments or assurances from Amazon.com Services LLC (Amazon) and its affiliates, suppliers or licensors. Amazon Services API products or services are provided “as is” without warranties, representations, or conditions of any kind, whether express or implied. The responsibilities and liabilities of Amazon regarding Amazon Services API are controlled by Amazon Services API agreements (including the Amazon Services API Developer Agreement or the Amazon Services Business Solutions Agreement), and this document is not part of, nor does it modify, any agreement between Amazon and any party.

© 2022 Amazon.com Services LLC or its affiliates. All rights reserved.