Creating and verifying licensing in a paid app for Office

I'm Krishnan Raghupathi, a Program Manager on the Office Store team. If you've read David's earlier post on choosing the right business model for your app for Office or SharePoint, and decided to charge users for your app, using our licensing service helps you enforce user licenses and prevent piracy. With the service, you can distinguish users on the trial mode from users who have paid for your apps, and direct each user to the appropriate experience.

One key principle to be aware of: The platform empowers your app to give the right experience based on the license, but does NOT directly enforce the user's license. Put differently, if you submit an app with a 30-day trial, users will be able to use that trial indefinitely unless your app implements logic to give a different experience (for example, encouraging users to buy the app on the 31st day).

This post outlines how you can add logic to enable licensing checks inside your code using the Office verification service. A follow-up post will cover the basics of enforcing licenses for apps for SharePoint.

We'll cover:

The basics of licensing for apps.

Verifying user licenses in your app for Office.

A call to action.

How do app licenses work?

The article Licensing apps for Office and SharePoint goes into more detail about what app licenses are and how they work. In essence, when users download an app for Office from the Office Store , an app license token gets downloaded along with it. The token is for the user who bought the app and is passed along to the application itself when the user starts using the app (see Figure 1).

Figure 1: App licensing end-to-end

What does a license token look like?

The following is an example of the license token (check the App License XML schema for the latest license schema).

For apps for Office, this token is passed as an encoded URL query parameter up to the web application supporting your app.

Licensing your app for Office

After you have the license token, you can pass it on the Office Verification service inside your web application to verify the token's validity. For best anti-piracy protection, you should use server-side code to take the token and pass it to the verification service, although you can choose to keep this logic in the (client-side) app itself if you want.

1. Decode the token: Because the token is passed up in an encoded format as a URL query parameter, you should apply URL decoding and base64 decoding to get a decoded version of the user token. The following code retrieves the decoded token:

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);

stringdecodedToken = Encoding.Unicode.GetString(decodedBytes);

2. Call the verification service: After you have your decoded token, the next step is to pass it up to the verification service. You can create a service reference to the verification service from inside Visual Studio using the Add Service Reference option. Assuming you're building an ASP.NET website, right-click the project in Visual Studio and choose Add Service Reference (see Figure 3).

Figure 3. Create a service reference inside Visual Studio

In the dialog box that pops up, enter the URL of the verification service—which is located at https://verificationservice.officeapps.live.com/ova/verificationagent.svc. Clicking Go downloads the service metadata. You can name the reference appropriately (in this sample, I'm calling it VerificationService), and then click OK (see Figure 4). This downloads the client contract to your project.

Figure 4. Create a client namespace for the Verification Service

Back in your code's logic, call the service with the decoded token:

//Create a client instance to call the service.

VerificationServiceClient client = newVerificationServiceClient();

//Create the interface request object and add your token to the request.

3. Provide the right experience: You can parse the response returned by the service to decide what experience to return to the user. In this sample, we have four different HTML files, one for each of the possible response actions. You can redirect the user to one of these files and show customized experiences for each of these scenarios. You should also check whether the token is valid using the Validity property. Also check whether the returned Product ID matches the Product ID in your app (which is defined in your App Manifest in the <Id> tag).

4. Testing and handling test tokens: To test your code, place the token file in a local folder along with the app manifest (.xml) file. You can then create a new registry key under [HKEY_CURRENT_USER\Software\Microsoft\Office\15.0\Wef\Developer] with a value of the folder name. This will let your app appear under the Developer category in your Word document (see Figure 5), where you can test that it works.

Handling test tokens also forms an important part of enforcing licenses. You can use this to perform special validation or to handle test tokens appropriately by giving a test experience. The verification service response lets you enable this using the IsTest property.