Automate Private Marketplace management for your organization

For organizations that have software procurement policies and processes in place, private marketplace provides controls to ensure users are operating within those policies while using AWS Marketplace. Once enabled, users will only be able to procure products approved within their private marketplace. This ensures that only vetted products adhering to the organization’s policies can be purchased, helping reduce the risk of unapproved purchases.

In large organizations, administrators find it cumbersome to sign in to the AWS Management console to create and manage multiple private marketplace catalogs for different business units. With AWS Marketplace Catalog APIs for private marketplace, administrators can programmatically set up and manage private marketplace. They can use an AWS SDK and their preferred tools to call the APIs that are tailored to the specific programming language or platform.

In this post, Deepa and I will share a solution to set up private marketplace catalogs using AWS CloudFormation templates. You can use this solution to enable automation through integration with your organization’s existing infrastructure-as-code (IaC) setup. Internally, this solution uses APIs through AWS SDK for Python (Boto3) and leverages AWS Lambda, Amazon EventBridge, and Amazon S3. It provides an automated way to enable the private marketplace feature in your organization, create and configure multiple private marketplace experiences, and manage these experiences.

Private Marketplace terminology

A private marketplace experience is a curated catalog of approved products along with customized branding. This experience takes effect when it is associated to an audience (list of principals), which can be the entire organization, organizational units (OUs), or individual AWS account(s). The experience that is enabled and closest to a node in the AWS Organizations hierarchy takes effect.

The following diagram explains how experiences in the organization govern different accounts.

1. Default Experience is enabled and associated to the organization. All accounts in the organization will only be allowed to procure the products in the Default Experience.
2. Finance Unit Experience is enabled and associated to an OU for the finance department. All accounts under that OU will only be allowed to procure the products in the Finance Unit Experience.
3. Account 1 Experience is enabled and associated to an AWS account, Account 1. The users in the account will only be allowed to procure products in Account 1 Experience.
4. Marketing Unit Experience is not enabled, but it is associated to an OU for the marketing department. The accounts under that OU will continue to be governed by the Default Experience. An experience has to be enabled for it to take effect.

Figure 1 shows the experience that is enabled and closest to a node takes effect.

Figure 1. Experience association hierarchy

Prerequisites

Before you begin, make sure you have access to the following:

1. An AWS Organizations in all features enabled mode.
2. Access to the management account to enable the private marketplace feature.
3. An account in the organization to register as a delegated administrator for private marketplace. This is optional. If you do not register a delegated administrator, you can continue using the management account to configure and manage private marketplace experiences.

Solution overview

This solution enables you to automate private marketplace setup in your organization and performs the following steps:

1. Enable the private marketplace feature in your organization.
2. Deploy CloudFormation stacks to set up AWS resources to create and manage private marketplace experiences.
3. Upload configuration files to S3 to trigger creation or management of private marketplace experiences.
4. Monitor the system to detect failures or to confirm successful completion.

Solution walkthrough: Automate private marketplace management for your organization

In this solution, you will be creating three CloudFormation stacks, uploading configuration files to S3, and monitoring the configuration status.

A. Enable the private marketplace feature in your organization

This step can only be performed from the management account of your organization. Follow the steps to create a CloudFormation stack listed below to create EnablePMPStack. Once the stack creation completes, you will have successfully enabled private marketplace in your organization. This includes:

1. Creation of a service-linked role in the management account to describe AWS Organizations and update private marketplace resources.
2. Enabling private marketplace as a trusted service in AWS Organizations.
3. Optionally, registering an account as a delegated administrator for private marketplace.

B. Deploy CloudFormation stacks to set up AWS Resources

The stacks to configure and monitor can be created in the management account or the delegated administrator account. Both stacks have to be created in the same account.

Stack to configure private marketplace experiences

To configure private marketplace experiences, create ConfigurePMPStack which sets up the following resources.

1. S3 bucket, for example, pmp_configuration to upload experience configuration. Bucket name is configurable.
2. A lambda AsyncConfigurePrivateMarketplaceLambda that is triggered by S3 object put events. It reads the configuration file, starts a change set to create or manage the experience, and writes to a status file to report the progress.

Stack to monitor private marketplace configuration

To monitor private marketplace configuration, create MonitorPMPStack which sets up the following resources.

1. EventBridge rule to listen to change set status.
2. ChangesetStatusUpdateLambda that gets triggered on change set status update. It writes to the status file and creates an error file if there are failures.

Steps to create a CloudFormation stack

1. Sign in to your AWS account and navigate to the Create stack option in AWS CloudFormation console.
2. Select the options Choose an existing template and Upload a template file.
3. Select a template file, and specify stack details.
   1. EnablePMPStack (management account):
      1. Select enable_private_marketplace.yaml and click Next.
      2. Optionally, to register a delegated administrator, enter an AWS account id in the DelegatedAdministratorAccount input. This will allow you to perform the configuration and monitoring steps from the delegated administrator account.
   2. ConfigurePMPStack (management or delegated administrator account):
      1. Select configure_private_marketplace.yaml and click Next.
      2. Provide a unique name for experience S3 bucket.
   3. MonitorPMPStack (same account as ConfigurePMPStack):
      1. Select private_marketplace_event_listener.yaml and click Next.
      2. You should match the name for the S3 bucket with the name used in ConfigurePMPStack.
4. On subsequent pages, leave all other fields to their default.
5. On the final page, acknowledge that AWS CloudFormation might create IAM resources.
6. Choose Submit. Stack creation completes when you see a CREATE_COMPLETE.

C. Upload configuration files to S3

To create or manage a private marketplace experience, upload a configuration file to the S3 bucket created by ConfigurePMPStack. The configuration file name should follow the format Experience_ShortName#version_id.json where ShortName must be unique and must be followed by a #. You can use an optional version_id for auditing.

You can specify the following fields. For details, refer the private marketplace Automation JSON schema.

• Name – Name of the experience.
• AssociatePrincipals – This can be a list of your organization ID, one or more OU IDs, or account IDs that will be associated to your private marketplace experience. If you specify principals that are associated to another experience, this will result in an error.
• DisassociatePrincipals – Same as above. These principals will be disassociated from your private marketplace experience. If you specify principals that are not associated to the experience, this will result in an error.
• AllowProducts – List of product IDs of the products to allow for procurement in the experience. To find the product IDs, refer to Finding products in the AWS Marketplace Catalog guide.
• DenyProducts – List of product IDs of the products to deny for procurement in the experience.
• Status – Status of the experience.
• PolicyResourceRequests – Setting to allow or deny users to request for new products.

Flow Diagram

Figure 2 illustrates the flow for private marketplace automation.Figure 2. Flow diagram for private marketplace automation

1. Upload a configuration file Experience_ShortName#version_id.json to the S3 bucket pmp_configuration created by ConfigurePMPStack stack.
2. AsyncConfigurePrivateMarketplaceLambda has an S3 trigger for put events on objects added to pmp_configuration bucket with Experience_ prefix. To decide whether to create or manage an experience, the lambda looks for STATUS_Experience_ShortName file.
   1. If it does not exist, a new experience is created.
   2. If it exists, the existing experience specified by Experience Id in the STATUS_ file will be updated.
3. The lambda starts a Catalog API change set, creates or updates the STATUS_ file with the change set id and sets the status to In Progress.
4. Catalog API publishes events to EventBridge. An EventBridge rule triggers the ChangesetStatusUpdateLambda when it receives one of these events: Change Set Succeeded, Change Set Failed, Change Set Cancelled.
5. ChangesetStatusUpdateLambda loops through the STATUS_ files and updates the STATUS_ file with Successful or Failed. For auditing, errors are written to an ERROR_ file.

Sample configuration files

It is recommended to start with a default private marketplace that is associated to the whole organization and customize or create more as you need them. Here are some sample configuration files that you can use after modifying the principals and product IDs.

Experience_Default#1_0.json: Configuration file to create a default experience associated to the organization.

{
    "Name": "Default Experience",    
    "AssociatePrincipals": [
        "o-abcdef1234"
    ],    
    "AllowProducts":[
        "12345678-0123-4567-abcd-43176543210", 
        "12345678-0123-4567-abcd-43176543211"
    ],
    "DenyProducts":[
        "12345678-0123-4567-abcd-43176543212"
    ],
    "Status": "Enabled",
    "PolicyResourceRequests": "Deny"
}

Experience_FinanceUnit#1_0.json: Configuration file to create an experience for the Finance OU.

{
    "Name": "Finance Unit Experience ",
    "AssociatePrincipals": [
        "ou-xyz1234"
    ],
    "AllowProducts":[
        "12345678-0123-4567-abcd-43176543213",
        "12345678-0123-4567-abcd-43176543214"
    ],
    "Status": "Enabled
}

Experience_FinanceUnit#1_0.json: Configuration file to update the experience for the Finance OU to allow a new product.

{
    "Name": "Finance Unit Experience ",
    "AllowProducts":[
        "12345678-0123-4567-abcd-43176543215"
    ]
}

How to manage experiences created outside of the automation

To manage an experience that was created outside of this automation, upload a status file with the experience id. You can find the experience id by opening the experience in the private marketplace dashboard and looking at the details tab. Use a file name with format STATUS_Experience_ShortName, where ShortName can be any unique name. Once a status file is uploaded, the experience can be managed like any experience that was created by the automation.

STATUS_Experience_MarketingUnit: Status file to indicate existing experience

{
    "Experience Id": " exp-abcdefghi"
}

Experience_MarketingUnit#1_0.json: Configuration file to update the Marketing Unit experience to associate an OU.

{
    "Name": "Marketing Unit Experience",
    "AssociatePrincipals":[
        "ou-marketing"
    ]
}

D. Monitor the configuration status

Once the updates are complete, the solution writes the status to the STATUS_ file in the S3 bucket. If there is a failure, an ERROR_ file will be written. To monitor the status, check the S3 bucket or set up additional monitoring, as required.

Additional considerations

To further streamline private marketplace administration, you can modify the templates to support additional actions by referring to Working with a private marketplace in the AWS Marketplace Catalog API guide.

Cleaning up

In our sample, we create multiple CloudFormation stacks and an S3 bucket. To clean up the environment, delete the files from your S3 bucket. You can also choose to delete the S3 bucket. Then, delete the CloudFormation stacks. These steps ensure that there are no forthcoming costs to your account stemming from this sample. To remove private marketplace governance, you can disable trusted access and delete the service-linked role.

Conclusion

In this post, we showed you how to programmatically create and manage multiple private marketplace experiences for your organization using CloudFormation. We showed how to enable the private marketplace feature and create two experiences. We also showed you how to manage your private marketplace experiences. The solution outlined in this post can help you integrate private marketplace setup with your organization’s existing systems.

Further reading:

• For more information on private marketplace, refer to the AWS Marketplace Buyer Guide.
• To understand more about the APIs, refer to AWS Marketplace Catalog API.

About the authors

Soumya Vanga is a solutions architect with expertise in designing and implementing scalable solutions for complex business problems. Outside of work, she enjoys audiobooks, building Legos and roadtrips with her family.

Deepa Remesh is a software development manager in AWS Marketplace. She loves designing and developing features that enable customers to govern and customize their experience on AWS Marketplace. Outside of work, she enjoys cooking, traveling, and spending time with her family.