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

  • Статья

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

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

Примечание

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

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

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

Общие сведения

Ниже описан от начала до конца процесс использования API коллекции и API покупки Microsoft Store:

  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 покупок в Microsoft Store необходимо предоставить секрет клиента при запросе маркера доступа от Azure AD.

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

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

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

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

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

Примечание

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

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

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

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

Важно!

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

О различных маркерах и URI аудиторий

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

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

    Важно!

    Используйте аудиторию 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, чтобы предоставить бесплатный продукт пользователю, получить подписки для пользователя или изменить состояние выставления счета подписки для пользователя, необходимо также создать маркер с https://onestore.microsoft.com/b2b/keys/create/purchaseURI аудитории. На более позднем этапе вам предстоит передать этот маркер в клиентский метод в Windows SDK для запроса ключа идентификатора 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 покупки Microsoft Store.

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

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

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

Прежде чем вы сможете вызвать какой-либо метод в API коллекции или API покупки Microsoft Store, ваше приложение должно создать ключ идентификатора Microsoft Store и отправить его службе. Этот ключ — это маркер JSON Web Token (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, созданный с использованием значения URI https://onestore.microsoft.com/b2b/keys/create/collections, из своей службы в свое клиентское приложение. Это один из маркеров, которые вы создали ранее на Шаге 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, созданный с использованием значения 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.

    Передайте маркер доступа 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
}