How licenses work for Office and SharePoint Add-ins

Note

Upcoming changes to the add-in payment model will affect all paid add-ins. For details, see Moving from paid to free add-ins.

The licensing framework for Office and SharePoint Add-ins 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 AppSource to check on the validity of an add-in license.

  • These usage rights include whether an add-in is for purchase or free, whether the add-in is available on a Per-User or Site basis, and whether the add-in 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.

Types of add-in licenses

The add-in license categories used by AppSource 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

    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 presents the same UI and functionality to anonymous users as it does to licensed users. For more information, see Add-in license tokens and anonymous access for Office Add-ins.

  • Outlook add-ins can be Free, Paid, or Subscription priced, and offered on a Per-User or Site basis. Outlook 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.

    Note

    SharePoint 2013 does not support subscription licensing.

SharePoint maps the license categories used by AppSource 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 AppSource.

SharePoint license type AppSource license category License applies to Duration Users Cost
Perpetual all user Free PaidSite 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

How users acquire add-in licenses

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 AppSource, selects the add-in, and then signs in to AppSource using their Microsoft account. When the purchaser gets the add-in—whether for free, payment, or as a trial—AppSource 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, AppSource 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. For more information, see Add-in license tokens and anonymous access.

  • Outlook add-in license tokens are downloaded to the appropriate Exchange mailbox. For Outlook add-ins with a Per-User license, the token is downloaded to the user's personal mailbox. For Outlook add-ins with a Site license, the token is downloaded to a special organization mailbox for the Exchange deployment.

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

  • For SharePoint Add-ins, the license token is downloaded and stored in the purchaser's SharePoint deployment.

    For SharePoint Add-ins, 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 on 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.

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

Acquiring an add-in license from AppSource

Figure 1 shows the add-in license acquisition process for content and task pane Office Add-ins when the add-in is acquired directly from AppSource. When the user acquires the add-in, AppSource generates an add-in license, which it retains, and downloads a corresponding add-in license token to the Office application. The user can then access the add-in.

Figure 1. Add-in purchase process from AppSource

Add-in purchase process from AppSource

Acquiring an add-in license from an add-in catalog

Figure 2 shows the add-in license acquisition process for Office Add-ins; this time the user acquires the add-in from an add-in catalog hosted on SharePoint. When the user acquires the add-in, the add-in catalog contacts AppSource for the appropriate add-in license. AppSource generates the add-in license, which it retains, and returns a corresponding add-in license token, which the add-in catalog downloads to the Office application. The user can then access the add-in.

Figure 2. Office add-in purchase process from corporate catalog

Office add-in purchase process from corporate catalog

Acquiring an add-in license for an Outlook add-in

Figure 3 shows the add-in license acquisition process for Outlook add-ins when the add-in is acquired directly from AppSource. When the user acquires the add-in, AppSource generates an add-in license, which it retains, and downloads a corresponding add-in license token to the user's Exchange deployment.

For Outlook add-ins with a Per-User license, the token is downloaded to the personal mailbox of the person acquiring the add-in.

For Outlook add-ins with a Site license, the token is downloaded to the organization mailbox of the Exchange deployment.

For Outlook add-ins offered for free or as unlimited trials, no license is generated or stored by AppSource, so no license token is downloaded to Exchange. The user can then use the add-in.

Figure 3. Mail add-in purchase from AppSource

Mail add-in purchase from AppSource

Acquiring an add-in license for a SharePoint Add-in

Figure 4 shows the add-in license acquisition and assignment process for SharePoint Add-ins. A user, who might or might not be one of the people who will use the add-in, acquires the add-in, either directly from AppSource or from a SharePoint add-in catalog. AppSource generates the appropriate add-in license, which it contains, and downloads a corresponding add-in license token to the SharePoint deployment from which the add-in was acquired. The user can then manage and assign the license to one or more users, based on the license type.

Figure 4. SharePoint add-in purchase from AppSource

SharePoint add-in purchase from AppSource

Add-in license tokens, duration, and scope

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

Add-in license duration and token expiration

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

The expiration of the add-in license, stored in AppSource, is determined by the terms of the add-in acquisition. For example, add-ins with a perpetual license type do not expire. Trial add-ins, however, do expire if they have a specified expiration date.

  • For content and task pane Office Add-ins, the Office application checks the license token each time the user launches the add-in, and renews the token if needed.

  • For Outlook add-ins, Exchange checks the license token each time Outlook loads the add-in manifest from Exchange, and renews the token if needed. Outlook loads the add-in manifests each time the user signs in to Outlook.

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

License scope in content and task pane add-ins

Each add-in license applies to the specific user for that specific add-in. For Office Add-ins, this means that a licensed user can access and use the add-in in any Office application instance that it applies to. For example, the user can use the add-in 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 AppSource for a list of the add-ins that user is licensed to use.

License scope in Outlook add-ins

For Outlook add-ins, each add-in license applies to a specific add-in for a specific Exchange deployment. An Outlook add-in with a Site license is available to everyone in the same Exchange deployment as the administrator who acquired it.

For Outlook add-in 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 add-in license token, and enforced in Exchange when add-ins 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, Exchange blocks the add-in.

License scope and the deployment ID for SharePoint Add-ins

For SharePoint Add-ins, each add-in license applies to a specific add-in for a specific SharePoint deployment. A user with a license for an add-in can use that add-in on any site for that particular SharePoint deployment. In general, for the purpose of add-in 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. Add-in license tokens are stored in the Add-in Management Shared Service; therefore, the actual scope of an add-in license is determined by the configuration of the Add-in Management Shared Service. A given SharePoint installation could contain multiple web applications using different instances of the Add-in 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 Add-in Management Shared Service might have multiple deployment IDs.

The deployment ID of the SharePoint installation to which an add-in license applies is included in each add-in license. The deployment ID is a GUID generated by SharePoint and recorded by AppSource the first time anyone from a specific SharePoint installation visits AppSource 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 SharePoint Add-ins

For SharePoint Add-ins that have a Per-User license, each add-in license can be assigned to the specified number of SharePoint users. The add-in license applies only to the specified SharePoint deployment and the specified users.

For add-ins with a Site license, that license is assigned to all users on that deployment automatically. The purchaser of the add-in license can use the SharePoint user interface to manage the add-in licenses he or she acquired, including assigning licenses to users and designating other users who can manage the add-in licenses. You cannot programmatically assign add-in licenses.

Best practices for add-in license checks

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 AppSource verification web service, instead of performing the license check client-side.
  • For Office Add-ins, you are required to use server-side code to query the AppSource verification web service.
  • For SharePoint Add-ins, if you are hosting your add-in pages on SharePoint, you can use the SharePoint web proxy to make JavaScript calls to the AppSource verification service. However, for security reasons we strongly recommend that you only use server-side code to query the AppSource verification web service.
Add license checks only as needed. Add license checks only at those points in your add-in 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 add-in, or when the user attempts to access certain add-in features that you want to control based on add-in license information.

For SharePoint Add-ins, do not perform add-in license checks on every page of your add-in. Constant querying of the SharePoint deployment for the add-in license token is rarely necessary, and can lead to your add-in performance being throttled.
Cache the license check appropriately. For add-ins with a perpetual unlimited user license, cache until the license token expires. For add-ins with a multiuser license, either trial or perpetual, cache per session because user assignment can change.

Make sure the production version of your add-in does not accept test licenses.

When you finish testing your add-in and are ready to move it to production, make sure you add code to the license checks in your add-in so that the add-in no longer accepts test licenses. After you pass the add-in license token to the verification service's VerifyEntitlementToken method, you can use the VerifyEntitlementTokenResponse object returned by that method to access the add-in license properties. For test add-in licenses, the IsTest property returns true and the IsValid property returns false.

Moving from paid add-ins to free add-ins

Seller Dashboard now supports moving from paid to free add-ins. You can choose within Seller Dahboard to move your paid add-ins to free. This changes what the add-in receives in the license token. The add-in will still be sent licensing tokens that contain the information about the user’s license, and those will still need to be parsed. The experience will depend on whether the license is for a new or existing user and whether the payment option was previously a subscription or a one-time purchase, as described in the following table.

Purchase type New user Existing user Action
Subscription The user will receive a free entitlement. The add-in will no longer be available to purchase but can be acquired for free; this will be returned in the token for the add-in entitlement. The user will no longer be charged after their currently billed month ends. At the end of the period they have paid for, the subscription license will be extended indefinitely to avoid any user disruption. Where a token in a free or extended subscription state is returned, you should take the opportunity to upsell the user to the new license. Some information to inform upsell decisions is maintained in the token. The license tokens will change when an add-in moves from paid to free as follows:
Update to all migrated tokens: ed="8999-12-31T23:59:59Z"
Update to all seat-based tokens: sl="true"
For seat-based tokens, where the customer previously purchased a site-license: ts="0"
For seat-based tokens, where the customer purchased 3 seats: ts="3"
One-time purchase The user will receive a free entitlement. The add-in will no longer be available to purchase but can be acquired for free; this will be returned in the token for the add-in entitlement. The user’s original purchase will still be valid. If the license was previously seat based, it will be modified to resemble a site license for the user. This will be returned in the token to the add-in. All active trial licenses will be converted to free entitlements. For existing users that return a valid paid token, those users should continue to work. If the original token was seat based, the new token will contain the originally purchased seat count. For new users, or users where the original seat count has been exceeded, you should take the opportunity to upsell the user to the new license. For most users, the license token returned to the add-in will not change. The license tokens will change when an add-in moves from paid to free for seat-based tokens:
Update to all seat-based tokens: sl="true"
For seat-based tokens, where the customer previously purchased a site-license: ts="0"
For seat-based tokens, where the customer purchased 3 seats: ts="3"

For the license token schema, see Add-in license schema.

Note

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

For information about using licensing to upsell your add-in services, see Implement licensing to upsell your Office Add-in services.

The following examples describe the experience after an add-in switches from paid to free:

  • Word user, purchased add-in via one-time purchase
    Because this user had purchased the add-in prior to the switch to free, the license token will still return an active paid entitlement for that user in the et parameter.
  • Word user, acquires free version of same add-in
    This user had not acquired the add-in when it was paid. The license token will return a free entitlement for that user in the et parameter.
  • Outlook user, purchases add-in via subscription
    In this case, the user will continue to use the subscription they paid for until the end of that billing period. The expiry date for the subscription will extend and they will no longer be charged for the add-in going forward.
  • Outlook user, acquires free version of same subscription add-in
    The user had not acquired the add-in when it was paid so the license token will return a free entitlement for that user in the et parameter.
  • SharePoint user, purchased Seat based license for three seats via one-time purchase
    In this case, the token will effectively come back as a site license but will also include the number of seats that had been purchased.
  • SharePoint user, purchased seat-based license for three seats via subscription
    In this case, the token will come back with an expiration date that will be extended. It will come back as a site license but will also include the number of seats that were acquired previously.
  • Excel user, acquired add-in as a trial
    Because this add-in was acquired prior to the trial expiration date, the trial will now return a free entitlement.
    Note: This applies for subscription or one-time purchase add-ins.

See also