Gerenciar direitos a produtos de um serviço

  • Artigo

Se você tiver um catálogo de aplicativos e complementos, poderá usar a API de coleção da Microsoft Store e a API de compra da Microsoft Store para acessar informações de direitos para esses produtos de seus serviços. Um direito representa um direito do consumidor de usar um aplicativo ou complemento que está publicado na Microsoft Store.

Essas APIs consistem em métodos REST que são projetados para serem usados por desenvolvedores com catálogos de complementos que são suportados pelos serviços para várias plataformas. Essa API permite:

Observação

A API de coleção e a API de compra da Microsoft Store usam a autenticação do Azure Active Directory (Azure AD) para acessar informações de propriedade do cliente. Para usar essas APIs, você (ou sua organização) deve ter um diretório do Azure AD, e você deve ter permissão de Administrador global para o diretório. Se já usa o Microsoft 365 ou outros serviços comerciais da Microsoft, você já tem o diretório do Azure AD.

A biblioteca Microsoft.StoreServices

Para ajudar a simplificar o fluxo de autenticação e chamar os Serviços da Microsoft Store, examine o projeto Microsoft.StoreServices e o exemplo no Github. A biblioteca Microsoft.StoreServices ajudará a gerenciar as chaves de autenticação e fornece API de wrapper para chamar os Serviços da Microsoft Store para gerenciar produtos. O projeto de exemplo destaca como um serviço pode usar a biblioteca Microsoft.StoreServices, lógica de exemplo para gerenciar produtos consumíveis, reconciliar compras reembolsadas, renovar credenciais expiradas e muito mais. Um guia de configuração passo a passo é incluído com o exemplo para configurar o serviço de exemplo em seu computador ou por meio do Azure.

Visão geral

As etapas a seguir descrevem o processo de ponta a ponta para usar a API de coleção da Microsoft Store e a API de compra:

  1. Configure um aplicativo no Azure AD.
  2. Associe sua ID do aplicativo Azure AD ao seu aplicativo no Partner Center.
  3. Em seu serviço, crie tokens de acesso do Azure AD que representem sua identidade de fornecedor.
  4. No aplicativo cliente do Windows, crie uma chave de ID da Microsoft Store que represente a identidade do usuário atual e passe essa chave de volta para seu serviço.

Esse processo de ponta a ponta envolve dois componentes de software que executam tarefas diferentes:

  • Seu serviço. Esse é um aplicativo que é executado com segurança no contexto do seu ambiente de negócios e pode ser implementado usando qualquer plataforma de desenvolvimento que você escolher. Seu serviço é responsável por criar os tokens de acesso Azure AD necessários para o cenário e para chamar os URIs REST para a API de coleção da Microsoft Store e a API de compra.
  • Seu aplicativo cliente do Windows. Este é o aplicativo para o qual você deseja acessar e gerenciar informações de direitos do cliente (incluindo complementos para o aplicativo). Esse aplicativo é responsável por criar as chaves de ID da Microsoft Store necessárias para chamar a API de coleção da Microsoft Store e comprar a API do seu serviço.

Etapa 1: Configurar um aplicativo no Azure AD

Antes de usar a API de coleção da Microsoft Store ou a API de compra, você deve criar um aplicativo Web Azure AD, recuperar a ID do locatário e a ID do aplicativo para o aplicativo e gerar uma chave. O aplicativo Web Azure AD representa o serviço do qual você deseja chamar a API de coleção da Microsoft Store ou a API de compra. Você precisa da ID do locatário, da ID do aplicativo e da chave para gerar Azure AD tokens de acesso necessários para chamar a API.

  1. Se você ainda não fez isso, siga as instruções em Integrando aplicativos ao Azure Active Directory para registrar um aplicativo Web/aplicativo de API com Azure AD.

    Observação

    Ao registrar seu aplicativo, você deve escolher aplicativo Web/API como o tipo de aplicativo para que possa recuperar uma chave (também chamada de segredo do cliente) para seu aplicativo. Para chamar a API de coleção ou a API de compra da Microsoft Store, você deverá fornecer o segredo do cliente quando solicitar um token de acesso do Azure AD em uma etapa posterior.

  2. No Portal de Gerenciamento do Azure, navegue até Azure Active Directory. Selecione seu diretório, clique Registros de aplicativo no painel de navegação esquerdo e selecione seu aplicativo.

  3. Você será levado para a página de registro main do aplicativo. Nesta página, copie o valor da ID do Aplicativo para uso posterior.

  4. Crie uma chave que você precisará mais tarde (isso é chamado de segredo do cliente). No painel esquerdo, clique em Configurações e em Chaves. Nesta página, conclua as etapas para criar uma chave. Copie essa chave para uso posterior.

Etapa 2: Associar sua ID do aplicativo Azure AD ao aplicativo cliente no Partner Center

Antes de usar a API de coleção da Microsoft Store ou a API de compra para configurar a propriedade e as compras para seu aplicativo ou complemento, você deve associar sua ID do aplicativo Azure AD ao aplicativo (ou ao aplicativo que contém o complemento) no Partner Center.

Observação

Você só precisa executar essa tarefa uma vez. Depois de ter a ID do locatário, a ID do aplicativo e o segredo do cliente, você poderá reutilizar esses valores sempre que precisar criar um novo token de acesso Azure AD.

  1. Entre no Partner Center e selecione seu aplicativo.
  2. Acesse a páginaColeções e compras de Produtos de Serviços> e insira sua ID do aplicativo Azure AD em um dos campos de ID do Cliente disponíveis.

Etapa 3: criar tokens de acesso do Azure AD

Para poder recuperar uma chave de ID da Microsoft Store ou chamar a API de coleção ou API de compra da Microsoft Store, seu serviço deve criar diversos tokens de acesso do Azure AD diferentes que representem sua identidade de fornecedor. Cada token será usado com uma API diferente. A vida útil desses tokens é de 60 minutos, e você pode atualizá-los depois que expirarem.

Importante

Crie tokens de acesso do Azure AD somente no contexto de seu serviço, e não em seu aplicativo. O segredo do cliente pode ser comprometido se ele for enviado para seu aplicativo.

Noções básicas sobre os diferentes tokens e URIs de audiência

Dependendo dos métodos com os quais você deseja chamar a API de compra ou API de coleção da Microsoft Store, você deve criar dois ou três tokens diferentes. Cada token de acesso é associado a um URI de público-alvo diferente.

  • Em todos os casos, você deve criar um token com o https://onestore.microsoft.com URI de público. Em uma etapa posterior, você irá passar esse token para o cabeçalho Authorization dos métodos na API de compra ou API de coleção da Microsoft Store.

    Importante

    Use o https://onestore.microsoft.com público apenas com tokens de acesso que sejam armazenados com segurança dentro de seu serviço. Expor tokens de acesso com esse público fora de seu serviço poderia tornar seu serviço vulnerável a ataques de repetição.

  • Se você deseja chamar um método na API de coleção da Microsoft Store para consultar produtos pertencentes a um usuário ou declarar um produto consumível como providenciado, você também deve criar um token com o URI de audiência https://onestore.microsoft.com/b2b/keys/create/collections. Em uma etapa posterior, você passará esse token para um método de cliente no SDK do Windows para solicitar uma chave de ID da Microsoft Store que você pode usar com a API de coleção da Microsoft Store.

  • Se você deseja chamar um método na API de compras da Microsoft Store para conceder um produto gratuito a um usuário, obter assinaturas para um usuário ou alterar o estado de cobrança de uma assinatura para um usuário, também é necessário criar um token com o URI de audiência https://onestore.microsoft.com/b2b/keys/create/purchase. Em uma etapa posterior, você passará esse token para um método de cliente no SDK do Windows para solicitar uma chave de ID da Microsoft Store que você pode usar com a API de compra da Microsoft Store.

Criar os tokens

Para criar os tokens de acesso, use a API OAuth 2.0 em seu serviço, seguindo as instruções em Chamadas de serviço a serviço usando credenciais do cliente para enviar uma solicitação HTTP POST para o ponto de extremidade https://login.microsoftonline.com/<tenant_id>/oauth2/token. Aqui está um exemplo de solicitação.

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

Para cada token, especifique os seguintes dados de parâmetro:

  • Para os parâmetros client_id e client_secret , especifique a ID do aplicativo e o segredo do cliente para o aplicativo recuperado do Portal de Gerenciamento do Azure. Esses dois parâmetros são necessários para criar um token de acesso com o nível de autenticação exigido pela API de compra ou API de coleção da Microsoft Store.

  • Para o parâmetro de recurso, especifique um dos URIs de audiência listados na seção anterior, dependendo do tipo de token de acesso que você está criando.

Depois que seu token de acesso expirar, você poderá atualizá-lo seguindo as instruções descritas aqui. Para obter mais detalhes sobre a estrutura de um token de acesso, consulte Tipos de declaração e token com suporte.

Etapa 4: Criar uma chave de ID da Microsoft Store

Antes de chamar qualquer método na API de coleção ou a API de compra da Microsoft Store, o aplicativo deve criar uma chave de ID da Microsoft Store e enviá-la para o serviço. Esta chave é um JSON Web Token (JWT) que representa a identidade do usuário cujas informações de propriedade de produto você deseja acessar. Para obter mais informações sobre as declarações nessa chave, consulte Declarações em uma chave de ID da Microsoft Store.

Atualmente, a única forma de criar uma chave de ID da Microsoft Store é chamando uma API da Plataforma Universal do Windows (UWP) no código do cliente em seu app. A chave gerada representa a identidade do usuário que fez logon na Microsoft Store no dispositivo.

Observação

Cada chave de ID da Microsoft Store é válida por 90 dias. Depois que uma chave expira, você pode renovar a chave. Nós recomendamos que você renove as chaves de ID da Microsoft Store em vez de criar chaves novas.

Para criar uma chave de ID da Microsoft Store para a API de coleção da Microsoft Store

Siga estas etapas para criar uma chave de ID da Microsoft Store que você pode usar com a API de coleção da Microsoft Store para procurar por produtos pertencentes a um usuário ou declarar um produto consumível como providenciado.

  1. Passe o token de acesso do Azure AD criado com o URI de público https://onestore.microsoft.com/b2b/keys/create/collections de seu serviço para o app cliente. Esse é um dos tokens que você criou anteriormente na etapa 3.

  2. No código do seu app, chame um desses métodos para recuperar uma chave de ID da Microsoft Store:

  • Se seu aplicativo usa a classe StoreContext no namespace Windows.Services.Store para gerenciar as compras no aplicativo, use o método StoreContext.GetCustomerCollectionsIdAsync.

  • Se seu aplicativo usa a classe CurrentApp no namespace ApplicationModel para gerenciar as compras no aplicativo, use o método CurrentApp.GetCustomerCollectionsIdAsync.

    Passe o token de acesso do Azure AD para o parâmetro serviceTicket do método. Se você mantiver IDs de usuário anônimas no contexto de serviços gerenciados como o editor do aplicativo atual, também poderá passar uma ID de usuário para o parâmetro publisherUserId para associar o usuário atual à nova chave de ID da Microsoft Store (a ID de usuário será inserida na chave). Caso contrário, se você não precisar associar uma ID de usuário à chave de ID da Microsoft Store, poderá passar qualquer valor de cadeia de caracteres para o parâmetro publisherUserId .

  1. Depois que seu app criar com êxito uma chave de ID da Microsoft Store, repasse a chave para seu serviço.

Para criar uma chave de ID da Microsoft Store para a API de compra da Microsoft Store

Siga estas etapas para criar uma chave de ID da Microsoft Store que você pode usar com a API de compras da Microsoft Store a fim de conceder um produto gratuito a um usuário, obter assinaturas para um usuário ou alterar o estado de cobrança de uma assinatura para um usuário.

  1. Passe o token de acesso do Azure AD criado com o URI de público https://onestore.microsoft.com/b2b/keys/create/purchase de seu serviço para o app cliente. Esse é um dos tokens que você criou anteriormente na etapa 3.

  2. No código do seu app, chame um desses métodos para recuperar uma chave de ID da Microsoft Store:

  • Se seu aplicativo usa a classe StoreContext no namespace Windows.Services.Store para gerenciar as compras no aplicativo, use o método StoreContext.GetCustomerPurchaseIdAsync.

  • Se seu aplicativo usa a classe CurrentApp no namespace Windows.ApplicationModel.Store para gerenciar as compras no aplicativo, use o método CurrentApp.GetCustomerPurchaseIdAsync.

    Passe o token de acesso do Azure AD para o parâmetro serviceTicket do método. Se você mantiver IDs de usuário anônimas no contexto de serviços gerenciados como o editor do aplicativo atual, também poderá passar uma ID de usuário para o parâmetro publisherUserId para associar o usuário atual à nova chave de ID da Microsoft Store (a ID de usuário será inserida na chave). Caso contrário, se você não precisar associar uma ID de usuário à chave de ID da Microsoft Store, poderá passar qualquer valor de cadeia de caracteres para o parâmetro publisherUserId .

  1. Depois que seu app criar com êxito uma chave de ID da Microsoft Store, repasse a chave para seu serviço.

Diagrama

O diagrama a seguir ilustra o processo de criação de uma chave de ID da Microsoft Store.

Criar chave de ID da Windows Store

Declarações em uma chave de ID da Microsoft Store

Uma chave de ID da Microsoft Store é um Token Web JSON (JWT) que representa a identidade do usuário cujas informações de propriedade de produto você deseja acessar. Quando decodificada usando Base64, uma chave de ID da Microsoft Store contém as declarações a seguir.

  • iat: identifica a hora em que a chave foi emitida. Essa declaração pode ser usada para determinar a idade do token. Esse valor é expresso como época.
  • iss: identifica o emissor. Isso tem o mesmo valor que a reivindicação aud.
  • aud: identifica o público-alvo. Deve ser um dos seguintes valores: https://collections.mp.microsoft.com/v6.0/keys ou https://purchase.mp.microsoft.com/v6.0/keys.
  • exp: identifica o tempo de expiração em ou após o qual a chave não será mais aceita para processar nada, exceto para renovar chaves. O valor dessa declaração é expresso como época.
  • nbf: identifica a hora em que o token será aceito para processamento. O valor dessa declaração é expresso como época.
  • http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId: a ID do cliente que identifica o desenvolvedor.
  • http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload: uma carga opaca (criptografada e codificada em Base64) que contém informações destinadas apenas para uso pelos serviços da Microsoft Store.
  • http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId: uma ID de usuário que identifica o usuário atual no contexto de seus serviços. É o mesmo valor que você transmite para o parâmetro publisherUserId opcional do método usado para criar a chave.
  • http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri: o URI que você pode usar para renovar a chave.

Veja aqui um exemplo de um cabeçalho de chave de ID da Microsoft Store decodificado.

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

Aqui está um exemplo de uma declaração de chave de ID da Microsoft Store decodificada definida.

{
    "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
}