Software as a Service (SaaS) Quick Start

Transcription

1 Software as a Service (SaaS) Quick Start ** For Amazon Web Services Marketplace Sellers and Licensors only** v 1.1 Last updated March 1, 2018 The purpose of this document is to accelerate integrations with the AWS Marketplace for both SaaS Subscriptions and SaaS Contracts. This guide is intended for technical and development audiences, and provides supplemental technical guidance for software vendors wishing to integrate their SaaS products with the AWS Marketplace. For more general information about selling SaaS solutions on the AWS Marketplace, please see the AWS Marketplace Seller Guide, and the AWS SaaS Billing Seller Integration Guide. Contents 1. Introduction Prerequisites Registration Subscription Notifications Metering Usage (SaaS Subscriptions) Checking Entitlement (SaaS Contracts) Conclusion Additional Resources APPENDICES... 9 Page 1 of 10

2 1. Introduction The purpose of this document is to accelerate integrations with the AWS Marketplace for both SaaS Subscriptions and SaaS Contracts. This guide is intended for technical and development audiences, and provides supplemental technical guidance for software vendors wishing to integrate their SaaS products with the AWS Marketplace. For more general information about selling SaaS solutions on the AWS Marketplace, please see the AWS Marketplace Seller Guide, and the AWS SaaS Billing Seller Integration Guide Integration Overview The integration is broken down into four distinct sections: registration, subscription change notifications, metering usage, and checking entitlement. The first two elements registration and handling subscription notifications are required for all SaaS integrations, both Subscriptions and Contracts. The third integration for metering usage is only required for SaaS Subscriptions integrations, and the final integration for checking entitlement is only required for SaaS Contracts integrations. The code samples in this document are provided for reference purposes only. Examples in this document are shown leveraging our Python SDK, boto3. However, the same concepts can be applied across many of our SDKs. Documentation for the API endpoints these SDKs are calling can be found in the AWS Marketplace Metering Service Documentation, as well as the AWS Marketplace Entitlement Service Documentation. 2. Prerequisites This document assumes you have access to the AWS CLI, and have the requisite privileges required to carry forward the integration. This document also assumes that you are registered as a seller in the AWS Marketplace, and have submitted a SaaS Subscriptions or SaaS Contracts product that has been published to limited. For more information on registration and product listing, please refer to the AWS Marketplace Seller Guide. Before we begin, we ll want to make sure you have a couple things setup. Note: Information on setting up the AWS CLI, along with credentials, can be found here. If you are new to the AWS Python SDK, there is a quick start guide here. Page 2 of 10

3 2.1. IAM USER Policy For Marketplace Actions In order to enable the service account under which the integration is running, we ll need to define a very constrained IAM policy for that user, as shown in Figure 1. Attach this to the IAM user or role you ll use for the integration. { "Version": " ", "Statement": [ { "Action": [ "aws-marketplace:resolvecustomer", "aws-marketplace:batchmeterusage", "aws-marketplace:getentitlements" ], "Effect": "Allow", "Resource": "*" } ] } Figure 1: SaaS Metering and Entitlements Policy NOTE: The first permission is required for all SaaS integrations. The second and third are only needed for subscriptions and contracts, respectively. For more information about creating IAM users, see the documentation here. For more information about creating and assigning policies, see the documentation here. This policy grants access to the APIs for the role or IAM user to which the role is attached. For brevity, this document provides code samples that assume the code is running with the permissions of that user or role. For additional information on how to enable role assumption by another account for these API calls, see the documentation here. 3. Registration When a customer chooses Subscribe on your SaaS listing in the AWS Marketplace, their browser will be redirected to a page designated by you at product listing using HTTPS. This page should look for the x-amznmarketplace-token in the form data (Figure 2), and pass the registration token value to our API to resolve for the unique customer identifier and corresponding product code. These values will be used to interact with the metering and entitlements APIs, so store them with the associated record. Page 3 of 10

4 ##### Resolving Customer Registration Token ##### formfields = urlparse.parse_qs(postbody): if formfields.has_key('x-amzn-marketplace-token'): marketplaceclient = boto3.client('meteringmarketplace') customerdata = marketplaceclient.resolve_customer( RegistrationToken=formFields['x-amzn-marketplacetoken']) productcode = customerdata['productcode'] customerid = customerdata['customeridentifier'] # TODO: Store information away with your customer record # TODO: Validate no other accounts share this identifier Figure 2: Resolving the Customer Registration Token NOTE: The customer identifier is not the customer s AWS account ID, but it is universal between products. 4. Subscription Notifications Secondly, we ll need to subscribe to the AWS Marketplace SNS topic that was provided to you during product listing. This topic will provide notifications about changes to customers subscription and entitlement statuses, allowing you to know when to provide and revoke access for specific customers Subscribing an SQS Queue to the SNS Topic As is mentioned in the AWS SaaS Billing Seller Integration Guide, we recommend subscribing an AWS SQS queue to the provided SNS topic. Detailed instructions on creating an SQS queue can be found here; instructions for subscribing that queue to the provided topic can be found here Granting Permissions to Access the Queue When you subscribe the SQS queue to the provided SNS topic, permissions will automatically be added to allow the SNS topic to publish messages to the queue. However, we still need a policy for granting the API user access to the queue. This can be applied to the same user, if the services will run with the same credentials. Create a policy with the following contents, and attach it to your IAM user (or associated role). Page 4 of 10

5 Figure 3: SQS Access Policy Note: The Resource field will be your SQS Queue ARN. For more information regarding cross-account SNS and SQS subscription, please see Appendix A at the end of this document. Page 5 of 10

6 4.3. Polling the SQS Queue for Notifications Finally, you need to define a service that continually polls the queue, looking for messages and handling them accordingly. Figure 4: Polling for SQS messages Note: The only message action you need to handle as a SaaS Contracts seller is the entitlement-updated action. All other actions are required by SaaS Subscription integrations only. Page 6 of 10

7 5. Metering Usage (SaaS Subscriptions) In the SaaS Subscriptions model, you will need to report usage to AWS on an hourly basis for all your customers, in batches of up to 25 at a time. The dimensions on which you meter are defined when you list your product on AWS Marketplace. Figure 5: Metering usage Page 7 of 10

8 6. Checking Entitlement (SaaS Contracts) In the SaaS Contracts model, instead of reporting usage for billing, your software will check if a user is entitled to a particular action or resource. For example, if your application is constrained or priced by the number of users a customer is allowed to use, the entitlements response would specify the number of users that the customer has elected for their contract. Entitlement checks are accomplished by passing the product code to retrieve associated contracts, at a maximum rate of 10TPS. You can also filter by the desired customer or dimension. It is important to note that there may be multiple entitlements for varying dimensions, and expiry should be checked, as seen below. Figure 6: Checking entitlements for SaaS Contracts An example of the entitlement response object can be found in section 3.4 of the AWS SaaS Billing Seller Integration Guide. 7. Conclusion This document has outlined code examples and integration steps for SaaS Subscriptions and SaaS Contracts integrations with the AWS Marketplace. Page 8 of 10

9 8. Additional Resources AWS Marketplace Seller Guide AWS SaaS Billing Seller Integration Guide AWS Marketplace Metering Service Documentation AWS Marketplace Entitlement Service Documentation Configuring the AWS CLI Boto 3 Quick Start Guide 9. Appendices 9.1. Appendix A: Subscribing to the SNS Topic to an SQS queue that does not belong to your AWS MP Seller account The following assumes you have an AWS seller account (seller), but your product is running in a different AWS account (production). To subscribe to the topic from the console: 1. Create an SQS queue in your production AWS account. 2. With the new queue selected in the console, click the Permissions tab, then click Add a Permission. 3. For the principal, choose Everybody. 4. For the Actions, select SendMessage from the list of actions. 5. Click Add Conditions. 6. For the Condition, select ArnEquals. 7. For the Key, select aws:sourcearn. 8. In the value, enter your SNS topic ARN. 9. Click Add Permission. 10. Copy the ARN for the queue for use later. 11. Switch to your AWS seller account. 12. Navigate to the SNS Service, then select Subscriptions. 13. Click Create Subscription. 14. In the Subscribe to a Topic dialog, paste your products SNS ARN into the Topic ARN field. 15. Select Amazon SQS as the Protocol. 16. Enter the ARN for the SQS queue you copied earlier as the Endpoint. 17. Click Create Subscription. 18. Switch back to the production AWS account and view the messages for the queue you created previously. You should have a message asking to confirm the subscription. In the message, locate the SubscribeURL field, and past the URL into your browser. You should receive an XML confirmation. See this page in the SNS documentation for more details Troubleshooting If you receive the error You are not authorized to subscribe to this topic, check that you are subscribing to a queue located within the seller AWS account you have registered with AWS Marketplace. Page 9 of 10

10 If you receive a client error (AccessDenied) check your account has sufficient permissions to perform the commands. If you have created a subscription from a SQS Queue not in your seller account, but have not received a confirmation message, check you have the correct permissions on the queue and retry the subscription. Page 10 of 10