SharePoint Server 2016 AddIn Environment Configuration



Published: 4 November 2017

In the older SharePoint Days, we were mostly using Server Side Object Model to customize SharePoint. Since the code ran within the main W3WP thread, deployments resulted in brief downtime and increased the risk that came along with untested code. Moreover, Server Side code was not feasible with Office 365 based SharePoint Online implementations. To overcome the sharing of the SharePoint thread by the code, Sand boxed solutions were introduced that executed in its own SPUCWorkerProcess. However, they had their own limitations and are in a deprecated stage now.

Later, SharePoint Add-ins were introduced which leveraged the client side development approach and helped developers deploy solutions to Office 365 SharePoint Online as well as On Premise. In addition to it, the Add-ins were installed in the app web which was separate from the main SharePoint Host web creating the required isolation

SharePoint provides two types of add-ins (Previously Apps)

SharePoint Hosted Add-ins

Used to deploy SharePoint resources like pages, lists, workflows, custom content types, list templates, Web Parts and so on. It cannot contain custom server side object model code but supports REST and JSOM.

Provider Hosted Add-ins

Used to deploy components outside the SharePoint Farm. It can include a web application, web service or database that is deployed outside SharePoint.

 In this article we will see how to configure the Add-In environment in a multi-server farm environment so as to get started with SharePoint 2016 Add-In development . We have the below topology in the farm :

  • VM01Azure AD acts as the AD Server where we will create the domain and forward look up zone used by the AddIn
  • SharePoint 2016 Server with Host Name SharePoint2016 where we will be deploying the AddIn
  • IIS Server with Host Name SP2016 where we will be deploying the AddInWeb in the case of a Provider Hosted AddIn. For SharePoint Hosted AddIns, we just need the first two server setup.

The reason why we have the AD Server in the above picture is because we need to create a separate domain as AddIns reside in their own domain knows as AppWeb. A normal HostWeb URL will look like below

However once we have deployed the AddIn, its URL will be of the below format :

Decomposition of the AddIn URL is given below :

Get Started with AddIn Environment Configuration 

One of the benefits of SharePoint add-ins is that they run in their own isolated domain, unlike the farm solutions that shares the process thread, resulting in performance risks. So, one of the prerequisites of SharePoint add-ins is that a domain has to be configured in the DNS. We can add the domain by going to the DNS configuration tool.

As part of security, while creating the domain for the app, it should not be a sub-domain of an existing domain. Say, if we have a domain of the name SharePoint2016.com, instead of creating Apps.SharePoint2016.com, we should be creating a domain of the format SharePoint2016Apps.com.

When an add-in is provisioned, it creates a unique domain name, like 23131123asas.SharePoint2016Apps.com, where 23131123asas is the unique identifier for the app. In order for the DNS domain to support these kinds of unique name, we will also have to set up a wildcard Canonical Name (CNAME).The process of setting up the domain and configuring the Add-In Environment can be summed up as,

  • Create Forward Lookup Zone
  • Add CNAME
  • Create Subscription settings service application
  • Configure App URL in Central Admin

Create Forward Lookup Zone

As the first step, let’s create a Forward Lookup Zone. In order to do this, one has to be a domain administrator.

From the DNS Manager, right click ‘Forward Lookup Zones’ and click on ‘New Zone’.

This will start the New Zone Wizard. Click on Next.

Select the zone type as ‘Primary’ and click on Next. 

In the Active Directory Zone Replication Scope page, select the appropriate replication method. By default, it is set as : ‘To all DNS servers running on domain controllers in this domain’.

This is the main stage where we get to specify the App Domain Name. Specify the name and click on Next.

Select the required dynamic update option. For Active Directory integrated zones, select ‘Allow only secure dynamic updates’.

Thus, we have completed the creation of the Forward Lookup Zone.

The new zone has come up in the available list of zones.

Add CNAME

Now, we can add a wildcard CNAME for the newly created domain. Right click the newly created zone and select ‘New Alias(CNAME)’.

Specify ‘*’ as the wildcard alias and this will automatically add ‘*.NewlyCreatedDomainName’ as the fully qualified domain name.

Now, we have to specify the FQDN for the target host. In case of a single server environment, Select "Browse" and go to the Forward Lookup Zone and double click it. Double click the domain that hosts the SharePoint sites. From there, select the record “same as parent folder” and click OK. This will work okay in case of a single server environment

However, in case of a multi-server farm like ours, ensure that you point to the DNS Record of the SharePoint server as shown below:

In our case the AD is configured in VM01-AzureAD and the SharePoint Server has the host name SharePoint2016.

So we will navigate to the SharePoin2016 record and select it. 

Click on OK. 

This completes the setting up of DNS entry. In order to ensure that the newly created domain name is working, we can try pinging it. If it returns an IP with successful delivery of data packets, we can be sure that the wildcard for the domain name was set up successfully.

Ping SharePoint2016.AzureAD.Contoso.com

Create Managed Account 

Before creating the service applications required for starting Add-in development, we will create the managed account that will be assigned to the App Management Service Application. Head over to Security->Configure Managed Accounts

Specify the managed account and password for the account and click on OK. This will provision the managed account. 

Create App Management Service Application and Subscription Settings Service Application

Once we have set up the DNS entry, we have to set up the Subscription Settings Service application and the App Management Service Application. App Management Service Application can be created from the Central Admin UI which is pretty straight forward.

App Management Service Application

In order to create the app management service application, select "Manage service applications" from Application Management and Select "App Management Service".

It will open up the window where we can specify the Service Application name and database name. 

Specify the app pool name and service account that will be used for the service application and click on OK.

This will start provisioning the App Management Service Application.

After some time, you will see the Service Application created and listed out.

Subscription Settings Service Application

Unlike App Management Service Application. Subscription Settings Service Application cannot be created from UI. Instead we will create it using PowerShell cmdlets as shown below;

Thus, the subscription settings service application has been created.

Configure App URL

Now, let’s configure the app URL. In order to do that, go to the Apps section in the Central Administration.

Click on Configure App URLs.

This will open up the page where we can add the app domain and app prefix.

SPjourney.com was the app domain that was created. Specify the app prefix which will come up prepended in the app URL in the browser.In case you face the below error while saving the page, it is an indication that the Subscription Settings Service Application has some configuration issue. Try restarting it.

We can verify the services is running by going to Services on Server page. 

Thus we have completed the Add-In Environment configuration. From this point we should be able to create SharePoint Hosted Add-in. However if we have to create High TrustProvider Hosted Add-in, we will have to complete the below two sections as well:

  • Setup Certificate for High Trust Provider Hosted Add-ins
  • Create SPTrustedSecurityTokenIssuer

Setup Certificate for High Trust Provider Hosted Add-ins

When we are developing highly-trusted Provider Hosted Add-ins, we will be using a self-signed certificate for Add-in authentication. However, in production, we will have to use a third-party provided trust certificate and self-signed certificate is not really an option. Let’s see how to generate the self-signed certificate for use with Provider Hosted add-in development.

Spin up IIS Manager and select ‘Server Certificates’.

Click on "Create Self-Signed Certificate" from the right window pane.

Specify a name for the certificate.

Click on OK. It will create the certificate which will be listed in the Server Certificates. 

Right click the certificate and click on Export.

Specify the export location and the password. This will export a ‘.pfx’ file in the specified location.Ensure to safely store the certificate password as it will be needed during Provider Hosted AddIn development.

Now, we have to generate the ‘.cer’ file. Double click the recently created certificate. 

From the details section, click on ‘Copy to File’.

This will open up the Certificate Export Wizard. 

Choose not to export the Private key and click on Next.

Select DER Encoded Binary X.509 format and proceed. 

Specify the export location and click on Next.

This will generate a .cer file in the export location.

Once we have the certificates, Copy the certificate to SharePoint Server.

Create SPTrustedSecurityTokenIssuer

As the final step, we will have to create SPTrustedSecurityTokenIssuer using the copied certificates. The token issuer is responsible for creating authentication tokens using the High Trust Certificate. 

Run Get-SPTrustedSecurityTokenIssuer to get the id of the Token Issuer and keep it safe as we will be re using the same ID while creating any Provider Hosted Add Ins. Here the Issuer ID is e66d3aab-f5dc-44a4-85ac-d707d02f6d79. It is the first part that precedes the @ sign in the RegisteredIssuerName value 

Test the Add-In Environment Configuration. 

To ensure that the Add-In environment configuration was completed successfully, we can create a dummy empty SharePoint Hosted Add-In. If it is successfully added to the SharePoint Site, we can be sure that the configuration was successful. Lets see some of the common issues :

  • Local SharePoint Server is not available :

One of the causes for this error is insufficient permission to the Central Admin and Configuraiton database. So provide dbowner rights to both the databases.

  • Login failed for user

The user should have SPDataAccess role membership in the App Management service application. Else we might get the below error message while deploying the app.

We can get more details of the error from the ULS logs. 

In case of authentication issues, identify the database and grant the required permissions. 

  • Sideloading of apps is not enabled :

This occurs because the sideloading feature is not enabled in the site. This is a default behavior to prevent unintended app deployment in the production servers. 

We can enable the side loading feature by running the below commands :

$site = Get-SPSite "http://sharepoint2016:50001"

$sideLoadingId = new-object System.Guid "ae3a1339-61f5-4f8f-81a7-abd2da956a7d"

$site.Features.Add($sideLoadingId)

Summary

Thus we saw how to configure the environment for SharePoint/Provider Hosted Add-in development in SharePoint Server 2016. In the upcoming article we will see how to create Provider Hosted Add-in and Remote Event Receivers. 



Join 7,000 subscribers and receive instant access to

Devendra's Library of Resources for SharePoint Developers


About Author

Priyaranjan is a SharePoint Consultant with 7+ years experience in developing and deploying SharePoint Applications.He has worked on various SharePoint iterations starting from MOSS 2007 through SharePoint 2016 and Office 365. He is a frequent contributor at Microsoft TechNet and has won 33 Gold Medals in various TechNet Wiki Guru Monthly Competitions.As a token of appreciation for the TechNet community activities, he was interviewed by Microsoft Program Manager,Ed Price. He has also published 300 Articles and 4 SharePoint Ebooks in different technical communities.You can find his Microsoft TechNet contributions here