Gestire i diritti relativi ai prodotti da un servizio

  • Articolo

Se disponi di un catalogo di app e componenti aggiuntivi, puoi usare l'API di raccolta di Microsoft Store e l'API di acquisto di Microsoft Store per accedere alle informazioni di proprietà per questi prodotti dai tuoi servizi. Un diritto rappresenta il diritto di un cliente di usare un'app o un componente aggiuntivo pubblicato tramite Microsoft Store.

Queste API sono costituite da metodi REST progettati per essere usati dagli sviluppatori con cataloghi di componenti aggiuntivi supportati da servizi multipiattaforma. Questi API consentono di eseguire le seguenti azioni:

Nota

L'API di raccolta e l'API di acquisto di Microsoft Store usano l'autenticazione di Azure Active Directory (Azure AD) per accedere alle informazioni sulla proprietà dei clienti. Per usare queste API, l'utente (o l'organizzazione) deve disporre di una directory di Azure AD e dell'autorizzazione di Amministratore globale per la directory. Se si usa già Microsoft 365 o altri servizi aziendali Microsoft, si dispone già di una directory di Azure AD.

Libreria Microsoft.StoreServices

Per semplificare il flusso di autenticazione e chiamare i servizi di Microsoft Store, esaminare il progetto Microsoft.StoreServices e l'esempio in Github. La libreria Microsoft.StoreServices consente di gestire le chiavi di autenticazione e fornisce l'API wrapper per chiamare i servizi di Microsoft Store per la gestione dei prodotti. Il progetto di esempio illustra come un servizio può usare la libreria Microsoft.StoreServices, ad esempio la logica per la gestione dei prodotti di consumo, la riconciliazione degli acquisti rimborsati, il rinnovo delle credenziali scadute e altro ancora. Una guida dettagliata alla configurazione è inclusa nell'esempio per configurare il servizio di esempio nel PC o tramite Azure.

Panoramica

I passaggi seguenti descrivono il processo end-to-end per l'uso dell'API di raccolta e dell'API di acquisto di Microsoft Store:

  1. Configurare un'applicazione in Azure AD.
  2. Associare l'ID applicazione Azure AD all'app nel Centro per i partner.
  3. Nel servizio creare token di accesso di Azure AD che rappresentano l'identità dell'editore.
  4. Nell'app di Windows client creare una chiave ID di Microsoft Store che rappresenta l'identità dell'utente corrente e passare di nuovo questa chiave al servizio.

Questo processo end-to-end prevede due componenti software che eseguono attività diverse:

  • Il servizio. Si tratta di un'applicazione che viene eseguita in modo sicuro nel contesto dell'ambiente aziendale e può essere implementata usando qualsiasi piattaforma di sviluppo scelta. Il servizio è responsabile della creazione dei token di accesso di Azure AD necessari per lo scenario e per chiamare gli URI REST per l'API di raccolta e l'API di acquisto di Microsoft Store.
  • L'app di Windows client. Questa è l'app per cui vuoi accedere e gestire le informazioni sui diritti dei clienti (inclusi i componenti aggiuntivi per l'app). Questa app è responsabile della creazione delle chiavi ID di Microsoft Store necessarie per chiamare l'API di raccolta di Microsoft Store e l'API di acquisto dal servizio.

Fase 1: Configurare un'applicazione in Azure AD

Prima di poter usare l'API di raccolta o di acquisto di Microsoft Store, è necessario creare un'applicazione Web di Azure AD, recuperare l'ID tenant e l'ID applicazione per l'applicazione e generare una chiave. L'applicazione Web Di Azure AD rappresenta il servizio da cui si vuole chiamare l'API di raccolta o l'API di acquisto di Microsoft Store. Sono necessari l'ID tenant, l'ID applicazione e la chiave per generare i token di accesso di Azure AD necessari per chiamare l'API.

  1. Se non è già stato fatto, seguire le istruzioni riportate in Integrazione di applicazioni con Azure Active Directory per registrare un'app Web o un'applicazione API con Azure AD.

    Nota

    Quando si registra l'applicazione, è necessario scegliere App Web/API come tipo di applicazione in modo da poter recuperare una chiave (detta anche segreto client) per l'applicazione. Per chiamare l'API di raccolta o l'API di acquisto di Microsoft Store, è necessario fornire un segreto client quando si richiede un token di accesso da Azure AD in un passaggio successivo.

  2. In Azure Management Portal andare a Azure Active Directory. Selezionare la directory, fare clic su Registrazioni app nel riquadro di spostamento a sinistra e quindi selezionare l'applicazione.

  3. Viene visualizzata la pagina di registrazione principale dell'applicazione. In questa pagina copiare il valore ID applicazione da usare in un secondo momento.

  4. Creare una chiave che sarà necessaria in un secondo momento (questa operazione è denominata segreto client). Nel riquadro sinistro fare clic su Impostazioni e quindi su Chiavi. In questa pagina completare i passaggi per creare una chiave. Copiare questa chiave per usarla successivamente.

Passaggio 2: Associare l'ID applicazione Azure AD all'app client nel Centro per i partner

Prima di poter usare l'API di raccolta o di acquisto di Microsoft Store per configurare la proprietà e gli acquisti per l'app o il componente aggiuntivo, è necessario associare l'ID applicazione di Azure AD all'app (o all'app che contiene il componente aggiuntivo) nel Centro per i partner.

Nota

È sufficiente eseguire questa attività una sola volta. Dopo aver ottenuto l'ID tenant, l'ID applicazione e il segreto client, puoi riutilizzare questi valori ogni volta che devi creare un nuovo token di accesso di Azure AD.

  1. Accedere al Centro per i partner e selezionare l'app.
  2. Passare alla pagina Servizi>Raccolte prodotti e acquisti e immettere l'ID applicazione Azure AD in uno dei campi ID client disponibili.

Passaggio 3: Creare token di accesso di Azure AD

Prima di poter recuperare una chiave ID di Microsoft Store o chiamare l'API di raccolta o di acquisto di Microsoft Store, il servizio deve creare diversi token di accesso di Azure AD che rappresentano l'identità dell'editore. Ogni token verrà usato con un'API diversa. La durata di ogni token è di 60 minuti ed è possibile aggiornarli dopo la scadenza.

Importante

Creare token di accesso di Azure AD solo nel contesto del servizio, non nell'app. Il segreto client potrebbe essere compromesso se viene inviato all'app.

Informazioni sui diversi token e URI del gruppo di destinatari

A seconda dei metodi che vuoi chiamare nell'API di raccolta o nell'API di acquisto di Microsoft Store, devi creare due o tre token diversi. Ogni token di accesso è associato a un URI del gruppo di destinatari diverso.

  • In tutti i casi, è necessario creare un token con l'URI del gruppo di destinatari https://onestore.microsoft.com. In un passaggio successivo questo token verrà passato all'intestazione authorization dei metodi nell'API di raccolta di Microsoft Store o nell'API di acquisto.

    Importante

    Usare il gruppo di destinatari https://onestore.microsoft.com solo con token di accesso archiviati in modo sicuro all'interno del servizio. L'esposizione di token di accesso con questo gruppo di destinatari all'esterno del servizio potrebbe rendere il servizio vulnerabile agli attacchi di riproduzione.

  • Se vuoi chiamare un metodo nell'API di raccolta di Microsoft Store per eseguire query sui prodotti di proprietà di un utente o segnalare un prodotto di consumo come evaso, devi anche creare un token con l'URI del https://onestore.microsoft.com/b2b/keys/create/collections gruppo di destinatari. In un passaggio successivo questo token verrà passato a un metodo client in Windows SDK per richiedere una chiave ID di Microsoft Store che è possibile usare con l'API di raccolta di Microsoft Store.

  • Se vuoi chiamare un metodo nell'API di acquisto di Microsoft Store per concedere un prodotto gratuito a un utente, ottenere sottoscrizioni per un utente o modificare lo stato di fatturazione di una sottoscrizione per un utente, devi anche creare un token con l'URI del https://onestore.microsoft.com/b2b/keys/create/purchase gruppo di destinatari. In un passaggio successivo questo token verrà passato a un metodo client in Windows SDK per richiedere una chiave ID di Microsoft Store che è possibile usare con l'API di acquisto di Microsoft Store.

Creare i token

Per creare i token di accesso, usare l'API OAuth 2.0 nel servizio seguendo le istruzioni riportate in Chiamate da servizio a servizio usando le credenziali client per inviare un HTTP POST all'endpoint https://login.microsoftonline.com/<tenant_id>/oauth2/token. Di seguito è riportata una richiesta di esempio.

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

Per ogni token, specificare i dati dei parametri seguenti:

  • Per i parametri client_id e client_secret, specificare l'ID applicazione e il segreto client per l'applicazione recuperata dal portale di gestione di Azure. Entrambi questi parametri sono necessari per creare un token di accesso con il livello di autenticazione richiesto dall'API di raccolta di Microsoft Store o dall'API di acquisto.

  • Per il parametro della risorsa, specificare uno degli URI del gruppo di destinatari elencati nella sezione precedente, a seconda del tipo di token di accesso che si sta creando.

Dopo la scadenza del token di accesso, è possibile aggiornarlo seguendo le istruzioni riportate qui. Per altre informazioni sulla struttura di un token di accesso, vedere Token e tipi di attestazione supportati.

Passaggio 4: Creare una chiave ID di Microsoft Store

Prima di poter chiamare qualsiasi metodo nell'API di raccolta o nell'API di acquisto di Microsoft Store, l'app deve creare una chiave ID di Microsoft Store e inviarla al servizio. Questa chiave è un token JSON Web (JWT) che rappresenta l'identità dell'utente alle cui informazioni sulla proprietà del prodotto si desidera accedere. Per altre informazioni sulle attestazioni in questa chiave, vedere Attestazioni in una chiave ID di Microsoft Store.

Attualmente, l'unico modo per creare una chiave ID di Microsoft Store consiste nel chiamare un'API piattaforma UWP (Universal Windows Platform) (UWP) dal codice client nella tua app. La chiave generata rappresenta l'identità dell'utente attualmente connesso a Microsoft Store nel dispositivo.

Nota

Ogni chiave ID di Microsoft Store è valida per 90 giorni. Dopo la scadenza di una chiave, è possibile rinnovare la chiave. Ti consigliamo di rinnovare le chiavi ID di Microsoft Store invece di crearne di nuove.

Creare una chiave ID di Microsoft Store per l'API di raccolta di Microsoft Store

Seguire questa procedura per creare una chiave ID di Microsoft Store che è possibile usare con l'API di raccolta di Microsoft Store per eseguire query sui prodotti di proprietà di un utente o segnalare un prodotto di consumo come evaso.

  1. Passare il token di accesso di Azure AD con il valore dell'URI del gruppo di destinatari https://onestore.microsoft.com/b2b/keys/create/collections dal servizio all'app client. Si tratta di uno dei token creati in precedenza nel passaggio 3.

  2. Nel codice dell'app chiamare uno di questi metodi per recuperare una chiave ID di Microsoft Store:

  1. Dopo che l'app ha creato correttamente una chiave ID di Microsoft Store, passare di nuovo la chiave al servizio.

Creare una chiave ID di Microsoft Store per l'API di acquisto di Microsoft Store

Seguire questa procedura per creare una chiave ID di Microsoft Store che è possibile usare con l'API di acquisto di Microsoft Store per concedere un prodotto gratuito a un utente, ottenere sottoscrizioni per un utente o modificare lo stato di fatturazione di una sottoscrizione per un utente.

  1. Passare il token di accesso di Azure AD con il valore dell'URI del gruppo di destinatari https://onestore.microsoft.com/b2b/keys/create/purchase dal servizio all'app client. Si tratta di uno dei token creati in precedenza nel passaggio 3.

  2. Nel codice dell'app chiamare uno di questi metodi per recuperare una chiave ID di Microsoft Store:

  1. Dopo che l'app ha creato correttamente una chiave ID di Microsoft Store, passare di nuovo la chiave al servizio.

Diagramma

Il diagramma seguente illustra il processo di creazione di una chiave ID di Microsoft Store.

Creare una chiave ID di Windows Store

Attestazioni in una chiave ID di Microsoft Store

Una chiave ID Microsoft Store è un token JSON Web (JWT) che rappresenta l'identità dell'utente alle cui informazioni sulla proprietà del prodotto si desidera accedere. Se decodificata con Base64, una chiave ID di Microsoft Store contiene le attestazioni seguenti.

  • iat: Identifica l'ora in cui è stata emessa la chiave. Questa attestazione può essere usata per determinare l'età del token. Questo valore è espresso come epoch time.
  • iss: Identifica l'autorità di certificazione. Ha lo stesso valore dell'attestazione aud.
  • aud: identifica il gruppo di destinatari. Deve essere uno dei seguenti valori: https://collections.mp.microsoft.com/v6.0/keys o https://purchase.mp.microsoft.com/v6.0/keys.
  • exp: identifica l'ora di scadenza nella quale o dopo la quale la chiave non verrà più accettata per l'elaborazione di alcun elemento, ad eccezione del rinnovo delle chiavi. Il valore di questa attestazione viene espresso come periodo temporale.
  • nbf: identifica l'ora in cui il token verrà accettato per l'elaborazione. Il valore di questa attestazione viene espresso come periodo temporale.
  • http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId: ID client che identifica lo sviluppatore.
  • http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload: payload opaco (crittografato e con codifica Base64) che contiene informazioni destinate solo all'uso da parte dei servizi di Microsoft Store.
  • http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId: ID utente che identifica l'utente corrente nel contesto dei servizi. Si tratta dello stesso valore passato al parametro publisherUserId facoltativo del metodo usato per creare la chiave.
  • http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri: URI che è possibile usare per rinnovare la chiave.

Di seguito è riportato un esempio di intestazione di chiave ID di Microsoft Store decodificata.

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

Ecco un esempio di un set di attestazioni di chiave ID di Microsoft Store decodificato.

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