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


Published on

Full-Day Tutorial:

  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide
  • You should understand how authentication flow works in SharePoint 2013. In a regular site (one that is not an app web), user authentication is essentially unchanged from SharePoint 2010. However, calls to app webs are authenticated with both user identity and app identity. When an app is running remotely, the app passes a security token to the SharePoint Web server to establish its identity. When an app creates a security token to send to a SharePoint Web server, it usually also includes the identity of the current user. However, it is also possible for an app to create a security token that is app-only which means it does not contain information about a specific user.Keep in mind that there are a few requirements for authenticating SharePoint app identity. First, the hosting Web Application must be a claims-based Web Applications. Also, incoming calls must target CSOM/REST endpoints as you will see in the next slide. Note that the supported CSOM/REST endpoints cannot be extended with custom Web services in SharePoint 2013. You can only authenticate an app using CSOM/REST entry points that ship with SharePoint 2013.
  • When SharePoint 2013 begins to authenticate an incoming request, it first looks to see if the incoming request contains a SAML token with a user identity. If the SharePoint 2013 authentication pipeline finds a SAML token, it can then assume that the incoming request was initiated by a user and not an app. Once it finds a SAML token, SharePoint 2013 then inspects the target URL of the incoming request to see whether it references a standard SharePoint site or a child site associated with a specific app (i.e. an AppWeb). If the incoming request targets a standard site, SharePoint 2013 conducts its authentication and authorization identically to how things worked in SharePoint 2010. If the incoming request targets an AppWeb, SharePoint 2013 initializes the call context with both a user identity and an app identity.When an incoming request does not contain a SAML token, SharePoint 2013 knows that a user did not initiate the request. In this scenario, the SharePoint 2013 authentication pipeline inspects the incoming request to see if it contains a security token identifying a provider-hosted app. The security token for an app can be created using OAuth when Office 365 and ACS is involved. If the security token for an app was created in a server-to-server (S2S) configuration, it will be similar to but slightly different from a valid OAuth token. Once SharePoint 2013 finds a security token identifying an app, it sets up call context with the app identity and optionally the user identity as well.
  • OAuth is an Internet security protocol for authenticating apps and authorizing them to access content on behalf of a specific user. Microsoft selected OAuth for app authentication with SharePoint 2013 because it provides a cross-platform mechanism for authenticating and authorizing apps. It is also noteworthy that the OAuth protocol is an increasingly popular Internet standard which is already used by sites that support apps such as Facebook, Google and Twitter. Note that these sites and SharePoint 2013 use OAuth version 2.0 which is significantly different from OAuth version 1.0.The OAuth protocol allows a SharePoint 2013 to authenticate a cloud-hosted app which is calling to a SharePoint site from across the network and to establish an identity for the app in the calling context. This makes it possible for SharePoint to manage permissions and enforce access control for apps separately from users. Note that the OAuth protocol has provisions to track app permissions in addition to app identity. However, SharePoint 2013 uses OAuth only to authenticate apps and establish app identity. SharePoint 2013 does not leverage to OAuth protocol in any way to track or pass permissions. Instead, SharePoint tracks all app permissions in its own internal databases.
  • Windows Azure Access Control Service (ACS) is a requirement for using the OAuth protocol with SharePoint 2013. The ACS server acts as authentication server. The SharePoint servers acting as the content servers must be configured to trust the ACS server. The client app must also be written to trust the ACS server as well. When you are using sites in an Office 365 tenancy, there is no need to configure a trust to ACS. That's because Office 365 and each new tenancy are preconfigured with trusts to the ACS authentication server. However, the same configuration is not done automatically performed for on-prem farms.
  • SharePoint 2013 makes it possible for Web servers in a SharePoint farm to respond and accept requests from a client app using a server-to-server (S2S) trust. This type of configuration can be used when deploying provider-hosted apps in a private network when it is beneficial to avoid any dependencies on ACS or any other servers running across the Internet. That means that all the servers involved can run behind a single firewall and on the same local area network.A S2S trust represents a trusted connection between a client app running on a local app server and the Web servers in the SharePoint farm. Configuring the trust requires an SSL certificate which is based on the URL with the DNS name (e.g https://appserver.wingtip.com) where the client app is located. The client app contains code which has access to the private key associated with the SSL certificate and it uses this private key to sign security tokens. On the SharePoint Web Server, you must create a security token service which can use the public key to authenticate and decrypt these security tokens generated by the client app.
  • There are several responsibilities for the developer when creating an S2S app. First, you must deploy the Web project that contains the implementation of the client app itself. Next, the client app must be configured to perform its own user authentication. This can be done using any supported style of authentication includingWindows Integrated Authentication, Basic Authentication,FBA, etc. Finally, the client app must create its own security tokens and sign them with the private key associated with the SSL certificate.Note that the security token created by a client app in the S2S trust scenario is like OAuth token but it differs from the OAuth specification in a few different ways. The security token created by a client app in an S2S trust must contain information that indicates the app identity. The security token created by a client app in an S2S trust usually contains information about the identity of the current user however this is not a requirement. Once the security token is created and contains the required information, it then must be signed with the private key before it is sent to SharePoint. This private key signing is what allows SharePoint to perform the authentication on calls originating from the client app.
  • Tutorial: Building Apps for SharePoint 2013 Inside and Outside of the Firewall by An…

    1. 1. Building Apps for SharePoint 2013 Inside and Outside of the Firewall Andrew Connell MVP, SharePoint Serverwww.AndrewConnell.com @AndrewConnell
    2. 2. Andrew Connell www.AndrewConnell.com me@AndrewConnell.com @andrewconnell www.CriticalPathTraining.comwww.Pluralsight.com
    3. 3. Agenda SharePoint App Model App Identity Authentication Authorization OAuth Client-Side Developmentwww.AndrewConnell.com @AndrewConnell
    4. 4. SharePoint 2013 Deployment Options On-Premises • Installed 100% on company servers (aka: on-prem • Access to 100% of SharePoint’s features & / behind capabilities firewall) Hosted (aka: Office • Installed 100% and managed in the cloud • Most common context: Office 365 / 365 / SharePoint Online SharePoint • Some features not available in the cloud Online)www.AndrewConnell.com @AndrewConnell
    5. 5. 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 upgradewww.AndrewConnell.com @AndrewConnell
    6. 6. 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 managementwww.AndrewConnell.com @AndrewConnell
    7. 7. 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 codewww.AndrewConnell.com @AndrewConnell
    8. 8. Creating SharePoint Hosted & Cloud-Hosted Appswww.AndrewConnell.com @AndrewConnell
    9. 9. 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 neededwww.AndrewConnell.com @AndrewConnell
    10. 10. Inspecting the AppWebwww.AndrewConnell.com @AndrewConnell
    11. 11. 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 Appwww.AndrewConnell.com @AndrewConnell
    12. 12. 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 Databasewww.AndrewConnell.com @AndrewConnell
    13. 13. Inspecting App Shapeswww.AndrewConnell.com @AndrewConnell
    14. 14. 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 extensiblewww.AndrewConnell.com @AndrewConnell
    15. 15. User vs. App Authentication Flow SharePoint Farm Web Servers SAML call from user token OAuth call from app tokenwww.AndrewConnell.com @AndrewConnell
    16. 16. SharePoint 2013 Authentication Flow start authentication request to set up call context SAML Token? YES NO app web with user identity NO YES set up call context CSOM/REST user info OAuth token? YES YES YES with user identity endpoint? in token? and app identity NO NO set up call context with app identity NO set up call context end with no identity authentication (anonymous access)www.AndrewConnell.com @AndrewConnell
    17. 17. Provider-Hosted Apps & App Identity • Apps can obtain an identity using one of two methods: High-Trust (via OAuth (via S2S Trust & Azure ACS) certificates)www.AndrewConnell.com @AndrewConnell
    18. 18. 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 farmswww.AndrewConnell.com @AndrewConnell
    19. 19. 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? Its configured automatically in Office 365 tenancies Not supported in on-prem farms in SharePoint 2013www.AndrewConnell.com @AndrewConnell
    20. 20. 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)www.AndrewConnell.com @AndrewConnell
    21. 21. 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 keywww.AndrewConnell.com @AndrewConnell
    22. 22. 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 keywww.AndrewConnell.com @AndrewConnell
    23. 23. 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?www.AndrewConnell.com @AndrewConnell
    24. 24. Creating Apps with Identities & Permissionswww.AndrewConnell.com @AndrewConnell
    25. 25. What You Might Not Be Aware Of: #2 Office 365 Azure != Windows Azure Office 365 Azure Windows Azure • “Private Cloud” • www.azure.com • Azure Web Sites • Cloud services • SQL Azure DBs • Web Sites • Access Control Service • Virtual Machines • Storage (blob / queue / table) • Service Bus • SQL Azure • Access Control Service •…www.AndrewConnell.com @AndrewConnell
    26. 26. 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!www.AndrewConnell.com @AndrewConnell
    27. 27. 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 appwww.AndrewConnell.com @AndrewConnell
    28. 28. 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 JavaScriptwww.AndrewConnell.com @AndrewConnell
    29. 29. 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 Applicationswww.AndrewConnell.com @AndrewConnell
    30. 30. 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 Datawww.AndrewConnell.com @AndrewConnell
    31. 31. SharePoint 2013 Remote API Architecture _api is new alias for _vti_bin/client.svc Server Execute Client Query OData JavaScript Silverlight .Net CLR Library Library Library Custom Client Codewww.AndrewConnell.com @AndrewConnell
    32. 32. 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 APIwww.AndrewConnell.com @AndrewConnell
    33. 33. 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 supportwww.AndrewConnell.com @AndrewConnell
    34. 34. 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); }www.AndrewConnell.com @AndrewConnell
    35. 35. 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)); }www.AndrewConnell.com @AndrewConnell
    36. 36. Programming CSOM with C#www.AndrewConnell.com @AndrewConnell
    37. 37. 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/webwww.AndrewConnell.com @AndrewConnell
    38. 38. 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)www.AndrewConnell.com @AndrewConnell
    39. 39. Testing REST Calls Through the Browserwww.AndrewConnell.com @AndrewConnell
    40. 40. Executing REST Queries Through The Browserwww.AndrewConnell.com @AndrewConnell
    41. 41. Returning ATOM XML vs. JSON <entry xml:base="http://intranet.wingtip.com/_api/"  Control data format 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 response with a" m:etag="&quot;0&quot;"> <id>http://intranet.wingtip.com/_api/Web/Lists(guid0c165f0c-fc82- ACCEPT header 44e6-ae8c-3d0405d2cbb2)</id> <category term="SP.List" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" /> <link rel="edit" href="Web/Lists(guid0c165f0c-fc82-44e6-ae8c- 3d0405d2cbb2)" /> <title />  ATOM-PUB (XML) <updated>2012-10-05T20:53:47Z</updated> <author> <name />  Verbose </author> <content type="application/xml"> <m:properties>  Easier to read <d:Title>Documents</d:Title> </m:properties> </content> </entry>  ACCEPT = application/atom+xml { "d":{ "__metadata":{ "id":"F05C411B-943E-42A0-A5DF-205F5C75E673",  JSON "uri":"http://intranet.wingtip.com/_api/Web/Lists(guid 0c165f0c-fc82-44e6-ae8c-3d0405d2cbb2)", "etag":""0"",  Condensed notation }, "type":"SP.List" "Id":"0c165f0c-fc82-44e6-ae8c-3d0405d2cbb2",  Smaller payload } "Title":"Documents" }  ACCEPT = application/json;odata=verbosewww.AndrewConnell.com @AndrewConnell
    42. 42. 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;www.AndrewConnell.com @AndrewConnell
    43. 43. 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); { } "d":{ "__metadata":{ function OnDataReturned(data) { "id":"F05C411B-943E-42A0-A5DF-205F5C75E673", var odataResults = data.d "uri":"http://intranet.wingtip.com/_api/Web", var siteTitle= odataResults.Title; "type":"SP.Web" $("#results").html("Title: " + siteTitle); }, } "Id":"0c165f0c-fc82-44e6-ae8c-3d0405d2cbb2", "Title":"My Site Title" function onError(err) { } $("#results").text("ERROR: " + JSON.stringify(err)); } }www.AndrewConnell.com @AndrewConnell
    44. 44. 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.asmxwww.AndrewConnell.com @AndrewConnell
    45. 45. 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 infowww.AndrewConnell.com @AndrewConnell
    46. 46. Creating Lists with JavaScript and REST function onCreateList() { var newList = { Create appropriate "__metadata":{ "type":"SP.List" }, JavaScript object and "BaseTemplate":105, convert to JSON format "TemplateFeatureId":"4AE88D99-DBBC-4B9E-95CC-CA3C320A2345", for request body "Title":"NewListName" } Create request headers var requestHeaders = { for "ACCEPT":"application/json", HTTP Request "X-RequestDigest":$("#__REQUESTDIGEST").val() Get form digest value from control on page } Send request to Web server using jQuery $.ajax({ $.ajax function url: _spPageContextInfo.webAbsoluteUrl + "/_api/web/lists", type: "POST", contentType: "application/json", data: JSON.stringify(newList), Convert request body headers: requestHeaders, data to string-based JSON success: onSuccess, object error: onError }); }www.AndrewConnell.com @AndrewConnell
    47. 47. Querying and Updating Content Using RESTwww.AndrewConnell.com @AndrewConnell
    48. 48. Questions? Want to Learn More? www.CriticalPathTraining.com www.Pluralsight.com Hands-On & Virtual Training On-Demand Training  SharePoint Courses for Everyone  SharePoint Courses for Everyone  SharePoint 2007, 2010 & 2013  SharePoint 2007, 2010 & 2013  Developers, Administrators & End Users  Developers, Administrators & End Users  Get Training How You Like it  Individual, Small Business & Enterprise Plans  Hands-On (classroom with hands-on labs)  Monthly or Annual Subscriptions  Online (live webcast with take-away labs)  Watch Online & Offline  Private Classes Available for Large Groups  Subscribers Have Access to Entire Catalogwww.AndrewConnell.com me@andrewconnell.com @AndrewConnell