Build the landing page for your transactable SaaS offer in the commercial marketplace
This article guides you through the process of building a landing page for a transactable SaaS app that will be sold on the Microsoft commercial marketplace.
Overview
You can think of the landing page as the "lobby" for your software as a service (SaaS) offer. After the buyer subscribes to an offer, the commercial marketplace directs them to the landing page to activate and configure their subscription to your SaaS application. Think of this as an order confirmation step that lets the buyer see what they've purchased and confirm their account details. Using Azure Active Directory (Azure AD) and Microsoft Graph, you will enable single sign-on (SSO) for the buyer and get important details about the buyer that you can use to confirm and activate their subscription, including their name, email address, and organization.
Because the information needed to activate the subscription is limited and provided by Azure AD and Microsoft Graph, there should be no need to request information that requires more than basic consent. If you need user details that require additional consent for your application, you should request this information after subscription activation is complete. This enables frictionless subscription activation for the buyer and decreases the risk of abandonment.
The landing page typically includes the following:
- Present the name of the offer and plan purchased, as well as the billing terms.
- Present the buyer's account details, including first and last name, organization, and email.
- Prompt the buyer to confirm or substitute different account details.
- Guide the buyer on next steps after activation. For example, receive a welcome email, manage the subscription, get support, or read documentation.
Note
The buyer will also be directed to the landing page when managing their subscription after activation. After the buyer's subscription has been activated, you must use SSO to enable the user to sign in. It is recommended to direct the user to an account profile or configuration page.
The following sections will guide you through the process of building a landing page:
- Create an Azure AD app registration for the landing page.
- Use a code sample as a starting point for your app.
- Use two Azure AD apps to improve security in production.
- Resolve the marketplace purchase identification token added to the URL by the commercial marketplace.
- Read information from claims encoded in the ID token, which was received from Azure AD after sign in, that was sent with the request.
- Use the Microsoft Graph API to gather additional information, as required.
Create an Azure AD app registration
The commercial marketplace is fully integrated with Azure AD. Buyers arrive at the marketplace authenticated with an Azure AD account or Microsoft account (MSA). After purchase, the buyer goes from the commercial marketplace to your landing page URL to activate and manage their subscription of your SaaS application. You must let the buyer sign in to your application with Azure AD SSO. (The landing page URL is specified in the offer's Technical configuration page.)
Tip
Don't include the pound sign character (#) in the landing page URL. Otherwise, customers will not be able to access your landing page.
The first step to using the identity is to make sure your landing page is registered as an Azure AD application. Registering the application lets you use Azure AD to authenticate users and request access to user resources. It can be considered the application's definition, which lets the service know how to issue tokens to the app based on the app's settings.
Register a new application using the Azure portal
To get started, follow the instructions for registering a new application. To let users from other companies visit the app, you must choose one of the multitenant options when asked who can use the application.
If you intend to query the Microsoft Graph API, configure your new application to access web APIs. When you select the API permissions for this application, the default of User.Read is enough to gather basic information about the buyer to make the onboarding process smooth and automatic. Do not request any API permissions labeled needs admin consent, as this will block all non-administrator users from visiting your landing page.
If you require elevated permissions as part of your onboarding or provisioning process, consider using the incremental consent functionality of Azure AD so that all buyers sent from the marketplace are able to interact initially with the landing page.
Use a code sample as a starting point
We've provided several sample apps that implement a simple website with Azure AD login enabled. After your application is registered in Azure AD, the Quickstart blade offers a list of common application types and development stacks as seen in Figure 1. Choose the one that matches your environment and follow the instructions for download and setup.
Figure 1: Quickstart blade in the Azure portal
After you download the code and set up your development environment, change the configuration settings in the app to reflect the Application ID, tenant ID, and client secret you recorded in the previous procedure. Note that the exact steps will differ depending on which sample you are using.
Use two Azure AD apps to improve security in production
This article presents a simplified version of the architecture for implementing a landing page for your commercial marketplace SaaS offer. When running the page in production, we recommend that you improve security by communicating to the SaaS fulfillment APIs only through a different, secured application. This requires the creation of two new applications:
- First, the multitenant landing page application described up to this point, except without the functionality to contact the SaaS fulfillment APIs. This functionality will be offloaded to another application, as described below.
- Second, an application to own the communications with the SaaS fulfillment APIs. This application should be single tenant, only to be used by your organization, and an access control list can be established to limit access to the APIs from only this app.
This enables the solution to work in scenarios that observe the separation of concerns principle. For example, the landing page uses the first registered Azure AD app to sign in the user. After the user is signed-in, the landing page uses the second Azure AD to request an access token to call the SaaS fulfillment API's and call the resolve operation.
Resolve the marketplace purchase identification token
When the buyer is sent to your landing page, a token is added to the URL parameter. This token is different from both the Azure AD-issued token and the access token used for service-to-service authentication, and is used as an input for the SaaS fulfillment APIs resolve call to get the details of the subscription. As with all calls to the SaaS fulfillment APIs, your service-to-service request will be authenticated with an access token that is based on the app's Azure AD Application ID user for service-to-service authentication.
Note
In most cases, it's preferable to make this call from a second, single-tenant application. See Use two Azure AD apps to improve security in production earlier in this article.
Request an access token
To authenticate your application with the SaaS fulfillment APIs, you need an access token, which can be generated by calling the Azure AD OAuth endpoint. See How to get the publisher's authorization token.
Call the resolve endpoint
The SaaS fulfillment APIs implement the resolve endpoint that can be called to confirm the validity of the marketplace token and to return information about the subscription.
Read information from claims encoded in the ID token
As part of the OpenID Connect flow, put the tenant id value you receive in https://login.microsoftonline.com/{tenant}/v2.0. Azure AD adds an ID token to the request when the buyer is sent to the landing page. This token contains multiple pieces of basic information that could be useful in the activation process, including the information seen in this table.
| Value | Description |
|---|---|
| aud | Intended audience for this token. In this case, it should match your Application ID and be validated. |
| preferred_username | Primary username of the visiting user. This could be an email address, phone number, or other identifier. |
| User's email address. Note that this field may be empty. | |
| name | Human-readable value that identifies the subject of the token. In this case, it will be the buyer's name. |
| oid | Identifier in the Microsoft identity system that uniquely identifies the user across applications. Microsoft Graph will return this value as the ID property for a given user account. |
| tid | Identifier that represents the Azure AD tenant the buyer is from. In the case of an MSA identity, this will always be 9188040d-6c67-4c5b-b112-36a304b66dad. For more information, see the note in the next section: Use the Microsoft Graph API. |
| sub | Identifier that uniquely identifies the user in this specific application. |
Use the Microsoft Graph API
The ID token contains basic information to identify the buyer, but your activation process may require additional details—such as the buyer's company—to complete the onboarding process. Use the Microsoft Graph API to request this information to avoid forcing the user to input these details again. The standard User.Read permissions include the following information, by default.
| Value | Description |
|---|---|
| displayName | Name displayed in the address book for the user. |
| givenName | First name of the user. |
| jobTitle | User's job title. |
| SMTP address for the user. | |
| mobilePhone | Primary cellular telephone number for the user. |
| preferredLanguage | ISO 639-1 code for the user's preferred language. |
| surname | Last name of the user. |
Additional properties—such as the name of the user's company or the user's location (country)—can be selected for inclusion in the request. See properties for the user resource type for more details.
Most apps that are registered with Azure AD grant delegated permissions to read the user's information from their company's Azure AD tenant. Any request to Microsoft Graph for that information must be accompanied by an access token for authentication. Specific steps to generate the access token will depend on the technology stack you're using, but the sample code will contain an example. For more information, see Get access on behalf of a user.
Note
Accounts from the MSA tenant (with tenant ID 9188040d-6c67-4c5b-b112-36a304b66dad) will not return more information than has already been collected with the ID token. So you can skip this call to the Graph API for these accounts.
Next steps
Video tutorials