Export (0) Print
Expand All

How to: Add license checks to your apps for Office

apps for Office and SharePoint

Learn how to add code to your app for Office that checks the validity of a user’s app license, and takes action based on the app license properties. Load test app license tokens to test your license checking code.

To help you test your app's license-checking code, you can use test licenses. The Office runtime treats these test tokens as if they were valid tokens acquired from the Office Store, with the exception that tokens loaded through the registry are not tested for expiration or entitlement type. These test licenses are strings that conform to the App License Schema.

To create a test token:

  • You can copy the example in the app license schema topic into a text file, saving it with a .tok extension.

  • Change the appropriate attributes, such as Product ID.

  • Finally, make sure the test attribute is present and set equal to true.

The Office Store verification web service, which you use to verify app license tokens, does not validate the encryption token or any of the attribute values of license tokens where the test attribute is set to true. You can edit your test tokens directly and use them to test app behavior code based on different attribute values.

Zoom into the Office object model for content apps Zoom into the object model for task pane apps

For content and task pane apps, follow these steps:

Zoom into the Office object model for mail apps

For mail apps, follow these steps:

  • Create your test token.

  • Create a URL-encoded version of the app license token.

  • In the app manifest file, manually edit the appropriate SourceLocation element. Add the URL-encoded version of the app license token to the source location URL as a query parameter named et.

Think about where in your app you want to check for a valid license or other license information. For example, check when the app launches, or when the user navigates to a specific app page or accesses certain app features.

Before you can check the license, you’ll have to acquire and cache the app license token. When a user opens an app for Office, the Office application containing the app requests the app home page. The Office application makes the HTTP request for the app home page, including the license token as a query string parameter on the page's URL.

For example, suppose your app home page has the following URL:

http://myApp/index.html

The Office application calling that URL would add the following query string to it and then pass the URL:

http://myApp/index.htm?et= PAByAD4APAB0ACAAYQBpAGQAPQAiAFcAQQAxADAAMgA4ADkAOQA1ADYANgAiACAAcABpAGQAPQAiADMAZAAyADgANwAwADcAYQAtAGYAYwBjAGUALQA0ADUAMQA3AC0AYQBjADYAZQAtAGMAYQAwAGEAZABkADYAMwA3ADMAYQBhACIAIABjAGkAZAA9ACIAMgAzAEEANwBFAEIAOABBADQAQwA0ADcARgA1AEEAMgAiACAAdABzAD0AIgAwACIAIABzAGwAPQAiAHQAcgB1AGUAIgAgAGUAdAA9ACIARgByAGUAZQAiACAAYQBkAD0AIgAyADAAMQAyAC0AMAA1AC0AMgAyAFQAMQA4ADoAMQAyADoAMgAzAFoAIgAgAHMAZAA9ACIAMgAwADEAMgAtADAANQAtADIAMgAiACAAdABlAD0AIgAyADAANgA3AC0AMAAyAC0AMgAzAFQAMQA4ADoAMQA0ADoAMAAwAFoAIgAgAC8APgA8AGQAPgAyADIAWABLAEEAdgA0ADMAQgBtAHMAcwByADAAcgBxADUANQBGAHUAdgBpAFUAVgBSAGkAVgBLAFMASQBEAGcAeAAyAHAAMgA0AFoAZwBzAGwANgBNAD0APAAvAGQAPgA8AC8AcgA%2bAA%3d%3d

The query string parameter—et—specifies a base-64 and URL-encoded version of the app license token.

Zoom into the Office object model for mail apps

For mail apps, the et query parameter string is only URL-encoded, and not base-64 encoded.

For example, the source location modified to include a test token for a mail app would look like this:

https://myApp/index.htm?et=%3Cr%20v%3D%221%22%3E%3Ct%20aid%3D%22WA104108294%22%20pid%3D%22463eafac-c123-45fe-bd21-b1b120b4c12b%22%20cid%3D%223BEC2F1C0124D801%22%20did%3D%22CONTOSO.COM%22%20ts%3D%221%22%20et%3D%22Paid%22%20ad%3D%222013-08-29T21%3A38%3A14Z%22%20sd%3D%222013-09-17%22%20te%3D%222013-12-23T09%3A10%3A42Z%22%20test%3D%221%22%20ss%3D%220%22%20%2F%3E%3Cd%3E7uM9j2%2FYZJeZrrm2TLjXufQlwkAXkq2RqjowBP9fAjo%3D%3C%2Fd%3E%3C%2Fr%3E

Important note Important

For security reasons, if you are licensing your app for Office, we strongly recommended you specify an HTTP Secure (https://) URL for your app home page.

To perform app license checks, you include code in your app that extracts the license token from the URL and caches it, so that the app can pass the token to the verification service later when you want to actually validate the app license.

For example, the following code extracts the token from the URL, decodes the token, and formats it as a string:

string token = Request.Params["et"].ToString(); // Obtains token URL

// Applies base64 decoding of the token to get a decoded token
byte[] decodedBytes = Convert.FromBase64String(token); 
string decodedToken = Encoding.Unicode.GetString(decodedBytes);

Zoom into the Office object model for content appsZoom into the object model for task pane apps

To help maximize the reach and adoption of your apps, as of Office 2013, Service Pack 1, task pane and content apps allow anonymous access. Microsoft will no longer require that a user be signed into Office with their Microsoft account in order to activate task pane and content apps for Office. The app license token will be passed as part of the initial HTTP request only if the user is signed in with their Microsoft Account.

So for task pane and content apps, your code should first test for the presence of the et parameter in the HTTP request. If it is not present, you should treat the user as anonymous, and present the appropriate user experience.

See App license tokens and anonymous access for apps for Office in Licensing apps for Office and SharePoint for more information.

Important noteImportant

Developers are advised not to parse or otherwise manipulate the app license token string before passing it to the Office Store verification web service for verification. While the app license token is structured as an XML fragment, for purposes of validation the Office Store verification web service treats the token as a literal string. The Office Store verification web service compares the contents of the <t> element to the value of the <d> element, which is an encrypted signature derived from the literal string contained in the <t> element. Any reformatting of the license token, such as adding white space, tabs, line breaks, etc., will change the literal value of the <t> element and therefore cause the license verification check to fail.

Also, do not store the license token using a service or application that adds a byte order mark (BOM) to the license token string, as including this character in the license token passed to the verification service will cause the license check to fail. If you do use an application that adds a BOM to the token, you must remove this character before passing the license token to the verification service.

When the app needs to perform a license check, pass the license token to the Office Store license verification web service for validation. The verification service is located at the following URL:

https://verificationservice.officeapps.live.com/ova/verificationagent.svc

The verification service has a single method, VerifyEntitlementToken, that takes the app license token as a parameter and returns a VerifyEntitlementTokenResponse object that contains the properties of the app license. The IsValid property specifies whether the app license token is valid. Other properties, such as ProductId and EntitlementType, contain information about the various license attributes.

The Office Store license verification web service also supports verifying app license tokens using REST calls. To validate an app license using REST, use the following syntax, where {token} is the app license token, encoded by a method that complies with RFC 2396. For example, the encodeURIComponent() function in JavaScript, or the Uri.EscapeDataString method in the .NET Framework:

https://verificationservice.officeapps.live.com/ova/verificationagent.svc/rest/verify?token={token}

Calling the Office Store verification service from client-side code is not supported. You must use server-side code to query the Office Store verification web service.

Add code to your app that takes the appropriate action, based on whether the license is valid and, if it is valid, based on any other license information that is important to you. For example, you could add code that enables the user to access certain app features if the user’s app license is for the paid version of the app—but not if the license is for the trial version of the app.

After you finish testing your app and are ready to move it to production, you add code to the license checks in your app so that the app no longer accepts test licenses. This prevents users from using test licenses to access your app.

After you pass the app license token to the verification service’s VerifyEntitlementToken method, you use the VerifyEntitlementTokenResponse object returned by that method to access the app license properties. For test app licenses, the IsTest property returns true and the IsValid property returns false.

Zoom into the Office object model for mail apps

For mail apps, make sure that you remove the et parameter, which represents the test license token, from all SourceLocation elements in your app manifest file.

The following example shows the basic logic flow of retrieving and validating the app license token for a content or task pane app for Office:

  1. The code retrieves the URL query string parameter, et, which contains the encoded license token.

  2. The code uses a custom function to decode the license token and convert it from base-64 to a string format that the Office Store verification service accepts.

    Zoom into the Office object model for mail apps

    For mail apps, the et query parameter string is only URL-encoded, and not base-64 encoded. So to use this example with a mail app, you would need to remove the code that converts the token from base-64 encoding.

  3. The code passes the token in string format to the verification service for validation. After the verification service returns a VerifyEntitlementTokenResponse object that represents the validation results, the code can access the object's properties that contain attributes of the license token.

In this code example, the code prints out the user ID of the app user and whether the license token is a test token.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Collections.Specialized;
using System.Text;
using EtokenWeb.OmexTokenService;

namespace EtokenWeb{

    public partial class EToken : System.Web.UI.Page{
        public string etoken = "";
        private static VerificationServiceClient service = new VerificationServiceClient();

        protected void Page_Load(object sender, EventArgs e){
           
            etoken = Request.QueryString["et"];
            if (etoken != null)
            {
                Response.Write("my value:" + etoken + "<br>");
                CallVerificationService(etoken);
            }
            else
                Response.Write("no token provided<br>?");
        }

        private void CallVerificationService(string etoken){
            VerifyEntitlementTokenRequest request = new VerifyEntitlementTokenRequest();
            request.EntitlementToken =  DecodeToken(etoken);
            VerifyEntitlementTokenResponse  omexResponse = service.VerifyEntitlementToken(request);
            Response.Write("Is Test:" + omexResponse.IsTest + "<br>") ;
            Response.Write("User ID: "+ omexResponse.UserId + "<br>") ;
        }

        private static string DecodeToken(string encodedToken){
            byte[] decodedBytes = Convert.FromBase64String(encodedToken);
            return Encoding.Unicode.GetString(decodedBytes);
        }
    }
}

Community Additions

ADD
Show:
© 2014 Microsoft