Associating licenses with AMI-based products using AWS License Manager
For Amazon Machine Image (AMI)-based products with contract pricing, you can use AWS License Manager to associate licenses with your product. AWS License Manager is a license management tool that enables your application to track and update licenses (also known as entitlements) that have been purchased by a customer. After the integration is complete, you can publish your product listing on AWS Marketplace. The following sections provide more information about using AWS License Manager to associate licenses with your AMI-based product.
For more information about AWS License Manager, refer to the AWS License Manager User Guide and the AWS License Manager section of the AWS CLI Command Reference.
Note
-
Customers can't launch new instances of the AMI after the contract expiry period. However, during the contract duration, they can launch any number of instances. These licenses are not node-locked or tied to particular instances.
-
Private Offer Creation– Sellers can generate private offers for the products using the Private offer creation tool in the AWS Marketplace Management Portal.
-
Reporting – You can set up data feeds by setting up an Amazon S3 bucket in the Report section in the AWS Marketplace Management Portal. For more information, refer to Seller reports, data feeds, and dashboards in AWS Marketplace.
Topics
License models
AWS Marketplace integration with AWS License Manager supports two license models:
Configurable license model
The configurable license model (also known as the quantifiable license model) entitles a buyer to a specific quantity of resources after a buyer has procured a license.
You set a pricing dimension and a per unit price. Then, buyer can choose the quantity of the resources that they want to purchase.
Example of pricing dimension and per unit price
You can set a pricing dimension (such as data backup) and per unit price (such as $30/unit)
The buyer can choose to purchase 5, 10, or 20 units.
Your product tracks and meters usage to measure the quantity of resources consumed.
With the configuration model, the entitlements are counted in one of two ways:
Drawdown licenses
The license is drawn from the pool of allowed amount of licenses upon use. That entitlement is checked out permanently and can't be returned to the license pool.
Example of processing a limited amount of data
A user is entitled to process 500 GB of data. As they continue to process data, the quantity is drawn from the pool of 500 GB until all 500 GB licenses are consumed.
For drawdown licenses, you can use the CheckoutLicense
API operation to
check out license units that are consumed.
Example of backup to S3 for a number of units/year
You have a storage product that allows backup to Amazon Simple Storage Service (Amazon S3) for up to 1024
units for data for one year. Your application can be launched by using multiple Amazon EC2
instances. Your application has a mechanism to track and aggregate data. Your software
calls the CheckoutLicense
API operation with the Product ID upon every
backup or at fixed intervals to update the consumed quantities.
In this example, your software calls CheckoutLicense
to check out 10
units of data. When the total capacity reaches the backup limit that the customer has
purchased, the API call fails.
Request
linux-machine ~]$ aws license-manager checkout-license\ --product-sku "2205b290-19e6-4c76-9eea-377d6bf7la47" \ --checkout-type "PERPETUAL" \ --key-fingerprint "aws:294406891311:AWS/Marketplace:issuer-fingerprint" \ --entitlements "Name=DataConsumption, Value=l0, Unit=Count" \ --client-token "AKIAIOSFODNN7EXAMPLE"
Response
{ "CheckoutType": "PERPETUAL", "EntitlementsAllowed": [ { "Name": "DataConsumption", "Count": 10, "Units": "Count", "Value": "Enabled" } }, "Expiration": "2021-04-22Tl9:02: 36", "IssuedAt": "2021-04-22Tl8:02:36", "LicenseArn": "arn:aws:license-manager::294406891311:license:l-16bf01b...", "LicenseConsumptionToken": "AKIAIOSFODNN7EXAMPLE" }
Floating licenses
The license is returned to the pool of the allowed amount of licenses after use.
Example of number of users from a fixed upper limit
A user is entitled to 500 simultaneous users on the application. As users log in and log out, the users are drawn and returned to the pool of 500 users. However, the application can't draw more than 500 users from the pool because 500 simultaneous users is the fixed upper limit.
For floating licenses, you can use the CheckInLicense
API operation to
return the license units to the entitlement pool.
Example of number of concurrent users for one year
Your product is priced based on number of concurrent users. The customer purchases a
license for 10 users for one year. The customer launches the software by providing
AWS Identity and Access Management (IAM) permissions. When a user logs in, your application calls the
CheckoutLicense
API operation to reduce the quantity by 1. When the user
logs out, the application returns that license to the pool by calling the
CheckInLicense
API operation. If you don't call
CheckInLicense
, the license unit will be automatically checked in after 1
hour.
Note
In the following Request, the key-fingerprint
isn't a placeholder value
but the actual value of the fingerprint with which all licenses will be
published.
Request
linux-machine ~]$ aws license-manager checkout-license\ --product-sku "2205b290-19e6-4c76-9eea-377d6bf7la47" \ --checkout-type "PROVISIONAL" \ --key-fingerprint "aws:294406891311:AWS/Marketplace:issuer-fingerprint" \ --entitlements "Name=ReadOnlyUSers, Value=l0, Unit=Count" \ --client-token "AKIAIOSFODNN7EXAMPLE"
Response
{ "CheckoutType": "PROVISIONAL", "EntitlementsAllowed": [ { "Name": "ReadOnlyUsers", "Count": 10, "Units": "Count", "Value": "Enabled" } }, "Expiration": "2021-04-22Tl9:02: 36", "IssuedAt": "2021-04-22Tl8:02:36", "LicenseArn": "arn:aws:license-manager::294406891311:license:l-16bf01b...", "LicenseConsumptionToken": "AKIAIOSFODNN7EXAMPLE" }
Tiered license model
The tiered license model entitles a buyer to a specific level, or tier, of application features after a buyer has procured a license.
You create tiers for your product, such as Basic, Intermediate, and Premium. The buyer then selects one of the predefined tiers.
The application doesn't need to track or meter usage of the application.
With the tiered license model, the entitlements aren't counted but instead signify a tier of service that was procured by the customer.
If you want to offer bundled features together, we recommend using the tiered license model.
Example of Basic, Intermediate, and Premium tiers
A customer can sign a contract for one of three possible tiers of the software: Basic,
Intermediate, or Premium. Each of these tiers has its own pricing. Your software can
identify the tier that the customer has signed up for by invoking the
CheckoutLicense
API operation and specifying all possible tiers in the
request.
The response of the request contains the entitlement corresponding to the tier the customer has procured. Based on this information, the software can provision the appropriate customer experience.
Request
linux-machine ~]$ aws license-manager checkout-license\ --product-sku "2205b290-19e6-4c76-9eea-377d6bf7la47" \ --checkout-type "PROVISIONAL" \ --key-fingerprint "aws:294406891311:AWS/Marketplace:issuer-fingerprint" \ --entitlements "Name=BasicTier, Unit=None" "Name=IntermediateTier, Unit=None" \ "Name=PremiumTier, Unit=None"
Response
{ "CheckoutType": "PROVISIONAL", "EntitlementsAllowed": [ { "Name": "IntermediateTier", "Units": "None" } }, "Expiration": "2021-04-22Tl9:02:36", "IssuedAt": "2021-04-22Tl8:02:36", "LicenseArn": "arn:aws:license-manager::294406891311:license:l-16bf01b...", "LicenseConsumptionToken": "AKIAIOSFODNN7EXAMPLE" }
Integration workflow
The following steps show the workflow for integrating your AMI product with AWS License Manager:
-
Seller creates a product with AWS License Manager integration.
-
Seller lists the product on AWS Marketplace.
-
Buyer finds the product on AWS Marketplace and purchases it.
-
A license is sent to the buyer in their AWS account.
-
Buyer uses the software by launching the Amazon Elastic Compute Cloud (Amazon EC2) instance, Amazon Elastic Container Service (Amazon ECS) task, or Amazon Elastic Kubernetes Service (Amazon EKS) pod software, The customer deploys by using an IAM role.
-
Software reads the license in the buyer's AWS License Manager account, discovers the entitlements purchased, and provisions the features accordingly.
Note
License Manager doesn't do any tracking or updates; this is done by the seller’s application.
License Manager integration prerequisites
Before publishing the product, you must do the following:
-
Create a new AMI product in the AWS Marketplace Management Portal, and make a note of its product code.
-
Fill out the Product Load Form (PLF) with the necessary price information, and return it to us for processing.
-
Use an IAM role for the task or pod running your application with the IAM permissions necessary to call
CheckoutLicense
,ExtendLicenseConsumption
, andCheckInLicense
.The required IAM permissions are detailed in the following IAM policy.
{ "Version":"2012-10-17", "Statement":[ { "Sid":"VisualEditorO", "Effect":"Allow", "Action":[ "license-manager:CheckoutLicense", "license-manager:GetLicense", "license-manager:CheckInLicense", "license-manager:ExtendLicenseConsumption", "license-manager:ListReceivedLicenses" ], "Resource":"*" } ] }
-
Make a test call to the
RegisterUsage
API operation with a record for all of the pricing dimensions you define.
Integrating an AMI-based product with AWS License Manager
You can integrate your AMI-based product with License Manager by using the AWS License Manager API. Launch the Amazon EC2 instances by using AWS Marketplace AMI-based products.
Note
Make sure that you have completed the License Manager integration prerequisites before you perform the following procedure.
To integrate your AMI-based product with License Manager
-
Complete the procedure in Creating a test license in License Manager. You must create a test license in License Manager for testing your integration.
-
Run the GetLicense API operation using the license Amazon Resource Name (ARN) that you obtained in step 1. Note the value of the
KeyFingerprint
attribute of theGetLicense
response for later use. -
Download and include the latest public AWS SDK in your application.
-
To verify that the buyer is entitled to use a license for your application, run the CheckoutLicense API operation. Use the entitlements details and the key fingerprint of the test license that you obtained in step 1.
If there are no entitlements found for the license, or the entitlement maximum count is exceeded, the
CheckoutLicense
API operation returnsNoEntitlementsAllowedException
. If the entitlements are valid, or available to use, theCheckoutLicense
operation returns a successful response with the requested entitlements and their values. -
(Required for floating entitlements only) Run the CheckinLicense API operation using the
LicenseConsumptionToken
that was received in theCheckoutLicense
response. This action releases previously checked-out entitlements back into the pool of available entitlements. -
After you successfully verify the License Manager integration with the test license that you created in step 1, update the key fingerprint in your code to
aws:294406891311:AWS/Marketplace:issuer-fingerprint
. Now, you're ready to work with licenses issued by AWS Marketplace.
Follow the release process of building the application to an AMI product and then submit the product to AWS Marketplace following the product publishing process.
Creating a test license in License Manager
You use version 2 of the AWS Command Line Interface (AWS CLI) to create a test license in AWS License Manager. This test license is only used for verifying and testing the AWS License Manager integration. After the testing is completed, you can delete the test license. The actual license is generated by AWS Marketplace with a different key fingerprint.
AWS Marketplace supports two types of entitlements in AWS License Manager. However, only one type can be enabled for a product. When you create a license, including a test license, you must specify one of the following types of entitlements:
Tiered entitlements – The tiered license model entitles the customer to certain application features. Customers can't define the quantity of units they want to purchase. However, they can select a single predefined package or tier. Customers can modify the contract later to subscribe to another tier.
Configurable entitlements – The configurable license model grants entitlements to a certain quantity of resources when the customer procures a license. The customer chooses the quantity of units they want to purchase during the subscription process and will be billed based on the unit price. Customers can also subscribe to multiple dimensions.
The required parameters for use in the CheckoutLicense
API operation are as
follows:
-
CheckoutType
– The valid values arePerpetual
orProvisional
:-
Perpetual
– Used when the quantity of entitlements checked out will be exhausted from the pool. Example: Buyer is entitled to process 500 GB of data. As they continue to process data, the quantity is drawn down and exhausted from the pool of 500 GB. Gets the status of a purchased license on whether the license is expired or about to be expired to send a notification to the customer. -
Provisional
– Used for floating license entitlements where entitlements are checked out of the pool and returned back after use. Example: User is entitled to 500 simultaneous users in the application. As users log in and log out, the users are drawn and returned to the pool of 500 users. For more information about floating license entitlements, see Seller issued licenses in AWS License Manager.
-
-
ClientToken
– Unique, case-sensitive identifier to ensure the exact result occurs and is the same no matter how many times attempted. We recommend that you use a random universally unique identifier (UUID) for each request. -
Entitlements
– List of entitlements to be checked out.-
For tiered entitlements, provide
Name
andUnit
properties as follows:{
"Name": "<
Entitlement_Name
>","Unit": "
None
"}
-
For configurable entitlements, provide
Name
,Unit
, andValue
properties as follows:{
"Name": "<
Entitlement_Name
>","Unit": "<
Entitlement_Unit
>","Value": <
Desired_Count
>{}
-
-
KeyFingerprint
– Use this key fingerprint to verify that the license is issued by AWS Marketplace. The key fingerprint for licenses issued by AWS Marketplace is as follows:aws:294406891311:AWS/Marketplace:issuer-fingerprint
-
Product SKU
– Product ID with a Globally Unique Identifier (GUID) format that is associated with an AWS Marketplace product.
Example of a configurable entitlement
The following is an example of a request that uses the CheckoutLicense
API operation to check out a configurable entitlement named
PowerUsers
.
aws license-manager checkout-license \ product-sku "2205b290-19e6-4c76-9eea-377d6bf71a47" \ checkout-type "PROVISIONAL" \ client-token "79464194dca9429698cc774587a603a1" \"Statement":[ entitlements "Name=PowerUsers,Value=1,Unit=Count" \ key-fingerprint "aws:294406891311:AWS/Marketplace:issuer-fingerprint"
Example of a tiered entitlement
The following is an example of a request that uses the CheckoutLicense
API operation to check out a feature entitlement named
EnterpriseEdition
.
aws license-manager checkout-license \ --product-sku "2205b290-19e6-4c76-9eea-377d6bf71a47" \ --checkout-type "PROVISIONAL" \ --client-token "79464194dca9429698cc774587a603a1" \ --entitlements "Name=EnterpriseEdition,Unit=None" \ --key-fingerprint "aws:294406891311:AWS/Marketplace:issuer-fingerprint"
To create a test license for your AMI-based product
-
From your local environment with AWS CLI v2 installed, run the following script. The script creates the test license and configures the appropriate product details.
Note
Use a different AWS account than the test AWS account in which you are deploying and testing your software. Licenses can't be created, granted to, and checked out in the same AWS account.
#!/bin/bash # Replace with intended product ID on AWS Marketplace PRODUCT_ID=<REPLACE-WITH-PRODUCT-ID> # Replace with license recipient's AWS Account ID BENEFICIARY_ACCOUNT_ID=<REPLACE-WITH-BENEFICIARY-ACCOUNT-ID> # Replace with your product's name PRODUCT_NAME="Test Product" # Replace with your seller name on AWS Marketplace SELLER_OF_RECORD="Test Seller" # Replace with intended license name LICENSE_NAME="AWSMP Test License" # Replace the following with desired contract dimensions # More info here: https://docs.aws.amazon.com/license-manager/latest/APIReference/API_Entitlement.html # Example "configurable entitlement" ENTITLEMENTS='[ { "Name": "ReadOnly", "MaxCount": 5, "Overage": false, "Unit": "Count", "AllowCheckIn": true } ]' # Example "tiered entitlement" # ENTITLEMENTS='[ # { # "Name": "EnterpriseUsage", # "Value": "Enabled", # "Unit": "None" # } # ]' # Format "yyyy-mm-ddTHH:mm:ss.SSSZ" # This creates a validity period of 10 days starting the current day # Can be updated to desired dates VALIDITY_START=$(date +%Y-%m-%dT%H:%M:%S.%SZ) VALIDITY_END=$(date --date="+10 days" +%Y-%m-%dT%H:%M:%S.%SZ) # Configuration for consumption of the license as set on Marketplace products CONSUMPTION_CONFIG='{ "RenewType": "None", "ProvisionalConfiguration": { "MaxTimeToLiveInMinutes": 60 } }' # License's home Region HOME_REGION=us-east-1 # License issuer's name ISSUER=Self # Run AWS CLI command to create a license aws license-manager create-license \ --license-name "${LICENSE_NAME}" \ --product-name "${PRODUCT_NAME}" \ --product-sku "${PRODUCT_ID}" \ --issuer Name="${ISSUER}" \ --beneficiary "${BENEFICIARY_ACCOUNT_ID}" \ --validity 'Begin="'"${VALIDITY_START}"'",End="'"${VALIDITY_END}"'"' \ --entitlements "${ENTITLEMENTS}" \ --home-region "${HOME_REGION}" \ --region "${HOME_REGION}" \ --consumption-configuration "${CONSUMPTION_CONFIG}" \ --client-token $(uuidgen)
-
Grant the license using the AWS License Manager console. For more information, see distribute an entitlement in the License Manager User Guide.
-
Sign in to the AWS account that acts as a buyer account where you will deploy and test your software. This must be a different AWS account from the AWS account that created and granted the license.
-
Go to the AWS License Manager console to accept and activate the granted licenses. For more information, see manage your granted licenses in the License Manager User Guide.
-
Run the following command in your environment.
# The following example uses a key fingerprint that should match the test license you created. # When checking out an actual AWS Marketplace created license, use the following fingerprint: # aws:294406891311:AWS/Marketplace:issuer-fingerprint aws license-manager checkout-license \ --product-sku <REPLACE-WITH-PRODUCT-ID> \ --checkout-type PROVISIONAL \ --key-fingerprint "aws:<ACCOUNT-ID-WHERE-YOU-CREATED-TEST-LICENSE>:Self:issuer-fingerprint" \ --entitlements "Name=ReadOnly,Value=1,Unit=Count" \ --client-token $(uuidgen)
The previous command uses
PROVISIONAL
as the value for theCheckoutType
parameter. If the entitlement uses a drawdown license, usePERPETUAL
for the value.
License Manager API calls
To manage the licenses stored in the customer's License Manager account, your software can use the following API calls:
-
GetLicense
– Gets the status of a purchased license on whether the license is expired or about to be expired to send a notification to the customer. -
CheckoutLicense
– Discovers licenses that the user has purchased. You can also use it to update the license quantity when the user has consumed some quantity of licenses. WithCheckoutLicense
, you can keep checking out the quantities of the licenses used by the customer. When the customer exhausts all the licenses, this call returns an error. For information about the suggested cadence to runCheckoutLicense
, see License renewals and upgrades. -
ExtendLicenseConsumption
– In case of floating dimensions, when the software check outs a license, it will return the license to the pool automatically after 60 minutes. If you want to extend the time the license remains checked out, your software can callExtendLicenseConsumption
to extend the license for another 60 minutes. -
CheckInLicense
– In case of floating dimensions, when you want to return the license to the entitlement pool, useCheckInLicense
. -
ListReceivedLicenses
– Lists licenses purchased by the buyer.
License renewals and upgrades
Customers can renew or upgrade their licenses on the AWS Marketplace Management Portal. After they make an additional purchase, AWS Marketplace generates a new version of the license that reflects the new entitlements. Your software reads the new entitlements using the same API calls. You don't have to do anything different in terms of License Manager Integration to handle renewals and upgrades.
Due to license renewals, upgrades, cancellations, and so on, we recommend that your
product performs the CheckoutLicense
API call at a regular cadence while the
product is in use. By using the CheckoutLicense
API operation at a regular
cadence, the product can detect changes in entitlements such as upgrades and expiry.
We recommend that you perform the CheckoutLicense
API call every 15 minutes.