Skip to content

Latest commit

 

History

History
220 lines (175 loc) · 16.5 KB

Installation-Instructions.md

File metadata and controls

220 lines (175 loc) · 16.5 KB
Raw

Installation instructions

Overview

This document describes how to implement the required components to enable the SDK for the SaaS Fulfillment API (v2), Marketplace Metering Service API, and additional components that demonstrate how to build a customer provisioning interface, logging, and administration of the customer's subscriptions.

Learn more about what's included and how to-use the SDK here.

Please note: this SDK is community-supported. If you need help or have questions using this SDK, please create a GitHub issue. Do not contact the marketplace pubisher support alias directly regarding use of this SDK. Thank you.

Deploy web applications and SQL Azure database using an ARM template

  • Log on to Azure
  • Search for Custom Template and select the option - Deploy a custom template Custom template
  • Click the link Build your own template in the editor Build your own template
  • Copy the content from the ARM template - deploy.json and paste the text in the text area after clearing the existing content
  • Click Save
  • The template is validated and you are navigated to a page that presents a form for you to fill in the parameters used to deploy the resources Deployment parameters

Note:

  • You can leave the Path to Web Application Packages as is to use the build packages from this repository
  • Make sure that you download the bacpac file from here and upload it to an Azure blob storage. Use the URL to the file in the storage as the link to Github is not currently supported.
  • Click Purchase to initiate the deployment of resources

Note

  • The template uses the Web App Name Prefix to create two web applications. For example, if the value provided for this field is contoso, the deployment creates the customer portal - https://contoso-portal.azurewebsites.net and the publisher portal - https://contoso-admin.azurewebsites.net.
  • Important For the login to the portals to work, it is important that you configure the Redirect URIs in the AD application to use these web applications. Here are the redirect Uris that should be in place:

Deploy web applications and SQL Azure database using Powershell

  1. Install Powershell 7.0.2
  2. Clone the repository
  3. Start a Windows PowerShell window as administrator and run the following commands to install Azure modules:

Note: Make sure that you are using the latest Powershell to avoid issues in Compress-Archive in 5.1 that got resolved in latest version.

Install-Module -Name Az -AllowClobber
  1. Navigate to the folder .\deployment\Templates
  2. Set the priorities running Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass. Choose "A", to change the policy to Yes to All. If you get a permission error, you can try:
    • Run the PowerShell terminal as an Administrator
    • Set the priorities running Set-ExecutionPolicy -ExecutionPolicy unrestricted.
  3. Run the command .\Deploy.ps1 with the following paramters
Parameter Description
WebAppNamePrefix Prefix used for creating web applications. Example: contoso
TenantID The value should match the value provided for Active Directory TenantID in the Technical Configuration of the Transactable Offer in Partner Center
ADApplicationID The value should match the value provided for Active Directory Application ID in the Technical Configuration of the Transactable Offer in Partner Center
ADApplicationSecret Secret key of the AD Application
SQLServerName Name of the database server (without database.windows.net)
SQLAdminLogin SQL Admin login
SQLAdminLoginPassword SQL Admin password
PublisherAdminUsers Provide a list of email addresses (as comma-separated-values) that should be granted access to the Publisher Portal
PathToWebApplicationPackages The base URI where artifacts required by the template are located. Ex: https://raw.githubusercontent.com/Azure/Microsoft-commercial-marketplace-transactable-SaaS-offer-SDK/master/deployment/
BacpacUrl The url to the SaaS DB bacpac Ex: https://raw.githubusercontent.com/Azure/Microsoft-commercial-marketplace-transactable-SaaS-offer-SDK/master/deployment/Database/AMPSaaSDB.bacpac
ResourceGroupForDeployment Name of the resource group to deploy the resources
Location Location of the resource group
AzureSubscriptionID Subscription where the resources be deployed
PathToARMTemplate Local Path to the ARM Template

Example

.\Deploy.ps1 
            -WebAppNamePrefix "contoso" 
            -TenantID "tenandId" 
            -ADApplicationID "clientId" 
            -ADApplicationSecret "secret" 
            -SQLServerName "contososqlsrv" 
            -SQLAdminLogin "adminlogin" 
            -SQLAdminLoginPassword "password" 
            -PublisherAdminUsers "user@contoso.com"              
            -BacpacUrl "https://raw.githubusercontent.com/Azure/Microsoft-commercial-marketplace-transactable-SaaS-offer-SDK/master/deployment/Database/AMPSaaSDB.bacpac" 
            -AzureSubscriptionID "subscriptionId" 
            -ResourceGroupForDeployment "resourcegroup" 
            -Location "East US" 
            -PathToARMTemplate ".\deploy.json"

Clone the repository, create an Azure SQL Database single database and prepare

Create a single database following the instructions on the SQL Database service [quickstart] (https://docs.microsoft.com/en-us/azure/sql-database/sql-database-single-database-get-started?tabs=azure-portal) document.

  • Run the script AMP-DB-2.1.sql to initialize the database using your favorite SQL management tool, such as SQL Server Management Studio, or Azure Data Studio. The scripts are in deployment/database folder.

  • Add the email for the Azure Active Directory user you are planning to log in to the solution to KnownUsers table on the database, with value "1" for the RoleId column. For example, if the user is expected to login with user@contoso.com run the following script in your favorite management tool.

      INSERT INTO KnownUsers (UserEmail, RoleId) VALUES ('user@contoso.com', 1)

Change configuration

Open the files appsettings.json under the project SaaS.SDK.CustomerProvisioning and SaaS.SDK.PublisherSolution update the values as follows:

  • GrantType - Leave this as client_credentials
  • ClientId - Azure Active Directory Application ID (the value for marketplace offer in Partner Center, under technical configuration tab). Steps to register an Azure AD application are here
  • ClientSecret - Secret from the Azure Active Directory Application
  • Resource - Set this to 20e940b3-4c77-4b0b-9a53-9e16a1b010a7 this value is important, it is the resource ID for the fulfillment API
  • FulFillmentAPIBaseURL - https://marketplaceapi.microsoft.com/api
  • SignedOutRedirectUri - Set the path to the page the user should be redirected to after signing out from the application
  • TenantId - Provide the tenant ID detail that was submitted in the. Technical configuration section of your marketplace offer in Partner Center.
  • FulfillmentApiVersion - Use 2018-08-31 for the production version of the fulfillment APIs
  • AdAuthenticationEndpoint - https://login.microsoftonline.com
  • SaaSAppUrl - URL to the SaaS solution
  • DefaultConnection - Set the connection string to connect to the database.

After making all of the above changes, the appSettings.json would look like sample below.

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "SaaSApiConfiguration": {
    "GrantType": "client_credentials",
    "ClientId": "<Azure AD application ID>",
    "ClientSecret": "<client secret>",
    "Resource": "20e940b3-4c77-4b0b-9a53-9e16a1b010a7",
    "FulFillmentAPIBaseURL": "https://marketplaceapi.microsoft.com/api",
    "SignedOutRedirectUri": "<provisioning_or_publisher_web_app_base_path>/Home/Index",
    "TenantId": "<TenantID of AD application>",
    "FulFillmentAPIVersion": "2018-08-31",
    "AdAuthenticationEndPoint": "https://login.microsoftonline.com",
    "SaaSAppUrl" : "<Link-to-SaaS-application>"
  },
  "connectionStrings" : {
    "DefaultConnection": "Data source=<server>;initial catalog=<database>;user id=<username>;password=<password>"
    },
  "AllowedHosts": "*"
}

(Optional but recommended) Setting and Loading above configuration values from KeyVault

Create Web Apps on Azure and deploy the code

The sample has two web apps to demonstrate the activation of a subscription for a SaaS offer, and potential scenarios for managing subscriptions and users.

There are many ways to create Web App resources on App Service and deploy the code,

You can use any of the methods above to create the web apps and deploy the code, but for the rest of this document, let's assume the use of Visual Studio method to deploy the following two apps. Give appropriate names to indicate the applications' roles, for example, <yourname>provisioning, and <yourname>publisher. Please remember that these names will be the dns prefix for the host names of your applications and will eventually be available as yournameprovisioning.azurewebsites.net and yournamepublisher.azurewebsites.net.

  1. Customer provisioning sample web application, create and deploy the provisioning sample web application project in folder src/SaaS.SDK.CustomerProvisioning
  2. Publisher sample web application, create and deploy the provisioning sample web application project in folder src/SaaS.SDK.CustomerProvisioning

Deploying the debug release, and choosing "self-contained" deployment mode is useful for the initial deployments.

publisoptions

Important, Add the redirect uri on the Azure AD app registration after deploying the publisher solution following the steps here. The value should be https://<yourappname>.azurewebsites.net/Home/Index

Running the solution locally

Press F5 in Visual Studio 2019 to run the application locally.

Important, Add the redirect uri on the Azure AD app registration after deploying the publisher solution following the steps here. The value should be https://<yourappname>.azurewebsites.net/Home/Index

Important, the actual flow of subscribing to an offer on the Azure marketplace and managing the relevant lifetime events of the subscription, such as activation, cancellation and upgrade is only possible for the provisioning solution deployed to a location accessible on the internet.

Landing page and webhook settings for the SaaS offer on Partner Center

The landing page and the webhook endpoint are implemented in the SaaS.SDK.CustomerProvisioning application.

The landing page is the home page of the solution, for example, if you have deployed the solution to <yourappname>, the landing page value should be https://<yourappname>.azurewebsites.net.

Webhook endpoint is at https://<yourappname>.azurewebsites.net/AzureWebhook

The Technical Configuration section of the Marketplace offer with the values filled using the web app names would look like as shown here.

Technical Configuration

Field Value
Landing page URL Path to the Provisioning Service. Eg: https://saaskit-portal.azurewebsites.net
Connection webhook Path to the web hook API in the Provisioning Service. Eg: https://saaskit-portal.azurewebsites.net/api/AzureWebhook
Azure Active Directory Tenant ID Tenant where the AD application is registered
Azure Active Directory Application ID ID of the registered AD application

Next steps

  • Customer portal - Sample web application: This document shows how to configure the web solution that enables the registration of a customer purchasing your SaaS Service and how a customer would manage their subscriptions and plans.
  • Publisher portal - Sample web application: This document shows how to configure the web solution that enables the activation of a customer purchasing your SaaS Service and how to send metered billing back to the Marketplace Metering Service API.