Migrating SharePoint Add-ins from Azure ACS to Azure AD

Agenda The Provider-hosted Add-in Model Classic Add-in Authentication with ACS Authentication with Azure Active Directory Migrating Server-side code to use Azure AD Migrating Client-side SPAs to use Azure AD #ITDevConnections

Classic Add-in Authentication with ACS

Provider-Hosted Add-ins Developer responsible for deploying remote web Add-in deployed to remote web on remote web server Developer deploys remote web prior to add-in installation Developer sometimes required to deploy database as well

Creating a Provider-hosted App Project

Provider-hosted App Projects Visual Studio create solution with two projects SharePoint add-in project ASP.NET Website project for remote web known as the “web project”

AppManifest.xml Provider-hosted app adds requirements to App Manifest StartPage must point to page in remote web AppPrincipal requires app authentication settings

Internal Authentication Internal authentication is used if the following are true Incoming call targets a CSOM or REST API endpoint Incoming call carries claims token with established user identity Incoming call targets URL of an exiting app web Important points about using internal authentication It just works – no need to program in terms of access tokens It’s always used with client-side calls from pages in the app web It can be used from remote web pages using cross domain library It does not support app-only authentication to elevate privledge

External Authentication which scenarios use external authentication? When server-side code in remote web calls to SharePoint Calls can target host web How does it work? App code must create and manage access tokens Access token carries app identity Access token usually carries user identity as well App must transmit access token in each call

SharePoint Add-in Authentication Flow 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 Protocol Flow in SharePoint 1 SharePoint authenticates user using claims Content Server SharePoint 2013 Web Server 2 SharePoint requests context token for user 3 ACS returns context token 1 2 4 SharePoint pass context token to User User desktop computer laptop computer mobile device tablet or iPad 4 3 5 Authentication Server Trusted ACS server that authenticates applications and creates OAuth tokens User POSTS to app passing context token 6 Client app is able to pull refresh token out of context token. Client app then passes refresh token to ACS to request OAuth token 8 9 7 ACS returns OAuth token to client app 5 Client App Web Server running remote app code 6 8 Client App makes CSOM/REST calls to SharePoint site passing OAuth token 10 7 9 SharePoint returns site content to app 10 Client App returns HTML to user device

Security Tokens used in OAuth 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

Programming with Access Tokens Visual Studio adds two utility helpful classes TokenHelper (it's been around since VS 2012) SharePointContext (this was introduced with Visual Studio 2013)

CSOM Calls using S2S Authentication TokenHelper class has methods specific to S2S SharePointContext has methods that are not S2S-specific

Examining CSOM Calls using Fiddler

REST Calls using OAuth Authentication Authorization header must be added explicitly

Examining REST Calls using Fiddler

Authentication with Azure Active Directory

OAuth 2.0 Resource service 1 User agent Client Resource service 2 End user working in browser Client Your Custom Application Resource service 2 Authentication Flow Resource service 3 access token Authorization server FaceBook, Google, Twitter, GitHub Azure Active Directory

View into an Access Token

OAuth Client Registration Client must be registered with authorization server Authorization server tracks each client with unique Client ID Client should be registered with one or more Reply URLs Reply URL should be fixed endpoint on Internet Reply URL used to transmit security tokens to clients Client registration tracks permissions and other attributes

Authentication Flows User Credentials Flow (public client) Used in Native clients to obtain access code Requires passing user name and password Authorization Code Grant Flow (confidential client) Client first obtains authorization code then access token Server-side application code never sees user’s password Client Credentials Grant Flow (confidential client) Authentication based on SSL certificate with public-private key pair Used to obtain access token when using app-only permissions Implicit Grant Flow (public client) Used in SPAs built with JavaScript and AngularJS Application obtains access token w/o acquiring authorization code

OAuth 2.0 and Authentication OAuth 2.0 was designed for authorization Creation of access token requires authentication Authorization server passes access token to client Client passes access token when calling resource services Access token serves as app credentials for authorization Access token not intended for user authentication Access token not designed to carry user identity data OAuth 2.0 doesn't require validation of access token Naïve OAuth 2.0 implementations subject to attack

Open ID Connect Resource service 1 Client (Relying Party) User agent End user working in browser Client (Relying Party) Your Custom Application Resource service 2 Authentication Flow Resource service 3 Id tokens Open ID Provider FaceBook, Google, Twitter, GitHub Azure Active Directory

Azure Active Directory (AAD) AAD plays role of an OpenID Connect Provider Creates access tokens based on OAuth 2.0 Creates id tokens based on OpenID Connect 1.0 AAD provides authentication & authorization for… Office 365, Exchange Online and SharePoint Online Power BI REST API Custom Web Applications and Web Services

Office 365 and Azure AD Office 365 environments are based on tenancies Tenancy provides scope for creating and managing users Tenancy provides a scope for site collections in SharePoint Online Office 365 is integrated with Azure Active Directory (AAD) Each Office 365 tenancy is backed by an AAD directory AAD directory can be managed using Office 365 administration AAD directory can be managed using Windows Azure Portal Azure support registering application within scope of AAD directory Application using Office 365 APIs must be registered with AAD This means you must become familiar with Azure Active Directory

Azure Management Portal Provides management over one or more directories View & configure AAD directory behind Office 365 developers site Create, view and configure AAD applications during development

Azure AD Applications Azure AD application configured with properties Name Sign-on URL Logo Single Tenant vs. Multi-tenant Client ID Keys (serves as password) App ID URI Reply URL Application Permissions Delegated Permissions

Application Permissions Applications can be granted permissions to other applications Application permissions are app-only permissions Delegated permissions are (app + user) permissions

OWIN and Katana OWIN = Open Web Interface for .NET Standard interface web servers and web applications Serves to decouple web server and application Encourages of simple modules for .NET web development Allows fasters evolution of specific web modules Katana is Microsoft's OWIN implementation Provides lots of support for implementing security

NuGet Packages used in Demo

Migrating Server-side code to use Azure AD

OWIN Security Middleware OWIN ties OpenIDConnect to ASP.NET Security Automatically redirects user to authorization endpoint Handles callback from authorization server to Reply URL Establishes User identity in AP.NET security model Makes user claims available to your code Let's you use [Authorize] attribute on your controllers

Token Caching with ADAL ADAL for .NET provides token caching Helps to save round trips & increase performance Helps to reduce user interaction with AAD How is ADAL used? Creates static cache for native clients ADAL 1.x did not support web clients ADAL 2.x adds support for web clients Web client support requires custom cache

Caching Security Tokens using Entity Framework Security tokens can (and should) be cached across requests Best practices lead to caching security tokens in database instead of Session object Entity Framework provides means to automatically create database to track per user data AppSecurityContextDB database created automatically by Entity Framework

MVC Application Code Walkthrough Sample MVC5 Application Provides user with Office 365 sign-on experience Acquires and manages access tokens for SharePoint Online Accesses SharePoint Online through CSOM and SharePoint REST API Development techniques employed Uses OWIN middleware to authenticate user and manage tokens Uses AccountController class to control sign-on experience Uses ADAL to authenticate user and retrieve access tokens Caches access tokens using ADAL and Entity Framework database

Migrating Client-side SPAs to use Azure AD

Understanding the Implicit Grant Flow Used when client cannot keep secrets (public client) Used with SPAs built using JavaScript and AngularJS Less secure than Authentication Code Grant How does it work? Client authorizes user with AD authorization endpoint AD returns access token directly to SPA in browser Authentication flow does not involve authorization code

Configuring Implicit Flow in Azure AD Requires configuring AD application in Azure AD Download manifest from Azure AD Update oauth2AllowImplicitFlow setting equal to true Upload manifest to Azure AD to save changes

Downloading the ADAL-JS Library Developing with ADAL-JS involves to two library files adal.js – core ADAL-JS library adal-angular.js –integration of ADAL-JS with AngularJS Library files downloadable from GitHub Repository https://github.com/AzureAD/azure-activedirectory-library-for-js

Initializing ADAL-JS Settings

Making Secure Calls to Custom Web Services adal-angular.js adds interceptors to $http service adal detects when calls are made to secure endpoints adal acquires & caches access tokens behind scenes adal attaches access token to Authorization header

Implementing the User Sign-In Experience

Inspecting Authenticated User Claims

Summary The Provider-hosted Add-in Model Classic Add-in Authentication with ACS Authentication with Azure Active Directory Migrating Server-side code to use Azure AD Migrating Client-side SPAs to use Azure AD #ITDevConnections

WIN Rate This Session Now! Tell Us What You Thought of This Session Rate with Mobile App: Be Entered to WIN Prizes! Tell Us What You Thought of This Session Select the session from the Agenda or Speakers menus Select the Actions tab Click Rate Session Rate with Website: Register at www.devconnections.com/logintoratesession Go to www.devconnections.com/ratesession Select this session from the list and rate it #ITDevConnections