Tutorial: Building Apps for SharePoint 2013 Inside and Outside of the Firewall by An…

www.AndrewConnell.com @AndrewConnell
Building Apps for SharePoint 2013
Inside and Outside of the Firewall
Andrew Connell
MVP, SharePoint Server

Andrew Connell
www.AndrewConnell.com
me@AndrewConnell.com
@andrewconnell
www.CriticalPathTraining.com
www.Pluralsight.com

Agenda
 SharePoint App Model
 App Identity
Authentication
Authorization
OAuth
 Client-Side Development

SharePoint 2013 Deployment Options
• Installed 100% on company servers
• Access to 100% of SharePoint’s features &
capabilities
On-Premises
(aka: on-prem /
behind firewall)
• Installed 100% and managed in the cloud
• Most common context: Office 365 / SharePoint
Online
• Some features not available in the cloud
Hosted
(aka: Office 365
/ SharePoint
Online)

Overview of the SharePoint App Model
 SharePoint app model based on these assumptions
Apps supported in Office 365 and in on-premises farms
App code never runs in SharePoint host environment
Apps talk to SharePoint using Web service entry points
App code is authenticated and has established identity
App has permissions independent of user permissions
Apps deployed to catalogs using a publishing scheme
Published apps are easier to find, install and upgrade

App Installation Scopes
 Site-Scoped Installation
 App is installed in a specific site
 App is launched from same site
 This site is known as host web
 Tenancy-Scoped
Installation
 App installed > app catalog site
 App available many host webs
 Host webs access one app instance
 Centralizes app management

SharePoint App Architecture
 SharePoint-Hosted Apps
 App resources added to SharePoint host
 Stored in child site known as app web
 App can have client-side code
 App cannot have server-side code
 Cloud-Hosted Apps
 App resources deployed on remote server
 Remote site known as remote web
 App can have client-side code
 App can have server-side code

Creating SharePoint Hosted &
Cloud-Hosted Apps

App Web
 App web is created during app installation
App web created as child to site where app is installed
 SharePoint-Hosted apps must create app web
App must add start page and related resources
App can add other SharePoint elements (e.g. lists)
 Cloud-Hosted apps can create app web
Most cloud-hosted apps will not create an app web
Cloud-hosted app can create app web if needed

Inspecting the AppWeb

App Shapes
 What SharePoint Tells you…
SharePoint-Hosted Apps
Cloud-Hosted Apps
 What Visual Studio Forces You to Select…
SharePoint-Hosted App
Provider-Hosted App
Auto-Hosted App

App Shapes – What It Really Is
 SharePoint-Hosted Apps
 Everything resides in SharePoint
 All Other Types
 Majority resides external to SharePoint (IIS, Azure, etc.)
 By default, don’t trigger creation of AppWeb…
Unless they include SharePoint artifacts
 Auto-Hosted Apps
 SharePoint handles deployment of external assets
Azure Web Site
SQL Azure Database

Inspecting App Shapes

Authentication in SharePoint 2013
 Authentication Flow in SharePoint 2013
 User authentication stays the same with standard sites
 In calls to app web, app authentication occurs internally
 Internal authentication occurs in calls to app web
 External authentication used for calls from remote web
 Call context can contain both user and app identity
 Requirements for establishing app identity
 Host web application must be a claims-based
 Incoming calls must target CSOM/REST endpoints
Supported CSOM/REST endpoints not extensible

User vs. App Authentication Flow
call from user SAML
token
call from app
OAuth
token
SharePoint Farm
Web Servers

SharePoint 2013 Authentication Flow
start
authentication
SAML Token?
OAuth token?
request to
app web
CSOM/REST
endpoint?
user info
in token?
end
authentication
set up call context
with user identity
set up call context
with user identity
and app identity
set up call context
with app identity
set up call context
with no identity
(anonymous access)
YES NO
YES
NO
NO
YES YES YES
NO
NO

Provider-Hosted Apps & App Identity
OAuth (via Azure
ACS)
High-Trust (via S2S
Trust & certificates)
• Apps can obtain an identity using one of two
methods:

OAuth 2.0 Primer
 What is OAuth?
Internet protocol for creating and managing app identity
A cross-platform mechanism for authenticating apps
Internet standard used by Facebook, Google
and Twitter
 SharePoint 2013 use OAuth to establish
app identity
SharePoint integration with OAuth based on Azure ACS
OAuth authentication used in Office 365 but not on-premises farms

Windows Azure ACS
 Windows Azure Access Control Service (ACS)
Required to use OAuth with SharePoint 2013
ACS server acts as authentication server
ACS server must be trusted by content server
ACS server must be trusted by client app
 How is ACS configured as authentication server?
It's configured automatically in Office 365 tenancies
Not supported in on-prem farms in SharePoint 2013

What is a Server-to-Server (S2S) Trust
 Trusted connection between client app and SharePoint
 Eliminates need for ACS when running apps in on-premises farm
 Trust between servers configured using SSL certificates
 App code requires access to private key of SSL certificate
 Requires creating Security Token Service on SharePoint server(s)

Developing Apps that use S2S Trusts
 What are the developer responsibilities with
an S2S app?
 Expose an endpoint to SharePoint to
discover service metadata
 Authenticate the user (can use Windows Auth, FBA, etc.)
 Create security tokens to send to SharePoint server
 Details of creating the S2S security token
 S2S token like OAuth token but differs from
OAuth specification
 Security token must contain app identity
 Security token can optionally include user identity
 Security token must be signed using certificate’s private key

OAuth & S2S Trusts
 OAuth Enabled Apps
 Before deployment marketplace, app must be registered with Azure ACS
 Apps obtain their identity / token from Azure ACS
 When calling SharePoint, app includes OAuth token
 SharePoint trusts Azure ACS
 On-Prem deployments will typically use S2S
 Before deployment, app must be
registered with SharePoint
 Developer registers a certificate with SharePoint & associates app with certificate
 App creates token using private key of certificate
 SharePoint trusts this token because it was signed with the private key

What You Might Not Be Aware Of: #1
 OAuth is only supported in Office 365
No support in On-Prem deployments at RTM
Why?
 Possible update to this story after RTM
Extra steps?
Hotfix?
Cumulative Update?
Service Pack?
Next Version?

Creating Apps with
Identities & Permissions

What You Might Not Be Aware Of: #2
Office 365 Azure
• “Private Cloud”
• Azure Web Sites
• SQL Azure DBs
• Access Control Service
Windows Azure
• www.azure.com
• Cloud services
• Web Sites
• Virtual Machines
• Storage (blob / queue / table)
• Service Bus
• SQL Azure
• Access Control Service
• …
Office 365 Azure != Windows Azure

The Sandbox Isn’t Dead
 Where you build sandbox solutions, try to replace them with
SharePoint Apps
 There are many scenarios where Apps can’t replace sandbox
solutions
 Some things are ONLY possible with sandboxed solutions in a
hosted deployment
 Remember, they are deprecated, not dead!

App Model Parting Thoughts
 SharePoint ALM has always been hard
 .NET ALM > SharePoint ALM
 More tools, more mature, more documentation & support
 No longer limited to what SharePoint supports
 Latest version of the .NET Framework
 New “toys” (MVC, Entity Framework, etc)
 Not limited to any technology stack / infrastructure
 Working with service layer vs. server side API
 More community tools & libraries to choose from
 Can follow more “standards”
 Don’t have to scale SharePoint, can now just scale the app

CSOM in SharePoint 2010
 CSOM made accessible through client.svc
 Direct access to client.svc not supported
 Calls to client.svc must go through
supported entry points
 Supported entry points:
.NET
Silverlight
JavaScript

Changes in SharePoint 2013
 client.svc extended with REST capabilities
client.svc now supports direct access from
REST clients
client.svc accepts HTTP GET, PUT, POST requests
Implemented in accordance with OData protocol
 CSOM extended with new APIs
New APIs for SharePoint Server functionality
New API for Windows Phone Applications

What is covered in the new CSOM?
 New APIs with SharePoint Server functionality
 User Profiles
 Search
 Taxonomy
 Feeds
 Publishing
 Sharing
 Workflow
 E-Discovery
 IRM
 Analytics
 Business Data

SharePoint 2013 Remote API Architecture
JavaScript
Library
Silverlight
Library
.Net CLR
Library
Custom Client Code
Client
Server
_api is new alias for _vti_bin/client.svc
OData
Execute
Query

What About ListData.svc?
 ListData.svc added REST support for reading & writing to
SharePoint lists in SharePoint 2010
 Still present in SharePoint 2013, but primarily only for backwards
capability
Existing code won’t break
 New development recommendation: use new SharePoint 2013
REST/OData API

Changes to CSOM in SharePoint 2013
 SharePoint Foundation 2013
No significant changes to CSOM beyond REST support
Primary investment was adding REST to existing API
 SharePoint Server 2013
New APIs added with CSOM and REST support

CSOM using Managed Code
ClientContext cc = new ClientContext("http://clientside.wingtip.com");
cc.Credentials = CredentialCache.DefaultCredentials;
Web site = cc.Web;
ListCollection lists = site.Lists;
// load site info
cc.Load(site, s => s.Title);
cc.ExecuteQuery();
Console.WriteLine("Site Title: " + site.Title);
// create list
ListCreationInformation newList = new ListCreationInformation();
newList.Title = "Customers CSOM";
newList.Url = "Lists/Customers_CSOM";
newList.QuickLaunchOption = QuickLaunchOptions.On;
newList.TemplateType = (int)ListTemplateType.Contacts;
site.Lists.Add(newList);
// refresh lists collection
cc.Load(lists);
// make round trip to Web server to do all the work
cc.ExecuteQuery();
foreach (List list in lists) {
Console.WriteLine(list.Title);
}

CSOM using JavaScript
var ctx;
var web;
var lists;
$(onPageLoad);
function onPageLoad() {
ExecuteOrDelayUntilScriptLoaded(initCSOM, "sp.js");
}
function initCSOM() {
ctx = SP.ClientContext.get_current();
web = ctx.get_web();
ctx.load(web);
ctx.load(web.get_currentUser());
lists = web.get_lists();
ctx.load(lists);
ctx.executeQueryAsync(onDisplaySiteInfo, onError);
}
function onDisplaySiteInfo() {
var siteTitle = web.get_title();
var siteId = web.get_id().toString();
var siteUrl = web.get_url();
var currentUser = web.get_currentUser().get_loginName();
// do something with these values
}
function onError(sender, args) { alert(JSON.stringify(args)); }

Programming CSOM with C#

REST URLs in SharePoint 2013
 CSOM URLS can go through /_api/ folder
Simplifies URLs that need to be built
Removes client.svc file name from URL
 You can replace this URL:
http://wingtipserver/_vti_bin/client.svc/web
 With this URL:
http://wingtipserver/_api/web

Mapping Objects to Resources
 Example REST URLs targeting SharePoint sites
http://[..]/_api/web/lists
http://[..]/_api/web/lists/getByTitle(‘Contacts')
http://[..]/_api/web/getAvailableWebTemplates(lcid=1033)

Testing REST Calls Through the Browser

Executing REST Queries
Through The Browser

Returning ATOM XML vs. JSON
 Control data format
response with
ACCEPT header
 ATOM-PUB (XML)
 Verbose
 Easier to read
 ACCEPT = application/atom+xml
 JSON
 Condensed notation
 Smaller payload
 ACCEPT = application/json;odata=verbose
{
"d":{
"__metadata":{
"id":"F05C411B-943E-42A0-A5DF-205F5C75E673",
"uri":"http://intranet.wingtip.com/_api/Web/Lists(guid'
0c165f0c-fc82-44e6-ae8c-3d0405d2cbb2')",
"etag":""0"",
"type":"SP.List"
},
"Id":"0c165f0c-fc82-44e6-ae8c-3d0405d2cbb2",
"Title":"Documents"
}
}
<entry xml:base="http://intranet.wingtip.com/_api/"
xmlns="http://www.w3.org/2005/Atom"
xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadat
a" m:etag=""0"">
<id>http://intranet.wingtip.com/_api/Web/Lists(guid'0c165f0c-fc82-
44e6-ae8c-3d0405d2cbb2')</id>
<category term="SP.List"
scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme"
/>
<link rel="edit" href="Web/Lists(guid'0c165f0c-fc82-44e6-ae8c-
3d0405d2cbb2')" />
<title />
<updated>2012-10-05T20:53:47Z</updated>
<author>
<name />
</author>
<content type="application/xml">
<m:properties>
<d:Title>Documents</d:Title>
</m:properties>
</content>
</entry>

REST Query from Managed Code
 Tips for making REST calls from managed code
Use HttpWebRequest & HttpWebResponse
Query XML using XDocument.Descendants
Or use JSON & JavascriptSeralizer / JSON.NET
// build request
Uri uri = new Uri(siteUrl + "/_api/web/lists/getByTitle('Documents')/?&select=Title");
HttpWebRequest request = WebRequest.Create(uri) as HttpWebRequest;
request.Credentials = CredentialCache.DefaultCredentials;
request.Accept = "application/atom+xml";
// send request
HttpWebResponse response = request.GetResponse() as HttpWebResponse;
// use LINQ to XML to get data
XDocument doc = XDocument.Load(response.GetResponseStream());
XNamespace nsDataService = "http://schemas.microsoft.com/ado/2007/08/dataservices";
string title = doc.Descendants(nsDataService + "Title").First().Value;

REST Query Using JavaScript & jQuery
$(onPageLoad);
function onPageLoad() {
$("#cmdGetSiteInfo").click(onGetSiteInfo);
}
function onGetSiteInfo() {
var requestUri = _spPageContextInfo.webAbsoluteUrl + "/_api/Web?$select=Title";
// execute AJAX request
jqxhr = $.getJSON(requestUri, null, OnDataReturned);
jqxhr.error(onError);
}
function OnDataReturned(data) {
var odataResults = data.d
var siteTitle= odataResults.Title;
$("#results").html("Title: " + siteTitle);
}
function onError(err) {
$("#results").text("ERROR: " + JSON.stringify(err));
}
{
"d":{
"__metadata":{
"id":"F05C411B-943E-42A0-A5DF-205F5C75E673",
"uri":"http://intranet.wingtip.com/_api/Web",
"type":"SP.Web"
},
"Id":"0c165f0c-fc82-44e6-ae8c-3d0405d2cbb2",
"Title":"My Site Title"
}
}

Updates and the Form Digest
 Updates using REST require Form Digest
 Special value created using cryptography
 Used to protect against replay attack
 SharePoint pages include control that contains the Form Digest
 Web service clients must acquire Form
Digest separately
 Form Digest can be acquired through
http://site/_vti_bin/sites.asmx

Creating Lists with Managed Code & REST
 Parse together URL to point to lists collection
 Add X-RequestDigest header with form
digest value
 Set HTTP method to POST
 Create body content with new list info

Creating Lists with JavaScript and REST
function onCreateList() {
var newList = {
"__metadata":{ "type":"SP.List" },
"BaseTemplate":105,
"TemplateFeatureId":"4AE88D99-DBBC-4B9E-95CC-CA3C320A2345",
"Title":"NewListName"
}
var requestHeaders = {
"ACCEPT":"application/json",
"X-RequestDigest":$("#__REQUESTDIGEST").val()
}
$.ajax({
url: _spPageContextInfo.webAbsoluteUrl + "/_api/web/lists",
type: "POST",
contentType: "application/json",
data: JSON.stringify(newList),
headers: requestHeaders,
success: onSuccess,
error: onError
});
}
Create appropriate
JavaScript object and
convert to JSON format for
request body
Get form digest value
from control on page
Create request headers for
HTTP Request
Send request to Web
server using jQuery $.ajax
function
Convert request body data
to string-based JSON object

Querying and Updating
Content Using REST

Questions? Want to Learn More?
 SharePoint Courses for Everyone
 SharePoint 2007, 2010 & 2013
 Developers, Administrators & End Users
 Get Training How You Like it
 Hands-On (classroom with hands-on labs)
 Online (live webcast with take-away labs)
 Private Classes Available for Large Groups
 SharePoint Courses for Everyone
 SharePoint 2007, 2010 & 2013
 Developers, Administrators & End Users
 Individual, Small Business & Enterprise Plans
 Monthly or Annual Subscriptions
 Watch Online & Offline
 Subscribers Have Access to Entire Catalog
www.CriticalPathTraining.com
Hands-On & Virtual Training
www.Pluralsight.com
On-Demand Training
me@andrewconnell.com

Tutorial: Building Apps for SharePoint 2013 Inside and Outside of the Firewall by An…

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Tutorial: Building Apps for SharePoint 2013 Inside and Outside of the Firewall by An…

Similar to Tutorial: Building Apps for SharePoint 2013 Inside and Outside of the Firewall by An… (20)

More from SPTechCon

More from SPTechCon (20)

Tutorial: Building Apps for SharePoint 2013 Inside and Outside of the Firewall by An…

Editor's Notes