您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

为商业市场中的可交易 SaaS 产品/服务构建登陆页Build the landing page for your transactable SaaS offer in the commercial marketplace

本文指导你完成为 Microsoft 商业市场中销售的可交易 SaaS 应用构建登陆页的过程。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

可将登陆页视为软件即服务(SaaS) 产品/服务的“大厅”。You can think of the landing page as the "lobby" for your software as a service (SaaS) offer. 买家订阅某个产品/服务后,商业市场会将其定向到登陆页以激活并配置他们对 SaaS 应用程序的订阅。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. 使用 Azure Active Directory (Azure AD) 和 Microsoft Graph,你可为买家启用单一登录 (SSO),并获取有关买家的重要详细信息,这些信息可用来确认并激活他们的订阅,包括他们的姓名、电子邮件地址和组织。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.

因为激活订阅所需的信息是有限的,并且由 Azure AD 和 Microsoft Graph 提供,所以不需要请求超出基本同意范围以外的信息。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.

备注

激活后,买家在管理其订阅时也会定向到登陆页。The buyer will also be directed to the landing page when managing their subscription after activation. 激活买家的订阅后,必须使用 SSO 来让用户登录。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:

  1. 为登陆页创建 Azure AD 应用注册Create an Azure AD app registration for the landing page.
  2. 使用代码示例作为应用的起点Use a code sample as a starting point for your app.
  3. 使用两个 Azure AD 应用来提高生产安全性Use two Azure AD apps to improve security in production.
  4. 解析由商业市场添加到 URL 的市场购买标识令牌Resolve the marketplace purchase identification token added to the URL by the commercial marketplace.
  5. 从 ID 令牌中编码的声明中读取信息,该令牌是登录后从 Azure AD 接收的,随请求一起发送。Read information from claims encoded in the ID token, which was received from Azure AD after sign in, that was sent with the request.
  6. 根据需要使用 Microsoft Graph API 收集其他信息。Use the Microsoft Graph API to gather additional information, as required.

创建 Azure AD 应用注册Create an Azure AD app registration

商业市场与 Azure AD 完全集成。The commercial marketplace is fully integrated with Azure AD. 买家进入通过 Azure AD 帐户或 Microsoft 帐户 (MSA) 进行身份验证的市场。Buyers arrive at the marketplace authenticated with an Azure AD account or Microsoft account (MSA). 购买后,买家将从商业市场转到你的登陆页 URL,以激活和管理 SaaS 应用程序的订阅。After purchase, the buyer goes from the commercial marketplace to your landing page URL to activate and manage their subscription of your SaaS application. 必须让买家使用 Azure AD SSO 登录到你的应用程序。You must let the buyer sign in to your application with Azure AD SSO. (登陆页 URL 在产品/服务的技术配置页中指定。)(The landing page URL is specified in the offer's Technical configuration page.

使用标识的第一步是确保登陆页注册为 Azure AD 应用程序。The first step to using the identity is to make sure your landing page is registered as an Azure AD application. 注册应用程序后,可以使用 Azure AD 对用户进行身份验证并请求访问用户资源。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.

使用 Azure 门户注册新应用程序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.

如果你打算查询 Microsoft Graph API,请配置新应用程序以访问 Web APIIf you intend to query the Microsoft Graph API, configure your new application to access web APIs. 当你为此应用程序选择 API 权限时,默认值 User.Read 足以收集有关买家的基本信息,从而顺畅地自动完成加入过程。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. 请勿请求任何标有“需要管理员同意”的 API 权限,否则会阻止所有非管理员用户访问登陆页。Do not request any API permissions labeled needs admin consent, as this will block all non-administrator users from visiting your landing page.

如果在执行加入或预配的过程中需要提升的权限,请考虑使用 Azure AD 的增量同意功能,以便发送自市场的所有买家都能够与登陆页进行初始交互。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

我们提供了多个示例应用,可实现一个启用了 Azure AD 登录的简单网站。We've provided several sample apps that implement a simple website with Azure AD login enabled. 在 Azure AD 中注册应用程序之后,“快速入门”边栏选项卡将提供常用应用程序类型和开发堆栈的列表,如图 1 所示。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.

图 1:Azure 门户中的“快速入门”边栏选项卡Figure 1: Quickstart blade in the Azure portal

演示 Azure 门户中的“快速入门”边栏选项卡。

下载代码并设置开发环境后,在应用中更改配置设置,以反映你在前面的过程中记录的应用程序 ID、租户 ID 和客户端机密。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.

使用两个 Azure AD 应用来提高生产安全性Use two Azure AD apps to improve security in production

本文提供了用来为商业市场 SaaS 产品/服务实现登陆页的体系结构的简化版本。This article presents a simplified version of the architecture for implementing a landing page for your commercial marketplace SaaS offer. 在生产环境中运行该页时,我们建议提高安全性,具体做法是仅通过另一个受保护的应用程序来与 SaaS 履行 API 通信。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:

  • 第一个应用程序是前面所述的多租户登陆页应用程序,只不过其中不包括用来与 SaaS 履行 API 通信的功能。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.
  • 第二个应用程序是负责与 SaaS 履行 API 通信的应用程序。Second, an application to own the communications with the SaaS fulfillment APIs. 此应用程序应是仅供你的组织使用的单租户,可以建立一个访问控制列表,以便仅限从此应用对 API 进行访问。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. 例如,登陆页使用注册的第一个 Azure AD 应用将用户登录。For example, the landing page uses the first registered Azure AD app to sign in the user. 在用户登录后,登陆页使用第二个 Azure AD 来请求访问令牌,以调用 SaaS 履行 API 并调用解析操作。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

将买家定向到登陆页后,会在 URL 参数中添加一个令牌。When the buyer is sent to your landing page, a token is added to the URL parameter. 此令牌不同于 Azure AD 颁发的令牌以及用于服务间身份验证的访问令牌,它用作输入,供 SaaS 履行 API 解析调用以获取订阅的详细信息。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. 与对 SaaS 履行 API 发出的所有调用一样,服务到服务的请求将通过一个访问令牌进行身份验证,该访问令牌基于应用的用于服务间身份验证的 Azure AD 应用程序 ID 用户。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.

备注

大多数情况下,最好从第二个单租户应用程序发出此调用。In most cases, it's preferable to make this call from a second, single-tenant application. 请参阅本文前面所述的使用两个 Azure AD 应用提高生产安全性See Use two Azure AD apps to improve security in production earlier in this article.

请求访问令牌Request an access token

若要使用 SaaS 履行 API 对应用程序进行身份验证,需要一个可以通过调用 Azure AD OAuth 终结点生成的访问令牌。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

SaaS 履行 API 实现解析终结点,可以调用该终结点来确认市场令牌的有效性并返回有关订阅的信息。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.

从 ID 令牌中编码的声明读取信息Read information from claims encoded in the ID token

作为 OpenID Connect 流的一部分,在将买家定向到登陆页时,Azure AD 会在请求中添加一个 ID 令牌As part of the OpenID Connect flow, 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
audaud 此令牌的目标受众。Intended audience for this token. 在本例中,它应与应用程序 ID 匹配并经过验证。In this case, it should match your Application ID and be validated.
preferred_usernamepreferred_username 进行访问的用户的主用户名。Primary username of the visiting user. 可以是电子邮件地址、电话号码或其他标识符。This could be an email address, phone number, or other identifier.
电子邮件email 用户的电子邮件地址。User's email address. 请注意,此字段可为空。Note that this field may be empty.
namename 用户可读值,用于标识令牌使用者。Human-readable value that identifies the subject of the token. 在本例中,它是买家的姓名。In this case, it will be the buyer's name.
oidoid Microsoft 标识系统中的标识符,用于在不同的应用程序中唯一标识用户。Identifier in the Microsoft identity system that uniquely identifies the user across applications. Microsoft Graph 将返回此值作为给定用户帐户的 ID 属性。Microsoft Graph will return this value as the ID property for a given user account.
tidtid 表示买家所属 Azure AD 租户的标识符。Identifier that represents the Azure AD tenant the buyer is from. 对于 MSA 标识,此值始终为 9188040d-6c67-4c5b-b112-36a304b66dadIn the case of an MSA identity, this will always be 9188040d-6c67-4c5b-b112-36a304b66dad. 有关详细信息,请参阅下一部分“使用 Microsoft Graph API”中的说明。For more information, see the note in the next section: Use the Microsoft Graph API.
subsub 唯一标识此特定应用程序中的用户的标识符。Identifier that uniquely identifies the user in this specific application.

使用 Microsoft Graph APIUse the Microsoft Graph API

ID 令牌包含用于标识买家的基本信息,但你的激活过程可能需要其他详细信息(例如买家的公司)才能完成加入过程。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. 使用 Microsoft Graph API 请求这些信息,以避免强制用户再次输入这些详细信息。Use the Microsoft Graph API to request this information to avoid forcing the user to input these details again. 默认情况下,标准的 User.Read 权限包含以下信息。The standard User.Read permissions include the following information, by default.

Value 说明Description
displayNamedisplayName 用户通讯簿中显示的名称。Name displayed in the address book for the user.
givenNamegivenName 用户的名字。First name of the user.
jobTitlejobTitle 用户的职务。User's job title.
mailmail 用户的 SMTP 地址。SMTP address for the user.
mobilePhonemobilePhone 用户的主要手机号码。Primary cellular telephone number for the user.
preferredLanguagepreferredLanguage 用户首选语言的 ISO 639-1 代码。ISO 639-1 code for the user's preferred language.
surnamesurname 用户的姓氏。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.

在 Azure AD 中注册的大多数应用都授予从其公司的 Azure AD 租户读取用户信息的委托权限。Most apps that are registered with Azure AD grant delegated permissions to read the user's information from their company's Azure AD tenant. 向 Microsoft Graph 发出针对该信息的任何请求都必须附带一个访问令牌用于身份验证。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.

备注

来自 MSA 租户(租户 ID 为 9188040d-6c67-4c5b-b112-36a304b66dad)的帐户返回的信息不会超过已使用 ID 令牌收集的信息。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. 因此你可以跳过对这些帐户进行的 Graph API 调用。So you can skip this call to the Graph API for these accounts.

后续步骤Next steps