Gérer les droits sur les produits à partir d’un service

Si vous disposez d’un catalogue d’applications et de modules complémentaires, vous pouvez utiliser l’API de collecte du Microsoft Store et l’API d’achat du Microsoft Store pour accéder aux informations de droits d’utilisation de ces produits à partir de vos services. Un droit représente le droit d’un client d’utiliser une application ou un module complémentaire publié via le Microsoft Store.

Ces API se composent de méthodes REST conçues pour être utilisées par les développeurs avec des catalogues d’extensions pris en charge par des services multiplateformes. Ces API vous permettent d’effectuer les opérations suivantes :

• API de collection du Microsoft Store : Interrogez les produits appartenant à un utilisateur et signalez un produit consommable tel qu’il est rempli.
• API d’achat du Microsoft Store : Accordez un produit gratuit à un utilisateur, obtenez des abonnements pour un utilisateur et modifiez l’état de facturation d’un abonnement pour un utilisateur.

Remarque

L’API de collecte du Microsoft Store et l’API d’achat utilisent l’authentification Azure Active Directory (Azure AD) pour accéder aux informations de propriété du client. Pour utiliser ces API, vous (ou votre organisation) devez disposer d’un annuaire Azure AD et vous devez disposer de l’autorisation d’administrateur général pour l’annuaire. Si vous utilisez déjà Microsoft 365 ou d’autres services professionnels de Microsoft, vous disposez déjà d’un annuaire Azure AD.

Bibliothèque Microsoft.StoreServices

Pour simplifier le flux d’authentification et appeler les services Microsoft Store, passez en revue le projet Microsoft.StoreServices et l’exemple sur Github. La bibliothèque Microsoft.StoreServices permet de gérer les clés d’authentification et fournit des API wrapper pour appeler les services Microsoft Store pour la gestion des produits. L’exemple de projet met en évidence la façon dont un service peut utiliser la bibliothèque Microsoft.StoreServices, par exemple la logique de gestion des produits consommables, la réconciliation des achats remboursés, le renouvellement des informations d’identification expirées, etc. Un guide de configuration pas à pas est inclus dans l’exemple pour configurer l’exemple de service sur votre PC ou via Azure.

• Bibliothèque Microsoft.StoreServices (GitHub)
• Exemple Microsoft.StoreServices (GitHub)

Vue d’ensemble

Les étapes suivantes décrivent le processus de bout en bout pour utiliser l’API de collection du Microsoft Store et l’API d’achat :

1. Configurez une application dans Azure AD.
2. Associez votre ID d’application Azure AD à votre application dans l’Espace partenaires.
3. Dans votre service, créez des jetons d’accès Azure AD qui représentent votre identité d’éditeur.
4. Dans votre application Windows cliente, créez une clé d’ID du Microsoft Store qui représente l’identité de l’utilisateur actuel et transmettez cette clé à votre service.

Ce processus de bout en bout implique deux composants logiciels qui effectuent différentes tâches :

• Votre service. Il s’agit d’une application qui s’exécute en toute sécurité dans le contexte de votre environnement d’entreprise et qui peut être implémentée à l’aide de n’importe quelle plateforme de développement que vous choisissez. Votre service est chargé de créer les jetons d’accès Azure AD nécessaires au scénario et d’appeler les URI REST pour l’API de collecte du Microsoft Store et l’API d’achat.
• Votre application Windows cliente. Il s’agit de l’application pour laquelle vous souhaitez accéder et gérer les informations de droits d’utilisation des clients (y compris les modules complémentaires pour l’application). Cette application est chargée de créer les clés d’ID du Microsoft Store dont vous avez besoin pour appeler l’API de collection du Microsoft Store et acheter l’API auprès de votre service.

Étape 1 : Configurer une application dans Azure AD

Avant de pouvoir utiliser l’API de collection du Microsoft Store ou l’API d’achat, vous devez créer une application web Azure AD, récupérer l’ID de locataire et l’ID d’application de l’application et générer une clé. L’application web Azure AD représente le service à partir duquel vous souhaitez appeler l’API de collection du Microsoft Store ou l’API d’achat. Vous avez besoin de l’ID de locataire, de l’ID d’application et de la clé pour générer des jetons d’accès Azure AD que vous devez appeler l’API.

1. Si ce n’est déjà fait, suivez les instructions de l’intégration d’applications à Azure Active Directory pour inscrire une application web/une application API auprès d’Azure AD.

   Remarque

   Lorsque vous inscrivez votre application, vous devez choisir l’application web /l’API comme type d’application afin de pouvoir récupérer une clé (également appelée clé secrète client) pour votre application. Pour appeler l’API de collecte du Microsoft Store ou l’API d’achat, vous devez fournir une clé secrète client lorsque vous demandez un jeton d’accès auprès d’Azure AD dans une étape ultérieure.

2. Dans le portail de gestion Azure, accédez à Azure Active Directory. Sélectionnez votre répertoire, cliquez sur Inscriptions d’applications dans le volet de navigation gauche, puis sélectionnez votre application.

3. Vous accédez à la page d’inscription principale de l’application. Dans cette page, copiez la valeur d’ID d’application à utiliser ultérieurement.

4. Créez une clé dont vous aurez besoin ultérieurement (c’est tout ce qu’on appelle une clé secrète client). Dans le volet gauche, cliquez sur Paramètres, puis sur Clés. Dans cette page, procédez comme suit pour créer une clé. Copiez cette clé pour une utilisation ultérieure.

Étape 2 : Associer votre ID d’application Azure AD à votre application cliente dans l’Espace partenaires

Avant de pouvoir utiliser l’API de collecte du Microsoft Store ou l’API d’achat pour configurer la propriété et les achats pour votre application ou module complémentaire, vous devez associer votre ID d’application Azure AD à l’application (ou à l’application qui contient le module complémentaire) dans l’Espace partenaires.

Remarque

Vous ne devez effectuer cette tâche qu’une seule fois. Une fois que vous avez votre ID de locataire, votre ID d’application et votre clé secrète client, vous pouvez réutiliser ces valeurs chaque fois que vous devez créer un jeton d’accès Azure AD.

1. Connectez-vous à l’Espace partenaires et sélectionnez votre application.
2. Accédez à la page Collections et achats de produits services>, puis entrez votre ID d’application Azure AD dans l’un des champs d’ID client disponibles.

Étape 3 : Créer des jetons d’accès Azure AD

Avant de pouvoir récupérer une clé d’ID du Microsoft Store ou appeler l’API de collection du Microsoft Store ou l’API d’achat, votre service doit créer plusieurs jetons d’accès Azure AD différents qui représentent votre identité d’éditeur. Chaque jeton sera utilisé avec une API différente. La durée de vie de chaque jeton est de 60 minutes et vous pouvez les actualiser une fois qu’ils expirent.

Important

Créez des jetons d’accès Azure AD uniquement dans le contexte de votre service, et non dans votre application. Votre clé secrète client peut être compromise si elle est envoyée à votre application.

Présentation des différents jetons et URI d’audience

Selon les méthodes que vous souhaitez appeler dans l’API de collection du Microsoft Store ou l’API d’achat, vous devez créer deux ou trois jetons différents. Chaque jeton d’accès est associé à un URI d’audience différent.

• Dans tous les cas, vous devez créer un jeton avec l’URI d’audience https://onestore.microsoft.com . Dans une étape ultérieure, vous transmettez ce jeton à l’en-tête d’autorisation des méthodes dans l’API de collection du Microsoft Store ou l’API d’achat.

  Important

  Utilisez l’audience https://onestore.microsoft.com uniquement avec des jetons d’accès stockés en toute sécurité dans votre service. Exposer des jetons d’accès avec ce public en dehors de votre service peut rendre votre service vulnérable aux attaques de relecture.

• Si vous souhaitez appeler une méthode dans l’API de collection du Microsoft Store pour rechercher des produits appartenant à un utilisateur ou signaler un produit consommable tel qu’il est rempli, vous devez également créer un jeton avec l’URI https://onestore.microsoft.com/b2b/keys/create/collections d’audience. Dans une étape ultérieure, vous transmettez ce jeton à une méthode cliente dans le Kit de développement logiciel (SDK) Windows pour demander une clé d’ID du Microsoft Store que vous pouvez utiliser avec l’API de collection du Microsoft Store.

• Si vous souhaitez appeler une méthode dans l’API d’achat du Microsoft Store pour accorder un produit gratuit à un utilisateur, obtenir des abonnements pour un utilisateur ou modifier l’état de facturation d’un abonnement pour un utilisateur, vous devez également créer un jeton avec l’URI https://onestore.microsoft.com/b2b/keys/create/purchase d’audience. Dans une étape ultérieure, vous transmettez ce jeton à une méthode cliente dans le Kit de développement logiciel (SDK) Windows pour demander une clé d’ID du Microsoft Store que vous pouvez utiliser avec l’API d’achat du Microsoft Store.

Créer les jetons

Pour créer les jetons d’accès, utilisez l’API OAuth 2.0 dans votre service en suivant les instructions fournies dans Service to Service Calls Using Client Credentials to Send an HTTP POST to the https://login.microsoftonline.com/<tenant_id>/oauth2/token endpoint. Voici un exemple de requête.

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

Pour chaque jeton, spécifiez les données de paramètre suivantes :

• Pour les paramètres client_id et client_secret , spécifiez l’ID d’application et la clé secrète client de votre application que vous avez récupérées à partir du portail de gestion Azure. Ces deux paramètres sont requis pour créer un jeton d’accès avec le niveau d’authentification requis par l’API de collecte du Microsoft Store ou l’API d’achat.

• Pour le paramètre de ressource , spécifiez l’une des URI d’audience répertoriées dans la section précédente, en fonction du type de jeton d’accès que vous créez.

Une fois votre jeton d’accès expiré, vous pouvez l’actualiser en suivant les instructions fournies ici. Pour plus d’informations sur la structure d’un jeton d’accès, consultez Jeton pris en charge et Types de revendications.

Étape 4 : Créer une clé d’ID du Microsoft Store

Avant de pouvoir appeler n’importe quelle méthode dans l’API de collection du Microsoft Store ou l’API d’achat, votre application doit créer une clé d’ID du Microsoft Store et l’envoyer à votre service. Cette clé est un jeton web JSON (JWT) qui représente l’identité de l’utilisateur dont vous souhaitez accéder aux informations de propriété du produit. Pour plus d’informations sur les revendications de cette clé, consultez Revendications dans une clé d’ID du Microsoft Store.

Actuellement, la seule façon de créer une clé d’ID du Microsoft Store consiste à appeler une API plateforme Windows universelle (UWP) à partir du code client dans votre application. La clé générée représente l’identité de l’utilisateur actuellement connecté au Microsoft Store sur l’appareil.

Remarque

Chaque clé d’ID du Microsoft Store est valide pendant 90 jours. Une fois qu’une clé expire, vous pouvez renouveler la clé. Nous vous recommandons de renouveler vos clés d’ID du Microsoft Store plutôt que de les créer.

Pour créer une clé d’ID du Microsoft Store pour l’API de collection du Microsoft Store

Suivez ces étapes pour créer une clé d’ID du Microsoft Store que vous pouvez utiliser avec l’API de collection du Microsoft Store pour rechercher les produits appartenant à un utilisateur ou signaler un produit consommable comme rempli.

1. Transmettez le jeton d’accès Azure AD qui a la valeur https://onestore.microsoft.com/b2b/keys/create/collections d’URI d’audience de votre service à votre application cliente. Il s’agit de l’un des jetons que vous avez créés précédemment à l’étape 3.

2. Dans votre code d’application, appelez l’une de ces méthodes pour récupérer une clé d’ID du Microsoft Store :

• Si votre application utilise la classe StoreContext dans l’espace de noms Windows.Services.Store pour gérer les achats dans l’application, utilisez la méthode StoreContext.GetCustomerCollectionsIdAsync .

• Si votre application utilise la classe CurrentApp dans l’espace de noms Windows.ApplicationModel.Store pour gérer les achats dans l’application, utilisez la méthode CurrentApp.GetCustomerCollectionsIdAsync .

  Transmettez votre jeton d’accès Azure AD au paramètre serviceTicket de la méthode. Si vous conservez des ID d’utilisateur anonymes dans le contexte des services que vous gérez en tant qu’éditeur de l’application actuelle, vous pouvez également transmettre un ID utilisateur au paramètre publisherUserId pour associer l’utilisateur actuel à la nouvelle clé d’ID du Microsoft Store (l’ID utilisateur sera incorporé dans la clé). Sinon, si vous n’avez pas besoin d’associer un ID utilisateur à la clé d’ID du Microsoft Store, vous pouvez transmettre n’importe quelle valeur de chaîne au paramètre publisherUserId .

3. Une fois que votre application a correctement créé une clé d’ID du Microsoft Store, transmettez la clé à votre service.

Pour créer une clé d’ID du Microsoft Store pour l’API d’achat du Microsoft Store

Suivez ces étapes pour créer une clé d’ID du Microsoft Store que vous pouvez utiliser avec l’API d’achat du Microsoft Store pour accorder un produit gratuit à un utilisateur, obtenir des abonnements pour un utilisateur ou modifier l’état de facturation d’un abonnement pour un utilisateur.

1. Transmettez le jeton d’accès Azure AD qui a la valeur https://onestore.microsoft.com/b2b/keys/create/purchase d’URI d’audience de votre service à votre application cliente. Il s’agit de l’un des jetons que vous avez créés précédemment à l’étape 3.

2. Dans votre code d’application, appelez l’une de ces méthodes pour récupérer une clé d’ID du Microsoft Store :

• Si votre application utilise la classe StoreContext dans l’espace de noms Windows.Services.Store pour gérer les achats dans l’application, utilisez la méthode StoreContext.GetCustomerPurchaseIdAsync .

• Si votre application utilise la classe CurrentApp dans l’espace de noms Windows.ApplicationModel.Store pour gérer les achats dans l’application, utilisez la méthode CurrentApp.GetCustomerPurchaseIdAsync .

  Transmettez votre jeton d’accès Azure AD au paramètre serviceTicket de la méthode. Si vous conservez des ID d’utilisateur anonymes dans le contexte des services que vous gérez en tant qu’éditeur de l’application actuelle, vous pouvez également transmettre un ID utilisateur au paramètre publisherUserId pour associer l’utilisateur actuel à la nouvelle clé d’ID du Microsoft Store (l’ID utilisateur sera incorporé dans la clé). Sinon, si vous n’avez pas besoin d’associer un ID utilisateur à la clé d’ID du Microsoft Store, vous pouvez transmettre n’importe quelle valeur de chaîne au paramètre publisherUserId .

3. Une fois que votre application a correctement créé une clé d’ID du Microsoft Store, transmettez la clé à votre service.

Diagramme

Le diagramme suivant illustre le processus de création d’une clé d’ID du Microsoft Store.

Revendications dans une clé d’ID du Microsoft Store

Une clé d’ID du Microsoft Store est un jeton web JSON (JWT) qui représente l’identité de l’utilisateur dont vous souhaitez accéder aux informations de propriété du produit. Lorsqu’elle est décodée à l’aide de Base64, une clé d’ID du Microsoft Store contient les revendications suivantes.

• iat: identifie l’heure à laquelle la clé a été émise. Cette revendication peut être utilisée pour déterminer l’âge du jeton. Cette valeur est exprimée sous forme d’heure d’époque.
• iss: identifie l’émetteur. Cela a la même valeur que la aud revendication.
• aud: identifie l’audience. Doit être l’une des valeurs suivantes : https://collections.mp.microsoft.com/v6.0/keys ou https://purchase.mp.microsoft.com/v6.0/keys.
• exp: identifie l’heure d’expiration sur ou après laquelle la clé ne sera plus acceptée pour le traitement de quoi que ce soit, à l’exception du renouvellement des clés. La valeur de cette revendication est exprimée sous forme d’heure d’époque.
• nbf: identifie l’heure à laquelle le jeton sera accepté pour traitement. La valeur de cette revendication est exprimée sous forme d’heure d’époque.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId: ID client qui identifie le développeur.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload: charge utile opaque (chiffrée et encodée en Base64) qui contient des informations destinées uniquement à être utilisées par les services du Microsoft Store.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId: ID d’utilisateur qui identifie l’utilisateur actuel dans le contexte de vos services. Il s’agit de la même valeur que celle que vous transmettez au paramètre publisherUserId facultatif de la méthode que vous utilisez pour créer la clé.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri: URI que vous pouvez utiliser pour renouveler la clé.

Voici un exemple d’en-tête de clé d’ID du Microsoft Store décodé.

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

Voici un exemple de revendication de clé d’ID du Microsoft Store décodée.

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

Rubriques connexes

• Demander des produits
• Signaler les produits consommables comme satisfaits
• Accorder des produits gratuits
• Obtenir des abonnements pour un utilisateur
• Modifier l’état de facturation d’un abonnement pour un utilisateur
• Renouveler une clé d’ID du Microsoft Store
• Intégration d’applications dans Azure Active Directory
• Connaître le manifeste d’application Azure Active Directory
• Types de jeton et de revendication pris en charge
• Bibliothèque Microsoft.StoreServices (GitHub)