Installation Manual. GBS AppDesigner for SharePoint 4.2. On-premise Deployment. Document Version 1

Transcription

1 Installation Manual GBS AppDesigner for SharePoint 4.2 On-premise Deployment Document Version 1

2 Contents Part 1 - Prerequisites for the installation Introduction Prerequisites Remote Web Application On-premise Setting up the Remote Web certificate Obtaining a Domain certificate SharePoint On-premise Central Administration Starting the services Setting up Service Applications Starting the Claims to Windows Token service Creating the App Catalog in the Central Administration Creating the Developer Site or the Team Site App Web Application DNS entries ADFS Configuration Configuring ADFS Server for AppDesigner Configuring ADFS for AppDesigner for SharePoint Next steps Part 2 - Setting up and installing the app Remote Web Application On-premise Requirements for the SQL Server Setting up the Remote Web Certificates Creating the WebApplication in the IIS A note on multi-tier farms Creating the website GBS Europa GmbH Page 2

3 7.3.3 Adjusting authentication methods Adding the Site Binding for http Adding the website content to the newly created website Adjusting the app domain bindings Disable Loopback check Setting up the SharePoint Token Issuer and Root Authority Installation of the GBS AppDesigner app Uploading the app to the App Catalog Using AppRegNew.aspx for registration Installing the app in SharePoint Configuration of the database Adjustment in the Internet Explorer Disabling the Minimal Download Strategy site feature Verifying the installation Part 3 - Appendix Possible errors Certificate errors File not found (error message) The type initializer for GBSAppDesigner.Common.Client.TokenHelper threw an exception (error message) Remote Server Returned an Error: (401) Unauthorized (error message) The required anti-forgery cookie " RequestVerificationToken" is not present. (error message) Error code Error when opening the app details App deployment error Login error when IE 11 is used Error code 502 after Azure website call Error code Helpful PowerShell scripts Find Trusted Security Token Issuer GBS Europa GmbH Page 3

4 10.2 Remove an app from a SharePoint site Remove-SPTrustedSecurityTokenIssuer Remove-SPTrustedRootAuthorityget Creating the AppFabric service GBS Europa GmbH Page 4

5 Part 1 - Prerequisites for the installation GBS Europa GmbH Page 5

6 1 Introduction Part 1 of this manual is addressed to administrators and describes the prerequisites that need to be installed on SharePoint Server before the installation and configuration of GBS AppDesigner for SharePoint and how these prerequisites can be configured. These prerequisites include AppCatalog and service applications like the User Profile Service Application, which are often configured in production environments. You can use the PrerequisitesCheck.ps1 Powershell script described in chapter 8.7 to verify if your existing environment meets the AppDesigner requirements. If the prerequisites are already met, please continue reading the second part of the manual Setting up and installing the app. GBS Europa GmbH Page 6

7 2 Prerequisites For a successful installation and execution of GBS AppDesigner for SharePoint, certain prerequisites must be met. 1. The following software must be installed: Microsoft SharePoint Server 2013 (on Windows Server 2012 or Windows Server 2012 R2 or 2008 R2), Microsoft SharePoint Server 2016 (on Windows Server 2012 or Windows Server 2012 R2) or Microsoft SharePoint Online or Office 365 Microsoft SQL Server 2012 to be used for SharePoint Server 2013 or Microsoft SQL Server 2014 to be used for SharePoint Server 2016 or Microsoft SQL Server 2016 RTM to be used for SharePoint Server Additional prerequisites: The following additional requirements must be fulfilled before the installation of the app can be started. How to proceed is described mainly in part 1 of this manual. SSL connection of the SharePoint Server Certificates for SharePoint and the Remote Web Application (chapter 3.2) Configured app domain on the SharePoint Server (chapters 4.1.4; 4.1.6; 4.2) App Catalog for the Web Application, on which the app gets installed (chapter 4.1.4) Running services: Claims to Windows Token Service (chapter 4.1.3) App Management Service (chapter ) Microsoft SharePoint Foundation Subscription Settings Service (chapter ) Workflow Service Application with associated workflow (chapter ) Microsoft Workflow Manager 1.0 (chapter ) Adding the addresses of SharePoint and the Remote Web to the Intranet zone of the Internet Explorer (chapter 8.5) GBS Europa GmbH Page 7

8 DNS entries for the Web Applications of the SharePoint-Server and the Remote Web Application, if it gets installed on-premise. The Web Application must be available. The creation of the Remote Web Application depends on the configuration; thus, the DNS records must be must be created accordingly. Numerous options are available. The use of the user interface requires a web browser on a Microsoft Windows operating system (Windows 7, Windows 8.1, Windows 10). GBS aims at ensuring to support the most current version of the web browsers listed below. However, please refer to the Release Notes for information on the version number that is currently supported. Microsoft Internet Explorer Mozilla Firefox Google Chrome Using another web browser might possibly cause problems. GBS Europa GmbH Page 8

9 3 Remote Web Application On-premise AppDesigner uses a Remote Web that can be created in IIS. For information on how to create the certificates for the IIS Web Application, refer to the following. 3.1 Setting up the Remote Web certificate It is possible to use a self-signed certificate, however, this is not common practice in production environments. Instead, use Active Directory Certificate Services to obtain a domain certificate. The required steps are described in chapter 3.2. If this service is not available in your environment, you must use a self-signed certificate. For information on how to obtain it, please refer to the numerous explanations in the Internet, e.g. at Microsoft. Use a self-signed certificate only in a development or evaluation environment. For a production environment, you should obtain a certificate from an official or local certificate authority. When using a self-signed certificate, you must execute the following PowerShell commands in the SharePoint Management Shell. Normally, the SharePoint does not accept demands from other Web applications that use a self-signed certificate and throws a 403 (forbidden) error. Use the following scripts to avoid this behavior. $serviceconfig = Get-SPSecurityTokenServiceConfig $serviceconfig.allowoauthoverhttp = $true $serviceconfig.update() 3.2 Obtaining a Domain certificate You can carry out the following steps on the web front end servers or the application servers. GBS Europa GmbH Page 9

10 1. On the Remote Web, go to the IIS, click on the server object and double-click Server Certificates. 2. On the right, click Create Domain Certificate. The following window is shown: GBS Europa GmbH Page 10

11 If the Select button is grayed-out, you can try to create the domain certificate on another SharePoint Server. Click Next and then Select and select the AD Certificate Authority. Click OK. Enter a Friendly name. GBS Europa GmbH Page 11

12 3. Click on Finish and the certificate should have been created Exporting the certificate To export the certificate, right-click on your created certificate to open the context menu and click Export. Enter a password for the certificate and save it in the C:\Certs\ folder Copying the certicate as cer file 1. Double-click on the certificate. Under Details, click Copy to File and then Next. 2. Select No, do not export the private key and click Next. 3. Click again Next and then save the certificate in the C:\Certs\ folder. Once the copying procedure is finished, you will see the following window: GBS Europa GmbH Page 12

13 4. Copy both created files (*.pfx, *.cer) to the SharePoint Application Server to path C:\Certs Permissions for the certificate 1. Use Win+R Certlm.msc to open the Certificate Manager. GBS Europa GmbH Page 13

14 2. Under Personal > Certificates, you can find the created certificate. Right-click on the certificate and choose All Tasks > Manage Private Keys. 3. Add the user account which is runs the App Web Application from chapter GBS Europa GmbH Page 14

15 Certificate Import (only for Multi-Tier Farms) If you use one or more SharePoint Application Servers or SharePoint Web Front End Servers, you have to import the certificates on every Web Front End Server. 1. In the IIS Manager of the Web Front End Servers, click on the name of the machine in the left hand navigation. Double-click Server Certificates. 2. On the right, in the Actions section, choose Import.. 3. In the new Import Certificate window, click on the three dots button ( ). Navigate to the folder where the exported certificates are saved, select the appropriate certificate GBS Europa GmbH Page 15

16 (.pfx) and click Open. 4. Enter the Password for the certificate and confirm your entries with OK. Having imported your certificate, you should see the following item in the Server Certificates window. GBS Europa GmbH Page 16

17 4 SharePoint On-premise 4.1 Central Administration Starting the services In the Central Administration, navigate to System Settings> Manage services on server. In the rows App Management Service and Microsoft SharePoint Foundation Subscription Settings Service click Start Setting up Service Applications App Management Service 1. In the Central Administration, navigate to Application Management > Service Applications > Manage service applications. In the ribbon menu, click on New and then on App Management Service. GBS Europa GmbH Page 17

18 2. Complete the new page as follows and then click OK. GBS Europa GmbH Page 18

19 GBS Europa GmbH Page 19

20 Subscription Settings Service Now, the Service Application Subscription Setting must be configured through the SharePoint 2013 Management Shell. Enter the Get-SPManagedAccount command. A list of the available managed accounts that can be used for the configuration is displayed. Choose one of them to use in the following commands. In this case we use gbs\sp_farm. Run the following script to configure the service. $account = Get-SPManagedAccount "gbs\sp_farm $apppoolsubsvc = New-SPServiceApplicationPool -Name SettingsServiceAppPool -Account $account $appsubsvc = New-SPSubscriptionSettingsServiceApplication - ApplicationPool $apppoolsubsvc $proxysubsvc = New-SPSubscriptionSettingsServiceApplicationProxy - ServiceApplication $appsubsvc The cmdlets complete without a success confirmation. Therefore, you can assume, that the configuration was successful if no red error messages appear in the shell Creating the User Profile Service Application This step has to be carried out only if no user profile service exists. It is responsible for forwarding the log on to the app by the SharePoint Server. Without it, an HTTP 401 error appears. GBS Europa GmbH Page 20

21 GBS Europa GmbH Page 21

22 GBS Europa GmbH Page 22

23 After a successful creation, the following window is displayed: GBS Europa GmbH Page 23

24 Workflow Service When you first navigate to Service Applications > Central Administration and click on Workflow Service, the error message Workflow is not connected is displayed. You have to install and configure the Workflow Manager. For information on the requirements, supported platforms, topologies and system requirements, refer to the website Planning Your Deployment (Workflow Manager 1.0). Among others, you will need PowerShell 3.0 and the ports and must be available. Download the Workflow Manager 1.0 and install it. Click Finish or open the Start menu and navigate to All Programs > Workflow Manager 1.0. Click on the Workflow Manager Configuration link to start the workflow configuration wizard. GBS Europa GmbH Page 24

25 A dialog box with three options opens. If you create a new farm with the default configuration settings, the Workflow Manager and the Service Bus Farm are created with the same settings. This manual guides you through the recommended default installation. For instructions regarding custom settings, refer to this Website. Creating a new farm with default configuration settings Choose the option Configure Workflow Manager with Default Settings. GBS Europa GmbH Page 25

26 In the SQL SERVER INSTANCE text field, by default, the name of the SQL Server instance on the current computer is displayed. If you want to specify another computer with the SQL server, enter the complete name of the SQL Server instance, that is hosting the database for the farm. Click Test Connection, to check whether the connection with the entered instance name can be established. If an error occurs, the wizard will display a message, for example: vs Under Configure Service Account, enter the user ID in the format domain\user or username@domain name and an appropriate password. The wizard verifies the combination. The same user logon information is used for the Workflow Manger services and the Service Bus services. GBS Europa GmbH Page 26

27 Under Certificate Generation Key, enter a key and confirm it. The wizard verifies the keys to ensure that they match. The key is required further when you add a new computer to the farm. Activate the Enable firewall rules on this computer checkbox, if you want to enable firewall rules. If firewall rules are not enabled, the required services might not get started. Click on Continue and the wizard will display the Summary screen. If all settings are displayed correctly, click Next. Workflow Manager and Service Bus have been installed. After installation, open the SharePoint 2013 Management Shell and enter the following: Register-SPWorkflowService -SPSite " - WorkflowHostUri " To check whether the configuration was successful, proceed as follows: GBS Europa GmbH Page 27

28 On your computer, open Services and check, whether the Workflow Manager Backend has started. If this service has not started yet, right-click to open the context menu and choose Start. Switch to Central Administration> Manage Service Applications and click Workflow Service Starting the Claims to Windows Token service To start the Claims to Windows Token, in the Central Administration first, navigate to Services on Server. Go to Application Management and, under Service Applications click Manage services on Server. In the row Claims to Windows Token Service of the displayed list, click Start. GBS Europa GmbH Page 28

29 4.1.4 Creating the App Catalog in the Central Administration 1. In the Central Administration, navigate to Apps > App Management > Manage App Catalog. Select Create a new app catalog site. 2. Enter a Title and a Website Address for the App Catalog. Then choose an Administrator for this catalog. In most cases, this is a farm administrator. Finally, click OK. GBS Europa GmbH Page 29

30 GBS Europa GmbH Page 30

31 After creation, you receive a small overview page of the created App Catalog which could look like this: After the creation of the catalog, specify the app URL. To do so, in the Central Administration navigate to Apps > App Management and click Configure App URLs. Enter an app domain and a prefix. Then click OK. GBS Europa GmbH Page 31

32 4.1.5 Creating the Developer Site or the Team Site In order to make the app available directly on the Site Collection, use the Developer Site or Team Site templates to create a Site Collection on the Application Server. Please note: The language set as default language when the Site Collection is created, determines the titles of the AppDesigner-specific buttons in the List Settings ribbon. This cannot be changed after site creation App Web Application In order to adjust for authentication requirements and to allow successful request forwarding per HTTPS for the app domain, you need to create a Web Application in Central Administration. 1. In the Central Administration, navigate to Application Management and then to Manage Web Applications. 2. In the ribbon menu, click on New, to create a new Web Application under SharePoint. 3. In the creation window, enter the following settings: Create a new IIS website Name: SharePoint App Domain Port: 443 Use Secure Sockets Layer: Yes Public URL: gbs-apps.intern Application Pool name: SharePoint App Domain. 4. Confirm the settings with OK. GBS Europa GmbH Page 32

33 4.2 DNS entries A new primary zone must be set up in the DNS server. 1. To do so, navigate to the DNS Manager. Right-click Forward Lookup Zones and choose New Zone. 2. In the wizard, choose the Primary Zone zone type and, depending on the default setting in your environment, use the AD to store the zone. GBS Europa GmbH Page 33

34 3. Now choose the domain or the Zone for the apps and complete the wizard. 4. After creation, click on the newly created zone and then on the white area on the right. There, choose the New Alias (CNAME) item. GBS Europa GmbH Page 34

35 5. Specify the alias (CNAME) properties. a) Enter an asterisk (*) as Alias name. b) In the field Fully qualified domain name (FQDN) for target host, click on Browse and navigate to the host (A) entry of the SharePoint Application Server, in this case T-SP2013.gbs-test.intern. The entry is located within the Forward Lookup Zone of the SharePoint Server. Then add a HOST A entry. The host must be providerhostedapp. Within the IP address, enter the IP of the Network Balancers to which the web front end servers are connected. GBS Europa GmbH Page 35

36 5 ADFS Configuration This chapter applies only if you are using ADFS in your organization. If you are using ADFS, it is possible that you have already configured AD FS to act as an Identity Provider Security Token Service (IP-STS) for a SharePoint web application. If not, we recommend that you familiarize yourself with the following article: and follow its steps. 5.1 Configuring ADFS Server for AppDesigner This chapter applies only when your organization is using ADFS. 1. Go to the ADFS Server, login as an Administrator and open the ADFS Management Console on the server 2. Select Application Groups and then Add Application Group. 3. In Add Application Group Wizard, give your Application Group a name. This Group Name should be similar to the application that authentication is extracted from. AppDesigner is used in the Setup and Configuration instructions at hand hence AppDesigner would be a suitable name. 4. Select the Web browser accessing a web application template and then select Next. At this point the Wizard will start to generate the native part of the application. 5. You will see the generated Client Identifier (Client ID). You can edit it here if you don t like the generated one or if you just want to use your own Client ID. 6. At this point you also have to specify a Redirect URL. The Redirect URL should be the URL which points back to the AppDesigner server. This is how ADFS will know where to send codes and/or tokens to this URL. Example Redirect URL: 7. Multiple Redirect URLs can be added. Together they make up the Allowed URLs List 8. Select Next. You will be asked to choose the Access Control Policy. Choose Permit everyone and then select Next again. An application summary will be displayed for you similar to this: GBS Europa GmbH Page 36

37 9. Then select Next and finally Close. Now the first part (Native Part of our Application Group) of the ADFS Server setup and configuration is complete. Next the automatically created Web application part has to be configured. GBS Europa GmbH Page 37

38 1. Open your Web application part (from the Application Groups, from your application): 2. Now setup and configure all the Web application Properties including [Identifiers], [Notes], [Access control policy], [Issuance Transform Rules] and [Client Permissions]. 3. In the Identifiers tab, you can setup the Relying Party Identifiers. Note that the Client ID from out the native part of the Application is already there as the first given Relying Party Identifier. No other is needed. 4. In the Notes tab, you can write any notes to do with our implementation. 5. In the Access control policy tab, you can select Permit everyone, but this has already been setup in a step of the previous chapter here you can change it if needed at some point. 6. In the Issuance Transform Rules, setup at least one rule (the rule describing exactly which claims to be added to the token). 7. Select Add Rule to open Add Transform Claim Rule Wizard. 8. From the dropdown list, select Send LDAP Attributes as Claims and then Next. Enter a Claim Rule Name, e.g. UPN as LDAP. In Attribute Store select Active Directory. You will see two columns of the Mapping of LDAP attributes to outgoing claim types 9. Select User-Principal-Name in the LDAP column. GBS Europa GmbH Page 38

39 10. Select UPN in the corresponding Outgoing Claim Type. 11. Select Finish. 12. Lastly, the permissions for the native application need to be set. In the Client Permissions tab, select Your Native Application 13. Create a new scope by selecting New Scope and call it read. 14. Enable the newly created read scope by ticking its checkbox. 15. Check also the allatclaims, aza, openid, profile, and user_impersonation scopes checkboxes. 16. Select Apply and then select OK. The permissions are set and the Application Group can be closed. 5.2 Configuring ADFS for AppDesigner for SharePoint 1. Locate and open the Application Group created in the previous chapter. 2. Open the Native Application, note the Client Id and add the URL of the Provider Hosted App that you will create in chapter 8.2 to the Redirect URI list. Those values will be needed for web.config setup later. 3. Open the Web Application and add the URL of the provider hosted app to the Relying Party Identifiers. The URL has to be exactly the same (including the protocol and the trailing slash). GBS Europa GmbH Page 39

40 4. Verify the Client Permissions, which will complete the process of registering the app: GBS Europa GmbH Page 40

41 6 Next steps At this point, the prerequisites for the installation of GBS AppDesigner for SharePoint are fulfilled. You can verify them using PrerequisitesCheck.ps1 Powershell script described in chapter 8.7. Refer to the second part of the manual for information on how to install the app. GBS Europa GmbH Page 41

42 Part 2 - Setting up and installing the app GBS Europa GmbH Page 42

43 7 Remote Web Application On-premise 7.1 Requirements for the SQL Server In the SQL Server; a login with SQL authentication must be created. This login requires dbcreator permissions at the Server Roles. You can also use an existing user; this user needs an SQL authentication and the dbcreator permissions. 7.2 Setting up the Remote Web Certificates It is possible to use a self-signed certificate, however, this is not common practice in production environments. Use Active Directory Certificate Services instead, to obtain a domain certificate. The required steps are described in chapter 3.2. If this service is not available in your environment, you must use a self-signed certificate. For information on how to obtain it, please refer to the numerous explanations in the Internet, e.g. at Microsoft. For information about how to obtain a domain certificate, refer to the first part of the manual. 7.3 Creating the WebApplication in the IIS A note on multi-tier farms The following steps have to be performed on all web front end servers of the farm Creating the website In the IIS, create an application pool named ProviderHostedApp. Once the application pool is created, the website can now be created. 1. In the navigation on the left, right-click the Sites entry and choose the Add Website. GBS Europa GmbH Page 43

44 2. In the window, enter the following data: Site name: ProviderHostedApp Host name: providerhostedapp 3. Click Select and select the ProviderHostedApp application pool that you had just created. Confirm your choice with OK. 4. Click the three dots ( ) button next to the Physical path input field. Navigate to the C:\inetpub\wwwroot\ path and create a new folder named ProviderHostedApp. Confirm the path with OK. GBS Europa GmbH Page 44

45 5. From the Type drop-down field select the https entry. 6. From the SSL certificate drop-down field select the entry of the certificate imported before, in this case ProviderHostedAppCert. 7. Check your entries and confirm with OK. GBS Europa GmbH Page 45

46 7.3.3 Adjusting authentication methods In the central section of the IIS, the properties page of the newly created website opens. 1. Double-click Authentication. 2. Right-click Anonymous Authentication and click Disable. Then right-click Windows Authentication and select Enable. 3. In the left section, click on the Services Folder. It is located below the website. GBS Europa GmbH Page 46

47 4. In the central section, select then Authentication. Here, deactivate Windows Authentication and activate Anonymous Authentication Adding the Site Binding for http The next step is to add an additional binding to the website. 1. Right-click the ProviderHostedApp website and then select Edit Bindings. 2. In the newly opened Site Bindings window, click Add button. GBS Europa GmbH Page 47

48 3. Under Host name, enter the providerhostedapp name and confirm with OK Adding the website content to the newly created website Installing Web Deploy In order to install the web application provided with the AppDesigner package, you need the Microsoft Web Deployment tool. You can install Web Deploy by using the Web Platform Installer, by running the Web Deploy Windows Installer, or from the command line by using Msiexec.exe. The Web Platform Installer requires fewer steps, while the other methods allow you to customize your installation. In all cases, you should perform the installation only if you are logged on as an administrator. The following tutorial will show how to install the Web Deployment tool using the Web Platform Installer. For instructions how to install Web Deploy from the command line please refer to the Microsoft article on Web Deployment Tool Installation. 1. Download the Web Deployment Tool from this location, choosing the correct bit version: GBS Europa GmbH Page 48

49 2. Run the downloaded.msi file: 3. Accept the terms in the License Agreement. 4. Choose a setup type. GBS Europa GmbH Page 49

50 5. Click Install to begin the installation. 6. After the program installed successfully, the Web Deploy Tool is ready Adjusting SetParameters.xml file. 1. In the installed version of the AppDesigner (by default C:\Program Files (x86)\gbs) navigate to the WebContent folder and open the GBSAppDesignerWeb.SetParameters.xml file: 2. Enter the IIS Web Application Name created in the previous chapters, e.g. PHA or ProviderHostedApp. In the example below it is PHA: 3. Enter the ClientID and ClientSecret. The values must be the same as the values entered during the app package registration described in chapter 8.2. You can generate them using /appregnew.aspx site described in chapter In all three connectionstrings the DataSource parameter must be adjusted. It is the database connection to the instance. In this example SP2013. The Initial Catalog denotes the name of the database. By default, it is AppDesigner. Change it only if you want to use a custom name to conform with your naming conventions. 5. After adjusting these values, the SetParameters.xml file is ready. Save it and exit the editor Running AppDesignerWeb.deploy.cmd command. Run the GBSAppDesignerWeb.deploy.cmd command. The command accepts several flags, the required ones being: /t which calls the msdeploy.exe with -whatif flag and simulates deployment and /y which deploys the package to the current machine. For the full list of accepted flags, please refer to the next chapter. You can test the command by running it with /t flag first: GBS Europa GmbH Page 50

51 To execute and deploy the package run the command with /t flag: <PATH>\WebContent\GBSAppDesigner.Solutions.GBS.AppDesignerWeb.deploy.cmd /y You will see the progress and the end result: After running the command, open the IIS site location (to do so, navigate to IIS>Sites>PHA and right click on Explore) and verify that the files are present Accepted Flags for AppDesignerWeb.deploy.cmd command Required Flags /T: Calls the msdeploy.exe with the "-whatif" flag, which simulates deployment. This does not deploy the package. Instead, it creates a report of what will happen when you actually deploy the package. /Y: Calls the msdeploy.exe without the "-whatif" flag, which deploys the package to the current machine or a destination server. Use /Y after you have verified the output that was generated by using the /T flag. Note: Do not use /T and /Y in the same command. Optional Flags By Default, this script deploys on the current machine where the script is called with current user s credentials without agent service. Only pass the following values in an advanced scenario: /M:<Destination server name or Service URL> GBS Europa GmbH Page 51

52 If this flag is not specified, the package is installed on the computer where the command is run. The Service URL can be in the following format: This format requires that IIS 7 be installed on the destination server and that IIS 7 Web Management Service(WMSvc) and Web Deployment Handler be set up. The service URL can also be in the following format: This format requires administrative rights on the destination server, and it requires that Web Deploy Remote Service (MsDepSvc) be installed on the destination server. IIS 7 does not have to be installed on the destination server. /U:<UserName> /P:<Password> /G:<True False> Specifies if the package is deployed by creating a temporary listener on the destination server. This requires no special installation on the destination server, but it requires you to be an administrator on that server. The default value of this flag is False. /A:<Basic NTLM> Specifies the type of authentication to be used. The possible values are NTLM and Basic. If the wmsvc provider setting is specified, the default authentication type is Basic; otherwise, the default authentication type is NTLM. /L Specifies that the package is deployed to local IISExpress user instance. Additional msdeploy.exe flags: The msdeploy.exe command supports additional flags. You can include any of these additional flags in the GBSAppDesignerWeb.Deploy.cmd" file, and the flags are passed through to the msdeploy.exe during execution. Alternatively, you can specify additional flags by setting the "_MsDeployAdditionalFlags" environment variable. These settings are used by this batch file. Note: Any flag value that includes an equal sign (=) must be enclosed in double quotation marks, as shown in the following example. Here, the deployment will skip deploying the databases that are included in the package: "-skip:objectname=dbfullsql" GBS Europa GmbH Page 52

53 For additional instructions refer to GBSAppDesignerWeb.deploy-readme.txt file in the WebContent folder Possible issues Argument cannot be null or empty Verify if you entered the values in the SetParameters.xml file and saved it. The system was unable to find the specified registry key or value. Verify if msdeploy.exe is installed on your machine. Follow the steps from Installing Web Deploy chapter Adjusting the web.config file In the content of your IIS website, you should find a web.config file. Open it e.g. with Notepad and navigate to the AppSettings section at the top of the document. In this section you should see the Client ID and Client Secret that you entered before in the Parameters.xml file: GBS Europa GmbH Page 53

54 Apart from the authentication settings, two more values need to be adjusted: IssuerID and x509certificate. The IssuerID should be the same as the Issuer ID in the script from chapter 7.5 Thumbprint comes from a certificate created in chapter 3.2 and associated with the remote website in chapter 7.2: Please refrain from copying-pasting the thumbprint directly from the certificate into the web.config file as it is possible that the first character is the invisible Unicode "left-to-right-mark". For more information on this topic, refer to this Microsoft article: A little below the IssuerID in the AppSettings section you will find the authentication parameters: a) If your organization is using ADFS, you need to enter the following parameter values: ADFS:AuthenticationType Enter the parameters as follows: GBS Europa GmbH Page 54

55 for ADFS authentication: ADFSOpenIDConnect for NTLM authentication: None for Azure site in a O365 installation scenario: AzureOpenIDConnect. The following lines describe the ADFS authentication, so please enter ADFSOpenIDConnect. ida:clientid on your ADFS server, under Application Groups you can find the registration of your native app. Choose its Client ID: ida:redirecturi the URL of the AppDesigner site in IIS ida:secret the Secret of your native app registration on the ADFS server ida:authority your local ADFS ida:resourceuri the address of AppDesigner spsaml:claimprovidertype enter SAML. b) If your organization is not using ADFS ADFS:AuthenticationType for ADFS authentication: ADFSOpenIDConnect for NTLM authentication: None for Azure site in a O365 installation scenario: AzureOpenIDConnect. The following lines describe the ADFS authentication, so please enter None. spsaml:claimprovidertype enter NONE spsaml:identityclaimtype enter SMTP". GBS Europa GmbH Page 55

56 Setting automatic start for Application Pool 1. Navigate to the IIS Manager and click on the server. In the central view, open the Management section and click Configuration Editor. 2. In the upper selection area Section choose the system.applicationhost path and there applicationpools. 3. Activate Collection and then click the three dots ( ) button. A window named Collection Editor system.applicationhost/applicationpools/ opens. 4. Choose the Application Pool of the Provider Hosted App. Under Properties, change the following items: autostart: True startmode: AlwaysRunning GBS Europa GmbH Page 56

57 5. Then close the Collection Editor system.applicationhost/applicationpools/ window and on the right, under Actions, click Apply NTFS permission of the website content folder 1. In the left section, right-click on the Provider Hosted App website and select Edit Permissions. 2. In the Properties windows, open the Security tab and then click the Edit button. 3. Click Add to add the Authenticated Users group. Choose the Read & execute, List folder contents and Read permissions. GBS Europa GmbH Page 57

58 7.3.6 Adjusting the app domain bindings The creating and adjusting of the website is completed (refer to the respective chapter). The following steps imply that you have already created a domain certificate and a website. For a detailed description on how to create a domain certificate, refer to the first part of the manual. Now, change the binding for the web application of the app domain. 1. Navigate to the Site bindings of the web application. 2. Double-click the HTTPS entry. Delete the Host name entry and, under SSL Certificate, choose the App Domain certificate. GBS Europa GmbH Page 58

59 7.4 Disable Loopback check To allow a local execution of the app on the IIS server, the Loopback Check must be disabled. This function is used to prevent local DDOS attacks. If the Loopback Check is activated, the logon data must be re-entered when a SharePoint web application is started. This prevents a smooth functioning of the app. Therefore, execute the following PowerShell command: New-ItemProperty HKLM:\System\CurrentControlSet\Control\Lsa -Name DisableLoopbackCheck -value 1 -PropertyType dword This script adds a registry key that deactivates the Loopback Check. 7.5 Setting up the SharePoint Token Issuer and Root Authority Execute this section on the SharePoint Application Server. The copied certificate is required to logon to the Root Authority and to sign in as official Token Issuer. The certificate is used to receive an Access Token from SharePoint. This token is required by the app for accessing the SharePoint Server. Add-PSSnapin Microsoft.SharePoint.Powershell $publiccertpath = "C:\certs\ProviderHostedApp.CER" $SPURL =" $SPWEB = GET-SPWEB $SPURL $certificate = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($publicCertPath) New-SPTrustedRootAuthority -Name "ProviderHostedAppCert" -Certificate $certificate $realm = Get-SPAuthenticationRealm $specificissuerid = " f a12-a2df-a12cafd8013e" $fullissueridentifier = $specificissuerid + '@' + $realm New-SPTrustedSecurityTokenIssuer -Name "Provider Hosted App Cert" -Certificate $certificate -RegisteredIssuerName $fullissueridentifier IsTrustBroker $APPPRINCIPAL = REGISTER-SPAPPPRINCIPAL -NAMEIDENTIFIER $fullissueridentifier -SITE $SPWEB -DISPLAYNAME "ProviderHostedApp Cert" SET-SPAPPPRINCIPALPERMISSION -SITE $SPWEB -APPPRINCIPAL $APPPRINCIPAL -SCOPE SITE - RIGHT FULLCONTROL GBS Europa GmbH Page 59

60 iisreset /noforce $serviceconfig = Get-SPSecurityTokenServiceConfig $serviceconfig.allowoauthoverhttp = $true $serviceconfig.update() Adjust the publiccertpath variable by entering the Path to the already created Certificate for the ProviderHostedApp. The specificissuerid is the same Issuer ID as in the web.config and does not need to be adjusted. GBS Europa GmbH Page 60

61 8 Installation of the GBS AppDesigner app Take the.app package provided and open it, e.g. with a WinRAR program. Open AppManifest.xml and enter the ClientID from web.config instead of *. Replace ~remoteappurl with an actual url of IIS website, like in the example below: In the same.app package navigate to the biggest elements<guid>.xml file and replace ~remoteappurl with the url of your IIS website: 8.1 Uploading the app to the App Catalog You can upload the delivered GBSAppDesigner.SP.app file to the app catalog that you have created. GBS Europa GmbH Page 61

62 1. To do so, navigate to Apps for SharePoint, then click on New app to upload the app. 2. In the newly opened window, enter the path of the GBSAppDesigner.SP.app file. Then confirm with OK. The app is now uploaded and its properties can now be updated. 3. Since the properties of the app cannot be filled through the appmanifest.xml, this has to be done manually. So you have to enter the information in the appropriate fields. You can obtain the information Either from the following sections Or from text files that have been delivered with the installation package for this purpose. There is a separate file for each language (German and English). The AppDesigner logo is also included in the installation package. Once the information is entered, confirm your entries with Save. Text and information in English: Title: GBS AppDesigner Short Description: GBS AppDesigner for SharePoint GBS Europa GmbH Page 62

63 Description: GBS AppDesigner allows for the intuitive creation of business applications, their use across platforms and on mobile devices and their integration into social business platforms such as Microsoft SharePoint and IBM Connections. The app makes it possible to run the business applications you created with GBS AppDesigner in Microsoft SharePoint. Using the app's full range of features requires a valid license for GBS AppDesigner. Icon URL: Publisher Name: GBS Europa GmbH GBS Europa GmbH Page 63

64 4. Wait until uploading of the app has finished and then refresh the browser. You should see the following page: 8.2 Using AppRegNew.aspx for registration You should use AppRegNew.aspx for the registration of your app for SharePoint if you will use the app only in one tenant or one farm. For example, if you create apps for one single organization and use the organization s app catalog to distribute the app, you can use the AppRegNew.aspx page of any website in a tenant or farm to register the app. To create the app identity, navigate to in the tenant or the farm. For the registration, you require the following values from the web.config or the AppManifest.xml: Client ID/App ID = 36ae3836-f863-4acd-b92b-c2b9218a26e3 Client Secret/App Secret = swwmrjfkrtg1tcf34+aurukxwj3pktt2+xn1dx0dgxa= Title = GBS AppDesigner App Domain = providerhostedapp Redirect URI = The deviation URI is required for those apps that are started from outside of SharePoint. The value must be a complete endpoint URL. HTTPS is required. GBS Europa GmbH Page 64

65 Please fill in the blanks as follows and then click on Create: Once you have registered the app successfully, the following window is displayed. Click OK to complete the registration. GBS Europa GmbH Page 65

66 8.3 Installing the app in SharePoint Add GBS AppDesigner to your SharePoint site: 1. To do so, click Add an app. Under Site Contents > Your Apps, the GBS AppDesigner app is displayed under Apps you can add. 2. Under AppDetails, you can display the information about the app: Remark: The AppDetails are entered manually as described in chapter 8.1 Uploading the app to the App Catalog of this manual. 3. Under Apps you can add, click GBS AppDesigner, to install this app. GBS Europa GmbH Page 66

67 4. Then, assign access rights to the app on the Site Collection. After a successful installation, the app you installed will be listed on the Site Contents and Home pages. GBS Europa GmbH Page 67

68 When you open the app, the login dialog appears for you to login. 8.4 Configuration of the database After the installation, in the GBSAppDesigner SQL database, add an entry to the dbo.applicationadmins table to assign the Application Administrator permission to a user. Users with such a permission can, for example, add comments to an error. Use the following SQL command to perform this task. Replace the values within the apostrophes. USE GBSAppDesigner INSERT INTO dbo.applicationadmins(salutation,firstname,lastname,loginname, ,phone) VALUES ('Hello','Max','Mustermann','dev\maxmustermann','maxmustermann@vorlage.de',' '); GBS Europa GmbH Page 68

69 8.5 Adjustment in the Internet Explorer To allow the forwarding of the login data to the Remote Web Application, we recommend adjusting the security settings of your browser for Trusted Sites and Local Intranet. 1. To do so, in your Internet Explorer, navigate to Tools > Internet Options > Security. 2. First, select Trusted Sites and click Sites. Add the URL of your app. 3. Now, select Local intranet and click Sites. Click Advanced. 4. Add the URL of your Web Application under which the app is installed. 5. Close the Internet Options window and the browser. When the browser is reopened, the app should open successfully. 8.6 Disabling the Minimal Download Strategy site feature 1. Open the Site Settings and follow the Manage Site Features link. 2. Search for the Minimal Download Strategy entry. 3. If this feature is active, disable it. 8.7 Verifying the installation Your installation package for AppDesigner includes a CheckPrerequisites.ps1 Powershell script which verifies if the AppDesigner prerequisites have been fulfilled and if the IIS website follows the above mentioned settings. As there is a wide number of possible SharePoint settings variations and every GBS Europa GmbH Page 69

70 installation can be customized and adjusted to individual needs, the script verifies only basic scenario, settings and general availability of the required services. It does not modify any settings nor apply any changes nor in way alter the existing setup of the SharePoint Server. It merely displays information in green on the settings that passed verification and in red on the settings that may need additional attention. Analyze the script suggestions critically and make sure they conform to your specific needs before you make any changes to your environment based on the outcome of this script. How to use the script? Open the file and enter the required values: # Name of the IIS Website for the provider hosted app, e.g. 'AppDesigner' $NameOFTheIISWebsite="PHA" # Url of the web application with app catalog and site collections. Please leave empty if you intend to deploy AppDesigner in multiple Web Applications $WAWithApp=" # Path to the log file $LogFilePath="C:\PrerequisiteChecklogfile.txt" GBS Europa GmbH Page 70

71 Possible outcome: GBS Europa GmbH Page 71

72 Part 3 - Appendix

73 9 Possible errors 9.1 Certificate errors When appropriate, please refer to File not found (error message) If a SharePoint error page displays the File Not Found text, when the app is called, the binding of the page was omitted or was named incorrectly. GBS Europa GmbH Page 73

74 9.3 The type initializer for GBSAppDesigner.Common.Client.TokenHelper threw an exception (error message) The app does not find the stored certificate on the Web Front End server. Check whether you have created the correct path in the web.config and the certificates are really located on the given locations on the Web Front End servers. 9.4 Remote Server Returned an Error: (401) Unauthorized (error message) If this error appears, the respective machine should be restarted. In addition, you should make sure, that the user who has logged-on to the client, is also a user of the SharePoint platform. Alternatively, use a browser other than the Internet Explorer. GBS Europa GmbH Page 74

75 9.5 The required anti-forgery cookie " RequestVerificationToken" is not present. (error message) If this error appears, change the URL of the app to This will set an http cookie. If the error still appears, we recommend adjusting the security settings of your browser for Trusted Sites and Local Intranet. 1. In your Internet Explorer, navigate to Tools > Internet Options > Security. 2. Select Trusted Sites and click Sites. Add the URL of your app. 3. Select Local intranet and click Sites. Click Advanced. 4. Add the URL of your Web Application under which the app is installed. GBS Europa GmbH Page 75

76 5. Close the Internet Options and the browser. When the browser is reopened, the app should open successfully. 9.6 Error code 503 If the app is not displayed and issues a 503 error, the Application Pool of the Provider Hosted App did not start. To resolve the error, navigate to the IIS Manager and open the view of the Application Pools. Click on the Application Pool of the ProviderHostedApp and on the right, in the Actions section, choose Start. Then execute the iisreset /noforce command as administrator. 9.7 Error when opening the app details If the Sorry, something went wrong error message appears, when opening the Details view, it might be because of the Service Pack 1 for SharePoint. The problem can be resolved by executing a PowerShell command. This command creates a new database for Usage and Health Logging Application Service. Add-PSSnapin Microsoft.SharePoint.PowerShell GBS Europa GmbH Page 76

77 Get-SPUsageApplication Set-SPUsageApplication -DatabaseServer "databasename" - DatabaseName "WSS_UsageApplication2" 9.8 App deployment error This error can appear if the app does not have the correct structure at deployment. This error often appears in connection to 7zip, when the folder of the app instead of the content is selected for zipping. Through this folder, the app structure becomes incorrect and cannot be deployed correctly. 9.9 Login error when IE 11 is used If Internet Explorer 11 is used, the login box is displayed in the iframe. 1. Open the Internet Options. 2. Switch to the Privacy tab and click Sites. GBS Europa GmbH Page 77

78 3. Enter the gbs.com website and click Allow. 4. Confirm the dialogs with OK. 5. Optionally: a) Use STRG + SHIFT + ENTF, to open the dialog for cash deletion. b) Restart the browser Error code 502 after Azure website call If the Azure website throws a 502 error, this can mean that the Bin folder of the GBS AppDesigner app contains old versions of DLLs or that some DLLs are missing. A 502 error is also thrown if SharePoint Online cannot route the context to the app. This happens if your SharePoint tenant is not configured for the connection with the Azure website. GBS Europa GmbH Page 78

79 9.11 Error code Grant read permissions to the IIS_IUSRS group for the folder of the ProviderHostedApp. GBS Europa GmbH Page 79