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

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

Louis Simonetti Microsoft Certified Professional in O365 and Azure Technology Architect Specialist Runner Proud Husband and Father @lousimonetti https://medium.com/@lousimonetti https://github.com/lousimonetti

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

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

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 https://graph.microsoft.com /{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.

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 https://developer.microsoft.com/en-us/graph/docs/concepts/permissions_reference

V1 – V2 V1: GET https://login.microsoftonline.com/common/oauth2/authorize?client_id=2d4d11a2-f814-46a7-890a-274a72a7309e &resource=https%3A%2F%2Fgraph.windows.net%2F... Account-agnostic Singular Application ID Scopes > Resources Dynamic of Statically applied permissions scopes V2: GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=2d4d11a2-f814-46a7-890a-274a72a7309e &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. https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-protocols https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-v2-compare

Register an Application (v2) Go to the New Portal: https://apps.dev.Microsoft.com Add a New application Define App Type, Endpoint and Required Scopes

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.

Authentication (App-Only) App Only requires Admin Consent Process https://login.microsoftonline.com/{tenant}/adminconsent ?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-4f1264799865 &scope=https%3A%2F%2Fgraph.microsoft.com%2F.default &client_secret=qWgdYAmab0YSkuL1qKv5bPX &grant_type=client_credentials "https://login.microsoftonline.com/common/adminconsent?client_id=$($clientId)a&state=demo&redirect_uri=$($redirecturi)"; $token_uri="https://login.microsoftonline.com/$($tenantId)/oauth2/v2.0/token"; $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

DEMO Authentication and Authorization

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/1.1200 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/1.1204 No Content Request DELETE https://graph.microsoft.com/v1.0/users/{upn or id} Response HTTP/1.1204 No Content

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) https://graph.microsoft.com/v1.0/groups?$filter=groupTypes/ any(c:c+eq+'Unified’) Request (All Groups) https://graph.microsoft.com/v1.0/groups?$orderby=displayName GET Request: https://graph.microsoft.com/v1.0/groups/{id}/owners HTTP/1.1 200 OK Content-type:application/json Content-length:55 { "value":[{ "@odata.type": "#microsoft.graph.user”}]} POST Request: https://graph.microsoft.com/v1.0/groups/{id}/owners/$ref Content-type:application/json Content-length:30 {"@odata.id":"https://graph.microsoft.com/v1.0/users/{id}"} GET Request: https://graph.microsoft.com/v1.0/groups/{id}/members HTTP/1.1200OKContent-type:application/jsonContent-length:55{"value":[{"id":"id-value"}]} POST Request: https://graph.microsoft.com/v1.0/groups/{id}/members/$ref Content-type:application/json Content-length:30 {"@odata.id":"https://graph.microsoft.com/v1.0/directoryObjects/{id}"} Request DELETE https://graph.microsoft.com/v1.0/groups/{id} Response HTTP/1.1204 No Content

Licensing Management List SubscribedSkus Assign or Remove Licenses Tasks Request TYPE GET POST Request https://graph.microsoft.com/beta/subscribedSkus Response HTTP/1.1200 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: https://graph.microsoft.com/beta/me/assignLicense Content-type: application/json {"addLicenses": [{"disabledPlans": […], "skuId": ”GUID"}, {"disabledPlans": […], "skuId": ”GUID"}], "removeLicenses":[]} Remove Request: https://graph.microsoft.com/beta/me/assignLicense Content-type: application/json Content-length:185 {"addLicenses":[],"removeLicenses":[”GUID-1",”GUID-2”, …]}

DEMO 2 Users and Groups

 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 https://graph.microsoft.com/ {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 https://developer.microsoft.com/en-us/graph/docs/api-reference/v1.0/resources/sharepoint

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: https://azure.microsoft.com/documentation/articles/active-directory-assign-admin-roles/ 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 : https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/resources/privilegedidentitymanagement_root *Add Member POST https://graph.microsoft.com/beta/directoryRoles/{id}/members Content-type:application/json Content-length:30 {"directoryObject": { ”id”: ”value" } } https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/resources/directoryrole

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 https://developer.microsoft.com/en-us/graph/docs/api-reference/beta/api/privilegedoperationevent_list

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

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%274453707402000100000017... $top Sets the page size of results. /users?$top=2 http://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part2-url-conventions/odata-v4.0-errata03-os-part2-url-conventions-complete.html#_Toc453752356http://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part2-url-conventions/odata-v4.0-errata03-os-part2-url-conventions-complete.html#_Toc453752356 https://developer.microsoft.com/en-us/graph/docs/concepts/query_parameters

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. http://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part2-url-conventions/odata-v4.0-errata03-os-part2-url-conventions-complete.html#_Toc453752356http://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part2-url-conventions/odata-v4.0-errata03-os-part2-url-conventions-complete.html#_Toc453752356 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. 5.1.1.10.1 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') https://developer.microsoft.com/en-us/graph/docs/concepts/query_parameters

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 http://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part2-url-conventions/odata-v4.0-errata03-os-part2-url-conventions-complete.html#_Toc453752356http://docs.oasis-open.org/odata/odata/v4.0/errata03/os/complete/part2-url-conventions/odata-v4.0-errata03-os-part2-url-conventions-complete.html#_Toc453752356 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. 5.1.1.10.1 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.  https://developer.microsoft.com/en-us/graph/docs/concepts/query_parameters

Azure Functions Intro and Demo

Links of note App Registration Portal (v2): http://apps.dev.Microsoft.com Error Code analyzer: https://apps.dev.microsoft.com/portal/tools/errors JWT.io JWT Token Decoder: https://jwt.io Microsoft Graph Site: https://graph.microsoft.com Graph Explorer: https://developer.microsoft.com/en-us/graph/graph-explorer Microsoft GitHub: https://github.com/microsoftgraph Microsoft Graph community calls, first one on Dec 5th(http://aka.ms/MicrosoftGraphCall)