Tuesday, February 03, 2015

Using SharePoint Apps On-Premise and FBA Custom Sign-In Page

Using SharePoint Apps and a Custom Sign In Page
If you follow the Microsoft recommended setup for SharePoint Apps, you will utilize a new domain name to host your apps. See Microsoft recommended setup on TechNet here - https://technet.microsoft.com/en-us/library/fp161236%28v=office.15%29.aspx.  (Note: if you don’t follow the recommendation of hosting your apps with a different domain name, the problem described below should not be present.)

The Problem
Following the recommend setup means a user navigates to extranet.contoso.com and after selecting a SharePoint app (such as Corporate News App as I used in my testing) that has been configured, the user will be prompted to login again due to the fact that it is utilizing a separate domain name.

If you aren’t using FBA and a custom sign in page then no problem will be present. A problem is presented when utilizing a custom sign in page, as is a best practice when using Extranet Collaboration Manager (ExCM) for SharePoint.

Following our ExCM instructions for a custom sign in page, you would access the sign in page in the _layouts directory. From the app domain, this will return a 403 forbidden error. According to extensive consultation with Microsoft support this is due to the fact that the apps domain does not have access to the _layouts directory in the 15 folder as other apps would.

Ensure Your Apps Are Working
Before going down the recommended path for correction, let’s be sure your apps are properly configured. It can be a complex process to get SharePoint apps configured properly.

We recommend testing without FBA enabled and without a custom sign in page. Doing so takes ExCM out of the picture and ensures your apps are properly configured without introducing additional complexity. If you already have ExCM configured on a web application, either create a new web app for testing or in central administration/manage web applications click on your extranet web app, select authentication providers, turn off FBA, and set it to use the default login page.

You should be able to access your app without issue with these settings. If it does not work, then you have an issue unrelated to ExCM. Please correct that issue and start over at this point once a successful test has been completed.

Ensure Problem Exists
Now that you’ve verified SharePoint apps are working on your web app, go ahead and enable FBA and set the custom sign in page in authentication providers for your extranet web app.

This time you should be able to login to your web app with an AD domain account (I utilize “in private” browsing to eliminate any cookie and caching issues that can interfere with testing). Once you click on your app you should receive a 403 forbidden error as below.

Now, in central administration/manage web applications select your Apps redirect web application, then select authentication providers – enable FBA, set the membership provider and role provider names (Ext and Extrole if you use the recommended names in our documentation) and set the custom sign in page to _layouts/spsolutions/excm/signin.aspx (or your custom location and page)

With this set, you should still receive a 403 forbidden error. Verify this is true.
Since the issue is related to the sign in page existing in the _layouts directory, let’s move it to an accessible location for the apps redirect web application. We will move it directly to the IIS directory.
Navigate to C:\Program Files\Common Files\microsoft shared\Web Server Extensions\15\TEMPLATE\LAYOUTS\SPSolutions\ExCM (or alternately your custom sign in page which could be in another location) and copy the signin.aspx file.

You need to paste it in a newly created virtual directory within IIS. To do so, open IIS manager, select your Apps redirect web site, right-click and select “Explore.”

Create a new folder called ExCM and paste the signin.aspx to the new folder.

Back in IIS, under your Apps web site, make sure the newly created ExCM folder is present (you might need to refresh).

Right-click on the Apps website and select “Add Virtual Directory.”

Give it an Alias of ExCM and navigate to the appropriate physical path created in previous step.

You now need to go to central administration/manage web applications and select your Apps web app and choose authentication providers. Update the custom sign in page to use this location –~/excm/signin.aspx, rather than the _layouts location.”

Open an in private browser window, navigate to your site and login as normal with an AD account. Next, click on your app, you should now be presented with the custom sign in page. Sign in with your windows credentials and the app should come up successfully.

If you would like to access the app with FBA accounts you need to configure the Apps web.config just as you did your original extranet web app following these steps.

If you have tried and failed, or are considering utilizing SharePoint apps in your on-premise SharePoint installation, I hope this article helps shed some light on how to properly configure your sign in page.

No comments: