What is SharePoint Add-Ins (formerly called as SharePoint Apps) – Steps and Notes

REFERENCES

https://msdn.microsoft.com/library/office/fp179930.aspx

Labs: http://dev.office.com/getting-started

Training: http://dev.office.com/training

Login: https://login.microsoftonline.com/

SharePoint Online Planning: https://support.office.com/en-us/article/SharePoint-Online-Planning-Guide-for-Office-365-for-business-d5089cdf-3fd2-4230-acbd-20ecda2f9bb8?ui=en-US&rs=en-US&ad=US

NOTES

Auto Hosted Apps have not being allowed since 30 Jun 2014 https://blogs.office.com/2014/05/16/update-on-autohosted-apps-preview-program/

SHAREPOINT HOSTED APPS

https://technet.microsoft.com/en-us/library/fp161236.aspx




Start the Subscription Settings and App Management services in Central Administration

  1. To configure the Subscription Settings service application by using Windows PowerShell

$account = Get-SPManagedAccount “domain\userid”

$appPoolSubSvc = New-SPServiceApplicationPool -Name SettingsServiceAppPool -Account $account

$appSubSvc = New-SPSubscriptionSettingsServiceApplication -ApplicationPool $appPoolSubSvc -Name SettingsServiceApp -DatabaseName SettingsService_DB

$proxySubSvc = New-SPSubscriptionSettingsServiceApplicationProxy -ServiceApplication $appSubSvc

  1. To configure the App Management service application by using Windows PowerShell

$account = Get-SPManagedAccount “domain\userid”

$appPoolAppSvc = New-SPServiceApplicationPool -Name AppServiceAppPool -Account $account

$appAppSvc = New-SPAppManagementServiceApplication -ApplicationPool $appPoolAppSvc -Name AppServiceApp -DatabaseName AppService_DB

$proxyAppSvc = New-SPAppManagementServiceApplicationProxy -ServiceApplication $appAppSvc

  1. To configure app URLs by using Windows PowerShell

Set-SPAppDomain SharePointApps.com

Set-SPAppSiteSubscriptionName -Name “smapp” -Confirm:$false

PROVIDER HOSTED APPS

Reference: https://msdn.microsoft.com/en-us/library/office/fp179901.aspx

Create high-trust SharePoint Add-ins

This article shows you how to create a high-trust add-in and provides setup instructions for running it within Visual Studio by pressing F5. You’ll learn to:

  1. Configure an add-in for use as a high-trust add-in.
  2. Configure SharePoint 2013 to use high-trust add-ins.
  3. Create a basic high-trust add-in.

Pre-requisites steps

  1. Create a self-signed certificate in IIS and export to pfx and cer format
  2. To configure SharePoint

$publicCertPath = “E:\Satyendra\Code\ProviderHostedAppIISCertificate.cer”

$certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($publicCertPath)

  1. Add the following line to ensure that SharePoint treats the certificate as a root authority.

New-SPTrustedRootAuthority -Name “ProviderHostedAppIISCertificate” -Certificate $certificate

  1. Add the following line to get the ID of the authorization realm.

$realm = Get-SPAuthenticationRealm

  1. Your remote web application will use an access token to get access to SharePoint data. The access token must be issued by a token issuer that SharePoint trusts. In a high-trust SharePoint Add-in, the certificate is the token issuer. Add the following lines to construct an issuer ID in the format that SharePoint requires: specific_issuer_GUID@realm_GUID.

$specificIssuerId = “11111111-1111-1111-1111-111111111111”

$fullIssuerIdentifier = $specificIssuerId + ‘@’ + $realm




The $specificIssuerId value must be a GUID because in a production environment each certificate must have a unique issuer. However, in this context, where you use the same certificate to debug all your high-trust add-ins, you can hard code the value. If for any reason, you use a different GUID from the one used here, be sure that all letters in the GUID are lower case. The SharePoint infrastructure currently requires lower case for certificate issuer GUIDs.

  1. Add the following lines to register the certificate as a trusted token issuer. The -Name parameter must be unique so in a production configuration, it is common to use a GUID as part (or all) of the name, but in this context, you can use a friendly name. The –IsTrustBroker switch is needed to ensure that you can use the same certificate for all the high-trust add-ins you develop. The iisreset command is required to make your token issuer registered immediately. Without it, you might have to wait as long as 24 hours for the new issuer to be registered.

New-SPTrustedSecurityTokenIssuer -Name “High Trust Sample Cert” -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier –IsTrustBroker

iisreset

  1. SharePoint 2013 does not normally accept self-signed certificates. So when you are using a self-signed certificate for debugging, add the following lines to turn off SharePoint’s normal requirement that HTTPS be used when remote web applications call into SharePoint. If you don’t, then you’ll get a 403 (forbidden) message when the remote web application calls SharePoint using a self-signed certificate. You will reverse this step in a later procedure. Turning off the HTTPS requirement means that requests from the remote web application to SharePoint are not encrypted, but the certificate is still used as a trusted issuer of access tokens which is its main purpose in high-trust SharePoint Add-ins.

$serviceConfig = Get-SPSecurityTokenServiceConfig

$serviceConfig.AllowOAuthOverHttp = $true

$serviceConfig.Update()

  1. Save the file with the name HighTrustConfig-ForDebugOnly.ps1.

Create a high-trust SharePoint Add-in

In this section, you learn how to create a high-trust SharePoint Add-in using Visual Studio.

To create a high-trust SharePoint Add-in

  1. In Visual Studio, choose File, New, Project.
  2. In the New Project wizard, expand the Visual C# or Visual Basic node, and then expand the Office/SharePoint node.
  3. Choose Add-ins, and then choose to create an Add-in for SharePoint project.
  4. Name the project HighTrustSampleApp.
  5. Save the project in a location you choose, and then choose OK.
  6. Specify the full URL of the SharePoint developer site. For example, http://TestServer/sites/devsite/
  7. Select the Provider-hosted option, and then choose the Next button.
  8. If you are prompted to specify the type of web project, select ASP.NET Web Forms Application for the continuing example in this topic, and then choose the Next button.
  9. The Configure authentication settings page of the wizard opens. The values that you add to this form will be added to the web.config file automatically. Under How do you want your add-in to authenticate? choose Use a certificate.
  10. Click the Browse button next to the Certificate location box and navigate to the location of the self-signed certificate (.pfx file) that you created (C:\Certs).
  11. The value of this field should be the full path C:\Certs\HighTrustSampleCert.pfx.
  12. Type the password for this certificate in the Password box. In this case, it is “password”.
  13. Type the issuer ID (11111111-1111-1111-1111-111111111111) in the Issuer ID box.
  14. Choose Finish. Much of the configuration is done when the solution opens. Two projects are created in the Visual Studio solution, one for the SharePoint Add-in and
  15. The other for the ASP.NET web application.




Complete debugging with a domain issued or commercial certificate

The Windows PowerShell script you created earlier turned off SharePoint’s usual requirement that remote web applications use the HTTPS protocol to access SharePoint. Working with HTTPS turned off might cause you as a developer to miss certain issues when building an add-in that would occur during a production deployment where HTTPS is required. Accordingly, you should not consider the developing and debugging phases completed until you have replaced the test certificate with a domain-issued or commercial certificate and then retested the add-in with the HTTPS requirement turned on.

When you have obtained the new certificate, you need to add a password to it, if it doesn’t already have one. In a production environment, you would use a strong password, but for debugging a SharePoint Add-in, you can use anything. You will need the certificate in two formats, pfx and cer. If it is not in pfx format when you obtain it, you may need to convert it to pfx using a utility. When you have a pfx file, you can import it into IIS and export the cer file as described in the following procedure.

To configure SharePoint 2013 to use the new certificate

Open the HighTrustConfig-ForDebugOnly.ps1 file for editing and make the following changes:

  1. Replace HighTrustSampleCert in both places where it appears with MyCert.
  2. Replace the specific issuer ID, 11111111-1111-1111-1111-111111111111, with 22222222-2222-2222-2222-222222222222 i.e. the new one.
  3. Replace “High Trust Sample Cert” with “My Cert” or some other appropriate friendly name.
  4. In the line $serviceConfig.AllowOAuthOverHttp = $true, replace the true with false. This will turn back on the requirement that HTTPS be used.

To reconfigure the remote web application

  1. In Visual Studio, open the web.config file of the web application project and make the following changes:
  2. In the ClientSigningCertificatePath key, replace C:\Certs\HighTrustSampleCert.pfx with C:\Certs\MyCert.pfx.
  3. Replace the ClientSigningCertificatePassword key value with the actual password of the certificate.
  4. Replace the IssuerId key value with 22222222-2222-2222-2222-222222222222.
  5. Press F5 to debug the add-in.

What do the TokenHelper and SharePointContext files do?

Office Developer Tools for Visual Studio includes a TokenHelper.cs (or .vb) file in the remote web application. Some versions of the tools also include a SharePointContext.cs (or .vb) file. The code in these files does the following:




  1. Configure .NET to trust certificates when making network calls.
  2. Retrieve a server-to-server access token that is signed by the remote web application’s private certificate on behalf of the specified WindowsIdentity object and that the SharePoint 2013 uses to establish trust.
  3. Get the SharePoint security token service (STS) certificate.
  4. In add-ins that use the low-trust rather than the high-trust authorization system, these files have additional tasks, such as handling OAuth tokens for the scenario described in Context Token OAuth flow for SharePoint Add-ins. That scenario is outside the scope of this article. For more details about TokenHelper and SharePointContext, see the comments in the files.

In a high-trust add-in, there is no context token. The context token is specific to configurations that use low-trust authorization. However, an access token is still required. If you’re using a high-trust configuration, your web application has to authenticate the user just as SharePoint does (that is, the add-in is responsible for creating the access token including the IDs of the user and the identity provider).

When you are debugging in Visual Studio with F5, Microsoft Office Developer Tools for Visual Studio uses Windows Authentication, and the two generated code files use the Windows identity of the person running the add-in to create the access token. When your add-in is published, you need to configure the remote web application in IIS Manager to use Windows Authentication if you want to use the two generated files without modification. If your add-in will not use Windows Authentication on the production environment, you will need to customize the generated code files, TokenHelper and/or SharePointContext, to use a different authentication system. You would also customize these files if your remote web application accesses SharePoint in an identity other than the user who is running the SharePoint Add-in. Finally, if the remote web application is PHP, node.js, Java, or some other non-ASP.NET platform, then your code needs to obtain the user’s ID from whatever authentication system is

being used, and then add that ID into the access token it constructs.

Package and publish high-trust SharePoint Add-ins

Reference: https://msdn.microsoft.com/en-us/library/office/jj860570.aspx

Register the high-trust add-in

Before you can publish the add-in, it has to be registered with the SharePoint farm’s add-in management service. High-trust SharePoint Add-ins are always registered on the SharePoint farm on which the add-in is to be installed. (They cannot be sold through the Office Store.) Registration is done on the page http://SharePoint_website/_layouts/15/appregnew.aspx as described in the following procedure.

To register the add-in

(Redirect URL concept: Authorization Code OAuth flow for SharePoint Add-ins: https://msdn.microsoft.com/en-us/library/office/jj687470.aspx)

E.g. https://blogs.msdn.microsoft.com/russmax/2014/06/26/part-2-intro-to-provider-hosted-apps-develop-package-and-deploy/

  1. Start Visual Studio 2013 and choose File, New Project.
  2. In the New Project wizard, expand the Visual C# or Visual Basic node, and then expand the Office/SharePoint node.
  3. Choose Apps, and then choose to create an App for SharePoint 2013 project.
  4. Name the project whatever you want. In my case: RemoteSampleApp.
  5. Ensure you point the URL to the developer site you created in SharePoint 2013
  6. Save the project in a location you choose, and then choose OK.
  7. Select the Provider-hosted option, and then choose the Next button.




Note: The site inputted above should point to the developer site

  1. If prompted to specify the type of web project, select ASP.NET Web Forms Application for the continuing example in this topic, and then choose the Next button
  2. For the Configure authentication settings page perform the following steps:
  3. Click the Browse button next to the Certificate location box and navigate to the location of the self-signed certificate (.pfx file) that you created (C:\Certs). The value of this field should be the full path C:\Certs\remotewebapps.pfx. (Note: this is my cert created from part 1 (previous blog) here)
  4. Type the password for this certificate in the Password box. In this case, it is “password”.
  5. Type the issuer ID (11111111-1111-1111-1111-111111111111 it is specific to sharepoint farm) in the Issuer ID box. (Note this is the issuer id (random guid) associated to the sptrustedsecuritytokenissuer I created from part 1 (previous blog) here)
  6. Click finish and the default.aspx page automatically opens so added a paragraph to the page and saved it.
  7. This step is just for observation purposes) Click on the AppManifest.xml for the app looks like the following:

Note: the Start page contains the virtual directory, path, and page name that will be deployed on the remote web.

  1. Save Project and Build the Solution

Register App in SharePoint Farm

The next step is the app must be registered in the SharePoint farm where it will be deployed. We also require the App ID generated for Visual Studio 2013 when we build the app package.

  1. Access any site and append /_layouts/15/appregnew.aspx
  2. Click Generate buttons for both App Id and App Secret fields.
  3. The App Domain is the domain name set on the remote web application server’s IIS Site that will be hosting this app.
  4. The redirect URI isn’t required in my case so click create button which produces the following:
  5. Copy the output as it’s needed during the packaging phase.

Publish the App Web (remote Web)

Publishing the App Web builds a package that includes files and a script. These files are copied to the remote web server and deployed. First, in Visual Studio 2013 you’ll have two different projects created. One is for the app which produces an app file and that file is uploaded to the app catalog and made available to SharePoint Sites. The second project is for the remote web and is a simple asp.net web application. In my case, RussMaxSecProvHostedApp is the app project and RussMaxSecProvHostedAppWeb is the remote web project. These steps apply to the remoteweb.

  1. Right click the “RussMaxSecProvHostedAppWeb” and hit publish.
  2. Created a New Profile and set the connection like the following

Note: In my case, I want all of my provided hosted apps living under the default web site as a virtual directory. So I specified the site name as “Default WebSite/RussMaxSecProvHostedApp”




  1. Click next and choose Release
  2. Choose Next
  3. Click Publish and Success!
  4. Checking the directory I have the package
  5. Copy this directory + output to the IIS Server hosting this remote web.

Deploy and Test Remote Web

At this point, the app/remote web package has been copied to the remote web server.

  1. Start Command Prompt and navigate to the directory containing the package files
  2. Run the following command

yourproviderhostedappwebname.deploy.cmd /y

Note: In my case it’s: russmaxsecprovhostedappweb.deploy.cmd

Note 2: It finished successfully and refreshing IIS gives me the new site.

  1. Test by manually attempted to browse to the site.

https://remoteweb/russmaxsecprovhostedapp/pages/default.aspx

And Page renders.

Note: I had to remove the inherits element from default.aspx page because of a server side error. In my case, I removed: Inherits=”RussMaxSecProvHostedAppWeb.Default”

Publish the App

At this point, the remotewebapp project has been packaged and deployed to the remoteweb. The final step includes publishing the app, deploying to the desired SharePoint 2013 app catalog, and finally installing the app to a team site and test.

  1. Within Visual Studio 2013, right click the “RussMaxSecProvHostedApp” and hit publish.
  2. Click Edit and fill out the fields.

Note: The client ID is the App ID which came from the appregnew page. The Issuer ID is assigned to the associated SPTrustedSecurityTokenIssuer object. I assume you know what this ID is?

  1. Hit OK and then click Package the App

Important: You must point at your site + virtual directory. In my case, the RussMaxSecProvHostedApp will be created under the Default Web Site like

https://localhost:8080/MyProviderHostedSharePointApp

  1. Click Finish and it builds the app package automatically.

Note: It automatically opens windows explorer to the app.

  1. Copy this file over to a server that can access the app catalog.

Add App to App Catalog

For an App to be consumed, it must be added to an app catalog.

  1. Navigate to the app catalog and select Apps for SharePoint
  2. Select New App and upload the .app file produced from the last set of steps

Install App to a site

  1. Access a team site and select site contents and click Add App.
  2. Click on it and click Trust It




Note: If it errors on this step and you’re logged in as the system account, try again using a non-system account.

  1. after install, test by clicking on the app.
  2. and the redirect works!

Web.Configs

APP

     Name=”MyProviderHostedSharePointApp”

     ProductID=”{80b0e602-cd1c-4b7a-b785-d5cfe0d7d201}”

     Version=”1.0.0.0″

     SharePointMinVersion=”15.0.0.0″>  

   MyProviderHostedSharePointApp

    ~remoteAppUrl/Pages/Default.aspx?{StandardTokens}

ADD-IN AUTHORIZATION POLICY TYPES IN SHAREPOINT 2013

Learn about the different authorization policies for add-ins in SharePoint: add-in-only policy, user + add-in policy, and user-only policy. It also provides guidelines for using add-in-only policy.

SharePoint provides three types of authorization policies:

User-Only policy

When the user-only policy is used, SharePoint checks only the permissions for the user. SharePoint uses this policy when the user is accessing resources directly without using an add-in, such as when a user first opens a SharePoint website’s home page or accesses SharePoint APIs from PowerShell.

User Add-in policy

When the user-add-in policy is used, SharePoint checks the permissions of both the user and the add-in principal. Authorization checks succeed only if both the current user and the add-in have permissions to perform the action in question.

For example this policy is used when a SharePoint Add-in wants to get access to the user’s resources on SharePoint. (The code in the remote components of the SharePoint Add-in have to be designed to make user-add-in calls to SharePoint.)

Add-in-Only policy

When the add-in-only policy is used, SharePoint checks only the permissions of the add-in principal. Authorization checks succeed only if the current add-in has sufficient permissions to perform the action in question, regardless of the permissions of the current user (if any).

See an example scenario of an add-in that uses the add-in-only policy

Let’s says a sales manager at Contoso, Adam, buys an expense submission add-in that uses the add-in-only policy. When Adam chooses to buy the add-in, Adam is prompted to allow the add-in to elevate user permissions; that is, to allow the add-in to make add-in-only calls to SharePoint. Adam grants the add-in the requested permissions. He then purchases enough licenses of the add-in for all of the Contoso sales people, and he installs the add-in in the sales team’s SharePoint website.




Soon, the salespeople are submitting expense reports using the new expense submission add-in. Salespeople usually cannot approve their own expense reports, but they can do this when using the add-in because Adam granted it the ability to do this for expense submissions below $50 because he set the add-in to automatically approve reports below $50. The add-in automatically assigns him a task to approve reports of $50 or more. This could be implemented by giving the SharePoint Add-in Write permission to a SharePoint list of approved expenses. But, among users, only human resources managers have Write permission to the list. The code in the add-in is designed to add the expense to the list by making an add-in-only call to SharePoint whenever the expense is less than $50. Since the user’s permissions aren’t checked, any user’s submissions below $50 are automatically added to the approved expenses list, even if the user doesn’t have Write permission to the list.

Learn how add-ins get permission to use the add-in-only policy

To be able to make add-in-only calls to SharePoint, your add-in must request permission to use the add-in-only policy. This request is made in the add-in manifest. You do this by adding the AllowAppOnlyPolicy attribute to the AppPermissionRequests element and setting it to true as shown in the following markup:

Note: Add-ins that do not make OAuth authenticated calls (for example, add-ins that are only JavaScript running in the add-in web) cannot use the add-in-only policy.

They can request the permission, but they will not be able to take advantage of it because doing so requires passing an add-in-only OAuth token. Only add-ins with web applications running outside of SharePoint can create and pass add-in-only tokens.

Like, Share & Subscribe!




Be Connected…

Satyendra

,

About Satyendra Mishra

Satyendra is a Technical Project Manager with 12+ years of experience on Project Management, Microsoft Technologies including ASP.NET, ASP.NET MVC, C#, SharePoint (On premises & Office 365), JavaScript Framework (AngularJS) and related technologies. He is a person with belief, sky is limit for a hard working and dedicated individual. That’s why he devoted himself to field of Software Development and now both are growing with each other. Every year for him turned out to be best year and he received enormous support and love from his companies and his clients from around the world. Now with vast knowledge of software development and its outsourcing process, he decided to move himself into knowledge sharing. Keep a fact in your mind about the comfort level of your clients and this will make you king/queen of your area.
View all posts by Satyendra Mishra →

Leave a Reply

Your email address will not be published. Required fields are marked *