Overview

This project shows how to build an Azure Marketplace Portal and webhook using a serverless setup. The scripting used to deploy the application assumes a bash shell. The application front end follows a minimalist design with a goal of making it easier for a web developer to customize the UI to meet their company styling needs. The only external JavaScript libaries in use are:

• jQuery: Used to do simple manipulation of the web page and send XmlHttpRequests.
• Azure App Insights: Used to track behavior on the deployed portal page.

This sample shows how to setup a SaaS Azure Marketplace Portal page using a custom domain. To follow along, it is assumed that you have a certificate which minimally supports two names:

1. yourdomain.com
2. www.yourdomain.com

Wildcard certificates, such as *.yourdomain.com, definitely work. You will need the certificate in the form of a .PFX.

Environment requirements

You will need some packages installed on your machine. The scripts and other pieces all assume a bash environment. Bash environments are available on Linux, Windows, and macOS.

Required software

The following packages must be installed in order to deploy your portal:

• Terraform: Deploys to Azure.
• Azure Command Line Interface: Used for interacting with Azure; some functionality is in the CLI but not in the portal.
• Azure Functions Core Tools: Allows for local development and debugging. Also used to upload to Azure.

Optional software

• pyenv: For the Python back-end example, this is a handy way to install a Python environment which is compatible for use with Azure Functions Core Tools. If you have other mechanisms, great!
• Visual Studio Code: While you can certainly use your tool of choice, VS Code has handy integrations for all things Azure. In our case, it integrates well with Azure Functions Core Tools and makes debugging easy.

Get the base solution running

Base login instructions

To login to Azure and select a default subscription, do the following from the command line:

1. Run az login
2. From the output, set the active subscription with az account set -s [subscription UUID]

Add the Azure CDN as a secureable application

The scripts will require that the Azure CDN is a selectable entity from your IAM configuration when you configure Key Vault a bit later. This is a one time operation on the subscription. To do this:

1. Login using these steps.
2. Run az ad sp create --id 205478c0-bd83-4e1b-a9d6-db63a3e1e1c8

Configure the deployment service principal and setup variables.conf

The Terraform scripts and other login scripts use a service principal login instead of an interactive login. This was done to allow for a CI/CD pipeline to be built around this sample.

Please note that variables.conf should never be checked into source control. This file contains secrets which, if exposed to a github crawl, would open your resources to misuse by others. All the values stored in variables.conf may also be stored as environment variables in a build environment. If you choose to do this, make sure to remove references to variables.conf from /src/deployment/deploy.sh.

To create the service prinicipal and configure the solution, follow these steps.

1. Login using these steps.
2. Create the service principal: az ad sp create-for-rbac --role="Contributor" --scopes="/subscriptions/[SUBSCRIPTION_ID]". This generates output like:

{
  "appId": "<app UUID>",
  "displayName": "azure-cli-<YEAR-MONTH-DATE-HOUR-MINUTE-SECOND>",
  "name": "http://azure-cli-<YEAR-MONTH-DATE-HOUR-MINUTE-SECOND>",
  "password": "<password as a UUID>",
  "tenant": "<tenant UUID>"
}

Save this output for use in step 5.

3. Open the file /src/deployment/variables.conf.template.
4. Save the file /src/deployment/variables.conf.template as /src/deployment/variables.conf.
5. Decide what region to deploy to. To get a list of regions, use az account list-locations | jq '[.[] | {name: .name, displayName: .displayName}]'. You will use the name in the next step when filling in resource_group_location.
6. Set the values in variables.conf.template by copying values from the output of the service principal creation as follows (Note: we will fill in the storage_access_key [in a moment](#Setup-Terraform-shared state-management-for-deployments)):

service_principal_client_id=[name]
service_principal_client_secret=[password]
azure_ad_tenant_id=[tenant]
azure_subscription_id=[SUBSCRIPTION_ID]
resource_group_location=[region name]
base_name=[base name to be used for created resources, eg. contosoinc]
domain_name=[yourdomain.com (eg. the name of the domain associated with your certificate)]
storage_access_key=[access key for the Terraform state storage account]

6. Save /src/deployment/variables.conf.

Setup Terraform shared state management for deployments.

Because this is designed to run in a CI/CD pipeline, we want the Terraform state information to be persisted to a shared location. For this, we want to setup a connection to Azure Storage.

1. From the /src/deployment/terraform_state directory, run terraform init. This initializes your Terraform environment in this directory. You only need to do this step once.
2. Run /src/deployment/terraform_state/deploy.sh. Output from this command will look something like this:

Outputs:

properties = [STORAGE KEY]

2. Open /src/deployment/variables.conf. Remote state info doesn't "do" variables, so we'll be entering this in manually.
3. Set storage_access_key to [STORAGE KEY]
4. Save /src/deployment/variables.conf.

Add your domain to your Azure Active Directory Tenant

1. Open up the Azure portal and open your AAD tenant.
2. Select Custom domain names as shown below.

3. Select + Add custom domain.
4. Add the domain. This should match the domain you use in your certificate.
5. Go to your registrar and add the appropriate TXT record. Once done, click Verify.

You now have your custom domain registered.

Deploy the basic application

Now, we will deploy the application to Azure.

1. From the /src/deployment directory, run terraform init. This initializes your Terraform environment in this directory. You only need to do this step once. When done, the state file will be stored based on the setup from Setup Terraform shared state management for deployments.
2. From the /src/deployment directory, run deploy.sh. This will provision the marketplace portal.

Once complete, there are some manual steps we need to perform to setup the security, SSL, and custom domains for the application.

Configure Azure Active Directory (AAD) with the function app.

The function application offers a feature called EasyAuth. This is a simplified endpoint that handles a lot of the AAD complexities. We will set this up next. For this, you need to open the Functions Application named [base_name]func. Follow these steps to setup AAD authentication.

1. Select Platform features.
2. Under Networking, click on Authentication / Authorization.

3. Set App Service Authentication to On.
4. Set Action to take when request is not authenticated to Log in with Azure Active Directory.
5. Click on Azure Active Directory.
6. For Management mode, select Express. Note: we will return here in a bit. We are using the "easy" path to configure things correctly.
7. Leave the defaults as is and click on OK.

8. Add the following to Allowed External Redirect URLs:
   • Localhost testing: http://localhost:63342/azuremarketplace/src/portal/index.html
   • Public website: https://[your domain]/index.html

9. Click on Save.

10. Navigate to Azure Active Directory within the portal.

11. Select App Registrations.

12. Select your portal app, [base_name]func. We are going to update the following items, in this order:
    • Branding
    • Expose an API
    • Authentication

13. On Branding, set the various fields to appropriate values. This includes updating the Publisher Domain to https://[your domain].

14. On Expose an API, change the Application ID URI to https://[your tenant].onmicrosoft.com/[base_name]func.

15. On Authentication, for Supported account types, do the following:

    • Select Accounts in any organizational directory (Any Azure AD directory - Multitenant).
    • Click on Save.

16. Open the Functions Application named [base_name]func.

17. Select Platform features.

18. Under Networking, click on Authentication / Authorization.

19. Click on Azure Active Directory.

20. Set Management mode to Advanced.

21. Clear Issuer Url. This allows the application to use the common login, required for multi-tenant AAD authentication.

22. Click on OK, then Save.

Update the endpoint at the CDN

Here, we are going to update the CDN endpoint mapping our storage account containing our HTML, CSS, and JavaScript. Once you are done with this piece, it can take 10 minutes for the files to propagate to the CDN.

1. From the Azure portal, find the CDN named `[base_name]cdn.
2. From the endpoint list, select the endpoint named [base_name]funcep.
3. Under Settings, select Origin.
4. Set the Origin path to /web.
5. Click on Save.

6. Select Custom domains.
7. Click on + Custom domain.
8. Set the Custom hostname to [your domain]. You can also use a different value, like portal.[your domain] or azuremarketplace.[your domain].
   • To complete this, you will also need to add an CNAME record in your DNS to point to the endpoint hostname, [base_name]funcep.azureedge.net.
9. Click on Add when you are done. Once the custom hostname is ready, you will see something like this:

10. Click on the Custom domain you just added.
11. Set Certificate management type to CDN managed.
12. Press Save.