Blog- SoHo Dragon

#DragonTalk

How to Create a High-Trust, Provider-Hosted Add-In?

If you've been wondering how you can create your own high-trust, provider-hosted add-ins: look no further! One of our experienced and technically skilled Senior SharePoint Developers; Suhil Jisahebwala, explains and shows you how to get it done!

In short, there are 3 steps to take:

  1. 1. Generate .cer file from the .pfx file
  2. 2. Register Certificate to the SharePoint Environment
  3. 3. Create Provider-Hosted Add-In 

Before you start creating your add-in, you must have the certificate of the server on which you're going to host your IIS website. We'll be registering the IIS server certificate with SharePoint. *Note: this is not required when you do the development of the add-in as your request will execute under the local IIS. This step is only required when you host your web-app under IIS.
Let's get started with registering your WebApp server's certificate to the SharePoint environment. In a deployment package, there's a PowerShell script that needs to be executed on the SharePoint server. That will register the WebApp server's certificate to your SharePoint.

A certificate with SharePoint is now registered.

New call-to-action

1. Generate a .cer file from the .pfx file

  • a) Connect to your WebApp server
  • b) Go to IIS
  • c) Open "Server Certificates" (see screenshot below)

1 . 1 Generate .cer file

  • a) Double-click on the valid certificate for your WebApp server.
  • b) Click on the "Details" tab.
  • c) Select "Copy to File".
  • d) In the welcome wizard click Next >>> No, do not export the private key >>> Next >>> Select export format (you can keep the default selected) >>> Next >>> Provide filename >>> Finish.

If you've executed the steps mentioned above, you'll now have the .cer file you need.

1 . 2 Generate .pfx file

Do not perform this step if you already have a <certificate>.pfx file.

  • a) Go to IIS >>> Server Certificates.
  • b) Select the certificate you want to export >>> Right-click on the Certificate >>> Select Export.
  • c) Export your .pfx file to the same location as where you previously saved your .cer file.

You now have two files available as shown in the image below.

  • 1) Your "Security Certificate" (.cer).
  • 2) Your "Personal Information Exchange" (.pfx).

Copy those files to your SharePoint App Server. Keep both files at the same location (e.g. C:\Cert\)

2. Register Certificate to the SharePoint environment

Now that your .cer and .pfx files are in order, it's time to move on to the next step. Get ready to register the Certificate your WebApp Server Certificate!

2 . 1 Generate Issuer ID

  • a) Connect to your SharePoint App Server to which we've just copied your Security Certificate & Personal Information Exchange.
  • b) Open SharePoint Management Shell.
  • c) Execute "HighTrustConfig-ForSharedCertificate.ps1 PowerShell script with the required parameter. (Please find the script below)

param(
    [Parameter(Mandatory)][String] $CertPath = $(throw "Usage: HighTrustConfig-ForSharedCertificate.ps1 -CertPath <full path to .cer file> -CertName <name of certificate> [-TokenIssuerFriendlyName <friendly name>]"),
    [Parameter(Mandatory)][String] $CertName,
    [Parameter()][String] $TokenIssuerFriendlyName
)
# Stop if there's an error
$ErrorActionPreference = "Stop"
# Ensure friendly name is short enough
if ($TokenIssuerFriendlyName.Length -gt 50)
{
    throw "-TokenIssuerFriendlyName must be unique name of no more than 50 characters."
}
# Get the certificate
$certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($CertPath)
# Make the certificate a trusted root authority in SharePoint
New-SPTrustedRootAuthority -Name $CertName -Certificate $certificate
# Get the GUID of the authentication realm
$realm = Get-SPAuthenticationRealm
# Generate a unique specific issuer ID
$specificIssuerId = [System.Guid]::NewGuid().ToString()
$specificIssuerId
# Create full issuer ID in the required format
$fullIssuerIdentifier = $specificIssuerId + '@' + $realm
# Create issuer name
if ($TokenIssuerFriendlyName.Length -ne 0)
{
    $tokenIssuerName = $TokenIssuerFriendlyName
}
else
{
    $tokenIssuerName = "High-Trust Add-ins " + [System.Convert]::ToBase64String($specificIssuerId.ToByteArray()).TrimEnd('=')
}
# Register the token issuer
New-SPTrustedSecurityTokenIssuer -Name $tokenIssuerName -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier -IsTrustBroker
# Output the specific issuer ID to a file in the same folder as this script. The file should be given to the developer of the high-trust SharePoint Add-in.
$specificIssuerId | select * | Out-File -FilePath "SecureTokenIssuerID.txt"

  • d) CertPath: the path to the certificate.
  • e) CertName: name to the Certificate (can be any).
  • f) TokenIssuerFriendlyName: friendly name (can be any).

SharePoint 2016 Administrator Management Shell

  • g) Once you've executed the command, you should see a window like a screenshot below. From that image, please copy your Issuer ID as highlighted in yellow.

  • h) Now you can verify whether the Certification has been registered with SharePoint, or not. To do so, open "Central Administration" in the SharePoint Application Server. Then select "Security" >>> Manage Trust.
  • i) In this window, you'll find your Certificate details with the name that you provided in the earlier executed command.

2 . 2 Get Personal Information Exchange's file-path and password

  • a) Go to the WebApp Server.
  • b) Navigate to the path where you've stored your Security Certificate & Personal Information Exchange.
  • c) Copy "Personal Information Exchange" file-path and its password into the same notepad file in which you've stored your Issuer ID in our earlier steps.

2. 3 Get Certificate's serial number

  • a) Go to the WebApp Server.
  • b) Navigate to the path where you've stored your Security Certificate & Personal Information Exchange file.
  • c) Double click on "Security Certificate file".
  • d) From the dialog box, click on the "Details" tab.
  • e) In the window that'll show, you will find the "Serial Number". Cope & paste that (remote the space) in the same notepad file in which you've stored your Issuer ID, Full Path and Certificate Password.

After performing the steps above, your notepad should look like the image you see below.

3. Create Provider-Hosted Add-In

  • a) Start Visual Studio.
  • b) Navigate to File >>> New >>> Project.
  • c) Select Templates >>> Visual C# >>> Office/SharePoint >>> SharePoint Add-In.
  • d) Provide the Add-In with a name and location and click "OK" to create a solution.

  • e)  Once you click "OK" it'll ask for the Site where you want this Add-In to be installed. Provide the site URL and select "Provider Hosted" (given we're creating a Provider-Hosted Add-In) and click on "Next".

  • f) You'll also need to provide the SharePoint Version on which your newly created Add-In will be deployed. Once you are done, click "Next".

  • g) Then select which type of Web Application project you want to use - we're using the ASP.Net Web Forms Application -. Click "Next".

  • h) Next up is your choice on how you want your Add-Inn to authenticate. Please select "Use a certificate (for SharePoint on-premises add-ins using high-trust)" and provide the Certificate Location / Password and Issuer ID that we previously generated. Done? Click "Finish"! (Yes, almost there...)

By clicking "Finish" in the previous step you've created a solution called "HighTrustAddIn".

Project “HighTrustAddInWeb” is a web-based project which will be deployed into your IIS&nbsp;and it'll be deploying add-ins onto the production server. This solution contains a config file which stores the configuration details (ClientSigningCertificatePath/Password/IssuerID) that you provided while creating the solution as shown in the image below.

a) There are few more App settings that we need to define in the web.config file like ClientID, ClientSigningCertificateSerialNumber, ClientSecret.
b) When you are running the add-in from the visual studio, you don't need to worry about the settings mentioned above, as Visual Studio will create a client ID while your app is in running mode.
c) There will be one page called “Default.aspx” which is automatically in a template. When you open the .cs file, there will be code that displays the web name on the page.


Now, when you hit F5 you'll see that your newly created Add-In will install and automatically uninstall any Add-Ins that were already deployed in the site. During the deployment, it'll also update the Client ID in the web.config file.

By performing all of the steps mentioned above you've now developed a High-Trust Provider-Hosted Add-In! Congratulations!

1. Generate a .cer file from the .pfx file

  • a) Connect to your WebApp server
  • b) Go to IIS
  • c) Open "Server Certificates" (see screenshot below)

1 . 1 Generate .cer file

  • a) Double-click on the valid certificate for your WebApp server.
  • b) Click on the "Details" tab.
  • c) Select "Copy to File".
  • d) In the welcome wizard click Next >>> No, do not export the private key >>> Next >>> Select export format (you can keep the default selected) >>> Next >>> Provide filename >>> Finish.

1 . 2 Generate .pfx file

Do not perform this step if you already have a <certificate>.pfx file.

  • a) Go to IIS >>> Server Certificates.
  • b) Select the certificate you want to export >>> Right-click on the Certificate >>> Select Export.
  • c) Export your .pfx file to the same location as where you previously saved your .cer file.

  • 1) Your "Security Certificate" (.cer).
  • 2) Your "Personal Information Exchange" (.pfx).

Copy those files to your SharePoint App Server. Keep both files at the same location (e.g. C:\Cert\)

2. Register Certificate to the SharePoint environment

Now that your .cer and .pfx files are in order, it's time to move on to the next step. Get ready to register the Certificate your WebApp Server Certificate!

2 . 1 Generate Issuer ID

  • a) Connect to your SharePoint App Server to which we've just copied your Security Certificate & Personal Information Exchange.
  • b) Open SharePoint Management Shell.
  • c) Execute "HighTrustConfig-ForSharedCertificate.ps1 PowerShell script with the required parameter. (Please find the script below)

param(
    [Parameter(Mandatory)][String] $CertPath = $(throw "Usage: HighTrustConfig-ForSharedCertificate.ps1 -CertPath <full path to .cer file> -CertName <name of certificate> [-TokenIssuerFriendlyName <friendly name>]"),
    [Parameter(Mandatory)][String] $CertName,
    [Parameter()][String] $TokenIssuerFriendlyName
)
# Stop if there's an error
$ErrorActionPreference = "Stop"
# Ensure friendly name is short enough
if ($TokenIssuerFriendlyName.Length -gt 50)
{
    throw "-TokenIssuerFriendlyName must be unique name of no more than 50 characters."
}
# Get the certificate
$certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($CertPath)
# Make the certificate a trusted root authority in SharePoint
New-SPTrustedRootAuthority -Name $CertName -Certificate $certificate
# Get the GUID of the authentication realm
$realm = Get-SPAuthenticationRealm
# Generate a unique specific issuer ID
$specificIssuerId = [System.Guid]::NewGuid().ToString()
$specificIssuerId
# Create full issuer ID in the required format
$fullIssuerIdentifier = $specificIssuerId + '@' + $realm
# Create issuer name
if ($TokenIssuerFriendlyName.Length -ne 0)
{
    $tokenIssuerName = $TokenIssuerFriendlyName
}
else
{
    $tokenIssuerName = "High-Trust Add-ins " + [System.Convert]::ToBase64String($specificIssuerId.ToByteArray()).TrimEnd('=')
}
# Register the token issuer
New-SPTrustedSecurityTokenIssuer -Name $tokenIssuerName -Certificate $certificate -RegisteredIssuerName $fullIssuerIdentifier -IsTrustBroker
# Output the specific issuer ID to a file in the same folder as this script. The file should be given to the developer of the high-trust SharePoint Add-in.
$specificIssuerId | select * | Out-File -FilePath "SecureTokenIssuerID.txt"

  • d) CertPath: the path to the certificate.
  • e) CertName: name to the Certificate (can be any).
  • f) TokenIssuerFriendlyName: friendly name (can be any).

  • g) Once you've executed the command, you should see a window like a screenshot below. From that image, please copy your Issuer ID as highlighted in yellow.

  • h) Now you can verify whether the Certification has been registered with SharePoint, or not. To do so, open "Central Administration" in the SharePoint Application Server. Then select "Security" >>> Manage Trust.
  • i) In this window, you'll find your Certificate details with the name that you provided in the earlier executed command.

2 . 2 Get Personal Information Exchange's file-path and password

  • a) Go to the WebApp Server.
  • b) Navigate to the path where you've stored your Security Certificate & Personal Information Exchange.
  • c) Copy "Personal Information Exchange" file-path and its password into the same notepad file in which you've stored your Issuer ID in our earlier steps.

2. 3 Get Certificate's serial number

  • a) Go to the WebApp Server.
  • b) Navigate to the path where you've stored your Security Certificate & Personal Information Exchange file.
  • c) Double click on "Security Certificate file".
  • d) From the dialog box, click on the "Details" tab.
  • e) In the window that'll show, you will find the "Serial Number". Cope & paste that (remote the space) in the same notepad file in which you've stored your Issuer ID, Full Path and Certificate Password.

After performing the steps above, your notepad should look like the image you see below.

3. Create Provider-Hosted Add-In

  • a) Start Visual Studio.
  • b) Navigate to File >>> New >>> Project.
  • c) Select Templates >>> Visual C# >>> Office/SharePoint >>> SharePoint Add-In.
  • d) Provide the Add-In with a name and location and click "OK" to create a solution.

  • e)  Once you click "OK" it'll ask for the Site where you want this Add-In to be installed. Provide the site URL and select "Provider Hosted" (given we're creating a Provider-Hosted Add-In) and click on "Next".

  • f) You'll also need to provide the SharePoint Version on which your newly created Add-In will be deployed. Once you are done, click "Next".

  • g) Then select which type of Web Application project you want to use - we're using the ASP.Net Web Forms Application -. Click "Next".

  • h) Next up is your choice on how you want your Add-Inn to authenticate. Please select "Use a certificate (for SharePoint on-premises add-ins using high-trust)" and provide the Certificate Location / Password and Issuer ID that we previously generated. Done? Click "Finish"! (Yes, almost there...)

Project “HighTrustAddInWeb” is a web-based project which will be deployed into your IIS&nbsp;and it'll be deploying add-ins onto the production server. This solution contains a config file which stores the configuration details (ClientSigningCertificatePath/Password/IssuerID) that you provided while creating the solution as shown in the image below.

a) There are few more App settings that we need to define in the web.config file like ClientID, ClientSigningCertificateSerialNumber, ClientSecret.
b) When you are running the add-in from the visual studio, you don't need to worry about the settings mentioned above, as Visual Studio will create a client ID while your app is in running mode.
c) There will be one page called “Default.aspx” which is automatically in a template. When you open the .cs file, there will be code that displays the web name on the page.


Now, when you hit F5 you'll see that your newly created Add-In will install and automatically uninstall any Add-Ins that were already deployed in the site. During the deployment, it'll also update the Client ID in the web.config file.

By performing all of the steps mentioned above you've now developed a High-Trust Provider-Hosted Add-In! Congratulations!

Tags

see all