Управление доступом к продукту из службы

Если у вас есть каталог приложений и надстроек, вы можете использовать API коллекции Microsoft Store и API покупки Microsoft Store, чтобы из ваших служб получить информацию о лицензиях на эти продукты. Право представляет собой право клиента на использование приложения или дополнения, опубликованного в Microsoft Store.

Эти API состоят из методов REST, предназначенных для использования разработчиками с каталогами надстроек, поддерживаемыми кроссплатформенными службами. Эти API позволяют выполнять следующие действия.

• API коллекции Microsoft Store: запрос продуктов, принадлежащих пользователю, и сообщить о выполнении потребляемого продукта.
• API покупки в Microsoft Store: предоставить пользователю бесплатный продукт, получить подписки для пользователяи изменить состояние выставления счетов для пользователя.

Заметка

API коллекции Microsoft Store и API покупок используют аутентификацию платформы удостоверений Майкрософт (Entra ID) для доступа к информации о владении клиентов. Чтобы использовать эти API, у вас (или вашей организации) должен быть клиент Entra ID, и у вас должно быть разрешение глобального администратора для клиента. Если вы уже используете Microsoft 365 или другие бизнес-службы компании Microsoft, у вас уже есть арендатор Entra ID.

Библиотека Microsoft.StoreServices

Чтобы упростить поток проверки подлинности и вызвать службы Microsoft Store, просмотрите проект Microsoft.StoreServices и пример на Github. Библиотека Microsoft.StoreServices поможет управлять ключами проверки подлинности и предоставляет API-оболочку для вызова служб Microsoft Store для управления продуктами. Пример проекта показывает, как служба может использовать библиотеку Microsoft.StoreServices, пример логики управления потребляемыми продуктами, согласование возвращенных покупок, продление учетных данных с истекшим сроком действия и многое другое. Пошаговое руководство по настройке включается в пример для настройки примера службы на компьютере или через Azure.

• библиотека Microsoft.StoreServices (GitHub)
• пример Microsoft.StoreServices (GitHub)

Обзор

Ниже описан комплексный процесс использования API коллекции Microsoft Store и API покупки:

1. Настройка приложения в Entra ID.
2. Свяжите идентификатор приложения Entra ID с приложением в Центре партнеров.
3. В вашей службе создаются токены доступа Entra ID, представляющие идентификацию издателя.
4. В вашем клиентском приложении Windows создайте ключ идентификатора Microsoft Store, представляющий удостоверение текущего пользователя, и передайте этот ключ обратно в службу.

Этот комплексный процесс включает два компонента программного обеспечения, выполняющие различные задачи:

• вашей службы. Это приложение, которое выполняется безопасно в контексте бизнес-среды, и его можно реализовать с помощью любой выбранной платформы разработки. Служба отвечает за создание токенов доступа Entra ID, необходимых для сценария, а также за вызовы REST URI для API коллекции Microsoft Store и API покупки.
• Ваше клиентское приложение для Windows. Это приложение, для которого требуется получить доступ к сведениям о правах клиента и управлять ими (включая надстройки для приложения). Это приложение отвечает за создание ключей идентификатора Microsoft Store, которые необходимы для вызова API коллекции Microsoft Store и API покупки из вашей службы.

Шаг 1. Настройка приложения в идентификаторе Entra

Прежде чем использовать API коллекции Microsoft Store или API покупки, необходимо создать веб-приложение Entra ID, получить идентификатор клиента и идентификатор приложения для приложения и создать ключ. Веб-приложение Entra ID представляет службу, из которой требуется вызвать API коллекции Microsoft Store или API покупки. Вам нужны идентификатор арендатора, идентификатор приложения и ключ, чтобы создать токены доступа Entra ID, необходимые для доступа к API.

1. Если это еще не сделано, следуйте инструкциям в кратком руководстве : Регистрация приложения с помощью платформы идентификации Майкрософт, чтобы зарегистрировать приложение веб-приложение или API с помощью Entra ID.

   Заметка

   При регистрации приложения необходимо выбрать веб-приложение или API в качестве типа приложения, чтобы получить ключ (также называемый секрет клиента) для приложения. Чтобы вызвать API коллекции Microsoft Store или API покупки, необходимо предоставить секрет клиента при запросе токена доступа из Entra ID на следующем этапе.

2. На портале управления Azureперейдите к идентификатору Microsoft Entra ID. Выберите арендатора, нажмите "Регистрация приложений" в левой области навигации в разделе "Управление", а затем выберите свое приложение.

3. Вы перейдете на главную страницу регистрации приложения. На этой странице скопируйте значение идентификатора приложения для последующего использования.

4. Создайте ключ, который потребуется позже (это все называется секретом клиента). В левой области щелкните Параметры, а затем Клавиши. На этой странице выполните действия, чтобы создать ключ. Скопируйте этот ключ для последующего использования.

Шаг 2. Связывание идентификатора приложения Entra ID с клиентским приложением в Центре партнеров

Прежде чем использовать API коллекции Microsoft Store или API покупки для настройки владения и покупок для приложения или надстройки, необходимо связать идентификатор приложения Entra с приложением (или приложением, содержащим надстройку) в Центре партнеров.

Заметка

Эту задачу нужно выполнить только один раз. После того как у вас будут идентификатор арендатора, идентификатор приложения и секрет клиента, вы можете повторно использовать эти значения в любое время, когда необходимо создать новый токен доступа Entra ID.

1. Войдите в Центр партнеров и выберите свое приложение.
2. Перейдите на страницу служб>коллекций продуктов и покупок и введите идентификатор приложения Entra в одно из доступных полей для идентификатора клиента .

Шаг 3: Создание токенов доступа Entra ID

Прежде чем получить ключ идентификатора Microsoft Store или вызвать API коллекции Microsoft Store или API покупки, ваша служба должна создать несколько различных маркеров доступа Entra ID, представляющих удостоверение издателя. Каждый токен будет использоваться совместно с разным API. Время существования каждого маркера составляет 60 минут, и их можно обновить после истечения срока действия.

Важный

Создавайте токены доступа Entra ID только в контексте вашей службы, а не в приложении. Секрет клиента может быть скомпрометирован, если он отправляется в ваше приложение.

Понимание различных токенов и URI для целевой аудитории

В зависимости от методов, которые необходимо вызвать в API коллекции Microsoft Store или API покупки, необходимо создать два или три разных токена. Каждый маркер доступа связан с другим универсальным кодом ресурса (URI) аудитории.

• Во всех случаях необходимо создать токен с URI аудитории https://onestore.microsoft.com. На следующем шаге вы передадите этот маркер в заголовок авторизации методов в API коллекции Microsoft Store или API покупки.

  Важный

  Используйте аудиторию https://onestore.microsoft.com только с маркерами доступа, надёжно хранящимися в вашей службе. Предоставление маркеров доступа этой аудитории за пределами службы может сделать службу уязвимой для воспроизведения атак.

• Если вы хотите вызвать метод в API коллекции Microsoft Store, чтобы запрашивать продукты, принадлежащие пользователю, или сообщить о потребляемом продукте как выполненном, необходимо также создать маркер с URI аудитории https://onestore.microsoft.com/b2b/keys/create/collections аудитории. На следующем шаге вы передадите этот маркер в клиентский метод в Windows SDK, чтобы запросить ключ идентификатора для Microsoft Store, который можно использовать с API коллекции Microsoft Store.

• Если вы хотите вызвать метод в API покупки Microsoft Store, чтобы предоставить пользователю бесплатный продукт, получить подписки для пользователяили изменить состояние выставления счетов подписки для пользователя, необходимо также создать токен доступа с URI аудитории https://onestore.microsoft.com/b2b/keys/create/purchase. На следующем шаге вы передадите этот маркер клиентскому методу в Windows SDK, чтобы запросить ключ идентификатора Microsoft Store, который можно использовать с API покупок Microsoft Store.

Создайте маркеры

Чтобы создать маркеры доступа, используйте API OAuth 2.0 в службе, следуя инструкциям, приведенным в статье Service to Service Calls Using Client Credentials для отправки HTTP POST в конечную точку https://login.microsoftonline.com/<tenant_id>/oauth2/token. Ниже приведен пример запроса.

POST https://login.microsoftonline.com/<tenant_id>/oauth2/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded; charset=utf-8

grant_type=client_credentials
&client_id=<your_client_id>
&client_secret=<your_client_secret>
&resource=https://onestore.microsoft.com

Для каждого маркера укажите следующие данные параметров:

• Для параметров client_id и client_secret укажите идентификатор приложения и секрет клиента для приложения, полученный на портале управления Azure. Оба этих параметра необходимы для создания токена доступа с уровнем аутентификации, требуемым API коллекции Microsoft Store или API покупок.

• Для параметра ресурса укажите один из URI аудитории, перечисленных в предыдущем разделе , в зависимости от типа создаваемого токена доступа.

После истечения срока действия токена доступа его можно обновить, следуя приведённым здесьинструкциям. Дополнительную информацию о структуре токена доступа см. в разделе Поддерживаемые типы токенов и утверждений.

Шаг 4. Создание ключа идентификатора Microsoft Store

Прежде чем вызывать любой метод в API коллекции Microsoft Store или API покупки, приложение должно создать ключ идентификатора Microsoft Store и отправить его в службу. Этот ключ — это веб-токен JSON (JWT), определяющий личность пользователя, информацию о владении продуктом которого вы хотите получить. Дополнительные сведения об утверждениях в этом ключе см. в разделе заявления в ключе идентификатора Microsoft Store.

В настоящее время единственным способом создания ключа идентификатора Microsoft Store является вызов API универсальной платформы Windows (UWP) из клиентского кода в приложении. Созданный ключ представляет удостоверение пользователя, вошедшего в Microsoft Store на устройстве.

Заметка

Каждый ключ идентификатора Microsoft Store действителен в течение 30 дней. До истечения срока действия ключа можно продлить ключ. Рекомендуется обновить ключи идентификатора Microsoft Store, а не создавать новые.

Создание ключа идентификатора Microsoft Store для API коллекции Microsoft Store

Выполните следующие действия, чтобы создать ключ идентификатора Microsoft Store, который можно использовать с API коллекции Microsoft Store для запроса продуктов, принадлежащих пользователю, или сообщить о выполнении потребляемого продукта.

1. Передайте токен доступа Entra ID, который содержит значение URI аудитории https://onestore.microsoft.com/b2b/keys/create/collections, от вашего сервиса вашему клиентскому приложению. Это один из токенов, созданных ранее на третьем шаге.

2. В коде приложения вызовите один из следующих методов, чтобы получить ключ идентификатора Microsoft Store:

• Если приложение использует класс StoreContext в пространстве имен Windows.Services.Store для управления покупками в приложении, используйте метод StoreContext.GetCustomerCollectionsIdAsync.

• Если приложение использует класс CurrentApp в пространстве имен Windows.ApplicationModel.Store для управления покупками в приложении, используйте метод CurrentApp.GetCustomerCollectionsIdAsync.

  Передайте маркер доступа вашего идентификатора Entra в параметр serviceTicket метода. Если вы поддерживаете идентификаторы анонимных пользователей в контексте управляемых вами служб как издателя текущего приложения, вы также можете передать идентификатор пользователя в параметр publisherUserId, чтобы связать текущего пользователя с новым ключом идентификатора Microsoft Store (идентификатор пользователя будет встроен в ключ). В противном случае, если вам не нужно связать идентификатор пользователя с ключом идентификатора Microsoft Store, можно передать любое строковое значение в параметр publisherUserId.

3. После успешного создания ключа идентификатора Microsoft Store передайте ключ обратно в службу.

Создание ключа идентификатора Microsoft Store для API покупки в Microsoft Store

Выполните следующие действия, чтобы создать ключ идентификатора Microsoft Store, который можно использовать с API покупки Microsoft Store, чтобы предоставить пользователю бесплатный продукт, получить подписки для пользователяили изменить состояние выставления счетов подписки для пользователя.

1. Передайте маркер доступа Entra ID, который имеет URI аудитории со значением https://onestore.microsoft.com/b2b/keys/create/purchase, из вашей службы в клиентское приложение. Это один из токенов, которые вы создали ранее на шаге 3.

2. В коде приложения вызовите один из следующих методов, чтобы получить ключ идентификатора Microsoft Store:

• Если приложение использует класс StoreContext в пространстве имен Windows.Services.Store для управления покупками в приложении, используйте метод StoreContext.GetCustomerPurchaseIdAsync.

• Если приложение использует класс CurrentApp в пространстве имен Windows.ApplicationModel.Store для управления покупками в приложении, используйте метод CurrentApp.GetCustomerPurchaseIdAsync.

  Передайте токен доступа Entra ID в параметр serviceTicket метода. Если вы сохраняете идентификаторы анонимных пользователей в рамках служб, которые вы управляете как издатель текущего приложения, вы также можете передать идентификатор пользователя в параметр publisherUserId, чтобы связать текущего пользователя с новым ключом идентификатора Microsoft Store (идентификатор пользователя будет внедрен в ключ). В противном случае, если вам не нужно связать идентификатор пользователя с ключом идентификатора Microsoft Store, можно передать любое строковое значение в параметр publisherUserId.

3. После успешного создания ключа идентификатора Microsoft Store передайте ключ обратно в службу.

Диаграмма

На следующей схеме показан процесс создания ключа идентификатора Microsoft Store.

Утверждения в ключе идентификатора Microsoft Store

Ключ идентификатора Microsoft Store — это веб-токен JSON (JWT), представляющий удостоверение пользователя, чью информацию о владении продуктами вы хотите получить. При декодировании с помощью Base64 ключ идентификатора Microsoft Store содержит следующие утверждения.

• iat. Определяет время выдачи ключа. Это утверждение можно использовать для определения возраста маркера. Это значение выражается как эпохальное время.
• iss: определяет издателя. Это имеет ту же ценность, что и утверждение aud.
• aud: определяет аудиторию. Должно быть одним из следующих значений: https://collections.mp.microsoft.com/v6.0/keys или https://purchase.mp.microsoft.com/v6.0/keys.
• exp. Определяет время истечения срока действия, начиная с которого ключ больше не будет приниматься для выполнения операций, за исключением возобновления ключей. Значение этого утверждения выражается как эпохальное время.
• nbf. Определяет время, в течение которого маркер будет принят для обработки. Значение этого утверждения выражается как эпохальное время.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId: идентификатор клиента, определяющий разработчика.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload: закрытые полезные данные (зашифрованные и закодированные в Base64), содержащие сведения, предназначенные исключительно для использования службами Microsoft Store.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId: идентификатор пользователя, определяющий текущего пользователя в контексте служб. Это то же значение, которое вы передаете в необязательный параметр publisherUserId метода , используемого для создания ключа.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri: универсальный код ресурса (URI), который можно использовать для продления ключа.

Ниже приведен пример декодированного заголовка ключа идентификатора Microsoft Store.

{
    "typ":"JWT",
    "alg":"RS256",
    "x5t":"agA_pgJ7Twx_Ex2_rEeQ2o5fZ5g"
}

Ниже приведен пример декодированного набора утверждений ключа идентификатора Microsoft Store.

{
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId": "1d5773695a3b44928227393bfef1e13d",
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload": "ZdcOq0/N2rjytCRzCHSqnfczv3f0343wfSydx7hghfu0snWzMqyoAGy5DSJ5rMSsKoQFAccs1iNlwlGrX+/eIwh/VlUhLrncyP8c18mNAzAGK+lTAd2oiMQWRRAZxPwGrJrwiq2fTq5NOVDnQS9Za6/GdRjeiQrv6c0x+WNKxSQ7LV/uH1x+IEhYVtDu53GiXIwekltwaV6EkQGphYy7tbNsW2GqxgcoLLMUVOsQjI+FYBA3MdQpalV/aFN4UrJDkMWJBnmz3vrxBNGEApLWTS4Bd3cMswXsV9m+VhOEfnv+6PrL2jq8OZFoF3FUUpY8Fet2DfFr6xjZs3CBS1095J2yyNFWKBZxAXXNjn+zkvqqiVRjjkjNajhuaNKJk4MGHfk2rZiMy/aosyaEpCyncdisHVSx/S4JwIuxTnfnlY24vS0OXy7mFiZjjB8qL03cLsBXM4utCyXSIggb90GAx0+EFlVoJD7+ZKlm1M90xO/QSMDlrzFyuqcXXDBOnt7rPynPTrOZLVF+ODI5HhWEqArkVnc5MYnrZD06YEwClmTDkHQcxCvU+XUEvTbEk69qR2sfnuXV4cJRRWseUTfYoGyuxkQ2eWAAI1BXGxYECIaAnWF0W6ThweL5ZZDdadW9Ug5U3fZd4WxiDlB/EZ3aTy8kYXTW4Uo0adTkCmdLibw=",
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId": "infusQMLaYCrgtC0d/SZWoPB4FqLEwHXgZFuMJ6TuTY=",
    "http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri": "https://collections.mp.microsoft.com/v6.0/b2b/keys/renew",
    "iat": 1733526889,
    "iss": "https://collections.mp.microsoft.com/v6.0/keys",
    "aud": "https://collections.mp.microsoft.com/v6.0/keys",
    "exp": 1733523289,
    "nbf": 1736118889
}

Связанные разделы

• запрос для продуктов
• Отчет о выполнении потребляемых продуктов
• Предоставление бесплатных продуктов
• Получение подписок для пользователя
• Изменение платежного состояния подписки для пользователя
• Продление ключа идентификатора Microsoft Store
• Интеграция приложений с платформой удостоверений Microsoft
• маркеры идентификаторов в платформе удостоверений Microsoft
• Библиотека Microsoft.StoreServices (GitHub)