1. Leveraging The Microsoft Graph
SharePoint Saturday Detroit | December 2nd, 2017

2. Agenda Introduction Microsoft Graph Authentication Scenarios Q&A
Saturday, December 2nd 2017

3. Louis Simonetti Microsoft Certified Professional in O365 and Azure
Technology Architect Specialist
Runner
Proud Husband and Father
@lousimonetti

4. Microsoft Graph unified REST endpoint
Full control on everything in Office 365
Resources connected by relationships
And you’re already using it

5. Routine Tasks by Resource
Group membership and auditing
User Administration
Licensing assignment and provisioning
Device management
SharePoint Sites, Lists, Libraries and Items
Microsoft Teams provisioning
Monitoring and Reporting
Directory Role Management
Exchange and Mailbox Tasks

6. Calling the API https://graph.microsoft.com /{version} /{resource}
Build 2015
9/11/2018 9:28 AM
HTTP verbs dictate the request intent: GET | POST | PATCH | PUT | DELETE
Version: /v1.0 or /beta
Resource: /users, /groups, /sites, /drives, /devices, more…
Member from collection: /users/jimbob
Property: /users/jimbob/department
Traverse to related resources via navigations: /users/jimbob/events
Query parameters: /users/jimbob/events?$top=5
Format results: $select | $orderby
Control results: $filter | $expand
Paging: $top | $skip | $skiptoken
/{version}
/{resource}
/{id}
/{property}
?{query-parameters}
© 2015 Microsoft Corporation. All rights reserved. MICROSOFT MAKES NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, AS TO THE INFORMATION IN THIS PRESENTATION.

7. Types of Apps and Permissions
App type
Native or Web
Service Daemon or Automated Tasks
Permission type
Delegated (Allow the app to access what the user is permissioned)
Application – Similar to an SPN in AD
Consent Type
Effective Permissions
User
Consent
Admin Consent
Admin Consent
App permissions
User permissions
App permissions

8. V1 – V2
V1: GET &resource=https%3A%2F%2Fgraph.windows.net%2F...
Account-agnostic
Singular Application ID
Scopes > Resources
Dynamic of Statically applied permissions scopes
V2: GET &scope=https%3A%2F%2Fgraph.windows.net%2Fdirectory.read%20https%3A%2F%2Fgraph.windows.net%2Fdirectory.write...
New “offline_access” scope
Offline_access permission -enable your web app to receive OAuth 2.0 refresh_tokens from the v2.0 endpoint. Refresh_tokens are long-lived, and can be exchanged for new OAuth 2.0 access_tokens for extended periods of access.

9. Register an Application (v2)
Go to the New Portal:
Add a New application
Define App Type, Endpoint and Required Scopes

10. Authentication Flow
msal.js targets the Azure Active Directory v2 endpoint - which enables personal, school and work accounts to sign in and acquire tokens. The Azure Active Directory v2 endpoint has some limitations. If you are interested only in school and work accounts, use adal.js and the V1 endpoint.  To understand differencesbetween the v1 and v2 endpoints read the v1-v2 comparison.

11. Authentication (App-Only)
App Only requires Admin Consent Process
?client_id={clientId}&state=demo&redirect_uri={redirecturi}
POST
/{tenant}/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded
client_id=535fb089-9ff3-47b6-9bfb-4f
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=qWgdYAmab0YSkuL1qKv5bPX
&grant_type=client_credentials
"
$token_uri="
$body="client_id=$($clientId)&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default&client_secret=$($secretencoded)&grant_type=client_credentials";
$contentType="application/x-www-form-urlencoded";
$token=Invoke-RestMethod-method GET-Uri$token_uri-body$body-contenttype$contentType

12. DEMO
Authentication and Authorization

13. Users Typical Tasks Method CREATE READ UPDATE DELETE Request TYPE POST
GET
PATCH
DELETE
Request Body
{ "accountEnabled":true, "displayName":”DN-value", "mailNickname":”MNN-Value", "userPrincipalName":”UPN", "passwordProfile":{ "forceChangePasswordNextSignIn":true, "password":"password-value"} }
Response:
HTTP/ OK Content-type: application/json Content-length:491 { "businessPhones":[], "displayName":"", "givenName":"", "jobTitle":"", "mail":"", "mobilePhone":"",
"officeLocation":"", "preferredLanguage":"", "surname":"", "userPrincipalName":"", "id":"” }
Request:
Content-type:application/json
{ "accountEnabled":true, "assignedLicenses": [{
"disabledPlans": [
”servicePlan-skuId-value” ],
"skuId":"skuId-value”
}],
"usageLocation":"" }
Response: HTTP/ No Content
Request DELETE or id}
Response
HTTP/ No Content

14. Groups Typical Tasks List Members and Add New Members Tasks
List Groups
Owners
DELETE
Request TYPE
GET
GET / POST
GET / POST
DELETE
Request (O365 Groups Only)
any(c:c+eq+'Unified’)
Request (All Groups)
GET Request:
HTTP/ OK Content-type:application/json Content-length:55 { "value":[{ "#microsoft.graph.user”}]}
POST Request: Content-type:application/json Content-length:30
GET Request:
HTTP/1.1200OKContent-type:application/jsonContent-length:55{"value":[{"id":"id-value"}]}
POST Request:
Content-type:application/json Content-length:30
Request DELETE
Response
HTTP/ No Content

15. Licensing Management List SubscribedSkus Assign or Remove Licenses
Tasks
Request TYPE
GET
POST
Request
Response
HTTP/ OK Content-type: application/json {"value":[{ "capabilityStatus":"", "consumedUnits": 99, "prepaidUnits":
{"enabled": 99,"suspended": 99, "warning":99},
"servicePlans":[{"servicePlanId":"","servicePlanName":"","provisioningStatus":"","appliesTo":""}], "skuId":"","skuPartNumber":""}]}
Assign Request:
Content-type: application/json {"addLicenses": [{"disabledPlans": […], "skuId": ”GUID"}, {"disabledPlans": […],
"skuId": ”GUID"}], "removeLicenses":[]}
Remove Request:
Content-type: application/json Content-length:185 {"addLicenses":[],"removeLicenses":[”GUID-1",”GUID-2”, …]}

16. DEMO 2
Users and Groups

17.  Sites
Access to SharePoint sites, lists, and drives (document libraries)
Read-only support for site resources (no ability to create new sites)
Read-write support for lists, listItems, and driveItems
Address resources by SharePoint ID, URL, or relative path
GET
{version}
/sites/
{hostname},{spsite-id},{spweb-id}/
lists/
{list-id}
/items/{item}
SITES only accept GET, Lists and Drives support GET and POST, and Items support GET, POST, PATCH, DELETE
Available in BETA and V1.0
Resource
Specific Site from the Collection of Sites either by hostname:/relative Path or site Id or web id

18. Directory Roles and Role Templates
Azure AD directory roles are also known as administrator roles.
Microsoft Graph => assign users to targeted directory roles.
Only shows currently activated Role Templates in the Graph
/directoryRoleTemplates/
{id}
/directoryRoles/
{id}
Assigning Admin Roles in Azure AD:
Only the Company Administrators directory role is activated by default. To activate other available directory roles, you send a POST request with the ID of the directoryRoleTemplate on which the directory role is based. Inherits from directoryObject.
PIM :
*Add Member
POST
Content-type:application/json
Content-length:30
{"directoryObject": { ”id”: ”value" } }

19. Privileged Identity Management
Just in Administration for Admin with AAD P2 License
Near identical capabilities in the Graph as the Portal
Functionality to fully automate
Role Eligibility
Role Assignments
Self activation / deactivation
Auditing
Privileged Identity Management is available to your entire organization when you license your Administrators with the Premium P2 edition of Azure Active Directory. For more information, see Azure Active Directory editions.+
/privilegedRoleAssignments/
{id}
/makePermanent
/makeEligible
/privilegedRoles /
{id}
?$expand=summary

20. Microsoft Teams /me/joinedTeams /beta/groups/{id}/team
A Group in AAD, represents an Office 365 group, a team in Microsoft Teams, a dynamic group, or a security group. Inherits from directoryObject.
In the Graph, A team is a collection of channels. A channel represents a topic, and therefore a logical isolation of discussion, within a team.
A Group has property methods and Relationships: Channels, Calendars, Conversations, Planner, Sites, Owners, Members.
/me/joinedTeams
/beta/groups/{id}/team
/beta/groups/{id}/channels

21. OData Query Operations
OData V4 Query Language support includes
Name
Description
Example
$count
Retrieves the total count of matching resources.
/me/messages?$top=2&$count=true
$expand
Retrieves related resources.
/groups?$expand=members
$filter
Filters results (rows).
/users?$filter=startswith(givenName,'J')
$format
Returns the results in the specified media format.
/users?$format=json
$orderby
Orders results.
/users?$orderby=displayName desc
$search
Returns results based on search criteria. Currently supported on messages and person collections.
/me/messages?$search=pizza
$select
Filters properties (columns).
/users?$select=givenName,surname
$skip
Indexes into a result set. Also used by some APIs to implement paging and can be used together with $top to manually page results.
/me/messages?$skip=11
$skipToken
Retrieves the next page of results from result sets that span multiple pages. (Some APIs use $skip instead.)
/users?$skiptoken=X%
$top
Sets the page size of results.
/users?$top=2

22. OData Query Operations $filter
filter is used to limit results to a subset of a collection of entities
Support for $filter operators varies across Microsoft Graph APIs. The following logical operators are generally supported: 
equals (eq)
not equals (ne)
greater than (gt)
greater than or equals (ge)
less than (lt), less than or equals (le)
and (and)
or (or)
not (not)
Example:
List all Office 365 groups in an organization.
ODATA Notes:
Lambda Operators
OData defines two operators that evaluate a Boolean expression on a collection. Both must be prepended with a navigation path that identifies a collection. The argument of a lambda operator is a lambda variable name followed by a colon (:) and a Boolean expression that uses the lambda variable name to refer to properties of the related entities identified by the navigation path.
 any
The any operator applies a Boolean expression to each member of a collection and returns true if the expression is true for any member of the collection, otherwise it returns false. The any operator without an argument returns true if the collection is not empty. 
/groups?$filter=groupTypes/any(c:c+eq+'Unified')

23. Delta Query
Delta query enables discovery of changes in your Organization
Typically a GET Request with the delta function on the resource
The GET Response always includes a URL specified in a nextLink or deltaLink Response Header
Supported Resources:
Groups
Events ( in a calendar view or primary calendar )
Mail folders
Messages in a folder
Users
Drive Items
Personal contact folder
Personal contacts in a folder
ODATA Notes:
Lambda Operators
OData defines two operators that evaluate a Boolean expression on a collection. Both must be prepended with a navigation path that identifies a collection. The argument of a lambda operator is a lambda variable name followed by a colon (:) and a Boolean expression that uses the lambda variable name to refer to properties of the related entities identified by the navigation path.
 any
The any operator applies a Boolean expression to each member of a collection and returns true if the expression is true for any member of the collection, otherwise it returns false. The any operator without an argument returns true if the collection is not empty. 

24. Azure Functions
Intro and Demo

25. Links of note
App Registration Portal (v2):
Error Code analyzer:
JWT.io JWT Token Decoder:
Microsoft Graph Site:
Graph Explorer:
Microsoft GitHub:
Microsoft Graph community calls, first one on Dec 5th(