Skip to content

Latest commit

 

History

History
238 lines (164 loc) · 12.3 KB

README.md

File metadata and controls

238 lines (164 loc) · 12.3 KB
Raw

Mona for SaaS

Version 2.0

Looking for Mona 1.0? It lives forever in perpetuity in the 1.0 branch.

The Azure Marketplace is an event-driven system. Customers purchase subscriptions to your SaaS app. They can change their subscriptions or purchase more seats. Some customers might cancel their subscriptions. These crucial events are the pulse of your SaaS app. Mona embraces this event-driven design by publishing all Marketplace-related events to a custom Event Grid topic deployed in your environment. From there, you can handle the events however you want. By default, Mona deploys a set of Logic Apps that enable you to control how your SaaS app responds to Marketplace events in a simple low/no-code environment.

Mona Architecture Overview

Quickstart

Clone this repo

Open an Azure Cloud Shell, choose the Bash experience, and clone this repo. Navigate to the setup folder.

git clone https://github.com/microsoft/mona-saas
cd mona-saas/Mona.SaaS/Mona.SaaS.Setup

Run the setup script

Run the basic-deploy.sh script to deploy Mona into your Azure environment. You'll need to provide only two parameters:

Name - Description
Region r The Azure region where Mona should be deployed. For a complete list of Azure regions to choose from, run az account list-locations -o table from the Bash Cloud Shell.
Name n A unique name for your Mona deployment. It must be 5-13 alphanumeric characters.

Example

./basic-deploy.sh -r "eastus" -n "monatest01"

Once the script is complete, you will be presented with a link to your Mona deployment's admin center. Click the link to finish setting up Mona. Be sure to bookmark the link so you can have quick and easy access to the Mona admin center later.

Both guests and members of your Entra (formerly Azure Active Directory) tenant have access to the Mona admin center.

Configure event integrations

Take a moment to familiarize yourself with the Mona admin center by clicking through the tabs.

Click on the This Mona deployment tab. This tab includes a deep link into the Azure portal and the resource group in which Mona was deployed. Click the resource group link. Within this resource group you will find seven different Logic Apps—each preconfigured to handle a specific Marketplace event. These Logic Apps are already connected to Mona's custom event grid topic. Configure these logic apps as your business needs dictate.

Why Azure Logic Apps?

Azure Logic Apps simplifies the way that you connect legacy, modern, and cutting-edge systems across cloud, on premises, and hybrid environments. You can use low-code-no-code tools to develop highly scalable integration solutions that support your enterprise and business-to-business (B2B) scenarios. The Azure Logic Apps integration platform provides more than 1,000 prebuilt connectors so that you can connect and integrate apps, data, services, and systems more easily and quickly.

You don't have to use Azure Logic Apps. Event Grid offers a wide range of built-in options for handling events.

Of course, once you've configured your integrations, you'll want to test them...

Test your event integrations

Mona makes it easy to test your Marketplace integrations before going live with your SaaS offer.

From the Mona admin center, click on the Integration testing tab. On this tab, you'll find two URLs:

  • Test landing page URL: Allows you test the complete end-to-end subscription purchasing experience.
  • Test webhook URL: Allows you to publish webhook notifications against test subscriptions previously created using the test landing page.

Using the test landing page

The test landing page implements the same flow as the live landing page that the Azure Marketplace will redirect your subscribers to. Any guest or member of your Entra tenant can use the test landing page. By default, the test landing page endpoint creates a fake test subscription complete with a full set of fake properties.

You can fully customize the test subscription that is created allowing you to test various subscription scenarios using the query string parameters listed below.

  • subscriptionId
  • subscriptionName
  • offerId
  • planId
  • isFreeTrial
  • seatQuantity
  • term_startDate
  • term_endDate
  • term_termUnit
  • beneficiary_aadObjectId
  • beneficiary_aadTenantId
  • beneficiary_userEmail
  • beneficiary_userId
  • purchaser_aadObjectId
  • purchaser_aadTenantId
  • purchaser_userEmail
  • purchaser_userId

For example, to customize the subscription name and offer ID, add query string parameters like this:

https://mona-admin-yourdeployment.azurewebsites.net/test?subscriptionName=MySubscription&offerId=OfferA

Properties not configured via query string parameters will automatically be assigned fake values.

See the Azure Marketplace docs for more information about these subscription properties.

Using the test webhook

Once you've created a test subscription, you can try issuing webhook notifications against it. While you don't have to authenticate against the test webhook endpoint, it will only work for subscriptions previously created via the test landing page. Use your favorite API client (e.g., Postman, cURL) to POST JSON webhook notifications to the test webhook endpoint. These test webhook notifications don't actually change the state of the test subscription; they are for integration testing purposes only.

Refer to the table below for more information on issuing webhook notifications.

Plan change

Occurs when a customer chooses a different plan for their subscription.

 
{
  "action": "ChangePlan", 
  "subscriptionId": "11111111-1111-1111-1111-111111111111",
  "planId": "Casey's Plan"
}

Seat quantity change

Occurs when the customer changes the number of purchased licenses (seats) for a subscription.

 
{
  "action": "ChangeQuantity", 
  "subscriptionId": "11111111-1111-1111-1111-111111111111",
  "quantity": 15
}

Suspension

Occurs when a customer's subscription payment instrument has become invalid and payment is not received on time.

 
{
  "action": "Suspend", 
  "subscriptionId": "11111111-1111-1111-1111-111111111111"
}

Cancellation

Occurs when a customer cancels their subscription.

 
{
  "action": "Unsubscribe", 
  "subscriptionId": "11111111-1111-1111-1111-111111111111"
}

Reinstatement

Occurs after a suspended subscription is reinstated. This notification indicates that the customer's payment instrument has become valid again, a payment has been made for the subscription, and the subscription is being reinstated.

 
{
  "action": "Reinstate", 
  "subscriptionId": "11111111-1111-1111-1111-111111111111"
}

Renewal

Occurs when a subscription is automatically renewed at the end of the subscription term of a month or a year.

 
{
  "action": "Renew", 
  "subscriptionId": "11111111-1111-1111-1111-111111111111"
}

Notify the Marketplace when a subscription has been activated

We are actively soliciting feedback to make this experience better. Please see this discussion for more information.

After a customer purchases a subscription, you have 30 days to activate it and notify the Marketplace. Billing starts when the subscription is activated.

Calls to the Marketplace API must be authenticated using Mona’s external managed identity.

To locate the managed identity:

  • Go to the Mona admin center.
  • Open the This Mona deployment tab.
  • Click Managed external identity.

This will direct you to the Azure portal, where you can manage the identity. You can use this identity in Logic Apps, Azure Functions, or other managed identity options. Use the managed identity to obtain a token for the Marketplace API and activate the subscription.

When requesting a token to call the Marketplace API, be sure to set scope to 20e940b3-4c77-4b0b-9a53-9e16a1b010a7.

Set up your SaaS offer in Partner Center

Important upgrade note: If you are upgrading from a previous version of Mona, your Partner Center technical configuration details will be different. Be sure to update your Partner Center technical configuration details after you upgrade.

Refer to these docs for more information on setting up your SaaS offer via the Partner Center.

During your SaaS offer setup, you'll be prompted to provide some "technical details" that are used to connect your SaaS offer to your Mona deployment. The Azure Marketplace uses these details to redirect new purchases to the Mona landing page and issue webhook notifications to the Mona webhook endpoint.

To find these settings:

  • Go to the Mona admin center.
  • Open the Marketplace offer technical details tab.

Copy and paste these settings into the Partner Center when setting up your SaaS offer.

Who supports Mona for SaaS?

Please see our support docs for more information.

Security

Please see our security docs for more information.

How can I contribute?

Please refer to these docs for more information.

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.