microsoft / commercial-marketplace-saas-api-emulator

An emulator for the Microsoft commercial marketplace SaaS Fulfillment APIs

Microsoft Commercial Marketplace API Emulator

This repository contains a Node.js implementation of an emulator for the Microsoft commercial marketplace SaaS Fulfillment APIs.

To make hosting the emulator as simple as possible, the repo includes a Dockerfile for a building a containerised version.

What challenges does this project address?

Integrating with the commercial marketplace has a few scaffolding requirements; a barrier to getting up and running quickly. The emulator breaks that dependency, allowing teams to start building for marketplace with zero friction. Specifically:

• Remove dependency on Partner Center
  • Partner Center onboarding and permissions can take some time to setup correctly. You can get started right away without waiting for this process.
  • Ordinarily, testing API flows against plans can only happen after they have been created in Partner Center. Emulated plans allow development to happen in parallel. Only final testing is required against Partner Center plans.
• Remove the AAD requirement
  • A SaaS transactable offer, or at least the integration with marketplace, must be built with AAD. The integration with the marketplace APIs requires the app to be registered in AAD and API calls are secured with OAuth2. Similarly, your landing page must support AAD SSO. The emulator removes these requirements to make it simpler (and quicker) to start implementing your integration flows.

Design goals

• Keep things simple
• Implement the minimum required whilst being fully functional out of the box
• Be consistent with the behaviour of APIs, note differences from the documented behaviour
• Support both unauthenticated use for simplicity and authenticated use for closer fidelity with the marketplace APIs.
• Flexible implementation that offers multiple hosting options to suit the user
• Offer configuration options to tailor the behaviour
• Provide a UI to step through and visualise certain actions

Getting started

The emulator is a Node.js application designed to be run as a Docker container for portability. Other hosting options are also possible. For more details see the relevant section:

• Hosting the emulator
• Configuring the emulator
• Usage scenarios

Using the emulator

With the emulator running, you can connect to it using a browser and standard tools such as the REST Client extension for VS Code, Postman etc.

The URL and port will depend on your chosen deployment method. eg if you're running the emulator locally using docker run, you would likely connect on http://localhost:8080.

1. Run the emulator using your chosen method
2. With a browser, connect to http://<domain>:<port> (domain, port depend on your run method)
   • You should be presented with a page for configuring a synthetic marketplace purchase token
3. Configure a purchase token
   1. (Optionally) configure properties on the purchase token (otherwise defaults will be populated)
   2. Click the Generate Token button
   3. Observe the generated JSON result
4. You can now either
   1. Use the emulator's simple, built-in landing page implementation to resolve & activate a subscription
   2. Exercise the APIs manually (eg using the VS Code REST client or Postman)

Use the Emulator's built-in landing page

1. Click on the Post to landing page button in the Token area
2. You will be taken to the emulator's built-in landing page
3. The purchase token is passed to the landing page as a query string parameter
4. When it loads, the landing page automatically calls the resolve API to decode the token
5. Key token properties are displayed on the page
6. Click the Activate subscription button to call the activate API
7. You should see a message indicating a 200 OK status response
8. Navigate to the Subscriptions page to see your new subscription has been activated

A word about the Publisher ID

Subscriptions need to be associated with a publisher. In the marketplace, the publisher is derived using claims from the AAD bearer token used to authenticate.

For the emulator, to keep things simple, we removed the AAD requirement. Instead, you can define the Publisher ID in one of two ways:

1. A publisherId query string parameter. This is set to "FourthCoffee" as a default in the emulator

   1. To see an example of this in action, take a look at the sample REST calls: subscriptions-apis.http
   2. To modify this Publisher ID for the built-in emulator functions, set the PUBLISHER_ID environment variable

2. A Publisher ID constructed from the publisher tenant and app IDs.

   1. This is useful to mirror the behaviour of the marketplace. The tenant and app ID from the app registration you use to authenticate with the marketplace APIs will also work with the emulator
   2. To modify this Publisher ID for the built-in emulator functions, set the PUBLISHER_TENANT_ID and PUBLISHER_APP_ID environment variables. Set these to the tenant and app ID from the app registration used to authenticate with the marketplace APIs. eg from the Azure Portal (see below) or Partner Center offer page.

   

You can use either approach (but not both at the same time!). The former is useful for early testing as you don't need to register with AAD, the latter is useful in the latter stages of emulator testing as it is directly compatible with the marketplace.

For more information on configuration see Configuring the emulator

Exercise the APIs manually

1. Click the Copy to clipboard button in the Token area (not the JSON result)
2. This copies the Base64 encoded purchase token to the clipboard
3. Call the resolve API to resolve (decode) the purchase token
   1. This repo includes helpers to call the emulated APIs using the REST Client extension for VS Code
   2. Open this repo in VS Code
   3. Install the REST Client
   4. Open subscription-apis.http from the \rest_calls folder
   5. In subscription-apis.http set
      • publisherId [string] simulates the Publisher ID (can be anything you like eg Contoso Corp)
      • baseUrl [sting] format as above eg http://localhost:8080
      • purchaseToken [string] the Base64 encoded purchase token (paste from the clipboard)
   6. Click Send Request (under ### Resolve)
      • You should see a Response appear with a 200 OK status
      • The payload will include the decoded purchase token
4. Call the activate API to activate the purchase
   1. In subscription-apis.http
   2. Update the planId on the activate request to match a valid planId as set in the purchase token
   3. Click on Send Request on the activate API call
   4. You should see a 200 OK status
   5. The payload will be OK

At this point you have

• Created a (synthetic) purchase token
• Resolved that purchase token to its properties
• Activated the purchase

You can now call other APIs to see their response

• eg the GetSubscriptions API would return a list of all subscriptions
• Having completed the above steps, this will return a collection with one item, the subscription you activated

There are helpers for all available SaaS Fulfillment v2 APIs in

• subscription-apis.http
• operations-apis.http

For more details on the available APIs and their operation, see

• SaaS subscription life cycle
• Subscription APIs
• Operations APIs

Functionality

The solution emulates all operations on the SaaS Fulfillment APIs v2 closely. It is close-to, but not 100% fidelity (see Limitations below.

Any solution should be thoroughly tested against the marketplace APIs before final release.

Capabilities include the following:

• Generate a synthetic purchase identification token
• This token has customisable subscription properties that can be resolved by the emulated resolve API
• Publisher ID can be set by query string parameter (publisherId) or authorization header (bearer token)
• Testing the following flows:
  • Landing page flow
  • Activation flow
  • Update flow
  • Suspend and reinstate flow
  • Webhook flows

The format of the marketplace purchase identification token is not documented. In the emulator, this has been simulated with a Base64 encoded JSON payload.

Limitations

• The activate call does not validate the publisher (as the 'faux' purchase token isn't associated with a specific publisher. This may be implemented in future.

Accelerator Integration

There are two Open Source projects from teams at Microsoft, the SaaS Accelerator and MONA SaaS that have been updated to work with the Emulator in place of the Azure Marketplace. Documentation: Integrations.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

commercial-marketplace-saas-api-emulator's Issues

Add min/max seat counts to offers

When creating a new offer, add the ability to set min and max seats
Align this to the Partner Center functionality that requires an overlap between plans
Add the validation to the API call to change quantity/plan

Subscriptions - Change Plan bug

(Running debugger locally)
Clicking Change Plan and cancelling is causing the debugger to Exit when navigating to another page.
Behaviour is not repeated with Change Quantity.

The presence of an in-built webhook response should be explained

When executing actions within the emulator that will generate webhook calls, it is not clear that there is an in-built emulation of a webhook implementation receiving events. This is confusing as the config indicates that there is a URL to a webhook location but without the user deploying their webhook endpoint, calls do not fail and there is no indication that their implementation is not present.

Address outstanding accessibility issues

Check accessibility using the Edge tooling

Landing Page URL configuration should match deployment location

When deploying the container in a location other than the local desktop (e.g. into an Azure container), the default landing page URL of localhost:80 results in the 'Post to landing page' button hitting a 404 as the emulator is running elsewhere.

The documentation indicates that the defaults should redirect to the mock landing page included with the emulator.

Update README - what are we solving for etc

Add

• Design Goals
• What problem(s) are we solving for

Update landing page text to mention SSO requirement

Purchase of per-seat offer allows zero or negative seat count

The textbox for the quantity of seats on the index/purchase page should only allow 1 or more to be entered

Document the workflow for pushing to container registries

Implement Metered Billing API

Update README for new environment variables

PUBLISHER_ID
PUBLISHER_TENANT_ID
PUBLISHER_APP_ID

SaaS Accelerator | MONA Documentation

Add documentation for SaaS Accelerator and MONA to work with the emulator - in Azure

Multiple npm version conflicts with node image in docker file

Multiple packages in the emulator are no longer compatible with the node version included in the image in the docker file. Attempting to build the image fails.

Error hosting emulator container image in App Service

Testing the different Azure hosting options for the emulator:

Azure Container Instances: works (no TLS, limiting testing options)
Azure Container Apps: Works
Azure App Service: Fails

App Service fails to load a container image of the emulator. The following error is in the deployment centre logs:

Message: failed to register layer: Error processing tar file(exit status 1): Container ID 1516583083 cannot be mapped to a host ID

Internet searching indicates that this could be an issue with a security layer in the hosting environment and the ID number being too large (https://circleci.com/docs/high-uid-error/). This might be unique to my environment but recreating a new container image and new App Service didn't resolve this and @scottperham recommended logging for testing.

Repro steps with ACR:
docker build -t marketplaceapiemulator -f docker/Dockerfile .
docker tag marketplaceapiemulator .azurecr.io/marketplaceapiemulator:v1
docker push .azurecr.io/marketplaceapiemulator:v1
Enable Admin User in ACR to light-up deployment options
Select App Service as a deployment option for the container
Review the logs in the App Service deployment centre for errors
Error on browsing to public endpoint

Offers - Plan Selection

Within Subscriptions (and possibly token creation) have give the option to select a plan, depending on the active Offer type, when changing plan details.
Remove hard coded Plan prompts on plan change.
Link to available plans API.

Implement UI for creating custom plans / offers