Sean Gerlinger’s Visual KB

Configuring SharePoint Apps or Add-ins with SSL encryption

Sean Gerlinger — Fri, 23 Feb 2018 18:30:31 GMT

If you are trying to configure SharePoint Add-ins or Apps on a farm that has multiple web applications using SSL encryption. It can be a bit of challenge to understand how to configure the App domain to work with SSL. Now that we can use Server Name Indication (SNI) since IIS 8.0. We can have multiple SSL certificates bound to one port in IIS for each IIS site. No need to have multiple IP addresses on the web front end servers anymore. Below I go through each configuration step briefly to help you understand how to set a SharePoint farm to use Add-in or Apps. Certificates You will need one SSL wildcard certificate for your app domain web application and one standard SSL certificate for each of your web applications that will be using SSL encryption. Step 1 – App Domain wildcard SSL endpoint certificate. You will need to have a SSL wildcard certificate generated for your App Domain. I'm using *.contosoapps.com for the friendly name in this example. Step 2- All Other Web Applications using SSL certificates. You will also need to have a Web applications SSL certificates generated with their friendly name for all your Web applications that will be using SSL encryption. I'm using portal.contoso.com in this example. DNS You will need a forward lookup zone in DNS for the App Domain with a wildcard Host record. Step 1 – Create a forward lookup zone in your DNS for your App domain. I'm using ContosoApps.com in my example. Step 2 – Create a Host (A) record in the forward lookup zone with a wildcard pointing to your SharePoint web application's VIP or server's IP address depending on how you have web application configured. In this example, I'm pointing the wildcard Host record to my SharePoint server's IP address since I'm not using a VIP. SharePoint Continue with the steps below to configure the SharePoint portion for Apps and Add-ins. Step 1 - App Management and Subscription Service applications We need to make sure we have a App Management and Subscription service application running in the farm. If not, create them using the PowerShell scripts listed below: App Management service application – To create a App Management service application with PowerShell, use the script below.

$AppPool = Get-SPServiceApplicationPool "SharePoint Web Services Default" $App = New-SPAppManagementServiceApplication -ApplicationPool $AppPool -Name "App Management" -DatabaseName AppManagement_DB $proxy = New-SPAppManagementServiceApplicationProxy -ServiceApplication $App -Name "App Management Proxy"

Subscription Settings service application – To create the Subscription service, you must use a PowerShell script to create it. Use the script below.

$AppPool = Get-SPServiceApplicationPool "SharePoint Web Services Default" $Sub = New-SPSubscriptionSettingsServiceApplication -ApplicationPool $AppPool -Name "Subscription Settings" -DatabaseName SettingsService_DB $proxy = New-SPSubscriptionSettingsServiceApplicationProxy -ServiceApplication $Sub

Step 2 - App Management and the Subscription Settings services Make sure the App Management and the Subscription Settings services are running at least on one of the servers in the farm by checking in Central Administration\System Settings\Manage Services on server. Start them both if they are not started. Step 3 - Configure App URLs Now we need to set your App domain and the App prefix for your URLs. Navigate to Central Administration\Apps\Configure App URLs to configure these settings. App domain – Enter the name of your app domain, usually it's your domain+apps. See the example below. App prefix – This will be the app prefix added to the applications URL Step 4 - App Domain Web application We need to create a web application for the App Domain that does not have a Host Header configured and will only be accessed by the Apps. We will bind the App Domain's SSL wildcard certificate to the IIS site once we create it.

Name – Give your App domain web application a name Port – Use port 443 for SSL Host Header – Leave the Host Header blank, we need to be able to access this site with any name. Use Secure Sockets Layer (SSL) - Yes

Step 5 - App domain wildcard SSL certificate Bind the App domain's wildcard SSL certificate to your new app domain web application using IIS manager on your web server. You will need to repeat this on all your SharePoint web front end servers in the farm. Note – Please make sure you have no Host name configured and bind your certificate to your site. Step 6 - SharePoint Web applications Now that you have the farm configured for SharePoint Add-ins and Apps. You can create a SSL web application or extend an existing web application to use SSL and Host Headers like my example below.

Name – Enter a name for you web application Port – 443 Host Header – Enter a Host Header for you site, should match the friendly name of the SSL certificate. Use Secure Sockets Layer (SSL) - Yes

Step 6 – Bind the Web applications SSL certificate to its IIS site. Make sure the Host name is correct and check the box for "Require Server Name Indication". Next bind the correct SSL certificate to the site that matches the Host name. SAML Authentication configuration notes (Don't do if you are not using SAML Authentication) If the SharePoint web applications is configured to use SAML authentication. You will need to perform these extra steps below to allow your SharePoint Apps and Add-ins to be authenticated correctly. Step 1 - UseWReplyParameter You will need to enable UseWReplyParameter in the SharePoint SAML configuration on your SharePoint farm by using the following PowerShell script. Note – Update the name of your Trusted Identity provider before running the script below.

$ap = Get-SPTrustedIdentityTokenIssuer "ADFS" $ap.UseWReplyParameter = $true $ap.Update()

Step 2 - Identity Provider extra configuration Your web application's relying party will need to have an extra Passive Endpoints for you Apps URLs. In my example below, I'm using ADFS as my claim provider and added the endpoint https://*.contosoapps.com/_trust/ to my URL list of endpoints. Depending on your claim provider, it might be called something else. This will allow SAML authentication to work with your SharePoint apps and add-ins. ADFS Relying party example: https://*.contosoapps.com/_trust/

SharePoint – Using PowerShell to query the userinfo table

Sean Gerlinger — Wed, 21 Feb 2018 18:11:19 GMT

If you are a SharePoint engineer that needs to collect the user's information for a site collection straight from the content database and you don't have access to SQL. You can use a PowerShell script like below to query the content database for your site collection and all its users. It will provide you with the list of users from the site collection's userinfo table along with the authentication format of the user's account. This will help you troubleshoot permissions issues with users that have been added incorrectly or a failed migration. Note - To run the script, update the site collection in Yellow below with the site collection you are troubleshooting. It will output the data to the screen and to a file called userinfo.txt in the local path.

############################################################################### # This script will return all the users in the Site collection's userinfo table # This output will show the user accounts and their authentication format # Update the site collection below with your site collection ###############################################################################

$sitecollection = "https://www.contoso.com/sites/site1"

############################################################################### Add-PSSnapin "Microsoft.SharePoint.PowerShell" $site = get-spsite $sitecollection $siteid = $site.ID $DBServer = $site.Contentdatabase.server $Database = $site.Contentdatabase.name

function Run-SQLQuery ($SqlServer, $SqlDatabase, $SqlQuery) { $SqlConnection = New-Object System.Data.SqlClient.SqlConnection $SqlConnection.ConnectionString = "Server =" + $SqlServer + "; Database =" + $SqlDatabase + "; Integrated Security = True" $SqlCmd = New-Object System.Data.SqlClient.SqlCommand $SqlCmd.CommandText = $SqlQuery $SqlCmd.Connection = $SqlConnection $SqlAdapter = New-Object System.Data.SqlClient.SqlDataAdapter $SqlAdapter.SelectCommand = $SqlCmd $DataSet = New-Object System.Data.DataSet $SqlAdapter.Fill($DataSet) $SqlConnection.Close() $DataSet.Tables[0] }

# File output to UserInfo.txt in the local folder Run-SQLQuery -SqlServer $DBServer -SqlDatabase $Database -SqlQuery "SELECT [tp_Login],[Tp_Title],[tp_Email],[tp_deleted] FROM Userinfo where tp_SiteID like '$siteid'" | out-file UserInfo.txt -append

# Screen output Run-SQLQuery -SqlServer $DBServer -SqlDatabase $Database -SqlQuery "SELECT [tp_Login],[Tp_Title],[tp_Email],[tp_deleted] FROM Userinfo where tp_SiteID like '$siteid'"

##############################################################################

SharePoint – Troubleshooting “Access denied” issues when using SAML authentication

Sean Gerlinger — Mon, 29 Jan 2018 18:42:42 GMT

Are SharePoint users getting the message "Sorry, this site hasn't been shared with you." when trying to give them access to a SharePoint site that uses SAML authentication? Below I explain some of the common mistakes that administrators make when giving users permissions to a SharePoint site that is using SAML authentication. Giving users access to SharePoint using SAML When using SAML claims with SharePoint, depending on your SAML configuration. You can give your users access either by using the user's identity claim or Group/Role claim. Below I go over both methods. Giving access using the Identity claim of the user To give access using the user's Identity claim, you first need to determine which claim is configured as the Identity claim in your SharePoint farm. This is the special claim that SharePoint uses to identify the user. If you are not sure which claim has been configured to be the identity claim in your farm. Then run the following PowerShell script on one of your SharePoint servers using the SharePoint Management Shell. In the screen shot below you can see that my identity claim is "E-Mail Address". In other cases, it might be configured as the UPN, SamAccount, or some other type of claim used for identifying the user. Get-SPTrustedIdentityTokenIssuer | % {$_.IdentityClaimTypeInformation} Now that you have found your identity claim type. We need to determine if the user is getting added to the site correctly. If you do not have a custom claim provider configured on your farm. It is important to understand that it is very easy to add the user in-correctly to SharePoint. SharePoint will not validate the user against the identity provider like you are used to when using Windows claims. This means you must enter the user's identity claim correctly without typos. Incorrectly adding the user Since my farm doesn't have a custom claim provider configured, I can accidently add the user in correctly. I should be using the E-Mail address claim and not something like the users display name. Correctly adding the user When picking your user, make sure you select the user in the list that has the identity claim and not some other claim that is not the user's identity claim. In the screen shot below I am choosing the user with the E-Mail claim by hovering over it to see the claim type. Giving access by using a Group/Role claim Depending on your custom claim provider, you might call your groups "Roles" or "Groups. They are both the same thing. Using the group/role claim can be just as tricky because they can come in a few different formats. Depending on the custom claim provider configuration, you could be using one of a few formats for groups. For example, they might be in the format as "domain\group name" or just "group name" without the domain name. Below I show examples of a few group format examples. Unique Group name – "Group A" Domain name with group name – "Contoso\Group A" If you are not sure what format your Group/Role claim is in. You can capture a Fiddler trace of the user to collect SAML token being created for the user. There we can determine if we are using the right claim format. See the next section below. Collecting the SAML token with a Fiddler trace If you have determined that you are correctly giving your user permissions either by the identity claim or by Group/Role claim. We can take a Fiddler trace from the user's workstation during the login process to the SharePoint site. You can validate what claims your custom claim provider is provider to the SharePoint server on for the user. Step 1 – Download and install the Fiddler application to the user's workstation - Fiddler Download Here. Installing Fiddler is straight forward, just go through the install wizard selecting Yes to all the menus till its completed. Step 2 – Once you have Fiddler installed, start the Fiddler application. Next make sure you enable HTTPS so we can decrypt the SSL packets. To do so, select "Tools/Options" on the Ribbon, then select the "HTTPS" tab. Check the box next to "Capture HTTPS CONNECTs" and the box next to "Decrypt HTTPS traffic". Select OK to complete the configuration. Step 3 – To start and stop the capturing, you can click on File in the top ribbon and select "Capturing Traffic" or by clicking "F12". When it's capturing you will see the words "Capturing" in the lower left corner. Step 4 – Once you have Fiddler capturing, have the user log in to the SharePoint site using Internet Explorer. The user should be re-directed to the custom claim provider for authentication. Step 5 – Once the user gets the error message, stop the Fiddler trace by pressing F12. Step 6 – Now review the Fiddler trace looking for the URL that contains "/_trust/". See my screen shot below. You can see in frames 2 through 5 the user accessed the SharePoint site and was re-directed to the custom claim provider in frames 7 through 9. Frame 10 is where we get the SAML token that was generated by the custom claim provider. Select the "Inspectors" tab and then the "WebForms" tab. Locate the "wresult" section and copy everything opposite from it in the value Colum. Step 7 – Paste the contents into a Notepad and save it as a XML file, see below. Be sure to switch your Save as type to "All Files (*.*)". Step 8 – Open the saved XML file using your web browser. Reviewing the information in the SAML token you can see the claims provided by your custom claim provider. SAML token explained: GREEN Box – Here you can see the email address identity claim for the user. This is the claim we are looking for when identifying the user. When giving this account permission to the SharePoint site, it has to be in the same format as found in the Fiddler trace above.. BLUE Box – Here you can find the role claims for the user. Take note of the format of the role claims in your SAML token, this is the format you should use when adding it to your SharePoint site with people picker. YELLOW Box – Here we can find the SAML Life time by subtracting the Created time from the Expired time. This value is set by the claim provider. In this example its set for 1 hour. STEP 9 – Using the information in the SAML token you can validate if you are giving the user permission correctly to the SharePoint site using the correct identity or Group/Role claims. Try re-adding the user to the site collection using one of the claims found in the users SAML token captured in the Fiddler trace and have the user test again. Once you get the right claim added the user should be able to access the SharePoint site successfully. Note – If you do not see the correct claim information in the SAML token. Then there must be a configuration problem with your custom claim provider.