SharePoint Tenants

Tested with SharePoint 2013 on premise, though should still apply to 2016 on premise.

So, while this isn't about my current home project, I ran into this at work today with my client.

The client needed to build a SharePoint hosted Add-in that could make REST calls across site collections.

The logic is to use the Tenant permission for the add-in, this is where you find it when building the add-in:


The above image just shows well, which allows the app permission to a web site.

There are the following:

  • Site Collection
  • List
  • Web
  • Tenant

In this post we are talking about Tenant.

Now there is an automatic assumption that if you pick tenant, then you must have a tenant to apply it to. I had made this mistake, but it's not true. A web app even one using host named site collections is a tenant. Each web application has it's own app catalog.

With a tenant, each tenant has it's own app catalog too. The purpose of a tenant is so that one web application can host several tenants. Each one with it's own management site, each one with its own app catalog. This can be useful even within a company, separate departments like HR might have a need to keep any applications available only to site collections belonging to HR.

Back to the issue at hand, a tenant is not needed when you set the tenant permission. Note: in order for your add-in to be able to make calls across site collections of a web app or tenant, it can only be deployed to the app catalog. That's right, your add-in has to first be added as an add-in to the app catalog and then Site Content/Add App/Apps from your organization. This isn't clean and it's understandable why someone wouldn't want to put it right on the site the app catalog is. Though you can create sub sites off the app catalog site collection. This is a good reason to have the app catalog site collection as a host header site collection. Such as, that way any tenant apps would be off sub sites. Such as

Now that we have resolved that you DO NOT need a tenant to have a SharePoint app go across site collections.

Lets look at what it takes to create a tenant.

A few things to keep in mind:

  1. Once you add a site as a tenant, it will no longer see the app catalog site setup for the web application.
  2. SharePoint on premise it's called a Subscription (confusing I know, as all the scripts and help is listed as subscription).
  3. When using Host Named site collections you must take additional steps, because each site collection created has it's own URL, using the UI may not be desirable.

Now you have several site collections each with a URL:


NOTE: The app catalog site collection must use a special template, review the following for creating the App catalog site.

New-SPSite -Url -OwnerAlias "Contoso\sp_admin" -Name "Contoso App Catalog" -Template "APPCATALOG#0"

Lets setup some variables:

$app = "http://URLDefaultAAM" #such as http://machinename:3456

$primaryAdmin = "domain\user"

 Now set the app domains for multiple domains, this setups each domain/tenant to have its own app domain.

 Step 1)

 $contentService = [Microsoft.SharePoint.Administration.SPWebService]::ContentService

$contentService.SupportMultipleAppDomains = $true



Step 2)

 New-SPWebApplicationAppDomain -AppDomain <AppDomain> -WebApplication <WebApplicationID> -Zone <Zone> -Port <Port> -SecureSocketsLayer

NOTE: if you get the error: Failed to connect to an IPC Port. This simply means you don't have a web app running at that port.

Also NOTE: if you get an exception "The App domain for this site has already been assigned" then restart the server.

Next step is to create the subscription and administration site collection: (note the site template)

New-SPSSiteSubscription | %{New-SPSite -url -hostheaderwebapplication $app -ownerAlias $primaryAdmin -language 1033 -sitesubscription $_ -Template "TenantAdmin#0"}

 The above creates a subscription and sets up the site collection to administer that subscription

Next get the subscription:

$sub = get-SPSiteSubscription -identity

You must set what the tenant administration site is:

Set-spsiteadministration -identity

Review the following in regards of the above command and why:

It's time to set up which site collections are in this tenant:

Run the following for each site collection that is to be part of the tenant:

Get-spsite | set-spsite -sitesubscription $sub

Get-spsite | set-spsite -sitesubscription $sub

Get-spsite | set-spsite -sitesubscription $sub

Get-spsite | set-spsite -sitesubscription $sub

Finally set the app catalog for the tenant:

Update-SPAppCatalogConfiguration -site -force:$true

Now give a name for your subscription/tenant

Set-SPAppSiteSubscriptionName -Name "Name for Subscription" -SiteSubscription $Sub

That's all there is to it, you now have a tenant!

Each tenant you create will have it's own app catalog, you can navigate to the tenant administration site to manage your tenant.

Important things to keep in mind:

  1. If a tenant permissioned add-in is deployed outside of the app catalog site collection, cross domain calls will trigger a prompt for credentials. The user gets three prompts and nothing but access denied is sent back for the call.
  2. If a site collection is added to a tenant, you will no longer see the app catalog of the web application. That app catalog settings in Central administration is only for web applications not site collections that are part of a subscription. This can be confusing for some but realize that this is the case and it makes sense.
  3. To remove a site collection from a subscription use the "Remove-SPSiteSubscription" command. As shown here:


Comments (0)

Skip to main content