The Following Instructions are for creating the AppManager website for an On-Premises server or on a Virtual Machine (VM) in the cloud where you can login as Administrator.
The installation example below is on a Windows Server 2012/R2 (with all Service Packs, Hotfixes, etc.).
Consider whether this is a “High Trust” or “Low Trust” configuration. If “High Trust” then follow the steps below to create the High Trust certificate.
Creating a High Trust Certificate using IIS
The high trust configuration is an option for the on-premise (FARM) SharePoint 2016 environment only. A high trust app uses digital certificates to establish trust between the web site “AppManager” and SharePoint. There are 2 ways to create a SSL Certificate either from IIS or from command line tool using mkcert. Here we will discuss using IIS to create the SSL Certificate.
Creating AppManager Site SSL Certificate – For High Trust environment
Log into the AppManager Web site Hosting Server, login as Administrator.
From the Windows “Start” menu, search for program “Internet Information Services” right click and “Run as administrator”.
The Internet Information Services (IIS) Manager will appear.
In the left Connections explorer click on your Server Name e.g. QA.
You will see the server Home window icons in the center window of IIS. In our sample it is: “QA”.
In the center window, scroll to the “IIS” section and double click on the “Server Certificates” icon.
In the Right Pane on the “Actions” menu, click “Create Self-Signed Certificate”.
The “Create Self-Signed Certificate” Dialog box will appear where you will:
- Enter a Friendly name for the certificate such as “AppManagerSSL”.
- Set the “Select a certificate store for the new certificate:” drop down to Personal.
Click on OK.
The certificate will show up as created on your Server Certificate pane.
Exporting the Certificate created on your AppManager Web Site Hosting Server
Right click on the Certificate you created in the steps above, in our example “AppManagerSSL”.
In the dropdown menu click on “Export…”.
In the “Export Certificate” dialog click on “…” button.
The “Specify save as file name” dialog box will appear.
- On the files explorer, navigate to c:\Akumina
- Enter a file name for your Certificate to be saved as e.g. “AppManagerSSL” leave the file extension set to *.pfx.
The Export Certificate dialog box will appear.
Enter the Password to associate your certificate with.
and
Confirm the Password to associate your certificate with.
Click on “OK”.
Importing the Certificate to your SharePoint Server.
The Certificate Generated in the Steps above needs to exist on both the AppManager website hosting server and the SharePoint 2016 server. If these two websites are hosted on different Servers then you need to complete the steps below:
Import your Certificate onto your SharePoint Server
The server hosting your SharePoint site will need a copy of the Certificate just created.
- Copy the Certificate you just created onto your local computer.
- Log into the SharePoint Hosting Server, login as Administrator.
- Copy The Certificate from your local computer to the Server where SharePoint is hosted on to C:\Akumina.
- From the Windows “Start” menu, search for program “Internet Information Services” right click and “Run as administrator”.
The Internet Information Services (IIS) Manager will appear.
In the left Connections explorer click on your Server Name e.g. QA.
You will see the server Home window icons in the center window of IIS. In our sample it is: “QA”
In the center window, scroll to the “IIS” section and double click on the “Server Certificates” icon.
The Server Certificate Page will display.
Click on “Import…” in the Right Action Pane.
The Import Certificate Dialog box will display.
Click on “…” button and navigate to the location on your server where you copied the Certificate, in our example C:\Akumina.
Click on the Certificate to Import and then the “Open” button.
From your MyAppManagerInstallNotes.txt file find the Certificate password that you created when exporting the Certificate, and enter the password.
Leave the “Select Certificate Store” set to “Personal”.
Click on the “OK” button.
The Certificate will now show up in your Server Certificates list.
Creating AppManagerSSL.cer from AppManagerSSL.pfx
“Microsoft Manage Console” (mmc) will be used to create AppManager.cer from the personal Certificate AppManagerSSL.pfx.
On the Server start menu enter mmc, right click on mmc and run as administrator.
The mmc console modal will open.
Click on File (menu option), from the dropdown select “Add/Remove Snap-In”.
Select “Computer account” and click on “Next” button.
Select Computer should be “Local Computer”, then click on Finish.
The Certificates will appear under the “Selected snap-ins” on the right pane then click OK
First Import the Certificate
Double Click on Console Root to expand it
Click on “Certificates – (Local Computer)” to expand it.
Right Click on Personal >Certificates, expand “All Tasks”, and select “Import…”
Click on Next on the Welcome Screen see below:
Click on Browser.
On the “open” modal, navigate to the folder where you have stored your *.pfx certificate, change the file extension to “*.pfx”.
Click on your personal Information Exchange Certificate example AppManagerSSL.pfx.
Click on Open.
Click on Next.
Enter the password you defined for your certificate earlier.
Click on Next.
On the Certificate Store, leave Certificate store = Personal and click on Next.
On the Completing the Certificate Import Wizard page, click on Finish.
You will see the message “The Import was successful” click on OK.
Export the certificate following the steps below
On the mmc modal, left column expand “Certificates”.
Click on “Personal”.
The center pane will display the Certificate folder associated with this user.
Click on the Certificate folder in the center pane.
The Certificates associated with this user will appear, including “AppManagerSSL”.
Right Click on AppManagerSSL, a dropdown menu will appear. Click on “All Tasks” and then “Export…”.
The “Certificate Export Wizard” modal will appear.
Click on “Next” button.
The “Export Private Key” pane displays where “No” (No – allows for the creation of a *.cer) will be left selected.
Click on “Next” button.
The Export File Format pane appears.
Verify “DER encoded binary X.509 (.CER)” is selected and then “Next” Button.
The File to Export pane appears.
Click on “Browse…”, in the File Explorer modal, navigate to c:\Akumina, enter filename AppManagerSSL, click on “Save” button.
The “File to Export” modal now has “File Name” filled in, Click on “Next” button.
The “Completing the Certificate Export Wizard” pane will display, Click on “Finish” button.
Import the Certificate into “Trusted Root Certification Authorities” and “SharePoint”> Certificates.
This Certificate also has to be in “Trusted Root Certification Authorities” > Certificates and SharePoint > Certificates – follow the steps below for both “Trusted Root Certification Authorities” and “SharePoint”.
On the left column expand “Trusted Root Certification Authorities”, right click on Certificates, select “All Tasks” and Import.
On the “Certificate Import Wizard” click on Next.
On File to Import click on Browse – Navigate to the Certificate location that you just created and select the *.cer file.
Certificate Store – Trusted Root Certification Authorities should be selected then click on Next
Then click on “Finish” on the Completing the Certificate Import Wizard.
Click OK. If the Import was successful message you will then see your Certificate on in the center pane.
Follow all steps in this Section replacing “Trusted Root Authorities” with SharePoint click here to begin.
Configuring SharePoint to use the Certificate and configure the trust of your app
Article of interest: http://msdn.microsoft.com/en-us/library/fp179901(v=office.15).aspx
Article of Interest: http://msdn.microsoft.com/en-us/library/fp179923(office.15).aspx#sthash.cz0sc1hF.dpuf
AppManager 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 app for SharePoint, the certificate is the token issue
Running Windows PowerShell cmdlet to set up a trusted security token service.
Login to the SharePoint Hosting Server, login as Administrator.
From the Windows “Start” menu, search for program “SharePoint 2016 Management Shell”, right click and “Run as administrator”.
Enter the following cmdlet to acquire your Issuer ID:
[System.Guid]::NewGuid()
The Issuer Id will be created.
SAVE to Notepad –the GUID returned this is your ISSUER ID. In Our Example:
f1ade2c5-9bdb-4b80-8082-e1902c1de4de
To configure the high trust a set of power shell cmdlets will have to be run. There are set of significate terms for these commands that are explained in the table below.
Term | Description | Example |
---|---|---|
publicCertPath | Path where I have saved my .cer file. Replace <yourcertificatepath.cer>with your c:\path.*.cer | C:\Akumina\AppManagerSSL.cer |
IssuerID | The GUID generated in the Previous step
You can replace <11111111-1111-1111-1111-111111111111> with the value you generated |
f1ade2c5-9bdb-4b80-8082-e1902c1de4de
|
Copy the Cmdlets below into a Note Pad file on your SharePoint Hosting Server. Edit the highlighted items in yellow. After the commands have been updated copy them into a “SharePoint 2016 Management Shell”.
NOTE: the [LINEBREAK] symbol in the command lines below represent when there should be a line break in the set of commands. DO NOT COPY [LINEBREAK] as part of your command into the Note Pad File or into the Manage Power Shell. If you do not copy these commands into a note file that is very wide the copy and paste may introduce line breaks where none should be!
$PUBLICCERTPATH = “<YOURCERTIFICATEPATH.CER>”
[LINEBREAK]
$CERTIFICATE = NEW-OBJECT SYSTEM.SECURITY.CRYPTOGRAPHY.X509CERTIFICATES.X509CERTIFICATE2($PUBLICCERTPATH) [LINEBREAK]
NEW-SPTRUSTEDROOTAUTHORITY -NAME “AKUMINA APPMANAGER” -CERTIFICATE $CERTIFICATE [LINEBREAK]
$REALM = GET-SPAUTHENTICATIONREALM
[LINEBREAK]
$SPECIFICISSUERID = “<11111111-1111-1111-1111-111111111111>”
[LINEBREAK]
$FULLISSUERIDENTIFIER = $SPECIFICISSUERID + ‘@’ + $REALM
[LINEBREAK]
NEW-SPTRUSTEDSECURITYTOKENISSUER -NAME “AKUMINA APPMANAGER” -CERTIFICATE $CERTIFICATE -REGISTEREDISSUERNAME $FULLISSUERIDENTIFIER –ISTRUSTBROKER
[LINEBREAK]
IISRESET
[LINEBREAK]
$SERVICECONFIG = GET-SPSECURITYTOKENSERVICECONFIG
[LINEBREAK]
$SERVICECONFIG.ALLOWOAUTHOVERHTTP = $TRUE
[LINEBREAK]
$SERVICECONFIG.UPDATE()
[LINEBREAK]
This is an example of what your Notepad file should look like before you updated the above highlighted in Yellow input values.