AWS License Manager integration patterns for AMI or container-based products with contract pricing

Upfront contract pricing models in AWS Marketplace

AWS Marketplace now enables you to create AMI and container listings with upfront contract pricing. With this pricing model, your customers can buy your application directly through AWS Marketplace or through a private offer from a reseller, initiated by paying upfront for a monthly, annual, or multiyear contract.

Customers can choose the license options they want, the quantity, and the contract duration. After procurement, they can immediately deploy the product and use AWS License Manager to track and govern usage. They can also return to upgrade and renew their contracts through the AWS Marketplace website.

By integrating with AWS License Manager, your application can track entitlements purchased by your customers and provision features accordingly. This blog post will show you how to integrate your software with AWS License Manager to create a new listing with contract pricing.

Overview of license integration process with AWS License Manager

1. Set IAM permissions to call AWS License Manager. For more information, see AWS License Manager integration prerequisites.
2. Download the supported AWS SDK.
3. Add license checks to your product using AWS License Manager API. Your product should call the CheckoutLicense API operation wherever the license check must be performed. You can learn more about it at Integration patterns section of this post. For checking the license, your product must know:

• • The trusted issuer of the license (AWS Marketplace)
  • The application’s Product SKU (Product ID)
  • The entitlement to check for this application

4. Publish your product listing to AWS Marketplace.

Integration patterns for tiered and configurable license models

The contract pricing model enables you to offer the contract pricing without the need for a pay-as-you-go (PAYG) component. The customer can purchase software with upfront contract pricing and opt in to request a Private Offer to have custom pricing, terms, and duration based on their needs. Contract pricing supports two entitlement types: a tiered license model or a configurable license model.

A. Tiered license model

The tiered license model is a license model that entitles the customer to certain application features. Customers can not define the quantity of units they want to purchase. However, they can select a single predefined package or tier and can modify the contract later to subscribe to another tier. For example, your product can have basic (100 GB), standard (300 GB), and premium tiers (1 TB) that enable the customer to back up data accordingly, based on what tier is purchased.

Common integration pattern for the tiered license model

1. Customer launches the application with appropriate IAM role

To enable your application to call the AWS License Manager API successfully, your application must be authorized with the IAM policies described in License Manager integration prerequisites.

• • For AMI products, you can refer to Attach an IAM role to an Instance for the details.
  • For containers-based products, you can either refer to Create an IAM role for a service account to grant permission to your Amazon Elastic Kubernetes Service (Amazon EKS) pod, or to IAM Roles for Tasks in case your product uses Amazon Elastic Container Service (Amazon ECS).

2. Performing CheckoutLicense API call at launch

To enable support for tiered license model, your application must perform a CheckoutLicense API call at launch time with PROVISIONAL as checkout type. This checkout type enables you to temporarily draw a unit and return it back to the license pool when the application is stopped. Use these required parameters:

• • KeyFingerprint: The value for this parameter is always aws:294406891311:AWS/Marketplace:issuer-fingerprint, which indicates that the license is issued by AWS Marketplace.
  • ProductSKU: The value is the product ID generated when you create a new container or AMI product on the AWS Marketplace Management portal.
  • ClientToken: You can use a random UUID as a value to ensure the idempotency of the request.
  • Entitlements: For tiered license model, the value of Name properties is all of the Contracts Dimension API Names (Dimension) you set for your product. The value of Unit properties should always be None. You also must include all dimension API names defined for your product.

The following is a CheckoutLicense API call example for tiered license model using AWS Command Line Interface (AWS CLI).

Request command:

aws license-manager CheckoutLicense \
--product-sku "<PRODUCT-ID>" \
--checkout-type "PROVISIONAL" \
--key-fingerprint "aws:294406891311:AWS/Marketplace:issuer-fingerprint" \
--entitlements "Name=< Contracts Dimension1 API Name>, Unit=None" "Name=< Contracts Dimension2 API Name>, Unit=None” \
--client-token "<Random-UUID>"

{
    "CheckoutType": "PROVISIONAL", 
    "Expiration": "2021-08-20T22:21:56", 
    "IssuedAt": "2021-08-20T21:21:56", 
    "LicenseConsumptionToken": "5a532584ab3f4c4a8b4f9a89xxxxxxxx",
    "LicenseArn": "arn:aws:license-manager::294406891311:license:l-xxxxxxxxxxxxxxxxx" 
    "EntitlementsAllowed": [
        {
            "Units": "Count",
            "Name": "dimension1", 
            "Value": "Enabled"
        }
    ]
}

B. Configurable license model

This is a license model that 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 get billed based on the unit price. Customers can also subscribe to multiple dimensions.

There are two categories of configurable entitlement models: drawdown entitlements and floating entitlements. Here are common integration patterns for both.

Common integration patterns for drawdown and floating entitlements

1. Integration pattern for drawdown entitlements

With a drawdown entitlement, the number of units is drawn from the pool of units that the customer purchased permanently. For example, the customer purchases 10 units, which enables them to migrate up to 10 TB of data per year. After six months, the customer used all of the available units purchased, so they must modify the contract to purchase extra units to continue migrating data. The common integration model for drawdown entitlements is as follows.

1. 1. Customer launches the application with the appropriate IAM role: Same as tiered license model step A.1.
   2. Perform CheckoutLicense API call

For drawdown entitlement, your application must make a CheckoutLicense API call similar to the tiered license model step A.2. However, the checkout-type is PERPETUAL, which does not allow the consumed unit to be returned to the license pool. For the Entitlements parameter, you only list specific dimensions and the quantity of units, which must be greater than 0, that the customer consumes in Value properties with Unit properties as Count. You make this call when the customers start consuming the resource.

This is the example of CheckoutLicense API call for drawdown entitlement using AWS CLIv2:

aws license-manager CheckoutLicense \
--product-sku "<PRODUCT-ID>" \
--checkout-type "PERPETUAL" \
--key-fingerprint "aws:294406891311:AWS/Marketplace:issuer-fingerprint" \
--entitlements "Name=< Contracts Dimension1 API Name>, Value=<n>, Unit=Count”\ #replace <n> by number of unit consumed  by customer.
--client-token "<Random-UUID>"

{
    "CheckoutType": "PERPETUAL", 
    "Expiration": "2021-08-20T22:21:56", 
    "IssuedAt": "2021-08-20T21:21:56", 
    "LicenseConsumptionToken": "5a532584ab3f4c4a8b4f9a89xxxxxxxx",
    "LicenseArn": "arn:aws:license-manager::294406891311:license:l-xxxxxxxxxxxxxxxxx" 
    "EntitlementsAllowed": [
        {
            "Unit": "Count",
            “Count”: n, 
            "Name": "dimension1", 
            "Value": "Enabled"
        }
    ]
}

1. 3. Handle the API response

Successful response: if the units are available to consume and the customer’s entitlement is valid, the CheckoutLicense API call will respond successfully. Your application can be activated and enable access to the customer accordingly.

Unsuccessful response: If the call fails, an exception/error message will be returned. Based on the exception, your application should take appropriate actions like deactivating the product or notifying the customer to resolve the issue. Read more about the CheckoutLicense API exceptions at API CheckoutLicense Errors.

1. 4. Expired, canceled, or upgraded license events

An extra implementation for handling this case isn’t necessary, as your product will deny the functionality if there are not units available to be checked out. No regular calls to CheckOutLicense API are required.

The following diagram illustrates the common integration pattern of drawdown entitlement I described in steps B.1.1-4. It includes the customer application launch (1) of a containers-based application, the CheckoutLicense call (2), and the customer’s AWS License Manager account response to the API call (3).

2. Integration pattern for floating entitlements

With floating entitlements, a number of concurrent units can be drawn from the pool of units that the customer purchased. With floating entitlements, the consumed units can be sent back to the pool for later reuse. For example, the customer purchases 10 units, which enable up to 10 users to log in to applications simultaneously. When one user logs in to an application, one unit will be checked out. When one user logs out of your application, one unit is checked back into the pool. The common integration model for floating entitlements is as follows.

1. 1. Customer launches the application with the appropriate IAM role: similar to tiered license model, described in section A.
   2. Perform CheckoutLicense API call

Your application must call a CheckOutLicense API similar to with drawdown entitlement (as shown in B.2). However, the CheckoutType is PROVISIONAL to enable the consumed unit to be returned to the license pool. For the Entitlements parameter, you must list the specific dimension and the quantity of units consumed in the Value field, and the Unit properties is always Count. As with the drawdown model, you only must check out the specific dimension when the customer starts consuming the resources.

This is the example of CheckOutLicense API call for floating entitlements using AWS CLIv2:

aws license-manager CheckoutLicense \
--product-sku "<PRODUCT-ID>" \
--checkout-type "PROVISIONAL" \
--key-fingerprint "aws:294406891311:AWS/Marketplace:issuer-fingerprint" \
--entitlements "Name=< Contracts Dimension1 API Name>, Value=<n>, Unit=Count”\ #replace <n> by number of unit consumed  by customer.
--client-token "<Random-UUID>"

Successful response:

{
    "CheckoutType": "PROVISIONAL", 
    "Expiration": "2021-08-20T22:21:56", 
    "IssuedAt": "2021-08-20T21:21:56", 
    "LicenseConsumptionToken": "5a532584ab3f4c4a8b4f9a89xxxxxxxx",
    "LicenseArn": "arn:aws:license-manager::294406891311:license:l-xxxxxxxxxxxxxxxxx" 
    "EntitlementsAllowed": [
        {
            "Unit": "Count",
            “Count”: n, 
            "Name": "dimension1", 
            "Value": "Enabled"
        }
    ]
}

1. 3. Handle the API response

• • • Successful response: if the units are available to consume and the customer’s entitlement is valid, the CheckoutLicense API call will respond successfully. Your application can be activated and enable access to the customer accordingly.
    • Unsuccessful response: If the call fails, an exception/error message will be returned. Based on the exception, your application should take appropriate actions, such as deactivating the product or notifying the customer to resolve the issue. Read more about the CheckoutLicense API exceptions at API CheckoutLicense Errors.

4. 4. Extend the license By default, the units of floating entitlement are automatically sent back to the license pool after 60 minutes. This prevents the consumed units from being locked indefinitely by an unexpected pod, task, or EC2 instance termination. Therefore, your application must call ExtendLicenseConsumption hourly before the unit checks in automatically. The ExtendLicenseConsumption API call requires the LicenseConsumptionToken from the CheckoutLicense API’s response as an input parameter. In the event that a license is expired, the response returns the exception ResourceNotFoundException.

This is the example of ExtendLicenseConsumption API call for floating entitlements using AWS CLIv2:

aws license-manager extend-license-consumption \
--license-consumption-token "5a532584ab3f4c4a8b4f9a89xxxxxxxx"

Successful response:

{
    "Expiration": "2021-08-20T22:26:15Z", 
    "LicenseConsumptionToken": "5a532584ab3f4c4a8b4f9a89xxxxxxxx"
}

The following diagram illustrates the common integration pattern of floating entitlements I described in steps B.2.1-4. It includes the customer application launch (1) of a containers-based application, the CheckoutLicense call (2), the customer’s AWS License Manager account response to the API call (3), and the license extension (4).

1. 5. Check in the license There are chances that the application might stop or the customer might stop consuming resources. For example, one user might log out of the application, which would allow 100 users to log in simultaneously. In this event, the application must send the available unit back to the license pool using CheckinLicense API. This enables other users to consume that available unit later. The CheckinLicense API uses LicenseConsumptionToken from the CheckoutLicense API’s response as an input parameter.

This is the example of extend-license-consumption API call using AWS CLIv2:

aws license-manager check-in-license \
--license-consumption-token "5a532584ab3f4c4a8b4f9a89xxxxxxxx"

Successful response: Successful check-in-license API call will have no response.

1. 6. License expired, canceled, or upgraded events Similar to drawdown entitlement described in section B.1, your application can detect the license’s status when performing the CheckoutLicense API and have appropriate actions.

C. License discovery (optional)

Optionally, your application may also need to discover more information about the customer license’s status, maximum number of license’s units (MaxCount), or license’s validity. To get that information, your application can call a GetLicense API with LicenseArn from CheckoutLicense API’s response as an input parameter.

The following is an example of get-license API call using AWS CLIv2:

aws license-manager get-license \
-- --license-arn "arn:aws:license-manager::294406891311:license:l-xxxxxxxxxxxxxxxxx"

And a successful response:

{
    "License": {
        "LicenseArn": " arn:aws:license-manager::294406891311:license:l-xxxxxxxxxxxxxxxxx",
        "LicenseName": "<Product title on the Marketplace product>",
        "ProductName": "<Product title on the Marketplace product>",
        "ProductSKU": "<ProductId of Marketplace Product>",
        "Issuer": {
            "Name": "AWS/Marketplace",
            "KeyFingerprint": "aws:294406891311:AWS/Marketplace:issuer-fingerprint"
        },
        "HomeRegion": "us-east-1",
        "Status": "AVAILABLE",
        "Validity": {
            "Begin": "2021-06-24T17:59:28.347Z",
            "End": "2022-06-24T17:59:28.347Z"
        },
        "Beneficiary": " arn:aws:iam::xxxxxxxxxxxx:root
        "Entitlements": [
            {
                "Name": "dimension1",
                "MaxCount": 10,
                "Unit": "Count",
                "AllowCheckIn”: true
            }
. . . .
}

If you must validate the customer’s entitlement, you can also call the CheckoutLicense API with the entitlement name AWS::Marketplace::Usage every 15 minutes or every hour. AWS::Marketplace::Usage is the default entitlement of all licenses created by AWS Marketplace that you can check out without worrying about consuming available units that customer purchased.

The following is the example of CheckoutLicense API call for validating customer’s entitlement using AWS CLIv2:

aws license-manager CheckoutLicense \
 --product-sku "<ProductId of Marketplace Listing>" \
 --checkout-type "PROVISIONAL" \
 --key-fingerprint "aws:294406891311:AWS/Marketplace:issuer-fingerprint" \
 --entitlements "Name=AWS::Marketplace::Usage, Unit=None" \
 --client-token "79464194dca9429698cc774587a603a1"

And its successful response:

{
  "CheckoutType": "PROVISIONAL",
  "LicenseConsumptionToken": "1cc4e75437654ecc8943758c5936c3dc",
  "EntitlementsAllowed": [
    {
      "Name": "AWS::Marketplace::Usage",
      "Value": "Enabled",
      "Unit": "None"
    }
  ],
  "IssuedAt": "2021-08-18T23:34:03",
  "Expiration": "2021-08-19T00:34:03",
  "LicenseArn": "arn:aws:license-manager::294406891311:license:l-dcdaa0b0a9614b72bba314564d2f8e99"
}

Conclusion

In this blog post, I shared with you the new contract pricing model for AMI and container-based AWS Marketplace products. I also introduced some common patterns for tier or configurable entitlements that you can use as a reference to integrate your application with AWS License Manager. You can start listing your AMI and container-based products today and learn more about AWS Marketplace’s new pricing model at Contract Pricing.

About the authors

	Linh Lam is a Senior Partner Solution Architect, ISV focusing on AWS Marketplace and is passionate about application modernization, serverless, and containers technology. Outside of work he enjoys hiking, camping, and building his home audio systems.
	Amit was a Senior Product Manager with AWS Marketplace. He is passionate about building products that delights users and make it easy for customers to run their businesses efficiently.