Export (0) Print
Expand All

How to: Add license checks to your app for SharePoint

apps for Office and SharePoint

Learn how to add code to your app for SharePoint 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 assist in testing the app license-checking code in your app, SharePoint enables you to upload up to ten test licenses per SharePoint deployment. These test licenses are XML fragments that conform to the App License Schema.

To import test licenses to your SharePoint deployment, use the ImportAppLicense method. To call this method, the caller must be one of the following:

  • An administrator of the site collection being called.

  • An administrator of the tenancy into which the license is imported, if the SharePoint deployment into which the license is imported is a tenancy.

  • A farm administrator

For test licenses, you don’t have to specify the deployment ID in the app license XML. The ImportAppLicense method supplies the correct deployment ID to the license token XML.

After you import the test licenses, they appear in the SharePoint user interface, just as regular app licenses do, and you can manage, assign, and delete them.

Code example: Importing a test license token into SharePoint

The following example takes a test app license token and imports it into the specified SharePoint installation.

// For this example to work, you must add a reference in your project to Microsoft.SharePoint.Client.dll and Microsoft.SharePoint.Client.Runtime.dll.

string rawXMLEntitlementToken = <token that you want to import>;
string webUrl = "http://localhost" // This localhost URL should be replaced with the URL of any site within the tenancy into which 
// You want to import the license.

using (ClientContext ctx = new ClientContext(webUrl))
{
    Microsoft.SharePoint.Client.Utilities.Utility.ImportAppLicense(
        context: ctx,
        licenseTokenToImport: rawXMLEntitlementToken,
        contentMarket: "en-US", // Replace this with whatever content market you want
        billingMarket8; "US", // Replace this with whatever billing market you want
        appName: "App Name", // Replace this with the name of the app
        iconUrl: "http://www.office.com", // Replace this with the URL of the icon of the app (as it appears on Office Store),
// Or you can simply leave the URL blank.
        providerName: "Provider Name"); // Replace this with the name of the provider of the app

    ctx.ExecuteQuery();
}

Identify where in your app you want to check for a valid license or other license information. For example, when the app launches, or when the user seeks to navigate to a specific app page or access certain app features. Add code at these points that queries your SharePoint deployment for the app license token, and then passes that token to the Office Store verification web service for validation.

To retrieve the app license token from SharePoint, use the GetAppLicenseInformation method. This method returns all licenses for the specified app applying to the user, based on the app product ID. (The app product ID can be found in the app’s manifest file.)

If multiple licenses are purchased for the same app by using different Microsoft accounts, the licenses are returned in the following order of priority:

  • Paid

  • Free

  • Unexpired Trial

  • Expired Trial

The GetAppLicenseInformation method does not return licenses with expired or preserved tokens. Preserved tokens are the license tokens that cannot be renewed automatically by SharePoint; to remain valid, preserved tokens must be renewed manually by having the purchaser sign in to the Office Store.

Code example: retrieving app license tokens

The following example retrieves all the app licenses for the current user of the app as a collection that can be iterated through.

// For this example to work, you must add a reference in your project to Microsoft.SharePoint.Client.dll and Microsoft.SharePoint.Client.Runtime.dll.
// For this API to work, the SharePoint deployment you are calling must be able to communicate with ACS to validate OAuth tokens.

string webUrl = "http://localhost" // This localhost URL should be replaced with the URL of the app web or host web of the app.
    // If you are redirected from the app web to the third-party side executing this code
    // in the code-behind, you can get the app web URL with 
    // HttpContext.Current.Request.QueryString["AppWebUrl"].

productId = new Guid(<product ID of the app>);
using(ClientContext ctx = new ClientContext(webUrl))
{
    ClientResult<AppLicenseCollection> licensecollection = Microsoft.SharePoint.Client.Utilities.Utility.GetAppLicenseInformation(ctx, productId);
    ctx.ExecuteQuery();
}

By the end of this example, licensecollection includes all the app licenses for the current user for this app as a collection of AppLicense objects. You can use the RawXMLLicenseToken property to access the app license token XML. So, for example, to access the app license token for the first app license token in the collection, you would use licensecollection.Value[0].RawXMLLicenseToken.

Important noteImportant

Developers are advised not to parse or otherwise manipulate the app license token string before passing it to the Office Store license 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.

Validating the app license token

After you retrieve the appropriate app license token, pass that token to the Office Store 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, which 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, and 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 verify an app license by using REST, use the following syntax:

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

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.The Office Store verification service does not support being called from client-side code.

Note Note

If you're hosting your app pages on SharePoint, you can use the SharePoint web proxy to make JavaScript calls to the Office Store verification service. However, for security reasons we strongly recommend that you use only server-side code to query the Office Store verification web service.

Caution note Caution

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.

Add code to your app that takes the appropriate actions, based on whether the license is valid and, if it is valid, 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 their app license is for the paid version of the app, but not if their license is for the trial version of the app.

Finally, after you finish testing your app and are ready to move it to production, you need to 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 on their SharePoint deployment.

After you pass the app license token to the verification service’s VerifyEntitlementToken method, you can 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.

The following example retrieves an app’s license token from the SharePoint deployment and passes the token to the Office Store verification service for validation. The sample catches a variety of possible errors if the verification fails. If the verification succeeds, the sample builds a string from the various license properties. Finally, the sample provides logic for specifying the level of app functionality based on the license type: Free, Paid, or Trial.

This sample requires a reference to Microsoft.SharePoint.Client.Utilities, and a web service reference to the Office Store verification service.

//Get the license token XML from SharePoint.
this.rawToken = GetLicenseTokenFromSP(this.productId, this.clientcontext);

//Call the Office Store verification service.
VerifyLicenseToken(this.rawToken);

private string GetLicenseTokenFromSP(Guid productId, ClientContext clientContext)
{
    //Get the license from SharePoint.
    ClientResult<AppLicenseCollection> licenseCollection = Utility.GetAppLicenseInformation(clientContext, productId);
    clientContext.Load(clientContext.Web);
    clientContext.ExecuteQuery();

    foreach (AppLicense license in licenseCollection.Value)
    {
        //Just get the first license token for now.
        rawLicenseToken = license.RawXMLLicenseToken;
        break;
    }
    return (rawLicenseToken);
}

private void VerifyLicenseToken(string rawLicenseToken)
{    
    if (string.IsNullOrEmpty(rawLicenseToken))
    {
        licVerifyEndPoint.Text = "There is no valid license for this user in SharePoint (OR) license cannot be obtained due to some error - check ULS.";
        return;
    }

    VerificationServiceClient service = null;
    VerifyEntitlementTokenResponse result = null;
    VerifyEntitlementTokenRequest request = new VerifyEntitlementTokenRequest();
    request.RawToken = rawLicenseToken;
    lblSPLicenseText.Text = System.Web.HttpUtility.HtmlEncode(request.RawToken);   

    try
    {
        service = new VerificationServiceClient();
        result = service.VerifyEntitlementToken(request);
    }
    catch (EndpointNotFoundException)
    {
        licVerifyEndPoint.Text = "Cannot access verification service endpoint";
    }
    catch (FaultException<ServiceUnavailableFault>)
    {
        licVerifyEndPoint.Text = "Error: entitlement verification service is unavailable.";
    }
    catch (FaultException<ServiceInternalErrorFault> internalFault)
    {
        licVerifyEndPoint.Text = "Error: entitlement verification service failed. Details: " + internalFault.Detail.Message;
    }
    catch (Exception exception)
    {
        licVerifyEndPoint.Text = "Error: entitlement verification service failed. Details: " + exception;
    }

    if (result != null && result.AssetId !=null)
    {
        string licenseDetails = string.Format("Asset Id: {0}; Product Id: {1}; License Type: {2}; Is Valid: {3}; License Acquisition Date: {4}; License Expiry Date: {5}; IsExpired: {6}; IsTest: {7}; IsSiteLicense: {8}; Seats: {9}; TokenExpiryDate: {10}",
                result.AssetId, result.ProductId, result.EntitlementType, result.IsValid, result.EntitlementAcquisitionDate, result.EntitlementExpiryDate, result.IsExpired, result.IsTest, result.IsSiteLicense, result.Seats, result.TokenExpiryDate);

        if (result.EntitlementType.ToUpper() == "FREE")
        {
          //Allow basic functionality
        }
        else if (result.EntitlementType.ToUpper() == "PAID")
        {
          //Allow all functionality
        }
        else //trial
        {
          //Allow limited functionality
        }
    }
            else
    {
        licVerifyEndPoint.Text = "Verification service didn't return any results";
    }
}

Show:
© 2014 Microsoft