This document discusses securing SharePoint apps using OAuth authentication. It provides an overview of app authentication in SharePoint 2013, including the use of OAuth and app principals. The key points covered are: - SharePoint 2013 supports app authentication using OAuth or on-premise using security token service. - Apps are assigned a principal that is used to manage app permissions separately from user permissions. - The OAuth workflow involves apps obtaining access tokens from Azure Access Control Service to make calls to SharePoint on behalf of users. - App principals must be registered both with SharePoint and ACS, and include a client ID, client secret, and redirect URL.

1. Securing SharePoint Apps
Using OAuth
Kashif Imran
kashif_imran@hotmail.com

2. Agenda
• Issues with SharePoint Development/Security In the Past
• SharePoint Apps
• Security Primer
• App Authentication in SharePoint 2013
• OAuth
• OAuth Flow in SharePoint 2013 and Security Tokens
• Managing App Principals
• Questions

3. Issues with SharePoint Security
• Farm Solutions
• Runs within the SharePoint workerprocess (w3wp.exe)
• Access to Server Object Model
• By default runs with current user’s permission
• Developer can use SPSecurity.RunWithElevatedPrivileges that reverts code to Windows
identity of host application pool
• Farm stability issues
• Installation and upgrade (iisreset)
• Upgrade farm to newer version of SharePoint
• Sandboxed Solutions
• SPUCWorkerProcess.exe
• Access to Server Object Model
• Feature activation has full access to content (runs as site administrator)
• Always runs as current user, can not use SPSecurity.RunWithElevatedPrivileges
• Deprecated in SharePoint 2013 in favor of developing apps for SharePoint

4. SharePoint Apps
• A web application that is registered with SharePoint using an app
manifest.
• Customize and extend SharePoint without full-trust access
• Get its own security principal
• Interacts with SharePoint using Client Object Model/REST
• Distributed as app package (.app) to the public marketplace or
corporate app catalog
• Installed at site or tenant scope
• Any Programming language/technology that can communicate with
SharePoint via REST and OAuth

5. Types of SharePoint Apps
• SharePoint-hosted
• App resources stored in child
site known as (app web)
• App can only have client-side code
• Cloud-Hosted
• App resources deployed on remote server
known as remote web
• App can have both client-side and
server-side code
• 2 Types of Cloud-Hosted Apps
• Autohosted (Hosted in Azure)
• Provider-hosted (Deployed by provider)

6. Security Primer
• Authentication (AuthN)
• Authentication establishes an identity
• SP 2010 supports user authentication
• SP 2013 supports user and app authentication
• Authorization (AuthZ)
• Based on ACL
• Ensure current principal has the proper permissions
• SP 2010 supports permission only for users
• SP 2013 supports permission for users and apps
• Security Principal
• An entity that is understood by a security system
• An entity on which you can configure permission for resources
• Examples: User in AD, FBA User, AD Group or FBA Role, SharePoint App

7. Claims-based Identity Model
• Way for applications to acquire the identity information about internal or external users
• Abstracts individual elements of identity and access control into “Notion of claims” and “Concept of issuer or an authority”
• Applications do not need to authenticate users, store user accounts or passwords, etc.
• Original intention behind the claims-based identity model was to enable federation between organization, but claims are not just
for federation
• Claim
• Statement that one subject (user or organization) makes about itself of another subject. E.g.: name, group, ethnicity etc.
• Why call these “claims” and not “attributes”? “Delivery method” => User delivers claims to application instead of application looking these up
in some directory
• Claims are NOT what a user can or can not do, they are what a user is or is not
• Each claim is made by an issuer, and you trust the claim only as much as you trust the issuer
• Issuer, Type, Value => (Google, Email, darwaish@gmail.com)
• Security Token
• Serialized set of claims that is digitally signed by the issuing authority (Claims are unchanged and comes from whoever signed in)
• Successful outcome of sign in
• SAML (Security Assertion Markup Language), SWT (Simple Web Token), JWT (JSON Web Token)

8. Relying Party and STS
• Relying Party (RP)
• An application that relies on claims
• Claims aware application
• Claims-based application
• Security Token Service
• Service component that builds, signs and issues security tokens
• Implicit authN (no token, no party)
• WS-Trust, WS-Fed, SAML
• IP-STS:
• authenticates a client and creates SAML token
• Façade for one or more identity stores
• RP-STS (R-STS: Resource STS, FP-STS: Federation Provider STS)
• Transforms token issues by another STS
• Does not authenticate the client but relies on SAML token provided by IP-STS that it trusts
• Façade for one boundary
• Federation Patterns
• Passive (Web Clients) WS-Trust emulated using GET, POST, redirects and cookies.
• Active: Code to acquire tokens explicitly

9. Windows Identity Foundation (WIF)
• .NET library encapsulating the inner workings of WS-Federation and
WS-Trust
• System.IdentityModel
• System.IdentityModel.Services
• IPrincipal (IsInRole, Identity), IIdentity (AuthenticationType,
IsAuthenicated, Name)
• IClaimsPrincipal = IPrincipal + Identities
• IClaimsIdentity = IIdentity + Claims
• Claims: Property bag, Subject, issuer, originalissuer, claimtype, value,
valuetype

10. SharePoint Claims

11. App Authentication in SharePoint 2013
• App are first class security principals and granted permissions separate
from user permission
• Granted as all or none and No hierarchy of permission
• App authentication is only supported in CSOM and REST API end points
• App authentication is NOT supported in custom web service entry points
• Apps have Full rights against app web, can request permissions for other
webs
• Full Control permission can not be used for OfficeStore apps
• Project Server permissions available if PWA is installed

12. Demo
App Permissions

13. SP Permission Policies
• App + User Policy
• Both user and app require permission on the resource
• App-Only Policy
• Only app needs permissions on resource
• Allow app code to elevate above permission of current user
• Only supported for server-side code in cloud-hosted apps
• AllowAppOnlyPolicy=“true” in AppManifest.xml
• Permission granted during install (all or nothing)
• User Policy
• Not used when app makes a call to SharePoint

14. SP 2013 AuthN Flow for CSOM/REST Endpoint

15. Types of App Authentication in SharePoint
• 3 basic types of app authentication
• Internal authentication
• External authentication using OAuth
• Office 365
• External authentication using S2S
• On-premise

16. Internal Authentication
• Used in Client-side calls from pages in app web or remote web which
use cross domain library
• Incoming calls require a SAML token holding an established user
identity
• Call targets unique domain of app web associated with an app
• SharePoint maps target URL to instance of an app
• App code is not required to create and manage security tokens

17. App Web
• App by default has full permissions to read/write content to app web
• No default permissions on any location in the SharePoint host environment
• App.master provides UI to go back to host web
• Isolated in its own private domain
• https://{ TenancyName}-{14 char App UID}. sharepoint.com/ sites/{ ParentSiteName}/{
AppName}/
• http:// apps-{ UniqueID}. sp2013apps.local/ sites/{ ParentSiteName}/{ AppName}/
• Why Private Domain?
• XSS: JavaScript code can not call back to host web
• JavaScript do not run with the same established user identity as host web
• SharePoint environment sees JavaScript callbacks from appweb with unique URLs and can
authenticate apps
• {StandardTokens}: { HostUrl}, {AppWebUrl}, { Language}
• Use Internal Authentication: App is not required to create/manage security tokens

18. Demo
App Web and Internal Authentication

19. External Authentication
• Calls to SP from server-side code running in remote web
• Used for both OAuth and S2S
• Incoming calls require access token with app identity
• Access token can optionally carry user identity as well
• Call can target any CSOM or REST endpoint in any site
• App code is required to create and manage security tokens

20. Demo
External Authentication

21. OAuth
• Manage app permission on the web
• OAuth.net
• Internet protocol/spec for creating/mapping app identity
• A cross platform, open protocol for authenticating apps
• Internet standard used by Google, Facebook, Twitter
• Authorize requests by an app for SharePoint to access SharePoint resources on behalf of a user
• SP2013 uses OAuth 2.0 (very different from OAuth 1.0)
• OAuth specs provides details on how to create access tokens
• Used for external auth in Office 365
• Delegated authorization codes or access tokens are issues by OAuth STS (Windows Azure Control Services)
• Remote web must communicate with ACS to obtain access tokens
• Access tokens pass to SharePoint host in CSOM or REST API calls
• WS-Federation STS and SAML passive sign-in STS are primarily intended to issue sign-in tokens
• In SP2013, OAuth STS is uses only for issuing context tokens and not used as identity providers

22. OAuth Concepts
• Content Owner(s)
• SharePoint user(s) who can grant permissions to site content
• Content Server
• SharePoint web server that hosts site with the content that is to be accessed
• Client App/ClientID/AppID
• Remote web that needs permissions to access site content
• Authentication Server
• Trusted service that provides apps with access tokens allowing access to
content
• Windows Azure ACS in Sp2013 apps case

23. App Principals
• Tenancy-scoped configuration for app identity
• App principals must be registered with SharePoint and ACS
• App Principal Properties
• Client Id: GUID based identifier for app principal
• Client Secret: Key to encrypt message between app and ACS
• App Host Domain: Base URL of domain hosting remote web
• Redirect URL: URL to a page used to configure security

24. Security Tokens used in OAuth
• Context Token
• Contextual information passed to app
• JWT
• Valid for 12 hours
• Cache key: identify unique user
(user, app, tenant)
• Refresh Token
• Used by client app to acquire an access token
• Valid for 6 months
• Access Token
• Token passed to SharePoint to app
when using external authentication
• Valid for 12 hours

25. OAuth Workflow in Office 365

26. Context Token

27. Access Token

28. Steps to use OAuth in O365
• Create new Cloud-hosted app project
• Register App Principal
• Registration handled automatically in autohosted apps
• Registration requires manual steps in provider hosted apps
• Registration requires extra steps for apps published to Office Store. Have to get client
id/secret from Seller Dashboard
• App principal properties
• Client ID: Guid or app principal
• Clint secret: key used to encrypt message sent between app and ACS
• App host domain: base url which defined hosting domain for remote web
• Redirect URL: URL to a page used to configure on the fly security
• Add code in remote web to manage tokens
• Code required to retrieve access tokens from ACS
• Explicit code required to add access token to csom and rest api calls

29. Demo
OAuth Tokens and App Principal

30. Managing App Principals in O365
• /_layouts/15/…
• AppRegNew.aspx
• AppInv.aspx
• AppPrincipals.aspx
• PowerShell for SPOnline to administer SharePoint apps and app
principals

31. Questions
• ???