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.
Important
Azure Active Directory (Azure AD) Graph is deprecated as of June 30, 2023. Going forward, we're making no further investments in Azure AD Graph. Azure AD Graph APIs have no SLA or maintenance commitment beyond security-related fixes. Investments in new features and functionalities will only be made in Microsoft Graph.
We'll retire Azure AD Graph in incremental steps so that you have sufficient time to migrate your applications to Microsoft Graph APIs. At a later date that we will announce, we will block the creation of any new applications using Azure AD Graph.
To learn more, see Important: Azure AD Graph Retirement and Powershell Module Deprecation.
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 Microsoft Entra ID 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 Microsoft Entra ID 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 a Microsoft Entra app registration for the landing page.
- Use a code sample as a starting point for your app.
- Use two Microsoft Entra 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 Microsoft Entra ID after sign in, that was sent with the request.
- Use the Microsoft Graph API to gather additional information, as required.
Create a Microsoft Entra app registration
The commercial marketplace is fully integrated with Microsoft Entra ID. Buyers arrive at the marketplace authenticated with an Microsoft Entra 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 Microsoft Entra 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 a Microsoft Entra application. Registering the application lets you use Microsoft Entra ID 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 Microsoft Entra ID 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 Microsoft Entra login enabled. After your application is registered in Microsoft Entra ID, 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 Microsoft Entra 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 Microsoft Entra app to sign in the user. After the user is signed-in, the landing page uses the second Microsoft Entra ID to request an access token to call the SaaS fulfillment APIs 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 Microsoft Entra ID-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 Microsoft Entra 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 Microsoft Entra 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 Microsoft Entra ID 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. Microsoft Entra ID 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 might 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 Microsoft Entra 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 might 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/region)—can be selected for inclusion in the request. See properties for the user resource type for more details.
Most apps that are registered with Microsoft Entra ID grant delegated permissions to read the user's information from their company's Microsoft Entra 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.
Related content
Video tutorials