This document provides an overview of Office 365 APIs and authentication using Azure Active Directory. It discusses the user authentication flow, OAuth principles, and application authentication flows. It covers development scenarios for provider-hosted apps and Office 365 APIs. Key topics include Azure AD, OAuth tokens, bearer tokens, the provider-hosted app flow, Office 365 clients, the Office 365 discovery service, and programming the OAuth controller.

1. SPS ATL
May 30, 2015
DEEP DIVE INTO OFFICE 365 APIS FOR AZURE
ACTIVE DIRECTORY

2. 2 SharePoint Saturday Atlanta2 |SharePoint Saturday Atlanta

3. 3 SharePoint Saturday Atlanta3 |SharePoint Saturday Atlanta

4. 4 SharePoint Saturday Atlanta4 |SharePoint Saturday Atlanta

5. ABOUT ME
Solutions Architect
Trainer
Hockey fan
http://www.schaeflein.net/blog

6. AGENDA
 Azure Active Directory
User Authentication Flow
 OAuth Primer
Application Authentication Flow
 Development Scenarios
Provider-hosted / SharePoint context
O365 OAuth / Discovery / Tokens

7. AZURE ACTIVE DIRECTORY
 Identity and Access Management for the cloud
 Can create new directories or manage existing ones in
Azure subscription
 Used by Office 365 for authentication
 Used by Azure for user authentication and application
authorization

8. ORGANIZATIONAL ACCOUNTS
 Term for User Accounts in AAD
 Required to Access Microsoft Cloud Services
 Tenant-Based

9. LINK OFFICE 365 AND AZURE
 Log into Microsoft Azure subscription as administrator
 Click on the Active Directory link.
 Click New>Active Directory>Directory>Custom Create
 Select to Add an Existing Directory
 Follow the steps to add an existing directory

10. USER AUTHENTICATION

11. USER AUTHENTICATION
 Users authenticate to Office 365 using Organizational
Account
 Users added to directory via O365, Azure Portal,
Synchronization

12. USER AUTHENTICATION

13. USER AUTHENTICATION
Userattemptsto access
SharePointonline
resource

14. USER AUTHENTICATION
Redirectedto
login.microsoftonline.com

15. USER AUTHENTICATION
Loginwith
OrganizationalAccount

16. USER AUTHENTICATION
IssueSAMLtoken

17. USER AUTHENTICATION
Presenttoken

18. USER AUTHENTICATION
ReturnFedAuthcookie

19. USER AUTHENTICATION
Subsequentrequests
UtilizeFedAuthcookie

20. OAUTH PRIMER

21. WHAT IS OAUTH 2.0?
 Simple mechanism to grant a third party access to a
user’s resources without sharing the user’s password.
 Cross platform app authorization
 Internet Standard supported by Azure, Facebook,
Google, Twitter, and more

22. OAUTH 2.0 ACTORS
 Client: application requesting access to a user’s
resources
 Resource Owner: the user who can grant rights to the
application
 Resource Server: the server hosting the protected
resources and exposing a web-based API
 Authorization Server – server issuing tokens

23. OAUTH 2.0 ACTORS IN OFFICE 365
 Client: SharePoint app, Azure web application,
Windows 8 app
 Resource Owner: individual or administrator with an
Organizational Account in Azure Active Directory
 Resource Server: SharePoint, Exchange
 Authorization Server: Azure Access Control Services

24. OAUTH 2.0 TOKENS
 Context Token
 Information about the Resource Owner & Client
 Used to get an Access Token later.
 Access Token
 A token passed to the Resource Server authorizing the
Client to access resources.

25. OAUTH 2.0 TOKENS
 Refresh Token
 A token used to get an Access Token from the
Authorization Server.
 Authorization Code
 A code that can be used to register an app
on-the-fly

26. BEARER TOKENS
 OAuth 2.0 Access Tokens are unbound tokens (a.k.a,
“Bearer Tokens”)
An Access Token can be used by any application that
possesses it
Always use SSL – OAuth design depends on it!
Never expose tokens in JavaScript or allow them to
be accessed by client-side debugging tools

27. BEARER TOKENS
 OAuth 2.0 Access Tokens are unbound tokens (a.k.a,
“Bearer Tokens”)
If an Access Token is compromised, damage is
limited by expiration
If a Refresh Token is compromised, damage is limited
because the Client ID and Client Secret are required
to get an Access Token from a Refresh Token.

28. DEVELOPMENT SCENARIOS
Provider-Hosted Apps
What we’ve used in SharePoint Online all along
Uses SharePoint-specific tokens
Office 365-based Apps
Uses service-wide capable tokens

29. PROVIDER-HOSTED APP
Demo

30. APP PRINCIPALS
 Apps are registered with SharePoint Online
Client ID / Secret
App Host Domain
Redirect URL
 SharePoint provides registration management pages
AppRegNew.aspx
AppInv.aspx
AppPrincipals.aspx

31. REGISTER AN APP
Generated value
Generated value
Free text value
Azure domain (e.g.,
myapp.azurewebsites.net)
Webaddress (e.g.,
https://myapp.azurewebsites.net)

32. PROVIDER-HOSTED APP FLOW
 User has Organizational Account
 App registered with SharePoint Online
 App deployed to SharePoint Online
 Remote Web deployed
 Client ID and Client Secret defined in AAD

33. OAUTH 2.0 FLOW PROVIDER-HOSTED APP
End User
(Resource Owner)
Azure ACS
(Authorization Server)
Azure Web Site
(Client)
SharePoint Online
(Resource Server)

34. OAUTH 2.0 FLOW PROVIDER-HOSTED APP
Userlaunchesapp
End User
(Resource Owner)
Azure ACS
(Authorization Server)SharePoint Online
(Resource Server)
Azure Web Site
(Client)

35. OAUTH 2.0 FLOW PROVIDER-HOSTED APP
RequestContexttoken
foruser
End User
(Resource Owner)
Azure ACS
(Authorization Server)
Azure Web Site
(Client)
SharePoint Online
(Resource Server)

36. OAUTH 2.0 FLOW PROVIDER-HOSTED APP
ContextTokenreturned
End User
(Resource Owner)
Azure ACS
(Authorization Server)
Azure Web Site
(Client)
SharePoint Online
(Resource Server)

37. OAUTH 2.0 FLOW PROVIDER-HOSTED APP
ContextTokenreturned
anduserredirectedto app
End User
(Resource Owner)
Azure ACS
(Authorization Server)
Azure Web Site
(Client)
SharePoint Online
(Resource Server)

38. OAUTH 2.0 FLOW PROVIDER-HOSTED APP
AppextractsRefreshToken
fromContextTokenEnd User
(Resource Owner)
Azure ACS
(Authorization Server)
Azure Web Site
(Client)
SharePoint Online
(Resource Server)

39. OAUTH 2.0 FLOW PROVIDER-HOSTED APP
ApprequestsAccessToken
usingrefreshToken
End User
(Resource Owner)
Azure ACS
(Authorization Server)
Azure Web Site
(Client)
SharePoint Online
(Resource Server)

40. OAUTH 2.0 FLOW PROVIDER-HOSTED APP
AccessTokenreturned
End User
(Resource Owner)
Azure ACS
(Authorization Server)SharePoint Online
(Resource Server)
Azure Web Site
(Client)

41. OAUTH 2.0 FLOW PROVIDER-HOSTED APP
AccessTokenpresented
Alongwith request
End User
(Resource Owner)
Azure ACS
(Authorization Server)
Azure Web Site
(Client)
SharePoint Online
(Resource Server)

42. OAUTH 2.0 FLOW PROVIDER-HOSTED APP
Responsereturned
End User
(Resource Owner)
Azure ACS
(Authorization Server)
Azure Web Site
(Client)
SharePoint Online
(Resource Server)

43. SHAREPOINTACSCONTEXT CLASS
 Inherits SharePointContext
 Provides specific properties and methods for dealing
with context and access tokens
CSOM REST
CreateAppOnlyClientContextForSPApp
Web
CreateAppOnlyClientContextForSPHos
t
CreateUserClientContextForSPAppWe
b
CreateUserClientContextForSPHost
AppOnlyAccessTokenForSPAp
pWeb
AppOnlyAccessTokenForSPHo
st
UserAccessTokenForSPAppW
eb
UserAccessTokenForSPHost

44. MAKING REST CALLS WITH OAUTH

45. MAKING CSOM CALLS WITH OAUTH

46. PROVIDER-HOSTED APPS

47. OFFICE 365 APIS

48. OFFICE 365 APIS FLOW
 User has Organizational Account
 Application deployed
 Application does not require explicit permission grant

49. OAUTH 2.0 FLOW OFFICE 365 APIS
End User
(Resource Owner)
Azure Active Directory
(Authorization Server)
Azure Web Site
(Client)
SharePoint Online
(Resource Server)

50. OAUTH 2.0 FLOW OFFICE 365 APIS
End User
(Resource Owner)
Azure Active Directory
(Authorization Server)
Azure Web Site
(Client)
SharePoint Online
(Resource Server)
Useraccesses
Webapplication

51. OAUTH 2.0 FLOW OFFICE 365 APIS
End User
(Resource Owner)
Azure Active Directory
(Authorization Server)
Azure Web Site
(Client)
SharePoint Online
(Resource Server)
Redirectedto AAD

52. OAUTH 2.0 FLOW OFFICE 365 APIS
End User
(Resource Owner)
Azure Active Directory
(Authorization Server)
Azure Web Site
(Client)
SharePoint Online
(Resource Server)
Consentdialog
displayed

53. OAUTH 2.0 FLOW OFFICE 365 APIS
End User
(Resource Owner)
Azure Active Directory
(Authorization Server)
Azure Web Site
(Client)
SharePoint Online
(Resource Server)
Grantaccessusing
ConsentDialog

54. OAUTH 2.0 FLOW OFFICE 365 APIS
End User
(Resource Owner)
Azure Active Directory
(Authorization Server)
Azure Web Site
(Client)
SharePoint Online
(Resource Server)
AuthCode
returnedand
userredirected

55. OAUTH 2.0 FLOW OFFICE 365 APIS
End User
(Resource Owner)
Azure Active Directory
(Authorization Server)
Azure Web Site
(Client)
SharePoint Online
(Resource Server)
AuthCode,
AppId,AppSecret
sent

56. OAUTH 2.0 FLOW OFFICE 365 APIS
End User
(Resource Owner)
Azure Active Directory
(Authorization Server)
Azure Web Site
(Client)
SharePoint Online
(Resource Server)
AccessandRefresh
Tokensreturned

57. OAUTH 2.0 FLOW OFFICE 365 APIS
End User
(Resource Owner)
Azure Active Directory
(Authorization Server)
Azure Web Site
(Client)
SharePoint Online
(Resource Server)
AccessTokenpresented
Alongwith request

58. OAUTH 2.0 FLOW OFFICE 365 APIS
End User
(Resource Owner)
Azure Active Directory
(Authorization Server)
Azure Web Site
(Client)
SharePoint Online
(Resource Server)
Responsereturned

59. OFFICE 365 DISCOVERY SERVICE
 Automatically determine URL of Office 365 services
 Supports device app and website flows
 Secured using Azure AD authentication
 Serves information stored about services in AAD

60. OFFICE 365 CLIENTS
 AadGraphClient – Azure Active Directory
 ExchangeClient – Calendar, Contacts, Mail
 SharePointClient - Files

61. OFFICE 365 CLIENTS

62. OFFICE 365 APIS

63. OFFICE 365 UNIFIED API
 Announced at //build/
http://dev.office.com/unifiedAPIs

64. OFFICE 365 UNIFIED API

65. OAUTH CONTROLLER

66. OAUTH CONTROLLER CLASS
 Embodies all OAuth operations
 Allows code customizations for special situations
 Available on GitHub
https://github.com/AzureADSamples/WebApp-WebAPI-OAuth2-UserIdentity-DotNet/
blob/master/WebApp/Controllers/OAuthController.cs

67. OAUTH CONTROLLER FLOW
 User has Organizational Account
 App deployed as an Azure Web Site
 App registered with Azure Active Directory
 Client ID and Client Secret defined in AAD
 Permissions granted specifically in AAD

68. PROGRAMMING THE OAUTH CONTROLLER

69. RESOURCES
 http://dev.office.com
 Azure AD Code Samples
https://msdn.microsoft.com/en-us/library/azure/dn646737.aspx