installing interchange in o365 or a thirdparty - cloud...

Installing InterChange in O365 or a Third-Party Cloud Provider

Version 3.1 (March 2017)

InterChange Cloud Install 2

Table of Contents

1. INTRODUCTION ......................................................................................................................................................3

1.1. Who should use this Documentation? ................................................................................................................................................ 3

1.2. How to use this Documentation ......................................................................................................................................................... 3

2. SYSTEM REQUIREMENTS ........................................................................................................................................3

3. PREPARING THE SHAREPOINT SITE ..........................................................................................................................4

3.1. Creating an App Identifier for InterChange using AppRegNew.aspx. ................................................................................................. 4

3.2. Acquiring the InterChange App Package from Akumina and coping it to C:\Akumina ....................................................................... 7

3.3. Setting up the InterChange Website ................................................................................................................................................... 7

3.4. Setting Your Office 365 SharePoint URL, Client ID and Client Secret for the InterChange Website ................................................... 7

3.4.1. Extracting the Cloud Base InterChange Solution ........................................................................................................................ 7

3.4.2. File Changes required for your site ............................................................................................................................................. 9

3.4.3. Customizing the web.config File ................................................................................................................................................. 9

3.4.4. Customizing the “Akumina.InterChange.App.app” File ............................................................................................................ 10

4. INSTALLING INTERCHANGE FILES INTO CLOUD HOSTED WEBSITE ........................................................................... 14

5. INSTALLING INTERCHANGE INTO OFFICE 365 SHAREPOINT SITE ............................................................................. 16

5.1. Installing InterChange into the App Catalog ..................................................................................................................................... 16

5.2. Adding the InterChange App to your Office 365 SharePoint Site Contents ...................................................................................... 19

APPENDIX A – LOG FILE ERROR MESSAGES................................................................................................................ 21


1. Introduction

1.1. Who should use this Documentation?

To fully use this documentation, you should be a SharePoint Administrator. To install InterChange requires a thorough administrative understanding of SharePoint 2013.

1.2. 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/item 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

2. System Requirements Browsers that work with InterChange

• Internet Explorer (Versions: 9, 10, and 11) • Google Chrome (Latest released version) • Mozilla Firefox (Version 32+) • Apple Safari (Version 7+)

InterChange App Web Server Requirements

• SharePoint 2013 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 5.2.3 • Be able to access the Interchange Hosting website via SSL.

SharePoint Versions

• SharePoint 2013 • SharePoint 2016 • SharePoint Online (O365)

NOTE: For Mac Firefox® 30.0 and above — 401 Error when trying to log into SharePoint is related to Insecure Supported Operating Systems and Prerequisites

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.

3. PREPARING THE SHAREPOINT SITE

3.1. Creating an App Identifier for InterChange using AppRegNew.aspx.

A Client Identity and App Secret Token has to be created for the new incoming APP – InterChange. AppRegNew.aspx will be used to generate those items.

• Login as Administrator onto your SharePoint Admin Center. • Click On apps in left column.

• Click on App Catalog.

Note the URL backspace to apps/_layouts/15/ and append AppRegNew.aspx

• Navigate to http://<SharePointAppCatalogURL>/_layouts/15/AppRegNew.aspx. • The App Information page will be displayed, where input field to create the Client Identity will be displayed:


Set the following fields:

• Client Id: - Click the Generate button and SharePoint will generate the Client ID. • Client Secret – Click the Generate button and SharePoint will generate the Client Secret.

SAVE to Notepad - Client Id - GENERATED VALUE you will need this “Client ID” 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 App this is where InterChange will be. If the remote application isn't using port 443, the app domain must also include the port number. That is, the app domain must match the URL bindings you use for your web application (InterChange). There should be no protocol ("https:") or "/" characters in this value. (If your web application host is using a DNS CNAME alias, use the alias.). Examples:

o myInterChangeHostingWebsiteAddress.com:8080 o akuminaqa.azurewebsites.net

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 https:// and include the alias /Explorer/Index. Examples:

https://myInterChangeHostingWebsiteAddress.com:8080/Explorer/Index

https://akuminaqa.azurewebsites.net/Explorer/Index

Save to Notepad – Redirect URI – You will use this later for your InterChange Install

http://www.myinterchangehostingwebsiteaddress.com:8080/

http://www.akuminaqa.azurewebsites.net/

https://myinterchangehostingwebsiteaddress.com:8080/Explorer/Index



• Verify that the Identifier was generated successfully.

BEFORE selecting “OK” button, verify you have saved the Client ID, and Client Secret, to use to complete the installation

• Click on OK button


3.2. Acquiring the InterChange App Package from Akumina and coping it to C:\Akumina

Contact Akumina at [email protected] or call 603-943-7109 to acquire the InterChange App Package.

When the app package has been received, create a folder on your local machine called C:\Akumina. Copy the Provided package to C:\Akumina.

3.3. Setting up the InterChange Website

This document assumes that your cloud hosting administrator has created your website for InterChange to be installed on. In the example below we have verified that www.akuminaqa.azurewebsites.net has been created and that we have FTP access to the site, required for installing InterChange.

3.4. Setting Your Office 365 SharePoint URL, Client ID and Client Secret for the InterChange Website

• On your local machine navigate to C:\Akumina, where you previously copied the App Package provided by Akumina. • You should see the following zips, installer (msi) and app files:

Note: Install date before each *.* name will be different this data will be based upon when your package was generated

3.4.1. Extracting the Cloud Base InterChange Solution

• Right click on “*InterChange.zip” file and from the dropdown menu select Expand • The Extract Compressed (Zipped) Folders popup will appear

mailto:[email protected]

http://www.akuminaqa.azurewebsites.net/


SAVE to Notepad – The location (e.g. C:\Akumina\03_18_2015_04_17_InterChange) where the InterChange Cloud solution will be stored

Click on Extract

You will see the InterChange Installation files and folders


3.4.2. File Changes required for your site

The InterChange App package provided to you from Akumina has 2 files that need to be customized for your sites. Unique values that are applicable to your SharePoint Office 365 and Cloud website InterChange must be set. These files are the web.config file that was just extracted from the zip file, and the “Akumina.InterChange.App.app” file.

3.4.3. Customizing the web.config File

• . Navigate to C:\Akumina\*InterIngerChange (in our example we will navigate to C:\Akumina\03_18_2015_04_17_InterChange)

• Double Click or right click on Web.config • The web.config will open in Visual Studio… (alternatively you can edit this file using notepad) • Search (Cntrol + F) for term = SharePointURL • Below, this section of the web.config will be highlighted. This is where you will set 3 things

• Set the SharePointURL to the SharePoint Site URL where you will be installing InterChange in my example it will be set to this URL: https://awemind.sharepoint.com

• Set the Client ID – you will copy and paste the value you have saved in your Notepad file “MyInterChangeInstallNotes.txt” (example similar to: b3824b0d-cffb-48c9-a006-508c7eda60f6)

• Set the Client Secret – you will copy and paste the value you have saved in your Notepad file “MyInterChangeInstallNotes.txt” (example similar to: NH+VK7RxsYC7HIaOQCEANVkkdxebTBxpKBmATnmtDW0=)

• Copy the following:

<add name="Access-Control-Allow-Origin" value="https://mysharepointurl.com" />

<add name="Access-Control-Allow-Credentials" value="true" />

<add name="Access-Control-Allow-Methods" value="GET,HEAD,OPTIONS,POST,PUT" />

<add name="Access-Control-Allow-Headers" value="Access-Control-Allow-Headers, Origin,Accept, X-Requested-With, Content-Type, Access-Control-Request-Method, Access-Control-Request-Headers" />


• Search web.config for “customHeaders” • Paste copied text within the opening and closing tags. Overwrite existing text as seen bellow.

Note: you need to change value: <add name="Access-Control-Allow-Origin" value="https://mysharepointurl.com" /> to the value of your SharePoint url.

• Click the SAVE icon and then from the File dropdown menu select Exit.

3.4.4. Customizing the “Akumina.InterChange.App.app” File

• 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 this confirmation popup select “YES”

• 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”.

There are 2 items that need to be changed

• StartPage • ClientId

Changing the Start Page

• Change the URL for the <StartPage> to your InterChange Redirect URL that you have in your “MyNotes.txt” for our example: https://akuminaqa.azurewebsites.net/Explorer/Index

• Change the <StartPage>https: to http: • So that the following values are now set for the <StartPage>:

<StartPage>http://akuminaqa.azurewebsites.net/Explorer/Index/?{StandardTokens}</StartPage>



Changing the ClientId Change the ClientId to the value that is saved in “MyNotes.txt” in our example the value will be changed to: b3824b0d-cffb-48c9-a006-508c7eda60f6

Below is the updated file:

Repacking the .app file

• 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”.

• Rename the file to App.zip • Move App Zip up one level to C:\Akumina • Rename your original “Akumina.InterChange.App.app” to “Original.Akumina.InterChange.App.app” • Rename your “App.zip” to “Akumina.InterChange.App.app” • When you rename the popup will appear click “Yes”


4. Installing InterChange files into Cloud Hosted Website • Connect to your Cloud hosted website via FTP, in the example below we will be using FileZilla to do just that. • My local computer folder structure appears on the LEFT while to cloud hosted website appears on the RIGHT.

• On the Cloud Site, Expand folders until site > wwwroot is selected • The folder should be empty. • Add directory called ‘Temp’ in wwwroot folder • Right click in the window and click create directory name new directory Temp

• In the Left pane expand the folders until you are in the folder containing the Instance of InterChange that you created via expanding the *IniterChange.zip in this example the folder will be Akumina > 03_18_2015_04_17_InterChange.

• The files and folder for this website instance will appear in the left lower pane.


• Click on the first folder/file name e.g. Areas then hold your SHIFT DOWN and select the Last folder/file in the left pane, entire list will become highlighted.

• DRAG that block of highlighted files/folder to the RIGHT pane under the Filename area for wwwroot.

• All the files and folder from the Right pane above should now appear in the wwwroot directory on the cloud website.

Your InterChange Website is now installed on your cloud hosting web site URL.


5. Installing InterChange into Office 365 SharePoint Site

5.1. Installing InterChange into the App Catalog

Once you receive and customize the Akumina InterChange App Package, it needs to be installed on your 365 SharePoint Site.

• Login as Administrator onto your Office 365 SharePoint site • Navigate to the “Office 365 Admin Center”, by selecting the Menu icon on the Office 365 ribbon, and then selecting the

Admin APP on the “app launcher”

• On the “Office 365 admin Center” page, navigate to the “SharePoint admin Center” by selecting “Admin > SharePoint” on the left Navigation.


• On The SharePoint admin Center page, click “apps” in the left column Navigation.

• The SharePoint Admin “apps” page will display.


• In the right pane under “apps” click on “App Catalog”.

• On the “App Catalog” page select left column Navigation “Apps for SharePoint”.

• On the Apps for SharePoint select “+new”.


• In the Popup window “Add a document” click on “Browse” • In the file explorer window navigate to the Folder C:\Akumina where the Akumina Installation package was copied to. • Click on file “Akumina.Interchange.App.app”, and click on “Open” button in the file explorer window. • Once the file “Akumina.Interchange.App.app” appears in the Choose a file input field, click “OK” button.

• When the App upload is complete you will see the Product ID for this APP and that the APP is installed.

5.2. Adding the InterChange App to your Office 365 SharePoint Site Contents

• Navigate to the “Site Contents” page by clicking the “Gear Icon” on the SITE Ribbon and from dropdown menu click “Site Contents” .

• On the Site Contents page below select “add an app”.


• On the “Site Contents > Your Apps” page, click on Left column Navigation under “Your Apps”, “From Your Organization”

• The dialog box “Do your Trust Akumina InterChange” will appear • Click on “Trust It”.

The “Site Contents” page will display where you will see your newly added App “Akumina InterChange”.


Appendix A – Log File Error Messages If you encounter errors with InterChange, the first place to check is in the log file which captures all error messages.

The log file can be found on your SITE ROOT > logs. An example of a log file would be .

If you see the following errors, then your web.config must be updated correctly.

WHEN PASSWORD IS WRONG

2016-02-11T02:15:11.4687394Z 0dc74b6c-eebf-53c0-1b33-63957412c647 101 1 [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()

at Akumina.Interchange.Services.ContentTypeService.GetAllWebs()]

WHEN .CER USED INSTEAD OF .PFX

2016-02-11T02:16:25.0927184Z 0dc74b6c-eebf-53c0-1b33-63957412c647 101 1 [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.ContentTypeService.a()]

WHEN ISSUERID IS WRONG

2016-02-11T02:17:37.5809047Z 0dc74b6c-eebf-53c0-1b33-63957412c647 101 1 [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.UserService.GetCurrent()

at Akumina.Interchange.Web.Controllers.BaseController.PoplateUser()]

installing interchange in o365 or a thirdparty - cloud...

Documents