Getting notified by the Microsoft Graph with Webhooks. Elio Struyf U2U MVP September 9th, 2017

Transcription

1 Getting notified by the Microsoft Graph with Webhooks Elio Struyf U2U MVP September 9th, 2017

2

3

4 What are WebHooks?

5 What are WebHooks? Event driven notifications AKA callbacks from the web Universal model used by many services: GitHub, Slack, MailChimp, Pushing mechanism à asynchronous! Implemented in various Office 365 Services Microsoft Graph Connectors SharePoint

6 Where can you use them? SharePoint List Libraries Microsoft Graph Messages Events Contacts Conversations in groups OneDrive Microsoft Teams Connectors (incoming webhooks)

7 The good and the bad WebHooks are asynchronous mechanism Mechanism to respond on things that happen-ed Retry mechanism Tries to send the event a number of times within 4 hours window Requires some setup, but once done, it is easy to maintain

8

9 How to start using WebHooks?

10 By subscribing to a WebHook! 1. Create a subscription 4. MS Graph responds with subscription info Notification service

11 Important things about subscribing Subscribing: POST { } "changetype": "created,updated,deleted", "notificationurl": "Your notification service URL HTTPS is required", "expirationdatetime": "The subscription expiration date", "resource": "The resource to monitor" "clientstate": "String value for validation in your service"

12 Expiration times vary per resource type Mail, Calendar, Contacts, Group conversations 4230 minutes à 2,9375 days OneDrive minutes à 60 days

13 What resource? The resource is the endpoint you are interested in. Example: me/messages me/contacts me/events

14 Important things about subscribing The Microsoft Graph calls your notification service: POST - Respond with: Status: 200 Body: validationtoken Important: notification service needs to respond within 10 seconds

15 Important things about subscribing When validation is done, Microsoft Graph returns the subscription information { } "@odata.context":" "id":"6d4f0dbd ab-b9ad-16ba6e7341e2", "resource":"users/admin@estruyfdev2.onmicrosoft.com/mailfolders('inbox')/messages", "changetype":"created,updated,deleted", "clientstate":"demowebhooksubscription", "notificationurl":" "expirationdatetime":" t13:14:01.68z

16 Local development and testing: ngrok - Secure tunnels to localhost

17

18 Demo Subscribing to a WebHook

19 More about the notification service

20 Notification service details You choose the technology: Web API, Node.js, Respond in < seconds and with status: Accepted Retry mechanism à multiple retries over timespan of 4 hours Not for the validation process Receives minimal information You have to define the logic what you want to do per type of change

21 What can I expect from the notification?

22 This is what you will receive { } "value": [{ "subscriptionid":"64a28ad9-08c9-4e6c-b f1bbc408", "subscriptionexpirationdatetime":" t13:05: :00", "changetype":"created", "resource":"users/4b37b e-91db-4baf0b39baaa/messages/message-id" "resourcedata":{ "@odata.type":"#microsoft.graph.message", "@odata.id":"users/4b37b e-91db-4baf0b39baaa/messages/message-id", "@odata.etag":"w/\"cqaaabyaaadytakpqfg/q6i7mg8jzqy0aaayjst2\"", "id": message-id }, "clientstate":"demowebhooksubscription }]

23 How do I know what happened? { } "value": [{ "subscriptionid":"64a28ad9-08c9-4e6c-b f1bbc408", "subscriptionexpirationdatetime":" t13:05: :00", "changetype":"created", "resource":"users/4b37b e-91db-4baf0b39baaa/messages/message-id" "resourcedata":{ "@odata.type":"#microsoft.graph.message", "@odata.id":"users/4b37b e-91db-4baf0b39baaa/messages/message-id", "@odata.etag":"w/\"cqaaabyaaadytakpqfg/q6i7mg8jzqy0aaayjst2\"", "id": message-id }, "clientstate":"demowebhooksubscription }]

24 How do I know what happened? { } "value": [{ "subscriptionid":"64a28ad9-08c9-4e6c-b f1bbc408", "subscriptionexpirationdatetime":" t13:05: :00", "changetype":"created", "resource":"users/4b37b e-91db-4baf0b39baaa/messages/message-id" "resourcedata":{ "@odata.type":"#microsoft.graph.message", "@odata.id":"users/4b37b e-91db-4baf0b39baaa/messages/message-id", "@odata.etag":"w/\"cqaaabyaaadytakpqfg/q6i7mg8jzqy0aaayjst2\"", "id": message-id }, "clientstate":"demowebhooksubscription }]

25 How do I know what happened? { } "value": [{ "subscriptionid":"64a28ad9-08c9-4e6c-b f1bbc408", "subscriptionexpirationdatetime":" t13:05: :00", "changetype":"created", "resource":"users/4b37b e-91db-4baf0b39baaa/messages/message-id" "resourcedata":{ "@odata.type":"#microsoft.graph.message", "@odata.id":"users/4b37b e-91db-4baf0b39baaa/messages/message-id", "@odata.etag":"w/\"cqaaabyaaadytakpqfg/q6i7mg8jzqy0aaayjst2\"", "id": message-id }, "clientstate":"demowebhooksubscription }]

26 Retrieve the message information GET - value} Example: 4baf0b39bbbb/Messages/AAMkADM5N2VjMjU3LWQyM2YtNGQ4MS05NzZkLTZhN WFmMTcwNGFjYQBGAAAAAAA88VAhp3C7SbzAOB6K6turBwDyTAkPqFG- Q6I7Mg8jZqy0AAAAAAEMAADyTAkPqFG-Q6I7Mg8jZqy0AAAYIipBAAA=

27 You still need permissions in order to get started

28 Permissions per resource type / item Resouce type / item Contacts Conversations Events Messages Drive (User s OneDrive) Drives (SharePoint shared content and drives) Permission Contacts.Read Group.Read.All Calendars.Read Mail.Read Files.ReadWrite Files.ReadWrite.All

29

30 Creating your notification service

31

32

33

34 Get an access token via client ID and secret public getapponlyaccesstoken(): Promise<any> { return new Promise<any>((resolve, reject) => { const context = new AuthenticationContext(authority); context.acquiretokenwithclientcredentials(graphurl, clientid, secret, (err, tokenres) => { if (err) { reject(err); return; } }); }); resolve(tokenres.accesstoken);

35 A bit more secure, working with certificates Azure AD app registration Generate a certificate Acquiring a token via a certificate sets the appidacr value to 2 Application Authentication Context Class Reference 0 = Public client 1 = Identified by a client id and secret 2 = Identified by a certificate

36 Azure AD application manifest Store this in a separate file (privatekey.pem) Fingerprint is also require to get the access token

37

38

39 Get an access token via a certificate and private key with ADAL for JS public getapponlyaccesstoken(config: IConfig): Promise<any> { return new Promise((resolve, reject) => { const certificate = fs.readfilesync(path.join( dirname, 'privatekey.pem'), { encoding : 'utf8'}); const authcontext = new adal.authenticationcontext(authority); authcontext.acquiretokenwithclientcertificate(resource, clientid, certificate, fingerprint, (err, tokenres) => { if (err) { reject(err); return; } } }); }); resolve(tokenres.accesstoken);

40 The subscription APIs Retrieve subscription information GET - Update a subscription PATCH - Body: { "expirationdatetime": "New expiration date" } Delete a subscription DELETE -

41 When do I use the token? request.get(" { headers: { "content-type": "application/json", "Accept": "application/json", "Authorization": "Bearer " + token } }, (error, response, body) => { if (error) { console.log('error: There was an error creating the subscription.'); console.log(json.stringify(body)); return null; } return body; });

42 Demo Sample application

43 Think about renewing your subscriptions

44 Renewing subscriptions Check expiration date per notification your service receives Be careful: could be that you do not receive notifications for a certain period of time Timer triggered job which renews each known subscription Better option

45 Real life scenario

46 A real life setup and configuration 1. Subscribe and validate 3. Notify service 5. Respond with 200 HTTP triggered function 4. Put notification message on a queue 10. Update sub. 2. Store the subscription ID Timer triggered function 6. Trigger another Azure function that will do change handling Queue triggered function 9. Your business logic starts here

47 Demo Azure Functions + Webhooks

48 Brand new from MS Ignite Azure Functions & Microsoft Graph integration

49 Microsoft Graph integration in preview

50 Microsoft Graph integration in preview

51 Recap Azure AD Application Permission configuration and token retrieval Notification service has to respond in < seconds Retry mechanism 4 hour timespan with multiple retries Subscription expiration date varies per resource! Think about your renewal process

52 Questions?

53 Elio Struyf Lead trainer and Office Servers & Services MVP Azure / Office 365 / SharePoint

54 Resources Webhook documentation - Certificate creation process with makecert - Keycred GitHub - Node.js mail tracker Azure Function - Microsoft Graph Webhooks Sample for Node.js - Microsoft Graph ASP.NET Webhooks -