Administrar los derechos de producto de un servicio

Si tienes un catálogo de aplicaciones y complementos, puedes usar la API de recopilación de Microsoft Store y la API de compra de Microsoft Store para acceder a la información de derechos de estos productos de tus servicios. Un derecho representa el derecho de un cliente a usar una aplicación o complemento que se publica a través de Microsoft Store.

Estas API constan de métodos REST diseñados para que los desarrolladores usen catálogos de complementos compatibles con servicios multiplataforma. Estas API le permiten hacer lo siguiente:

• API de recopilación de Microsoft Store: consulta de productos propiedad de un usuario e informa de un producto consumible como cumplido.
• API de compra de Microsoft Store: conceda un producto gratuito a un usuario, obtenga suscripciones para un usuario y cambie el estado de facturación de una suscripción para un usuario.

Nota:

La API de recopilación y la API de compra de Microsoft Store usan la autenticación de Azure Active Directory (Azure AD) para acceder a la información de propiedad del cliente. Para usar estas API, usted (o su organización) debe tener un directorio de Azure AD y debe tener permiso de administrador global para el directorio. Si usa Microsoft 365 u otros servicios empresariales de Microsoft, ya tiene el directorio de Azure AD.

La biblioteca Microsoft.StoreServices

Para ayudar a simplificar el flujo de autenticación y llamar a los servicios de Microsoft Store, revise el proyecto Microsoft.StoreServices y el ejemplo en Github. La biblioteca Microsoft.StoreServices ayudará a administrar las claves de autenticación y proporciona las API de contenedor para llamar a los Servicios de Microsoft Store para administrar productos. El proyecto de ejemplo resalta cómo un servicio puede usar la biblioteca Microsoft.StoreServices, por ejemplo, lógica para administrar productos consumibles, reconciliar las compras reembolsables, renovar las credenciales expiradas, etc. Se incluye una guía de configuración paso a paso con el ejemplo para configurar el servicio de ejemplo en el equipo o a través de Azure.

• Biblioteca Microsoft.StoreServices (GitHub)
• Ejemplo Microsoft.StoreServices (GitHub)

Información general

En los pasos siguientes se describe el proceso de un extremo a otro para usar la API de recopilación de Microsoft Store y la API de compra:

1. Configure una aplicación en Azure AD.
2. Asocie el identificador de aplicación de Azure AD a la aplicación en el Centro de partners.
3. En el servicio, cree tokens de acceso de Azure AD que representen la identidad del publicador.
4. En la aplicación windows cliente, cree una clave de identificador de Microsoft Store que represente la identidad del usuario actual y vuelva a pasar esta clave al servicio.

Este proceso integral implica dos componentes de software que realizan diferentes tareas:

• Su servicio. Se trata de una aplicación que se ejecuta de forma segura en el contexto del entorno empresarial y se puede implementar mediante cualquier plataforma de desarrollo que elija. El servicio es responsable de crear los tokens de acceso de Azure AD necesarios para el escenario y para llamar a los URI rest para la API de recopilación y la API de compra de Microsoft Store.
• Aplicación de Windows cliente. Esta es la aplicación para la que quiere acceder y administrar la información de derechos del cliente (incluidos los complementos de la aplicación). Esta aplicación es responsable de crear las claves de identificador de Microsoft Store que necesita para llamar a la API de recopilación de Microsoft Store y comprar la API del servicio.

Paso 1: Configuración de una aplicación en Azure AD

Para poder usar la API de recopilación o la API de compra de Microsoft Store, debe crear una aplicación web de Azure AD, recuperar el identificador de inquilino y el identificador de aplicación de la aplicación y generar una clave. La aplicación web de Azure AD representa el servicio desde el que quiere llamar a la API de recopilación o a la API de compra de Microsoft Store. Necesita el identificador de inquilino, el identificador de la aplicación y la clave para generar tokens de acceso de Azure AD que necesita para llamar a la API.

1. Si aún no lo ha hecho, siga las instrucciones de Integración de aplicaciones con Azure Active Directory para registrar una aplicación web o aplicación de API con Azure AD.

   Nota:

   Al registrar la aplicación, debe elegir Aplicación web o API como tipo de aplicación para poder recuperar una clave (también denominada secreto de cliente) para la aplicación. Para llamar a la API de recopilación de Microsoft Store o a la API de compra, debe proporcionar un secreto de cliente cuando solicite un token de acceso de Azure AD en un paso posterior.

2. En el Portal de administración de Azure, vaya a Azure Active Directory. Seleccione el directorio, haga clic en Registros de aplicaciones en el panel de navegación izquierdo y, a continuación, seleccione la aplicación.

3. Se le lleva a la página de registro principal de la aplicación. En esta página, copie el valor de Id. de aplicación para usarlo más adelante.

4. Cree una clave que necesitará más adelante (esto se denomina secreto de cliente). En el panel izquierdo, haga clic en Configuración y, a continuación, en Claves. En esta página, complete los pasos para crear una clave. Copie esta clave para su uso posterior.

Paso 2: Asociar el identificador de aplicación de Azure AD a la aplicación cliente en el Centro de partners

Para poder usar la API de recopilación de Microsoft Store o la API de compra para configurar la propiedad y las compras de la aplicación o el complemento, debe asociar el identificador de aplicación de Azure AD a la aplicación (o la aplicación que contiene el complemento) en el Centro de partners.

Nota:

Solo tiene que realizar esta tarea una vez. Una vez que tenga el identificador de inquilino, el identificador de aplicación y el secreto de cliente, puede reutilizar estos valores siempre que necesite crear un nuevo token de acceso de Azure AD.

1. Inicie sesión en el Centro de partners y seleccione la aplicación.
2. Vaya a la página Productos de servicios>y compras y escriba el identificador de aplicación de Azure AD en uno de los campos id. de cliente disponibles.

Paso 3: Creación de tokens de acceso de Azure AD

Para poder recuperar una clave de identificador de Microsoft Store o llamar a la API de recopilación o a la API de compra de Microsoft Store, el servicio debe crear varios tokens de acceso de Azure AD diferentes que representen la identidad del publicador. Cada token se usará con una API diferente. La duración de cada token es de 60 minutos y puede actualizarlas después de que expiren.

Importante

Cree tokens de acceso de Azure AD solo en el contexto del servicio, no en la aplicación. El secreto de cliente podría estar en peligro si se envía a la aplicación.

Descripción de los distintos tokens y URI de audiencia

Dependiendo de los métodos a los que quiera llamar en la API de recopilación o la API de compra de Microsoft Store, debe crear dos o tres tokens diferentes. Cada token de acceso está asociado a un URI de audiencia diferente.

• En todos los casos, debe crear un token con el URI de audiencia https://onestore.microsoft.com . En un paso posterior, pasará este token al encabezado authorization de los métodos de la API de recopilación de Microsoft Store o a la API de compra.

  Importante

  Use la https://onestore.microsoft.com audiencia solo con tokens de acceso que se almacenan de forma segura dentro del servicio. Exponer tokens de acceso con esta audiencia fuera del servicio podría hacer que el servicio sea vulnerable a ataques de reproducción.

• Si quieres llamar a un método en la API de recopilación de Microsoft Store para consultar productos propiedad de un usuario o notificar un producto consumible como cumplido, también debes crear un token con el URI de audiencia https://onestore.microsoft.com/b2b/keys/create/collections . En un paso posterior, pasará este token a un método de cliente en Windows SDK para solicitar una clave de identificador de Microsoft Store que pueda usar con la API de recopilación de Microsoft Store.

• Si quieres llamar a un método en la API de compra de Microsoft Store para conceder un producto gratuito a un usuario, obtener suscripciones para un usuario o cambiar el estado de facturación de una suscripción para un usuario, también debes crear un token con el URI de audiencia https://onestore.microsoft.com/b2b/keys/create/purchase . En un paso posterior, pasará este token a un método de cliente en Windows SDK para solicitar una clave de identificador de Microsoft Store que pueda usar con la API de compra de Microsoft Store.

Creación de los tokens

Para crear los tokens de acceso, use la API de OAuth 2.0 en el servicio siguiendo las instrucciones de Service to Service Calls Using Client Credentials (Llamadas de servicio a servicio mediante credenciales de cliente) para enviar un HTTP POST al https://login.microsoftonline.com/<tenant_id>/oauth2/token punto de conexión. Esta es una solicitud de ejemplo.

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 los siguientes datos de parámetro:

• Para los parámetros client_id y client_secret , especifique el identificador de aplicación y el secreto de cliente de la aplicación que recuperó del Portal de administración de Azure. Ambos parámetros son necesarios para crear un token de acceso con el nivel de autenticación requerido por la API de recopilación o la API de compra de Microsoft Store.

• Para el parámetro de recurso , especifique uno de los URI de audiencia enumerados en la sección anterior, en función del tipo de token de acceso que cree.

Una vez que expire el token de acceso, puede actualizarlo siguiendo las instrucciones que se indican aquí. Para obtener más información sobre la estructura de un token de acceso, consulte Tipos de notificación y token admitidos.

Paso 4: Crear una clave de identificador de Microsoft Store

Para poder llamar a cualquier método en la API de recopilación o la API de compra de Microsoft Store, la aplicación debe crear una clave de identificador de Microsoft Store y enviarla al servicio. Esta clave es un token web JSON (JWT) que representa la identidad del usuario cuya información de propiedad del producto desea acceder. Para obtener más información sobre las notificaciones de esta clave, vea Notificaciones en una clave de identificador de Microsoft Store.

Actualmente, la única manera de crear una clave de identificador de Microsoft Store es llamar a una API de Plataforma universal de Windows (UWP) desde el código de cliente de la aplicación. La clave generada representa la identidad del usuario que ha iniciado sesión actualmente en Microsoft Store en el dispositivo.

Nota:

Cada clave de identificador de Microsoft Store es válida durante 90 días. Una vez expirada una clave, puede renovar la clave. Te recomendamos que renueve las claves de identificador de Microsoft Store en lugar de crear nuevas.

Para crear una clave de identificador de Microsoft Store para la API de recopilación de Microsoft Store

Siga estos pasos para crear una clave de id. de Microsoft Store que pueda usar con la API de recopilación de Microsoft Store para consultar productos propiedad de un usuario o notificar un producto consumible como cumplido.

1. Pase el token de acceso de Azure AD que tiene el valor https://onestore.microsoft.com/b2b/keys/create/collections de URI de audiencia del servicio a la aplicación cliente. Este es uno de los tokens que creó anteriormente en el paso 3.

2. En el código de la aplicación, llame a uno de estos métodos para recuperar una clave de identificador de Microsoft Store:

• Si la aplicación usa la clase StoreContext en el espacio de nombres Windows.Services.Store para administrar las compras desde la aplicación, usa el método StoreContext.GetCustomerCollectionsIdAsync .

• Si la aplicación usa la clase CurrentApp en el espacio de nombres Windows.ApplicationModel.Store para administrar las compras desde la aplicación, use el método CurrentApp.GetCustomerCollectionsIdAsync .

  Pase el token de acceso de Azure AD al parámetro serviceTicket del método . Si mantiene identificadores de usuario anónimos en el contexto de los servicios que administra como publicador de la aplicación actual, también puede pasar un identificador de usuario al parámetro publisherUserId para asociar el usuario actual a la nueva clave de identificador de Microsoft Store (el identificador de usuario se incrustará en la clave). De lo contrario, si no necesita asociar un identificador de usuario con la clave de identificador de Microsoft Store, puede pasar cualquier valor de cadena al parámetro publisherUserId .

3. Después de que la aplicación cree correctamente una clave de identificador de Microsoft Store, vuelva a pasar la clave al servicio.

Para crear una clave de identificador de Microsoft Store para la API de compra de Microsoft Store

Siga estos pasos para crear una clave de identificador de Microsoft Store que pueda usar con la API de compra de Microsoft Store para conceder un producto gratuito a un usuario, obtener suscripciones para un usuario o cambiar el estado de facturación de una suscripción para un usuario.

1. Pase el token de acceso de Azure AD que tiene el valor https://onestore.microsoft.com/b2b/keys/create/purchase de URI de audiencia del servicio a la aplicación cliente. Este es uno de los tokens que creó anteriormente en el paso 3.

2. En el código de la aplicación, llame a uno de estos métodos para recuperar una clave de identificador de Microsoft Store:

• Si la aplicación usa la clase StoreContext en el espacio de nombres Windows.Services.Store para administrar las compras desde la aplicación, usa el método StoreContext.GetCustomerPurchaseIdAsync .

• Si la aplicación usa la clase CurrentApp en el espacio de nombres Windows.ApplicationModel.Store para administrar las compras desde la aplicación, use el método CurrentApp.GetCustomerPurchaseIdAsync .

  Pase el token de acceso de Azure AD al parámetro serviceTicket del método . Si mantiene identificadores de usuario anónimos en el contexto de los servicios que administra como publicador de la aplicación actual, también puede pasar un identificador de usuario al parámetro publisherUserId para asociar el usuario actual a la nueva clave de identificador de Microsoft Store (el identificador de usuario se incrustará en la clave). De lo contrario, si no necesita asociar un identificador de usuario con la clave de identificador de Microsoft Store, puede pasar cualquier valor de cadena al parámetro publisherUserId .

3. Después de que la aplicación cree correctamente una clave de identificador de Microsoft Store, vuelva a pasar la clave al servicio.

Diagrama

En el diagrama siguiente se muestra el proceso de creación de una clave de identificador de Microsoft Store.

Notificaciones en una clave de identificador de Microsoft Store

Una clave de identificador de Microsoft Store es un token web JSON (JWT) que representa la identidad del usuario cuya información de propiedad del producto desea acceder. Cuando se descodifica con Base64, una clave de identificador de Microsoft Store contiene las siguientes notificaciones.

• iat: identifica la hora en la que se emitió la clave. Esta notificación se puede usar para determinar la antigüedad del token. Este valor se expresa como tiempo de época.
• iss: identifica el emisor. Tiene el mismo valor que la aud notificación.
• aud: identifica la audiencia. Debe ser uno de los siguientes valores: https://collections.mp.microsoft.com/v6.0/keys o https://purchase.mp.microsoft.com/v6.0/keys.
• exp: identifica la hora de expiración en o después de la cual la clave ya no se aceptará para procesar nada excepto para renovar las claves. El valor de esta notificación se expresa como tiempo de época.
• nbf: identifica la hora en la que se aceptará el token para su procesamiento. El valor de esta notificación se expresa como tiempo de época.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/clientId: identificador de cliente que identifica al desarrollador.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/payload: una carga opaca (cifrada y codificada en Base64) que contiene información que solo está pensada para su uso por parte de los servicios de Microsoft Store.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/userId: identificador de usuario que identifica al usuario actual en el contexto de los servicios. Este es el mismo valor que se pasa al parámetro opcional publisherUserId del método que se usa para crear la clave.
• http://schemas.microsoft.com/marketplace/2015/08/claims/key/refreshUri: el URI que puede usar para renovar la clave.

Este es un ejemplo de un encabezado de clave de identificador de Microsoft Store descodificado.

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

Este es un ejemplo de un conjunto de notificaciones de clave de identificador de Microsoft Store descodificado.

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

Temas relacionados

• Consultar productos
• Notificar productos consumibles como cumplidos
• Concesión de productos gratuitos
• Obtención de suscripciones para un usuario
• Cambiar el estado de facturación de una suscripción para un usuario
• Renovación de una clave de identificador de Microsoft Store
• Integración de aplicaciones con Azure Active Directory
• Descripción del manifiesto de aplicación de Azure Active Directory
• Tipos de notificaciones y tokens admitidos
• Biblioteca Microsoft.StoreServices (GitHub)