Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

License your Office and SharePoint Add-ins

Office and SharePoint Add-ins

Use the app license framework for apps for Office and SharePoint to verify and enforce legal use of your apps that are downloaded from the Office Store.

Last modified: July 24, 2015

Applies to: Office 2013 | Office 365 | Office Add-ins | SharePoint Add-ins | SharePoint Foundation 2013 | SharePoint Server 2013

Note Note

The names "apps for Office" and "apps for SharePoint" are changing to "Office Add-ins" and "SharePoint Add-ins". During the transition, the documentation and the UI of some Office and SharePoint products and Visual Studio tools might still use the terms "apps for Office" and "apps for SharePoint". For details, see New name for apps for Office and SharePoint.

In this article
How you can use license information in your apps
In this section
Additional resources

The licensing framework for apps for Office and SharePoint gives you a way to include code in your apps to verify and enforce their legal use. You can restrict access to your apps to only those users who have a valid license, or specify which features are available, how the app behaves, or other logic, based on the properties of that license. If you plan to sell your app, you should build in logic that uses the licensing framework to determine whether a user has a valid license for the app, and give access to its features based on the license's properties.

The app license framework itself does not enforce app licenses. It's a structure in which you can add code to your apps to retrieve and then act on license information.

The app license framework applies only to apps acquired directly from the Office Store or apps from the Office Store that are made available in an app catalog hosted on SharePoint 2013. Apps made available in other ways—such as from a file system location, or uploaded directly to an app catalog hosted on SharePoint—cannot use the app license framework.

The Office and SharePoint 2013 app license framework includes:

  • The Office Store—a site where users can acquire licensed apps for Office and SharePoint. The Office Store handles payment and issues licenses.

  • Storage of licenses, and renewal of app license tokens.

  • APIs you can use to get license information.

  • A web service you can use to verify whether a license is valid.

  • Specifically for apps for SharePoint, SharePoint 2013 provides an administration user interface for app license management, where an app purchaser can assign the license to a user, and also delegate to other users how the license is managed.

  • Specifically for mail apps, Exchange 2013 provides the Exchange Administration Console, where administrators can purchase and manage mail apps for their organization.

The app license framework provides a way for you to customize app access and behavior based on license information. The following is the general pattern for performing app license checks.

Design your app user experience with licensing in mind

If you plan on using the licensing framework, you should design your app with this in mind. Decide what user experience you want to control or customize based on license information. For example, you might want to:

  • Check that the user has a valid license each time the user launches the app.

  • Make only certain functionality in your app available if the user has a trial license.

  • For task pane or content apps, offer the user a different experience based on whether they access your app anonymously, or signed in with a valid license.

Add license checks to your app code

For each experience you want to customize based on license information, add code for that event that performs a license check. The license check consists of determining if the license token is present, and if it is, validating that license token.

Retrieve the license token, if present

Your license checking code should determine if the app license token is present, and retrieve it if it is.

  • For content and task pane apps for Office, when the app is launched and the Office application requests the app home page, the Office application passes the license token as a query parameter in the HTTP request. The app code must extract and cache this information, so that the license checking code in the app can later access it.

    If the user is not signed in to their Microsoft account, the Office application requesting the app home page does not append the license token parameter. See App license tokens and anonymous access for apps for Office for more information.

  • For paid mail apps, Exchange appends the app’s source location URL with a license token as a query parameter of the URL, then transmits the app manifest to Outlook. When the app is launched, Outlook passes the license token as a query parameter in the HTTP request. The app code must extract and cache this information, so that the license checking code in the app can later access it.

  • For apps for SharePoint, the app’s license checking code queries the SharePoint deployment for the license token.

App license tokens and anonymous access for apps for Office

To help maximize the reach and adoption of your apps, as of Office 2013, Service Pack 1, Microsoft will no longer require that a user be signed into Office with their Microsoft account in order to activate apps for Office. As of Office 2013, Service Pack 1, 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.

If the user is not signed in to their Microsoft account, the Office application requesting the app home page does not append the license token parameter. Therefore, you must include code in your app that determines whether the license token is present on each HTTP request for the app’s home page. If it is not, your app can treat the request as coming from an anonymous user, and present the UI and functionality you decide is appropriate. Use the app licensing framework to customize what your app presents to users who are not signed into their Microsoft accounts. For example, your app could present UI that provides more information about your app, a link to your app’s Office Store listing, a reduced set of functionality, or other relevant material.

App license type

Recommended UX when the user is anonymous (license token is not present)

Free

No change in behavior, app can function the same. However, if you rely on the license token to determine user identity of your free app, you might want to provide a notice to the user asking them to sign in to Office with a Microsoft Account to get the full benefits of your app.

Trial

Provide the same trial app experience when the user anonymous. If you rely on the license token to determine user identity of your trial app, you might want to provide a notice to the user asking them to sign in to Office with a Microsoft Account to get the full benefits of your app.

Paid

If your app only supports paid licenses (that is, it doesn’t provide a trial experience), you should present the user with information about your app, rather than a functional app, along with a hyperlink to your app’s Office Store listing page. This way users will be aware of your app and encouraged to purchase it.

By default, if your app task pane or content app does not perform this licensing check, your app will present the same UI and functionality to anonymous users as it does to licensed users.

Validate the license

After the app receives the app license token, the app must pass it to the Office Store verification web service to determine that the license is valid and the information it contains is accurate. The verification service returns whether the license is valid and the license attribute values. The app code can then take appropriate action, based on whether the license is valid and on the license information.

The Office Store verification service does not support being called from client-side code.

  • For apps for Office, you are required to use server-side code to query the Office Store verification web service.

  • For apps for SharePoint, if you are 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 only use server-side code to query the Office Store verification web service.

Take action based on license properties

Finally, add code to your app that takes the desired action based on the properties of the user’s app license. This could include displaying different UI based on subscription status, disabling certain functionality for trial licenses, or any other customization you want to make based on the license properties.

App license query and validation flows

The following figure shows the app license query and validation process for apps for Office.

Note Note

Task pane and content apps allow anonymous access. If the user is not signed in to their Microsoft account, the Office application requesting the app home page does not append the license token parameter. For details, see App license tokens and anonymous access for apps for Office.

Office app license verification process
  1. The user launches the app.

  2. The Office application that hosts the app requests the home page.

  3. The Office application appends the app license token to the HTTP request as a query string parameter.

  4. The app code extracts and caches the license token.

  5. When the app needs to verify the license token, it uses server-side code to pass the token to the Office Store verification service.

  6. The verification service returns whether the license token is valid, and if it is, also returns the license properties.

  7. The app can then take action, based on the validity of the license and its properties.

The following figure shows the app license query and validation process for apps for SharePoint.

SharePoint app license verification process
  1. The user launches the app from within SharePoint.

  2. This launches the app code in the cloud.

  3. When the app needs to verify a user’s app license, it uses server-side code to query SharePoint, via the client object model, for the app license token.

  4. It then passes that token to the Office Store verification service.

  5. The verification service returns whether the license token is valid, and if it is, also returns the license properties.

  6. The app can then take action, based on the validity of the license and its properties.

Show:
© 2015 Microsoft