Fall. Installing InterChange on Premise. Version 5.0 (October 2016) 2016 Akumina, Inc. All rights reserved. k

Transcription

1 Fall 08 Installing InterChange on Premise Version 5.0 (October 2016) 2016 Akumina, Inc. All rights reserved. k

2 Table of Contents About this Document Who should use this Documentation? How to use this Documentation Knowledge of SharePoint System Requirements Supported Browsers Supported Operating Systems and Prerequisites SharePoint Versions... 5 Prerequisites Manage services on server need to have started: Manage Service Applications that must be started and configured correctly Verify Manage Meta Data Service Connection is configured correctly... 7 Setup a SharePoint App Catalog If one does not already exist Determine if this SharePoint Site has an App Catalog Already Setup If the App Catalog is NOT Configured for the Appropriate Site, Then: Creating an App Catalog Configuring App URLs for your app catalog Creating an App Identifier (APP ID OR CLIENT ID) for InterChange using 16 Creating the InterChange website on Premise or on a VM in the Cloud Creating a High Trust Certificate using IIS Creating InterChange Site SSL Certificate For High Trust environment Exporting the Certificate created on your InterChange Web Site Hosting Server Importing the Certificate to your SharePoint Server Import your Certificate onto your SharePoint Server Creating InterChangeSSL.cer from InterChangeSSL.pfx First Import the Certificate Export the certificate following the steps below Import the Certificate into Trusted Root Certification Authorities and SharePoint > Certificates Configuring SharePoint to use the Certificate and configure the trust of your app Running Windows PowerShell cmdlet to set up a trusted security token service Creating your InterChange Web Site Completing the Add Website Dialog Box Installing the InterChange App In SharePoint Customizing the App Package for your InterChange Site Copy all required files from your Local Computer to your SharePoint Server and the InterChange Hosting server 42 Adding the InterChange Apps to SharePoint App Catalog Executing the InterChange Website Installer If your InterChange site is https then Update the interchange.settings.config for SSL to work Enabling Windows Authentication and Disabling Anonymous Authentication for on Premise Installation Make sure the Port is open for InterChange On your InterChange Server verify the Port ENDPOINT has been established

3 Pre-Requests for you Site Collection turn on site Features Navigate to Site Collection Features Navigate to Manage site Features Adding the Akumina InterChange App to your Site Collection Appendix - A Error messages in the log file and what they Mean

4 About this Document This document will discuss installing InterChange for SharePoint On-premises (referenced as SharePoint Hosting Server below) + InterChange app in on-premises server (referenced as Web Hosting Server below). Note: If SharePoint is installed on premise as the same server as the website InterChange then in this documentation below SharePoint Hosting Server = InterChange Web Site Hosting Server Who should use this Documentation? To fully use this documentation, you should be a SharePoint Administrator How to use this Documentation Throughout this documentation you will find a consistent structure to help you quickly go through each section. Notice the hierarchical structure for Actions/Results and their typical meanings below: Action Used to indicate an action that needs to be taken. Result Indicates what the results should be, based on the preceding action. Images are also provided for additional clarification, as well as notes throughout. You will be asked through this document to TAKE NOTES in certain results/items those Items will be highlighted in green outlined box with gray background example seen below. You should open a Notepad file and store all called out items in there for future reference, your Notepad file will be referred to as MyNotes.txt Make a Note Item to be stored in MyInterChangeInstallNotes.txt Knowledge of SharePoint InterChange administrators should have a general working knowledge of SharePoint 2013/2016 administration. 1.2 System Requirements Supported Browsers Browsers that work with InterChange Internet Explorer (Versions: 9, 10, and 11) Google Chrome (Latest released version) 4

5 Mozilla Firefox (Version 32+) Apple Safari (Version 7+) NOTE: For Mac Firefox 30.0 and above 401 Error when trying to log into SharePointis related to Insecure NTLM (pre-ntlmv2) authentication being disabled in Firefox. Resolution: Type about:config in the URL bar and hit Enter. Accept the warning. Type NTLM in the Search bar at the top. Right-click network.negotiate-auth.allow-insecure-ntlm-v1 and select Toggle (this will switch the Value column to true ). Then close Firefox and restart. You should now be able to access that SharePointwebsite without getting that 401 message Supported Operating Systems and Prerequisites InterChange App Web Server Requirements SharePoint 2013/2016 or SharePoint Online (Office 365) Windows Server 2008 R2 or Windows Server 2012/R2 (with all Service Packs, Hotfixes, etc.).net Framework 4.5 IIS 7 (or higher) MVC Must be able to access the interchange Hosting website via SSL, because you have to link to it via SharePoint Versions SharePoint 2013/2016 (with any or no Service Pack) Prerequisites 5

6 Verify the following Services is running on your SharePoint Site Login to your SharePoint Hosting Server as Farm Administrator. 2.1 Manage services on server need to have started: Navigate to System Settings > Manage services on server verify the following Services are started. Managed Meta Data Web Service User Profile Service Search Applications (1. Search Host Controller Service, 2. Search Query and Site Settings Service, and 3. SharePoint Server Search) Microsoft Office must be installed and configured on your SharePoint Server. Configure Following on your SharePoint Server SharePoint Central Administration > Application Management > Manage service Applications > User Profile Service Application > Manage Following (under My Site Settings) - see this link for additional information - For Following Configure outgoing settings SharePoint Central Administration > System Settings > Configure outgoing settings (under and Text Messages) - see this link for additional information Manage Service Applications that must be started and configured correctly The Following Features must be configured on your SharePoint Farm From the Windows Start menu, click on All Programs, under Microsoft SharePoint 2013/2016 Products, right click on SharePoint 2013/2016 Central Administration and select Run as administrator. Navigate to Application Management > Manage Service Application (under Service Applications). Verify that App Management Service is Started. Verify that Managed Metadata Service is Started. Verify that User Profile Service Application is Started Verify that Search Service Application is Started 6

7 Note if these Services are not started then when you try and add the InterChange App to your site collection you will get an error: Sorry, app is not support on your server Verify Manage Meta Data Service Connection is configured correctly Navigate to SharePoint Central Administration > Application Management > Manage service Applications highlight (do not click the title, click on the row) Managed Metadata Service. Then click on Properties in the Ribbon. 7

8 Verify the following Check boxes are checked on the Managed Metadata Service Connection modal. Enable Apps that require accessible internet facing endpoints follow the following steps: 1. Navigate to Application Management > Managed web application. 2. Click on your SharePoint web application and then Manage Features (in the ribbon on the top). 8

9 3. Verify that Apps that require accessible internet facing endpoints is set to ACTIVE. Setup a SharePoint App Catalog If one does not already exist 3.1 Determine if this SharePoint Site has an App Catalog Already Setup On SharePoint Central Administrator page, Left Column, select Apps. The Apps page will be displayed, click on Manage App Catalog. Set the Web Application from the dropdown to the web application that InterChange will be added as an app. 9

10 SAVE to Notepad SharePointSiteAppCatalogURL - If the App Catalog Exists then save the URL highlighted in YELLOW above. In the example above If the App Catalog is NOT Configured for the Appropriate Site, Then: Note: This section can be skipped if this SharePoint Site already has set up an App Catalog. Click on Central Administration (left Column). Under System Settings Click Manage services on server You will be directed to the Services on Server page On the Services on Server page verify that the App Management Service status is Started. 10

11 On the Left Menu, under Central Administration Click on Apps Creating an App Catalog On the Apps page, click on Manage App Catalog. Verify that the Web Application URL is your SharePoint site URL Click Create a new app catalog site Click OK. On The Create App Catalog page, use the table below to fill in the Fields and then click OK. Input Field Description Example Title App Catalog Name apps 11

12 Web Site Address User Name The Dropdown should have SITE selected, complete the URL by entering apps Using the People picker select an Administrator for this catalog. Remember this user, they will manage the apps Usually this SharePoint administrator app Catalog. End Users Everyone Everyone can see the App Catalog items. SAVE to NotePad SharePointSiteAppCatalogURL You will need this URL to create the Client ID and Secret. SAVE to Notepad This will be the Primary administrator listed above, this user will be need to add apps to the site and register the New App with the site. You App Catalog will now be created Configuring your App Catalog Term Description Example Webapplication Domain <yourdomain> Sp13dev1 Farm Administrator <domain\username>" dev\sharepoint 12

13 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 2013/2016 Management Shell Running as Administrator. 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! net start spadminv4 [LINEBREAK] net start sptimerv4 [LINEBREAK] Set-SPAppDomain "<yourdomain>" [LINEBREAK] Get-SPServiceInstance where{$_.gettype().name -eq "AppManagementServiceInstance" -or $_.GetType().Name -eq "SPSubscriptionSettingsServiceInstance"} Start-SPServiceInstance [LINEBREAK] $account = Get-SPManagedAccount "<domain\username>" [LINEBREAK] $apppoolsubsvc = New-SPServiceApplicationPool -Name SettingsServiceAppPool -Account $account [LINEBREAK] $apppoolappsvc = New-SPServiceApplicationPool -Name AppServiceAppPool -Account $account [LINEBREAK] $appsubsvc = New-SPSubscriptionSettingsServiceApplication ApplicationPool $apppoolsubsvc Name SettingsServiceApp DatabaseName SettingsServiceDB [LINEBREAK] $proxysubsvc = New-SPSubscriptionSettingsServiceApplicationProxy ServiceApplication $appsubsvc [LINEBREAK] $appappsvc = New-SPAppManagementServiceApplication -ApplicationPool $apppoolappsvc - Name AppServiceApp -DatabaseName AppServiceDB [LINEBREAK] 13

14 $proxyappsvc = New-SPAppManagementServiceApplicationProxy -ServiceApplication $appappsvc [LINEBREAK] Set-SPAppSiteSubscriptionName -Name "Apps" -Confirm:$false [LINEBREAK] Below is an example of an edited set of commands to copy and paste into a Managed Power Shell Configuring App URLs for your app catalog. NOTE: This section assumes DNS is configured properly. See MSDN Documentation. In SharePoint 2013/2016 Central Administration Left column, click on Apps. Click on Configure App URLs. 14

15 The Configure App URLs page will be displayed. Note: If you do not see the input fields described below then you will need follow these sets: Navigate to Application Management > Manage Service Application (under Service Applications). Verify that Subscription Settings Service is listed and is Started. There are two input fields on this page which maybe already populated CLEAR both Fields and fill them in appropriately as described in the table below. Input field Description Example App domain Enter in the App Domain sp13dev1 App prefix Fill in the App prefix. It is best to use something short like Apps Apps Once the fields are completed, click on OK. 15

16 Creating an App Identifier (APP ID OR CLIENT ID) for InterChange using New.aspx. A Client Identity (Client ID) and App Secret Token (Client Secret) has to be created for the new incoming APP InterChange. AppRegNew.aspx will be used to generate those items. Here you will be using the SharePointSiteAppCatalogURL that you SAVED into your notepad file to build the appropriate link to the AppRegNew page for this SharePoint site. NOTE: BECAUSE we will be use the APP CATALOG URL AppRegNew.aspx will generate a App Id and App Secret. APP ID = CLIENT ID - in SharePoint APP Secret = Client Secret - in SharePoint On your local machine open a Browser e.g. Firefox, Chrome or Safari. Navigate to http[s] (note s here if SharePoint binding in IIS is configured for https) Login as the APP CATALOG Administrator. The App Information page will be displayed, where input field to create the Client Identity (Client ID) and App Secret Token (Client Secret) will be displayed: Set the following fields: App Id: - Click the Generate button and SharePoint will generate the Client ID. SAVE to Notepad App Id - GENERATED VALUE you will need this Client ID for your InterChange Installation App Secret Click the Generate button and SharePoint will generate the Client Secret. 16

17 SAVE to Notepad - App Secret - GENERATED VALUE you will need this Client Secret for your InterChange Installation TITLE Enter the name of your user Friendly title (this will be the app name that appears on the Site Contents list) e.g. Akumina InterChange. SAVE to Notepad - this will be the app name that appears on the Site Contents list App Domain - The host name of the remote component of the app for SharePoint (this is the URL where InterChange will be installed). If the remote application isn't using port 443, the app domain must also include the port number, we will always plan on using a port number. That is, the app domain must match the URL bindings you use for your web application. There should be no protocol (" or www) or "/" characters in this value. (If your web application host is using a DNS CNAME alias, use the alias.). Examples: myinterchangehostingwebsiteaddress.com:44301 sp13dev1:44301 SAVE to Notepad - App Domain You will use this later for your InterChange Install Redirect URI - The endpoint in your remote application InterChange (web site), this must begin with and include the alias /Explorer/Index. Examples: Verify that the Identifier was generated successfully. 17

18 BEFORE selecting OK button, verify you have saved the Client ID, and Client Secret, to use to complete the installation Click on OK button Creating the InterChange website on Premise or on a VM in the Cloud The Following Instructions for creating the InterChange website for an on Premise 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.). Log into your server as Administrator. 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. 5.1 Creating a High Trust Certificate using IIS Note: the Certificate used in the token provider and the interchange site MUST BE THE SAME. If you apply a different certificate then Interchange will not work. The high trust configuration is an option for the on premise (FARM) SharePoint 2013/2016 environment only. A high trust app uses digital certificates to establish trust between the web site InterChange 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 InterChange Site SSL Certificate For High Trust environment Log into the InterChange Web site Hosting Server, login as Administrator. 18

19 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. 19

20 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 InterChangeSSL. Set the Select a certificate store for the new certificate: drop down to Personal. Click on OK. 20

21 The certificate will show up as created on your Server Certificate pane. SAVE to Notepad Certificate Name You will use this later for your InterChange Install Exporting the Certificate created on your InterChange Web Site Hosting Server Right click on the Certificate you created in the steps above, in our example InterChangeSSL. 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. InterChangeSSL leave the file extension set to *.pfx. 21

22 And The Export Certificate dialog box will appear. Enter the Password to associate your certificate with. Confirm the Password to associate your certificate with. SAVE to Notepad Certificate password If you associate a password with the certificate, whoever imports the certificate must know the password before the certificate can be applied to the target server e.g. your SharePoint server. Click on OK. 5.2 Importing the Certificate to your SharePoint Server. Skip this section if the InterChange web site and the SharePoint on Premise are both hosted on the same server. Click HERE and advance to Creating InterChangeSSL.cer from InterChangeSSL.pfx The Certificate Generated in the Steps above needs to exist on both the InterChange website hosting server and the SharePoint 2013/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 22

23 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. 23

24 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. 24

25 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 MyInterChangeInstallNotes.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. 25

26 The Certificate will now show up in your Server Certificates list. 5.3 Creating InterChangeSSL.cer from InterChangeSSL.pfx Microsoft Manage Console (mmc) will be used to create InterChange.cer from the personal Certificate InterChangeSSL.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. 26

27 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 27

28 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 InterChangeSSL.pfx. Click on Open. 28

29 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. 29

30 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 InterChangeSSL. 30

31 Right Click on InterChange SSL, 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. 31

32 The File to Export pane appears. Click on Browse, in the File Explorer modal, navigate to c:\akumina, enter filename InterChangeSSL, 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. 32

33 5.3.3 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 Authories 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 33

34 Then click on Finish on the Completing the Certificate Import Wizard. Click OK on the Import was successful message you will then see your Certificate on in the center pane. Follow ass steps in this Section replacing Trusted Root Authorities with SharePoint click here to begin. 5.4 Configuring SharePoint to use the Certificate and configure the trust of your app Articles of interest: Article of Interest: InterChange 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 issuer 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 2013/2016 Management Shell, right click and Run as administrator. 34

35 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-4b e1902c1de4de NOTE the above is case sensitive only lower case letters can be used. 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 IssuerID Path where I have saved my.cer file. Replace <yourcertificatepath.cer>with your c:\path.*.cer The GUID generated in the Previous step You can replace < > with the value you generated C:\Akumina\InterChangeSSL.cer f1ade2c5-9bdb-4b 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 2013/2016 Management Shell. 35

36 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 InterChange" -Certificate $certificate [LINEBREAK] $realm = Get-SPAuthenticationRealm [LINEBREAK] $specificissuerid = "< >" [LINEBREAK] $fullissueridentifier = $specificissuerid + '@' + $realm [LINEBREAK] New-SPTrustedSecurityTokenIssuer -Name "Akumina InterChange" -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. 36

37 5.5 Creating your InterChange Web Site The web site InterChange has to be created on your Hosting Server for on premise. The Example below is an on Premise solution. The local server is running Windows Server 2012/R2 (with all Service Packs, Hotfixes, etc.). The InterChange website will be created using IIS. Login to your InterChange Web Site Hosting Server as Administrator From the Windows Start menu, open IIS as an administrator. In the Connections explorer (left pane), right click on the Sites folder and click Add Web Site The Add Website Popup window will appear Completing the Add Website Dialog Box. In The dialog box below complete the following: Set the Site Name and Application Pool. Example: Site name = O365InterChange, Application pool = O365InterChange. Navigate and click or create the Physical Path for your website (our example is C:\inetpub\InterChange). Set binding Type should be http. 37

38 Leave IP address set to All Unassigned. Set binding for https: Set the Port address to (not 443 because other SharePoint sites may use this port). Click Select and set the SSL certificate (if https is being used). Example: InterChange SSL. Set binding for http: Enable the port as you defined in the APPRegNew example the binding can be set to http. Click Start Web site immediately Click OK. SAVE to Notepad Site name you will need this when running the InterChange Installer. Save to Notepad Physical path you will need this when running the InterChange Installer. The Site will now appear in IIS Site Tree in the left Column and be displayed in the center pane. 38

39 Installing the InterChange App In SharePoint 6.1 Customizing the App Package for your InterChange Site. The InterChange App Package provided to you from Akumina has a file Akumina.InterChange.App.app, which needs to be customized for your sites. Unique values that are applicable to your SharePoint and InterChange web site must be set. NOTE: BECAUSE we will be use the APP CATALOG URL AppRegNew.aspx will generate a App Id and App Secret. App Id = Client Id - in SharePoint App Secret = Client Secret - in SharePoint You will see in the section below input fields for Client Id fill those with the App Id Customizing the Akumina.InterChange.App.app File On your local computer. Using File Explorer, navigate to C:\Akumina where you copied the InterChange App package. RIGHT click on Akumina.InterChange.App.app and select COPY from the dropdown menu. RIGHT click on your mouse and PASTE the file. You will see the file Akumina.InterChange.App Copy.app. Right Click on Akumina.InterChange.App Copy.app and from the dropdown list select RENAME Change the name from Akumina.InterChange.App Copy.app to Akumina.InterChange.App.zip. You will get a Rename confirmation popup select YES. 39

40 Right Click on Akumina.InterChange.App.zip and click on Extract All from the dropdown menu. In the Extract Compressed (Zipped) Folders Dialog box change the folder destination for the extracted files to C:\Akumina\Apps and then click on Extract button. The following files/folder will appear in the C:\Akumina\Apps folder: Right click on AppManifest.xml and click Open with > Notepad. 40

41 There are 2 items that need to be changed 1. StartPage ~remoteappurl replace with your Redirect URL saved in MyInterChangeInstallNotes.txt file. In our example: 2. ClientId Replace * with the App Id created by AppRegNew which you have stored in your MyInterChangeInstallNotes.txt file. Example: 271a8dc0-b0d8-40bd aad24fbcbf8. On the Notepad top menu, click File and from the dropdown menu, click Save. On File Explorer Select all files in folders in the C:\Akumina\Apps Directory. Right Click from the dropdown select Send to > Compressed (zipped) folder. 41

42 Rename the generated zip *.zip to Akumina.InterChange.App.app The Rename confirmation popup will appear click Yes. 6.2 Copy all required files from your Local Computer to your SharePoint Server and the InterChange Hosting server Login to your SharePoint Hosting Server as Administrator. If folder does not exist create folder C:\Akumina. Copy the customized App Package Akumina.InterChange.App.app and Akumina.AddIn.Hosted.DMS.app (which was provided as part install package) to C:\Akumina on the SharePoint Server. If you are hosting the InterChange website on another On Premise server login to that server as Administrator. If folder does not exist create C:\Akumina on the InterChange hosting server. Copy the file *InterChange.msi (installer) to that InterChange hosting server c:\akumina. Adding the InterChange Apps to SharePoint App Catalog On Your SharePoint Server open a browser and enter the app catalog URL (value saved in note file). If you do not know what your App Catalog URL is then click HERE and follow the steps to find the URL). In this example the URL looks like this: However, this SharePoint site is configured to use https so I must substitute the http for https. 42

43 Enter into a Browser - login as the SharePoint Administrator. On the left Column Navigation, click Apps for SharePoint. Click on +new app to upload the app packages Akumina.InterChange.App.app and Akumina.AddIn.Hosted.DMS.app provided to you by Akumina. Click on the Browser button navigate to c:\akumina\akumina.interchange.app.app Click the Open Button. The choose file input field will fill in with C:\Akumina\Akumina.Interchange.App.app. Click on OK. The properties form will appear with a message indicating that the document was successfully uploaded. 43

44 Click on SAVE. The Apps for SharePoint Page will display with the newly added app Akumina InterChange displaying. Executing the InterChange Website Installer The Following InterChange Installation can be followed for when the InterChange website is install on Premise or on a Virtual Machine (VM) in the cloud where you can login as Admin. Login to your InterChange Web Site Hosting Server as Administrator. Earlier you were instructed to copy the InterChange*.msi (* is the verision number) file to this server in directory c:\akumina. From the Windows Start menu, right click on Command Prompt and Run as administrator. 44

45 Navigate to C:\Akumina. In a file explorer window also navigate to C:\Akumina. Right Click on the *InterChange.msi file and from the dropdown menu click on Properties. On The Properties dialog copy the name of the Installation file, by highlighting and selecting Cntrl+C. In your Command Prompt window right click and select Paste from the dropdown window. MAKE SURE.msi (the file extention) is passed as part of the name, if not then tack.msi onto the file name. Hit the ENTER key. The Akumina InterChange Setup dialog box will appear. Click on Next To Begin the Akumina InterChange install. 45

46 The License Agreement page will be displayed. Click on the accept box. Click on Next to then proceed with the install. If all Prerequisites must be met before the install can continue, if all are met, green check boxes will appear. Click on Next to continue. 46

47 The Configuration Settings dialog is displayed. IIS Existing Site click on the dropdown arrow and select the Site name of your InterChange Website in this example InterChange (you would have saved the Site name in your MyInterChangeInstallNotes.txt file when creating the website). Site Path no action required. Client ID Copy/PASTE from your MyInterChangeInstallNotes.txt file, the APP ID. SharePoint Site URL - Copy your SharePoint Web Application mapping, in our example paste it into the SharePoint Site URL input field. Determine if this will be a High Trust or Low Trust configuration. IF Low Trust then: o Client Secret - Copy from your MyInterChangeInstallNotes.txt, your Client Secret, which was generated by SharePoint when you ran AppNewReg.aspx, into the Client Secret input field. Else IF High Trust then: o Click on the High Trust Radio button. o Click on Browse and navigate to the security certificate associated with this website in our example: C:\certs\InterChangeSSL.pfx o Enter the Certificate password you should have stored this in your MyInterChangeInstallNotes.txt file. Issuer ID Copy from your MyInterChangeInstallNotes.txt file, and paste it into the Guid or Issuer ID input field. Click on Next. InterChange will be installed into your specified website s Physical Path. 47

48 Upon a successful installation your will see the following dialog. Click on the Finish button. If your InterChange site is https then Update the interchange.settings.config for SSL to work Navigate on your InterChange Server to the root of the InterChange website. Edit using note pad interchange.settings.config change the value for the key "akumina:customcertificatevalidation = true <add key="akumina:customcertificatevalidation" value="true" /> Save the file. Enabling Windows Authentication and Disabling Anonymous Authentication for on Premise Installation. Since we have configured this site to use HIGH TRUST we must disable FORM Authentication and ENABLE Windows Authentication. If this was a low trust environment we would do the opposite. Now that InterChange has been installed we need to enable Windows Authentication by Disabling Anonymous Authentication. 48

49 From the Windows Start menu, right click on IIS, and Run as administrator. Expand Sites, and Click on your site InterChange, and then double click on Authentication in the IIS section of the features in the center window. The Authentication pane appears in the Center pane. Verify/Change Anonymous Authentication set to Disable. Verify/Change Forms Authentication set to Disable. Verify/Change Windows Authentication set to Enable. Make sure the Port is open for InterChange From the Start menu select Window Firewall with Advanced Security. 49

50 Right click on Inbound Rules, and select New Rule. On the New Inbound Rule Wizard select Port and then Next. On the Protocol and Ports pane, select TCP and Specific local ports, enter port and click on Next. 50

51 On the Action pane select Allow the Connection and click on Next. On the Profile pane, leave Domain, Private, and Public CHECKED. Enter a Name and Desired Description for the New Run e.g. InterChange 51

52 Do an IISRESET in SharePoint 2013/2016 Management Shell. On your InterChange Server verify the Port ENDPOINT has been established This example is from an azure virtual machine. Select your virtual machine and click on ENDPOINTS (right column). Add the Port Endpoint for your server (top ribbon right column) Enter Name, Protocol = TCP, Public Port, Private Port and then Click OK. 52

53 Pre-Requests for you Site Collection turn on site Features Navigate to Site Collection Features. On the Site Settings > Site collection features (found under Site Collection Administration) page, verify the following feature is ACTIVE: SharePoint Server Standard Site Collection features SharePoint Server Publishing Infrastructure. See below: Navigate to Manage site Features Navigate to Site Settings > Mange site features. Verify that the SharePoint Server Publishing feature is Active (blue button) on the site. If this feature is not Active, then the Activate button will be displayed, click on Activate. 53

54 Adding the Akumina InterChange App to your Site Collection NOTE: The User who adds the App to the SharePoint site cannot be the Primary Farm administrator. SAVE to Notepad SITEOWNER This will be the Primary administrator listed above, NOTE: The User who adds the App to the SharePoint site cannot be the Primary Farm administrator, they must have 1. FULL Site permissions on this SharePoint site 2. On the SharePoint server itself they must be an administrator. 3. Must be in the Farm Administration Group in Sharepoint. On the SharePoint Hosting server open SharePoint 2013/2016 Central Administration, and navigate to Security (left Column menu item) > Manage the farm administrator group the user must be in this group This User will be referred to as SITEOWNER. Follow the Instructions below for both the Akumina InterChange Login to your SharePoint Site as SITEOWNER. Navigate to you Site Contents page by clicking on the GEAR and from the dropdown Site Contents. Click on add an app. The Site Contents > Your Apps page will be displayed. Click in the Left Navigation menu From Your Organization. 54

55 This page will change the content to only display the Apps from your organization, here you will see Akumina InterChange. Click on Akumina InterChange. The Do you trust Akumina InterChange dialog box will appear. Click on Trust It. When the app is completely installed on your Site Collection, it will appear as seen below. 55

56 56

57 Installation complete. Appendix - A Error messages in the log file and what they Mean Look in the log file if Interchange does function, it can be found on your SITE ROOT > logs. An example of a log file would be correctly.. If you see these errors, then your web.config must be updated WHEN PASSWORD IS WRONG T02:15: Z 0dc74b6c-eebf-53c0-1b c [ERROR] Info Error 0 [errormessage : System.TypeInitializationException: The type initializer for 'Akumina.Infrastructure.SharePoint.TokenHelper' threw an exception. ---> System.Security.Cryptography.CryptographicException: The specified network password is not correct. at System.Security.Cryptography.CryptographicException.ThrowCryptographicException(Int32 hr) at System.Security.Cryptography.X509Certificates.X509Utils._LoadCertFromFile(String filename, IntPtr password, UInt32 dwflags, Boolean persistkeyset, SafeCertContextHandle& pcertctx) at System.Security.Cryptography.X509Certificates.X509Certificate.LoadCertificateFromFile(String filename, Object password, X509KeyStorageFlags keystorageflags) at System.Security.Cryptography.X509Certificates.X509Certificate2..ctor(String filename, String password) at Akumina.Infrastructure.SharePoint.TokenHelper..cctor() --- End of inner exception stack trace --- at Akumina.Infrastructure.SharePoint.TokenHelper.GetS2SClientContextWithWindowsIdentity(Uri targetapplicationuri, WindowsIdentity identity) at Akumina.Interchange.Services.BaseService.a() at Akumina.Interchange.Services.BaseService.CreateClientContext() at Akumina.Interchange.Services.BaseService.GetContext() 57

58 at Akumina.Interchange.Services.ContentTypeService.GetAllWebs()] WHEN.CER USED INSTEAD OF.PFX T02:16: Z 0dc74b6c-eebf-53c0-1b c [ERROR] Info Error 0 [errormessage : System.TypeInitializationException: The type initializer for 'Akumina.Infrastructure.SharePoint.TokenHelper' threw an exception. ---> System.ArgumentException: ID2057: Cannot construct a X509SigningCredentials instance for a certificate without the private key. Parameter name: token at Microsoft.IdentityModel.SecurityTokenService.X509SigningCredentials..ctor(X509SecurityToken token, SecurityKeyIdentifier ski, String signaturealgorithm, String digestalgorithm) at Microsoft.IdentityModel.SecurityTokenService.X509SigningCredentials..ctor(X509Certificate2 certificate, String signaturealgorithm, String digestalgorithm) at Akumina.Infrastructure.SharePoint.TokenHelper..cctor() --- End of inner exception stack trace --- at Akumina.Infrastructure.SharePoint.TokenHelper.GetS2SClientContextWithWindowsIdentity(Uri targetapplicationuri, WindowsIdentity identity) at Akumina.Interchange.Services.BaseService.a() at Akumina.Interchange.Services.BaseService.CreateClientContext() at Akumina.Interchange.Services.BaseService.GetContext() at Akumina.Interchange.Services.ContentTypeService.a()] WHEN ISSUERID IS WRONG T02:17: Z 0dc74b6c-eebf-53c0-1b c [ERROR] Info Error 0 [errormessage : System.Net.WebException: The remote server returned an error: (401) Unauthorized. at System.Net.HttpWebRequest.GetResponse() at Microsoft.SharePoint.Client.SPWebRequestExecutor.Execute() at Microsoft.SharePoint.Client.ClientRequest.ExecuteQueryToServer(ChunkStringBuilder sb) at Akumina.Interchange.Services.BaseService.CreateClientContext() at Akumina.Interchange.Services.BaseService.GetContext() 58

59 at Akumina.Interchange.Services.UserService.GetCurrent() at Akumina.Interchange.Web.Controllers.BaseController.PoplateUser()] 59