diff --git a/README.md b/README.md index 134b36d..c4d4169 100644 --- a/README.md +++ b/README.md @@ -2,16 +2,15 @@ ![](misc/banner.png) -This project provides example of serverless integration for SaaS products listed on the AWS Marketplace. +This project provides example of serverless integration for SaaS products listed on the AWS Marketplace. -If you are a new seller on AWS Marketplace, we advise you to check the following resources: - -* [SaaS Product Requirements & Recommendations](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-guidelines.html) : This document outlines the requirements that must be met before gaining approval to publish a SaaS product to the catalog. -* [SaaS Listing Process & Integration Guide](https://awsmp-loadforms.s3.amazonaws.com/AWS+Marketplace+-+SaaS+Integration+Guide.pdf) : This document outlines what is required to integrate with Marketplace for each SaaS pricing model. You will find integration diagrams, codes examples, FAQs, and additional resources. -* [SaaS Integration Video](https://www.youtube.com/watch?v=glG44f-L8us) : This video guides you through the requirements and steps needed to integrate. -* [SaaS Pricing Video](https://www.youtube.com/watch?v=E0uWp8nhzAk) : This video guides you through the pricing options available when choosing to list a SaaS product. -* [AWS Marketplace - Seller Guide](https://docs.aws.amazon.com/marketplace/latest/userguide/what-is-marketplace.html) : This document covers more information about creating a SaaS product, pricing, and setting up your integration. +If you are a new seller on AWS Marketplace, we advise you to check the following resources: +- [SaaS Product Requirements & Recommendations](https://docs.aws.amazon.com/marketplace/latest/userguide/saas-guidelines.html) : This document outlines the requirements that must be met before gaining approval to publish a SaaS product to the catalog. +- [SaaS Listing Process & Integration Guide](https://awsmp-loadforms.s3.amazonaws.com/AWS+Marketplace+-+SaaS+Integration+Guide.pdf) : This document outlines what is required to integrate with Marketplace for each SaaS pricing model. You will find integration diagrams, codes examples, FAQs, and additional resources. +- [SaaS Integration Video](https://www.youtube.com/watch?v=glG44f-L8us) : This video guides you through the requirements and steps needed to integrate. +- [SaaS Pricing Video](https://www.youtube.com/watch?v=E0uWp8nhzAk) : This video guides you through the pricing options available when choosing to list a SaaS product. +- [AWS Marketplace - Seller Guide](https://docs.aws.amazon.com/marketplace/latest/userguide/what-is-marketplace.html) : This document covers more information about creating a SaaS product, pricing, and setting up your integration. # Project Structure @@ -25,23 +24,23 @@ The sample in this repository demonstrates how to use AWS SAM (Serverless applic ## Register new customers -With SaaS subscriptions and SaaS contracts, your customers subscribe to your products through AWS Marketplace, but access the product on environment you manage in your AWS account. After subscribing to the product, your customer is directed to a website you create and manage as a part of your SaaS product to register their account and configure the product. +With SaaS subscriptions and SaaS contracts, your customers subscribe to your products through AWS Marketplace, but access the product in the environment you manage in your AWS account. After subscribing to the product, your customer is directed to a website you create and manage as a part of your SaaS product to register their account and configure the product. -When creating your product, you provide a URL to your registration landing page. AWS Marketplace uses that URL to redirect customers to your registration landing page after they subscribe. On your software's registration URL, you collect whatever information is required to create an account for the customer. AWS Marketplace recommends collecting your customer’s email addresses if you plan to contact them through email for usage notifications. +When creating your product, you provide a URL for your registration landing page. AWS Marketplace uses that URL to redirect customers to your registration landing page after they subscribe. On your software's registration URL, you collect whatever information is required to create an account for the customer. AWS Marketplace recommends collecting your customer’s email addresses if you plan to contact them through email for usage notifications. -The registration landing page needs to be able to identify and accept the x-amzn-marketplace-token token in the form data from AWS Marketplace with the customer’s identifier for billing. It should then pass that token value to the AWS Marketplace Metering Service and AWS Marketplace Entitlement Service APIs to resolve for the unique customer identifier and corresponding product code. +The registration landing page needs to be able to identify and accept the `x-amzn-marketplace-token` token in the form data from AWS Marketplace with the customer’s identifier for billing. It should then pass that token value to the AWS Marketplace Metering Service and AWS Marketplace Entitlement Service APIs to resolve the unique customer identifier and corresponding product code. ![](misc/onbording.gif) > NOTE: Deploying the static landing page is optional. -You can choose to use your existing SaaS registration page, after collecting the data you should call the register new subscriber endpoint. Please see the deployment section. +> You can choose to use your existing SaaS registration page. After collecting the data, you should invoke the Register New Subscriber endpoint. Please see the Deployment section. ### Implementation -In this sample we created CloudFront Distribution, which can be configured to use domain/CNAME by your choice. The POST request coming from AWS Marketplace is intercepted by the Edge `src/redirect.js`, which transforms the POST request to a GET request, and passes the x-amzn-marketplace-token in the query string. -A static landing page hosted on S3 which takes the users inputs defined in the html form and submits them to the /subscriber API Gateway endpoint. << [!NOTE] -For simplicity, we use [AWS CloudShell](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html) to deploy the application since it has the required tools pre-installed. If you wish to run the deployment in an alternate shell, you'll need to install [Docker community edition](https://hub.docker.com/search/?type=edition&offering=community), [Node.js 10 (including NPM)](https://nodejs.org/en/), [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html), and [SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html). - - -To build and deploy your application for the first time, complete the following steps. +> For simplicity, we use [AWS CloudShell](https://docs.aws.amazon.com/cloudshell/latest/userguide/welcome.html) to deploy the application since it has the required tools pre-installed. If you wish to run the deployment in an alternate shell, you'll need to install [Docker community edition](https://hub.docker.com/search/?type=edition&offering=community), [Node.js 10 or later (including NPM)](https://nodejs.org/en/), [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html), and [SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html). +To build and deploy your application for the first time, follow these steps: -1. Using the AWS account registered as your [AWS Marketplace Seller account](https://docs.aws.amazon.com/marketplace/latest/userguide/seller-registration-process.html), open [AWS CloudShell](https://us-east-1.console.aws.amazon.com/cloudshell). +1. Using the AWS account registered as your [AWS Marketplace Seller account](https://docs.aws.amazon.com/marketplace/latest/userguide/seller-registration-process.html), open [AWS CloudShell](https://us-east-1.console.aws.amazon.com/cloudshell). -2. Clone the **aws-marketplace-serverless-saas-integration repository** and change to the root of the repository. +2. Clone the **aws-marketplace-serverless-saas-integration repository**: - ```bash - git clone https://github.com/aws-samples/aws-marketplace-serverless-saas-integration.git - ``` - -3. Change to the root directory of the repository +```bash +git clone https://github.com/aws-samples/aws-marketplace-serverless-saas-integration.git +``` - ```bash - cd aws-marketplace-serverless-saas-integration - ``` +3. Change to the root directory: -4. Build the application using SAM. +```bash +cd aws-marketplace-serverless-saas-integration +``` - ```bash - sam build - ``` +4. Build the application using SAM. -5. Deploy the application using the SAM guided experience. +```bash +sam build +``` - ```bash - sam deploy --guided --capabilities CAPABILITY_NAMED_IAM - ``` +5. Deploy the application using the SAM guided experience: -6. Follow the SAM guided experience to configure the deployment. Reference the following table for solution parameters. - - Parameter name | Description - ------------ | ------------- - Stack Name | Name of the resulting CloudFormation stack. - AWS Region | Name of the region that the solution is being deployed in. Default value: us-east-1 - WebsiteS3BucketName | S3 bucket to store the HTML files; Mandatory if CreateRegistrationWebPage is set to true; will be created - NewSubscribersTableName | Name for the New Subscribers Table; Default value: AWSMarketplaceSubscribers - AWSMarketplaceMeteringRecordsTableName | Name for the Metering Records Table; Default value: AWSMarketplaceMeteringRecords - TypeOfSaaSListing | allowed values: contracts_with_subscription, contracts, subscriptions; Default value: contracts_with_subscription - ProductId | Product id provided from AWS Marketplace - MarketplaceTechAdminEmail | Email to be notified on changes requiring action - MarketplaceSellerEmail | (Optional) Seller email address, verified in SES and in 'Production' mode. See [Verify an email address](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-email-addresses-procedure.html) for instruction to verify email addresses. - SNSAccountID | AWS account ID hosting the Entitlements and Subscriptions SNS topics. Leave as default. - SNSRegion | AWS region that the Entitlements and Subscriptions SNS topics are hosted in. Leave as default. - CreateCrossAccountRole | Creates a cross-account role granting access to the NewSubscribersTableName and AWSMarketplaceMeteringRecordsTableName tables. Default value: false. - CrossAccountId | (Optional) AWS account ID for the cross-account role. - CrossAccountRoleName | (Optional) Role name for the cross-account role. - CreateRegistrationWebPage | Creates a registration page. Default value: true +```bash +sam deploy --guided --capabilities CAPABILITY_NAMED_IAM +``` -7. Wait for the stack to complete successfully. +6. Follow the SAM guided steps to configure the deployment, referring to the following table for solution parameters: + + | Parameter name | Description | + | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | + | Stack Name | Name of the resulting CloudFormation stack. | + | `AWS Region` | Name of the region that the solution is being deployed to (default value `us-east-1`) | + | `WebsiteS3BucketName` | S3 bucket to store the HTML files (mandatory if `CreateRegistrationWebPage` is set to true; will be created) | + | `NewSubscribersTableName` | Name for the New Subscribers Table (default value `AWSMarketplaceSubscribers`) | + | `AWSMarketplaceMeteringRecordsTableName` | Name for the Metering Records Table (default value `AWSMarketplaceMeteringRecords`) | + | `TypeOfSaaSListing` | Allowed values: `contracts_with_subscription`, `contracts`, or `subscriptions` (default value `contracts_with_subscription`) | + | `ProductId` | Product ID provided by AWS Marketplace | + | `MarketplaceTechAdminEmail` | Email address for notifications of changes requiring action, verified in SES with AWS account in 'Production' (not 'Sandbox') mode (see **Post deployment steps** below for instructions on how to verify email addresses) | + | `MarketplaceSellerEmail` | (Optional) Seller email address (also verified) | + | `SNSAccountID` | AWS account ID hosting the Entitlements and Subscriptions SNS topics - leave as default | + | `SNSRegion` | AWS region that the Entitlements and Subscriptions SNS topics are hosted in - leave as default | + | `CreateCrossAccountRole` | Specifies whether to create a cross-account role granting access to the `NewSubscribersTableName` and `AWSMarketplaceMeteringRecordsTableName` tables (default value `false`) | + | `CrossAccountId` | (Optional) AWS account ID for the cross-account role | + | `CrossAccountRoleName` | (Optional) name for the cross-account role | + | `CreateRegistrationWebPage` | Specifies whether to create a registration page (default value `true`) | + | `UpdateFulfillmentURL` | Specifies whether to create a Lambda function to obtain the Product Code from AWS Marketplace for the solution (default value `false`) | + +7. Wait for the stack deployment to complete successfully. 8. Check the email account for **MarketplaceTechAdminEmail** and approve the subscription to the SNS topic. - ### Diagram of created resources -Based on the value of the **TypeOfSaaSListing** parameter different set of resources will be created. - -In the case of *contracts_with_subscription* all of the resources depicted on the diagram below will be created. +Based on the value of the `TypeOfSaaSListing` parameter, a different set of resources will be created: -In the case of a *contracts*, the resources market with orange circles will not be created. +In the case of _contracts_with_subscription_, all of the resources depicted on the diagram below will be created. -In the case of a *subscriptions* the resources market with purple circles will not be created. +In the case of _contracts_, the resources marked with orange circles will not be created. -The landing page is optional. Use the CreateRegistrationWebPage parameter. +In the case of _subscriptions_, the resources marked with purple circles will not be created. +The landing page is optional, depending on the value of the `CreateRegistrationWebPage` parameter. ![](misc/AWS-Marketplace-SaaS-Integration.drawio.png) - ## Cleanup -To delete the sample application that you created, use the AWS CLI. Assuming you used your project name for the stack name, you can run the following: +To delete the sample application that you created, use the AWS CLI. Assuming you used your project name for the stack name, run the following command: ```bash aws cloudformation delete-stack --stack-name app @@ -259,15 +248,7 @@ This library is licensed under the MIT-0 License. See the LICENSE file. ## Post deployment steps -## Registration page is true -1. Update the MarketplaceFulfillmentUrl in your AWS Marketplace Management Portal with the value from the output key 'MarketplaceFulfillmentUrl'. The value would be in a the form of a AWS cloudfront based url. -2. Replace the baseUrl value in the web/script.js file from the web template provided with the value from the output key 'RedirectUrl'. -3. Replace the RedirectUrl value in the lambda environment variable with the value from the output key 'RedirectUrl'. Navigate to the AWS Console, look for AWS Lambda service, filter to the lambda with name ....Redirect... . Select the lambda function, go to configuration tab and then select the environment variable. -4. Ensure the email address used is a verified identity/domain in Amazon Simple Email Service. -5. Ensure your Amazon Simple Email Service account is a production account. - -## Registration page is false -1. Update the MarketplaceFulfillmentUrl in your AWS Marketplace Management Portal with the value from the output key 'MarketplaceFulfillmentUrl'. The value would be in the form of an AWS API gateway url. -2. Replace the baseUrl value in the web/script.js file from the web template provided with the value from the output key 'RedirectUrl'. -3. Ensure the email address used is a verified identity/domain in Amazon Simple Email Service. -4. Ensure your Amazon Simple Email Service account is a production account. +1. Ensure the email address used is a verified identity/domain in Amazon Simple Email Service - instructions: [Verify an email address](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-email-addresses-procedure.html). +2. Ensure your Amazon Simple Email Service account is a production account - instructions: [Request production access (Moving out of the Amazon SES sandbox)](https://docs.aws.amazon.com/ses/latest/dg/request-production-access.html). + +