Licensing apps for Office and SharePoint

apps for Office and SharePoint

Learn how you can 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.

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.

An app license is a digital set of verifiable information stating usage rights of an app for Office or app for SharePoint:

  • The information is verifiable in that you can query the Office Store to check on an app license validity.

  • These usage rights include whether an app is for purchase or is free, whether the app is available on a per-user or site basis, and whether the app is a trial or full version.

The app license categories used by the Office Store are based on how or whether you pay for them and on their scope. Payment categories include: Free, Paid (with or without a trial offer), and Subscription (again, with or without a trial offer). Scope categories include Per-User or Site.

Information specific to apps for Office

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

For task pane and content apps, apps can be Free, Paid, or Subscription, and are offered on a Per-User basis only.

Zoom into the Office object model for mail apps

For mail apps, apps can be Free, Paid, or Subscription priced, and offered on a Per-User or Site basis. Mail apps bought on a Per-User basis apply only to the person who bought them. Only administrators can buy apps on a site license basis and make them available to all of the users in their organization.

Information specific to apps for SharePoint

For apps for SharePoint, apps can be Free, Paid, or Subscription priced, and offered on a Per-User or Site basis.

When a user acquires an app from the Office Store or an app catalog—either paid, free, or as a trial—that user is also acquiring the app’s license. The Office Store downloads a version of that app license—an app license token—to the appropriate repository, as detailed below. The Office Store retains a record of each app license for verification and disaster recovery purposes.

Information specific to apps for Office

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

For task pane and content apps, the app license token gets downloaded to the Office application.

Zoom into the Office object model for mail apps

For mail apps, the app license token gets downloaded to the appropriate Exchange mailbox. For mail apps with a per-user license, the token is downloaded to the personal mailbox of the person acquiring the app. For mail apps with a site license, the token is downloaded to a special organization mailbox for the Exchange deployment.

For mail apps offered for free or as unlimited trials, no license is generated or stored by the Office Store, and so no license token is downloaded to Exchange.

Information specific to apps for SharePoint

For apps for SharePoint, the app license token gets downloaded to your SharePoint installation.

Each app license applies to the specific user, for that specific app.

Information specific to apps for Office

For apps for Office, this means that a licensed user can access and use the app in any Office application instance that it applies to.

For mail apps with a site license, that license is assigned to all users on that Exchange deployment automatically.

Information specific to apps for SharePoint

For apps for SharePoint, each app license applies to a specific app for a specific SharePoint deployment. A user with a license for an app can use that app on any site for that particular SharePoint deployment.

For apps for SharePoint that have a per-user license, each app license can be assigned to the specified number of SharePoint users. The app license applies only to the specified SharePoint deployment and the specified users.

For apps with a site license, that license is assigned to all users on that deployment automatically.

For a detailed overview of app licenses, including how users acquire licenses, app license assignment, duration, and scope, see How app licenses work for apps for Office and SharePoint.

The app license framework provides a way for app developers 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.

Information specific to apps for Office

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

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.

As of Office 2013, Service Pack 1, 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.

Zoom into the Office object model for mail apps

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.

Information specific to apps for SharePoint

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.

Information specific to apps for Office

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

Information specific to apps for SharePoint

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 figure below shows the app license query and validation process for apps for Office:

  1. The user launches the app.

  2. The Office application containing the app requests the app 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.

As of Office 2013, Service Pack 1, 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. See App license tokens and anonymous access for apps for Office for more information.

Office app license verification process

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

  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.

SharePoint app license verification process
Show:
© 2014 Microsoft