Securing SharePoint Apps using OAuth in Office 365 Ted PattisonAuthor/Instructor

SPC204

• App Authentication in SharePoint 2013• Requesting and Granting App Permissions• Understanding How OAuth Authentication

Works• Developing SharePoint Apps that use OAuth• Developing External Apps that use OAuth

Agenda

• Code in farm solutions considered fully-trusted• By default, code runs with permissions of current user• Developer can call SPSecurity.RunWithElevatedPrivledges• Code runs as all-powerful SHAREPOINT\SYSTEM account• Code reverts to Windows identity of host application pool

• Sandbox solution code runs as current user• Code always runs with permissions of current user• Activation code runs as site administrator• No ability to elevate permissions if user is visitor or contributor

Security Problems in SharePoint 2010

• Authentication establishes an identity• Authentication is performed on a security principal• Authentication produces some form of security token• SharePoint 2010 supports user authentication• SharePoint 2013 supports user authentication and app authentication

• Authorization provides access to resources• Authorization systems based on access control lists (ACLs)• ACLs can be configured b privileged users• ACLs used by system to ensure current principal has the proper

permission• SharePoint 2010 supports configuring permissions only for users• SharePoint 2013 supports configuring permissions for users and apps

Authentication and Authorization

• What is a security principal?• An entity that is understood by a security system• An entity for which you can configure authorized access to resources

• Examples of security principals• A user with an account in Active Directory• A user with an account in some other identity management system

(FBA)• An Active Directory group or an FBA role• A computer which has been added to an Active Directory domain• A SharePoint app (as of SharePoint 2013)

Let’s start with a basic question

• Users are authenticated using claims• Works in SharePoint 2013 just as it does in SharePoint 2010• User security token created in XML with Security Assertion Markup

Language• User security token known as a SAML token• SAML tokens are created by Security Token Service (STS)

• Note: SharePoint apps are not supported in classic mode web applications

User Authentication in SharePoint 2013

• SharePoint 2013 supports App Authentication• Apps promoted to first class security principals• App authentication makes it possible for app authorization• App authentication is only supported in CSOM and REST API endpoints• App authentication not supported in custom web service entry points

• There are 3 basic types of app authentication• Internal authentication• External authentication using OAuth• External authentication using S2S

App Authentication in SharePoint 2013

• 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

SharePoint App Architecture

• Every app requires a start page• Start page provides entry point into app• SharePoint adds app launcher to Site Contents in host web• SharePoint-Hosted app start page hosted by SharePoint• Cloud-Hosted app start page hosted in remote web

App Start Page

Creating a SharePoint-hosted App for Office 365Ted Pattison

• 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

App Web

• App web pages served out of isolated domain• Isolates JavaScript code on app web pages• Allows SharePoint to authenticate callbacks from app

• URL to app web made up of 4 parts• Tenancy name: tedpattison• APPUID: 4b5b001f544dc0• App web hosting domain: sharepoint.com• App name: MyFirstApp

App Web Hosting Domain

https://tedpattison-4b5b001f544dc0.sharepoint.com/sites/TedsDevSite/MyFirstApp

• In which scenarios is internal authentication used?• Client-side calls from pages in the app web• Client-side calls from pages in remote web which use cross domain

library• Server-side calls to app web in on-premises scenarios

• How does it work?• 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• Your app code is not required to create and manage security tokens

Internal Authentication

• SharePoint-Hosted App• App deployed to app web created under child site

• Provider-Hosted App• App deployed to remote web on remote web server• Developer deploys remote web prior to app installation

• Autohosted App• App deployed to remote web in Office 365 environment• Office 365 deploys remote web during app installation

App Hosting Models

• Developer responsible for deploying remote web• App deployed to remote web on remote web server• Developer deploys remote web prior to app installation• Developer often required to deploy database as well

Provider-Hosted App

• Office 365 responsible for deploying remote web• Office 365 deploys remote web during app installation• Office 365 can also deploy SQL Azure database• Developer doesn't worry about scaling or multi-tenancy

Autohosted App

• In which scenarios is external authentication used?• Calls to SharePoint from server-side code running in the remote web

• How does it work?• Incoming calls requires access token with app identity• Access token can optionally carry a user identity as well• Call does not need to target URL inside app web• Call can target any CSOM or REST endpoint in any site• Your app code is required to create and manage security tokens

External Authentication

• There are three possibilities for authentication• Remember, this is only for CSOM and REST API endpoints

Authentication and Security Token Type

call from user SAMLtoken

call from app using external authentication

AccessToken

call from app using Internal authentication

SAMLtoken

SharePoint Farm

Web Servers

SharePoint 2013 Authentication FlowStart Authentication

Does access token contain user identity

Does call carry a SAML token?

Does call carryan access token?

Does call target an app web

No Authentication

set up call context using anonymous access

App Authentication

set up call context with identity of app only

App Authentication

set up call context with identity of app and user

User Authentication

set up call context with identity user only

End Authentication

No

Yes

Yes

No

No

Yes

Yes

No

Important: this flow only for calls that target a CSOM or a REST endpoint

App Authentication in SharePoint 2013Requesting and Granting App Permissions• Understanding How OAuth Authentication

Works• Developing SharePoint Apps that use OAuth• Developing External Apps that use OAuth

Agenda

• SharePoint 2013 tracks user permissions• No big changes from previous version• User permissions managed at the site collection level• User permissions in site collection configured on hierarchy of securable

objects• User permissions can be overridden at web application level through

user policy

• SharePoint 2013 also tracks app permissions• App permissions managed very differently from user permissions• App permissions do not involve hierarchy of securable objects• App permissions are assigned to target permission scopes• Permission scope can be site (aka web), site collection (aka site) and

tenancy

Permissions in SharePoint 2013

• App + User Policy• Both user and app require permissions to access resource• Access denied error occurs if either user or app has insufficient

permissions

• App-only Policy• Only the app needs permissions to access a resource• Allows for app code to elevate above permissions of current user• Only supported for server-side code in cloud-hosted apps

• User policy• Never used when an app makes a call to SharePoint

SharePoint Permission Policies

• App are granted permissions• App permissions are different from user permissions• App permissions are granted as all or nothing• App permissions have no permissions hierarchy

• this is different than user permissions which have a hierarchy inside a site collection

• An app has default permissions• App has full control over app web and limited read permissions on host

web• App can request additional permissions in application manifest• Installing user grants/denies permissions during installation• If permission request denied, SharePoint does not install app

App Permissions

• Permissions requests are added to app manifest• App manifest designer makes this relatively easy

Adding Permission Requests

• App Permission Scope Defines• Product• Permission Provider• Target object - where grant is requested

Permission Requests

<AppPermissionRequest Scope="http://sharepoint/content/sitecollection" Right="Read"/>

Product PermissionProvider

TargetObject

Capability

• Used for two key scenarios• To call into SharePoint with permissions greater than the current user

(elevation)• To call in to SharePoint when there is no current user

• Steps to accomplish this• Add AllowAppOnlyPolicy to AppManifest.xml• Write code to acquire an app only access token

App-Only Permissions

• User prompted during app installation• Trust It button grants requested permissions to app• Cancel button prevents app from being installed

Granting Consent in SharePoint 2013

Installing an App with a Permission RequestTed Pattison

App Authentication in SharePoint 2013Requesting and Granting App PermissionsUnderstanding How OAuth Authentication

Works• Developing SharePoint Apps that use OAuth• Developing External Apps that use OAuth

Agenda

• You can give app a user login and password…• Allows app to do whatever user can do• App can complete its works• However...

• Design based on giving user credentials is bad• System cannot distinguish app from user• App can do anything user can do (e.g. delete content)• User must reset password to revoke permissions• This approach cannot be used as basis for granting permissions to apps

Managing App Permissions on the Web

• What is OAuth?• Internet protocol/specification for creating and managing app identity• A cross-platform mechanism for authenticating apps• Internet standard used by Facebook, Google and Twitter• With SharePoint 2013, Microsoft is using OAuth 2.0 - very different from OAuth

1.0

• SharePoint 2013 support authentication using OAuth • OAuth specification provides details on how to create access tokens• OAuth used for external authentication in Office 365 environment• OAuth authentication requires Windows Azure Access Control Service

(ACS)• Remote web must communicate with ACS to obtain access tokens• Access tokens pass to SharePoint host in CSOM calls and REST API calls

OAuth 2.0 Primer

• Content Owner(s)• SharePoint user (or users) 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• Remote web that needs permissions to access site content

• Authentication Server• Trusted service that provides apps with access tokens allowing access

to content

OAuth Concepts and Terms

• Windows Azure Access Control Service (ACS)• Required service when using OAuth with SharePoint 2013• ACS server acts as authentication server• Office 365 is configured with a trust to ACS• Client app (i.e. remote web) must communicate with ACS to acquire

access tokens

Windows Azure ACS

SharePoint 2013Content ServerOffice 365 Tenancy

End User• computer• mobile device• tablet or iPad

Client AppWeb Server running remote app code

Windows Azure ACSAuthentication server

• External authentication requires app principals• App principal provides 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 (aka app identifier)• Client Secret: Key used to encrypt message sent between app and

ACS• App Host Domain: Base URL which defines hosting domain for remote

web• Redirect URL: URL to a page used to configure on-the-fly security

App Principals

• Context Token• Contextual information passed to app

• Refresh Token• Used by client app to acquire an access token

• Access Token• Token passed to SharePoint to app when using external authentication

• Authorization Code• Used to register an app with on the fly permissions

Security Tokens used in OAuth

OAuth Protocol Flow in Office 365

SharePoint 2013Content ServerOffice 365 Tenancy

End User• computer• mobile device• tablet or iPad

Client AppWeb Server running remote app code

Authentication ServerTrusted ACS server that authenticates applications and creates OAuth tokens

1

1 SharePoint authenticates user using claims

2

2 SharePoint requests context token for user

3

3 ACS returns context token

4

4 SharePoint passes context token to user

5

5 User POSTS to app and passes context token

6

6 Client app extracts refresh token from context tokenand passes it to ACS to request access token

7

7 ACS returns access token to client app

8

8 Client App makes CSOM/REST calls to SharePoint site passing OAuth token

9

9 SharePoint authenticates app and processes CSOM/REST calls and returns content to app

10

10 Client App returns HTML to user device

• Your code must create/manage access tokens• Visual Studio adds TokenHelper class to cloud-hosted app projects

TokenHelper Class

• Create a new cloud-hosted app project• Can be either provider-hosted or autohosted• Make sure to do so with the Preview 2 version of VS Tools

• Register an App Principal• Registration handled automatically in autohosted apps• Registration requires explicit steps for provider-hosted apps• Registration requires extra steps for apps published to Office Store

• 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

Steps to using OAuth in Office 365

Calling to an Office 365 site from an Autohosted AppTed Pattison

App Authentication in SharePoint 2013Requesting and Granting App PermissionsUnderstanding How OAuth Authentication

WorksDeveloping SharePoint Apps that use OAuth• Developing External Apps that use OAuth

Agenda

• Get to know the built-in app management pages• AppRegNew.aspx• AppInv.com• AppPrincipals.aspx

• There is also management support using PowerShell• Download and install Windows PowerShell for SharePoint Online (when

available)• Use PowerShell cmdlets to establish connection to Office 365 tenancy• Use PowerShell cmdlets to administer SharePoint apps and app

principals

Managing App Principals in Office 365

AppRegNew.aspx

AppInv.aspx

AppPrincipals.aspx

• Required when publishing OAuth apps to Office Store• Create a new reseller account• Create client ID with required information• Seller Dashboard generates Client Secret for you

Getting a Client ID from the Seller Dashboard

App Manifest for an Autohosted App

Web.config for an Autohosted App

App Manifest for a Provider-hosted App

Web.config for a Provider-hosted App

Incoming Data

Context Token

Access Token

Acquiring Access Tokens

Making REST Calls with OAuth

Making CSOM Calls with OAuth

Managing Access Tokens in a SharePoint App in Office 365Ted Pattison

App Authentication in SharePoint 2013Requesting and Granting App PermissionsUnderstanding How OAuth Authentication

WorksDeveloping SharePoint Apps that use OAuthDeveloping External Apps that use OAuth

Agenda

• Request permission without installing an app• Navigate to page to begin request for authorization code

• Call GetAuthorizationUrl and then redirect user using Response.Redirect

Requesting Permissions on the Fly

Authorization by a Privileged User

Using the Authorization Code

Requesting Permissions to an Office 365 Site on the FlyTed Pattison

App Authentication in SharePoint 2013Requesting and Granting App PermissionsUnderstanding How OAuth Authentication

WorksDeveloping SharePoint Apps that use OAuthDeveloping External Apps that use OAuth

Summary

Evaluate this session now on MySPC using your laptop or mobile device: http://myspc.sharepointconference.com

MySPC

© 2012 Microsoft Corporation. All rights reserved. Microsoft, Windows, Windows Vista and other product names are or may be registered trademarks and/or trademarks in the U.S. and/or other countries.The information herein is for informational purposes only and represents the current view of Microsoft Corporation as of the date of this presentation. Because Microsoft must respond to changing market conditions, it should not be interpreted to be a commitment on the part of Microsoft, and Microsoft cannot guarantee the accuracy of any information provided after the date of this presentation. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.