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

How licenses work for Office and SharePoint Add-ins

Office and SharePoint Add-ins

Find out how add-in licenses work and the best way to implement licensing checks in your add-ins.

Last modified: July 24, 2015

Applies to: apps for Office | apps for SharePoint | 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
Types of add-in licenses
How users acquire add-in licenses
Add-in license tokens, duration, and scope
Best practices for add-in license checks
Additional resources

The licensing framework for apps for Office and SharePoint gives you a way to include code in your add-ins to verify and enforce their legal use. You can restrict access to your add-ins to only those users who have a valid license, or specify which features are available, how the add-in behaves, or other logic, based on the properties of that license. To write effective license checks, it is important to understand the types of licenses that are available, how users acquire licenses, and how licenses work in terms of duration and scope.

The add-in license itself is a digital set of verifiable information stating usage rights of an Office or SharePoint Add-in:

  • 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 free, whether the app is available on a per-user or site basis, and whether the app is a trial or full version.

To include code in your add-ins that performs licensing checks, see License your Office and SharePoint Add-ins.

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.

  • Task pane and content add-ins can be Free, Paid, or Subscription priced, and are offered on a Per-User basis only.

    Important note Important

    To help you maximize reach and adoption, task pane and content add-ins allow anonymous access. Users don't have to sign in to Office with their Microsoft account to activate Office Add-ins. By default, if your task pane or content add-in does not implement licensing checks, it will present the same UI and functionality to anonymous users as it does to licensed users.

    See App license tokens and anonymous access for apps for Office in License your Office and SharePoint Add-ins for more information.

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

  • SharePoint Add-ins can be Free, Paid, or Subscription priced, and offered on a Per-User or Site basis.

SharePoint 2013 maps the license categories used by the Office Store to add-in license types, based on user access. The following table shows how the SharePoint add-in license types map to the classifications used by the Office Store.

SharePoint license type

Office Store license category

License applies to

Duration

Users

Cost

Perpetual all user

Free

Paid

Site

All users of a SharePoint deployment, with no expiration.

Perpetual

Unlimited

Free or paid

Perpetual multiuser

Paid

Per user, with no expiration.

Perpetual

N (per user)

Paid

Trial all user

Trial

All users of a SharePoint deployment.

Can have a set expiration date.

15, 30, 60 days, or unlimited

Unlimited

Free

Trial multiuser

Trial

Per user.

Can have a set expiration date.

15, 30, 60 days, or unlimited

N (per user)

Free

When a user acquires an add-in — either paid, free, or as a trial — that user is also acquiring the add-in’s license.

To get an add-in, a user browses the Office Store, selects the add-in, and then logs on to the Office Store using their Microsoft account. When the purchaser gets the add-in — whether for free, payment, or as a trial — the Office Store generates the appropriate add-in license and downloads a token that represents the license to the purchaser’s environment.

  • For content and task pane add-ins, the Office Store downloads the license token and stores it in the purchaser’s Office client application. The purchaser can then access and use the add-in.

    Task pane and content add-ins allow anonymous access. See App license tokens and anonymous access for apps for Office in License your Office and SharePoint Add-ins for more information.

  • Mail add-in license tokens are downloaded to the appropriate Exchange mailbox. For mail add-ins with a per-user license, the token is downloaded to the user's personal mailbox. For mail add-ins with a site license, the token is downloaded to a special organization mailbox for the Exchange deployment.

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

  • For apps for SharePoint, the license token is downloaded and stored in the purchaser’s SharePoint deployment.

    For apps for SharePoint, only site, tenant, or farm administrators can purchase add-in licenses, because only users with those roles have sufficient privileges to install an add-in in a site. Therefore, in many cases, the person acquiring the add-in is an administrator or purchasing agent, not the person who will actually use it.

    The add-in's purchaser can then manage the license, assign those licenses to other users within their deployment, and enable other users to manage the licenses. A user who is assigned an add-in license can access and use the add-in.

The Office Store retains a record of each add-in license for verification and disaster recovery purposes.

Acquiring an app license from the Office Store

The following figure shows the app license acquisition process for content and task pane apps for Office when the app is acquired directly from the Office Store. When the user acquires the app, the Office Store generates an app license, which it retains, and downloads a corresponding app license token to the Office application. The user can then access the app.

App purchase process from Office Store

Acquiring an app license from an app catalog

The following figure shows the app license acquisition process for apps for Office; this time the user acquires the app from an app catalog hosted on SharePoint 2013. When the user acquires the app, the app catalog contacts the Office Store for the appropriate app license. The Office Store generates the app license, which it retains, and returns a corresponding app license token, which the app catalog downloads to the Office application. The user can then access the app.

Office app purchase process from corporate catalog

Acquiring an app license for a mail app

The following figure shows the app license acquisition process for mail apps when the app is acquired directly from the Office Store. When the user acquires the app, the Office Store generates an app license, which it retains, and downloads a corresponding app license token to the user’s Exchange deployment. 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 the organization mailbox of 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. The user can then use the app.

Mail app purchase from the Office Store

Acquiring an app license for an app for SharePoint

The following figure shows the app license acquisition and assignment process for apps for SharePoint. A user, who might or might not be one of the people who will use the app, acquires the app, either directly from the Office Store or from a SharePoint app catalog. The Office Store generates the appropriate app license, which it contains, and downloads a corresponding app license token to the SharePoint deployment from which the app was acquired. The user can then manage and assign the license to one or more users, based on the license type.

SharePoint app purchase from Office Store

App licenses vary in duration, depending on their type. Also, app licenses for apps for Office differ from licenses for apps for SharePoint in terms of their scope, or where users can access them. Understanding these and other details of how app licenses operate will help you write more effective license checks.

Add-in license duration and token expiration

When you acquire an app license from the Office Store, the Office Store downloads a version of that app license—an app license token—to your SharePoint installation, Exchange deployment, or Office application, as applicable. For security reasons, app license tokens expire and must be renewed periodically.

The expiration of the app license, stored in the Office Store, is determined by the terms of the app acquisition. For example, apps with a perpetual license type do not expire. Trial apps, however, do expire if they have a specified expiration date.

  • For content and task pane apps for Office, the Office application checks the license token each time the user launches the app, and renews the token if needed.

  • For mail apps, Exchange checks the license token each time Outlook loads the app manifest from Exchange, and renews the token if needed. Outlook loads the app manifests each time the user logs into Outlook.

  • For apps for SharePoint, the license token is renewed by SharePoint as part of a preset timer job. Users can also manually renew an app license, for example, as part of a disaster recovery scenario.

License scope in content and task pane add-ins

Each app license applies to the specific user, for that specific app. 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 example, the user can use the app across multiple computers, each with a separate instance of the applicable Office application installed. When a user launches an Office application, and signs in with their Microsoft account, the Office application queries the Office Store for a list of the apps that user is licensed to use.

License scope in mail add-ins

For mail apps, each app license applies to a specific app for a specific Exchange deployment. A mail app with a site license is available to everyone in the same Exchange deployment as the administrator who acquired it.

For mail app licenses, the deployment ID is the primary authoritative mail domain for the Exchange deployment. For example, "CONTSO.COM". This deployment ID string is included in each app license token, and enforced in Exchange when apps are installed or loaded to Outlook. Exchange inspects the license token and verifies that the deployment ID matches the organization of the user. If it does not match, then Exchange blocks the app.

License scope and the deployment ID for 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. In general, for the purpose of app licenses, deployment is defined as the SharePoint farm for on-premises SharePoint installations, and the tenancy for SharePoint Online in Office 365.

Deployment scope can vary, however, based on the configuration of the on-premises SharePoint installation. App license tokens are stored in the App Management Shared Service; therefore, the actual scope of an app license is determined by the configuration of the App Management Shared Service. A given SharePoint installation could contain multiple web applications using different instances of the App Management Shared Service, and possibly using a federated service. In addition, an on-premises SharePoint installation might be configured for multitenancy, is which case a single instance of the App Management Shared Service might have multiple deployment IDs.

The deployment ID of the SharePoint installation to which an app license applies is included in each app license. The deployment ID is a GUID generated by SharePoint and recorded by the Office Store the first time anyone from a specific SharePoint installation visits the Office Store site.

For on-premises SharePoint installations, you can set the deployment ID via Windows PowerShell, for disaster recovery or test/production environment scenarios.

Add-in license assignment for apps for SharePoint

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. The purchaser of the app license can use the SharePoint user interface to manage the app licenses he or she acquired, including assigning licenses to users and designating other users who can manage the app licenses. You cannot programmatically assign app licenses.

Apply the following best practices when you create and enforce add-in licenses and restrictions.

Best practice

Description

Minimize access to code that performs add-in license checks.

For security reasons, we strongly recommended that you place the code that performs the license check somewhere outside the reach of potential tampering. For example, you can limit your add-in’s security exposure by using server-side code to query the Office Store verification web service, instead of performing the license check client-side.

  • 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.

Add license checks only as needed.

Add license checks only at those points in your app where you want to take some action based on whether the user has a valid license or other license information. For example, when the user launches the app, or when the user attempts to access certain app features that you want to control based on app license information.

For apps for SharePoint, do not perform app license checks on every page of your app. Constant querying of the SharePoint deployment for the app license token is rarely necessary, and can lead to your app performance being throttled.

Cache the license check appropriately.

For apps with a perpetual unlimited user license, cache until the license token expires. For apps with a multiuser license, either trial or perpetual, cache per session because user assignment can change.

Make sure the production version of your app does not accept test licenses.

When you finish testing your app and are ready to move it to production, make sure you add code to the license checks in your app so that the app no longer accepts test licenses. 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.

Show:
© 2015 Microsoft