Throughout this book, we have explored the various ways an app for SharePoint can leverage the resources of the SharePoint farm. The components that make up our apps have been hosted locally or in remote web sites outside of SharePoint to enable us to use server-side ASP.NET logic. In all cases, the custom logic for our apps has executed outside of the SharePoint server farmin a web server, a web service, or a web browser. In spite of this separation, we have always had a connection back to the SharePoint farm, in the form of context or access tokens. We have had these because our apps were always launched from inside SharePoint.

In this chapter, we will step outside of SharePoint and look at how to access SharePoint resources without using apps for SharePoint. In doing so, we will go over the following points:

• We will describe how an application running outside of SharePoint can perform authentication and access resources within the farm.
• We will integrate the Microsoft Office client applications, such as Word and Excel, with our SharePoint app solutions.
• We will create applications that access SharePoint while runningasa Windows .NET application or in the Windows Runtime (WinRT).
• We will extend the reach of our SharePoint data to include native Windows Phone apps.

Unlike in previous chapters, we will not be focusing on building SharePoint apps here. The applications in this chapter will access SharePoint from an untrusted connection, requiring the application to log on to SharePoint in order to ensure privacy and data integrity.

Authenticating with SharePoint

When a user launches an app for SharePoint, the server records the current user, the app, and other information making up the context of the app. SharePoint uses this information to create a context token, which is provided to the app as part of the page request that launches the app. The context token is then used to make requests back into the SharePoint server in a secure fashion.

When an app outside of SharePoint wishes to make a request into SharePoint, there is no pre-existing context with which to work. This means that the application is responsible for authenticating with SharePoint before any other requests can be processed. This process is sometimes referred to as active authentication. It is active in the sense that the application must actively perform the authentication process in its code. The authentication performed by SharePoint when launching app could be called passive authentication. The only difference is whether the authentication process is initiated by SharePoint or the application.

In order to access SharePoint through one of the client-side object model libraries, the REST interface or one of SharePoint’s native web services, the results of either active or passive authentication must be provided in the client request. Later in this chapter, we will describe some of the techniques for performing active authentication and passing the results to SharePoint. In this section, we will disassemble the authentication process to understand what is happening under the covers.

Figure 14-1 illustrates the sequence of messages that must be passed between the application, the Security Token Service (STS), and the SharePoint farm. These messages occur in three request/response pairs. The first pair establishes the user’s identity with the STS. The second “logs in” to SharePoint by supplying this identity to SharePoint. The third pair represents one or more client requests from the application to SharePoint.

Step 1 in the figure involves formatting a request for the Security Token Service. When using SharePoint Online, the STS role is assumed by the Windows Azure Access Control Services (ACS). When running SharePoint in a local server farm, SharePoint’s own STS is used. The request is formatted as a Security Assertion Markup Language (SAML) request. The SAML request is an XML document that contains the URL of the target SharePoint site, user name, and password, as shown in Listing 14-1.

Listing 14-1.  Sample SAML Login Request

<s:Envelope
xmlns:s=" http://www.w3.org/2003/05/soap-envelope "
  xmlns:a=" http://www.w3.org/2005/08/addressing"
xmlns:u=" http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
<s:Header>
<a:Action
 s:mustUnderstand="1"> http://schemas.xmlsoap.org/ws/2005/02/trust/RST/Issue </a:Action>
<a:ReplyTo>
<a:Address> http://www.w3.org/2005/08/addressing/anonymous</a:Address >
</a:ReplyTo>
<a:To s:mustUnderstand="1"> https://login.microsoftonline.com/extSTS.srf</a:To >
<o:Security s:mustUnderstand="1"
        xmlns:o=" http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd ">
<o:UsernameToken>
<o:Username> MyUserName </o:Username>
<o:Password> Pass@word1 </o:Password>
</o:UsernameToken>
</o:Security>
</s:Header>
<s:Body>
<t:RequestSecurityToken xmlns:t=" http://schemas.xmlsoap.org/ws/2005/02/trust ">
<wsp:AppliesTo xmlns:wsp=" http://schemas.xmlsoap.org/ws/2004/09/policy ">
<a:EndpointReference>
<a:Address> https://swrightjet.sharepoint.com</a:Address >
</a:EndpointReference>
</wsp:AppliesTo>
<t:KeyType> http://schemas.xmlsoap.org/ws/2005/05/identity/NoProofKey</t:KeyType >
<t:RequestType> http://schemas.xmlsoap.org/ws/2005/02/trust/Issue</t:RequestType >
<t:TokenType>urn:oasis:names:tc:SAML:1.0:assertion</t:TokenType>
</t:RequestSecurityToken>
</s:Body>
</s:Envelope>
  

When the STS receives the SAML request, it verifies that the format of the request is correct, that the request is from a known source, and that the request is for a known target site. If the request is valid, the STS attempts to verify the login information. This may involve accessing the Microsoft Online Directory Service (MS-ODS) or passing the request to a federated identity service for validation. In step 2, the result of this validation is sent to the requesting application. If the request was successful, the STS returns a security token that has been generated for this session.

The application passes the supplied SAML security token to the SharePoint server as proof of the user’s credentials in step 3. Note that the user’s password is not included in this token. Only the STS ever sees the user’s password. SharePoint validates that the security token is from a trusted STS and for a valid resource in SharePoint.

In step 4, SharePoint formats two cookies that are returned to the calling application. These are called FedAuth and rtFa. These cookies are represented by the context token in an app for SharePoint. In the remote application, these cookies are saved to allow for future client requests into the SharePoint site.

The application will format a request for SharePoint using one of the client APIs for SharePoint. The request can be a CSOM batch, or a WebRequest containing a REST interface call or web service call. In order to be processed by SharePoint, the authentication cookies provided by SharePoint must be included in the request. This is step 5.

Only requests that contain the correct authentication cookies will be acted upon by SharePoint. The CSOM libraries’ client content object adds these cookies automatically when using passive authentication with a context token. When using active authentication, these cookies must be injected into the request by the application. In CSOM code, this can be accomplished by handling the context object’s ExecutingWebRequest event. This event fires just before the request is sent to SharePoint, giving the application the opportunity to modify the request.

The final step, step 6, is a normal response message from SharePoint with the results of the request. This response is no different when using active or passive authentication. The type of response is determined by the type of request that was made (CSOM, REST, etc.).

Active authentication, also known as remote authentication, is a complex subject. There are several good articles on TechNet, MSDN, and elsewhere, as well as available sample code. Detailing all of these options is beyond the scope of this discussion. The best strategy is to pick a solution, wrap it into a set of common classes or scripts, and reuse that solution throughout your codebase. For more on active authentication, visit the following web sites:

• “Remote Authentication in SharePoint Online Using Claims-Based Authentication,” http://msdn.microsoft.com/en-us/library/hh147177.aspx
• “SharePointWinRTClient” sample project on CodePlex,http://sharepointwinrt.codeplex.com/
• “How to do active authentication to Office 365 and SharePoint Online,” http://www.wictorwilen.se/Post/How-to-do-active-authentication-to-Office-365-and-SharePoint-Online.aspx
• “Remote authentication in SharePoint Online,” http://allthatjs.com/2012/03/28/remote-authentication-in-sharepoint-online/

Creating Office Apps

The Cloud App Model described in Chapter 1 applies to more than just apps for SharePoint. Microsoft’s Office productivity suite also supports the use of apps. An app for Office is basically an add-in that appears in the office client application. There are different types of apps for Office that can be surfaced in different members of the Office family of products. Apps for Office can also be used in the web-based versions of the Office Web Apps.

An app for Office is a web application that is designed to run in a small web browser window hosted within the Office application. As web pages, apps for Office can use technologies such as web services, REST, HTML, and JavaScript to provide a rich user experience. Office apps also have the ability, with proper permissions, to read and write data in Office documents and affect the state of the Office application.

In the following sections, we will describe the different types of Office apps, how they are hosted within an Office application, and how they are published to consumers. We will also see how these apps can be integrated into apps for SharePoint to create deep integration between apps for SharePoint and the documents with which they interact.

Setting Up the Development Environment

Before creating Windows Phone apps for SharePoint, there is a certain amount of setup required in the developer’s environment.

First, of course, Visual Studio 2012 must be installed. Then, we need to load the correct SDKs. SharePoint 2013 supports the two most recent versions of the Windows Phone platform: version 7.1 and version 8. Table 14-2 provides the URLs for downloading the necessary SDKs for each version. The Windows Phone SDK should be installed first, followed by the SharePoint SDK.

The Windows Phone SharePoint 2013 SDK installs four important assemblies for developing Windows Phone apps for SharePoint.

• Microsoft.SharePoint.Client.Phone and Microsoft.SharePoint.Client.Phone.Runtime—These libraries contain the client-side object model (CSOM) classes for the Windows Phone platform.
• Microsoft.SharePoint.Phone.Application—This assembly contains base types for SharePoint fields and lists including model and view-model base classes for these objects.
• Microsoft.SharePoint.Client.Phone.Auth.UI—This library contains classes that simplify creating the Windows Phone user experience when using SharePoint. It includes the following classes:
  • BrowserLogin—This class is the code-behind for an automated browser login page (BrowserLogin.xaml). This page is shown when login credentials are required.
  • Authenticator—This class greatly simplifies active authentication because it implements the exchange of SAML messages and tokens to authenticate to SharePoint. The result is a client context object that is ready to use.
  • ODataAuthenticator—This version of the authenticator class is designed to work with OData connections that may involve indirect connections to the data service.

The SharePoint SDK for Windows Phone also includes two Visual Studio project templates. These templates provide a starting point for developing apps. These templates will be described in the next sections.

Windows Phone Empty SharePoint Application Template

The first template included in the Microsoft SharePoint SDK for Windows Phone is the empty application template. As the name implies, this template contains only the minimal set of files needed to create an app.

This template is basically the same as the empty app template that is included in the Windows Phone SDK. The difference is that this template includes references to the SharePoint SDK assemblies. This template includes a blank main page and an App.xaml file to define the app.

Windows Phone SharePoint List Application Template

The other template included in the SharePoint SDK generates a fully functional application that can read and write SharePoint data.

A common use of mobile apps is to review and update lists of data. Since SharePoint is very good at maintaining lists, it is not surprising that this is a common use for SharePoint apps on mobile platforms. The List Application template was created to provide a quick start to creating this type of app.

The List Application template uses a wizard to connect to an existing SharePoint site, read the views and fields for a list, and generate an app that can perform CRUD operations on the list’s data. The template can read any list to create the app, including document libraries and custom lists. Apps based on lists that include custom field types or complex lookups may need to be modified before being ready for production use.

A list app contains a single project for the Windows Phone app. This project includes several files. The most important of these are the following:

• App.xaml—This file represents the overall Windows Phone application. The code-behind file associated with App.xamlcontains event handlers for app lifecycle events such as launching, activating, deactivating, and closing of the application.
• ListDataProvider.cs—This class loads list items from the associated SharePoint list and views.
• Views Folder
  • List.xaml—This view presents the list items in each of the views selected in the wizard.
  • DisplayForm.xaml—This view presents a read-only form, containing all of the data fields selected in the wizard.
  • EditForm.xaml—This is a data entry form used to update an existing entry in the list.
  • NewForm.xaml—This is a data entry form used to create a new entry in the list.
• ViewModels Folder
  • ListViewModel.cs—This is the view-model object for the List view.
  • DisplayItemViewModel.cs—This is the view-model object for the DisplayForm view.
  • EditItemViewModel.cs—This is the view-model object for the EditForm view.
  • NewItemViewModel.cs—This is the view-model object for the NewForm view.

In our final exercise, we will use the wizard to create an app that reads and writes data in a SharePoint calendar list.