Поделиться через

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

  • Статья

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

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

Примечание.

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

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

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

Обзор

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

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

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

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

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

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

  1. Если это еще не сделано, следуйте инструкциям в статье "Интеграция приложений с Azure Active Directory ", чтобы зарегистрировать веб-приложение или приложение API в Azure AD.

    Примечание.

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

  2. На портале управления Azure перейдите к Azure Active Directory. Выберите каталог, щелкните Регистрация приложений в области навигации слева и выберите приложение.

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

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

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

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

Примечание.

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

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

Шаг 3. Создание маркеров доступа Azure AD

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

Внимание

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

Общие сведения о различных маркерах и URI аудитории

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

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

    Внимание

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

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

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

Создание маркеров

Чтобы создать маркеры доступа, используйте API OAuth 2.0 в службе, следуя инструкциям в разделе "Вызовы службы для вызовов службы", используя учетные данные клиента для отправки 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 действителен в течение 90 дней. После истечения срока действия ключа можно продлить ключ. Рекомендуется обновить ключи идентификатора Microsoft Store, а не создавать новые.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Схема

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

Создание ключа идентификатора Магазина Windows

Утверждения в ключе идентификатора 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": 1442395542,
    "iss": "https://collections.mp.microsoft.com/v6.0/keys",
    "aud": "https://collections.mp.microsoft.com/v6.0/keys",
    "exp": 1450171541,
    "nbf": 1442391941
}