Microsoft Graph provides REST APIs for integrating with Intelligent Security Graph providers that enable your app to retrieve alerts, update alert lifecycle properties, and easily email an alert notification. This sample consists of a Python web application that invokes common Microsoft Graph security API calls, using the Requests HTTP library to call these Microsoft Graph APIs:
| API | Endpoint | |
|---|---|---|
| Get Alerts | /security/alerts | docs |
| Get user profile | /me | docs |
| Send mail | /me/microsoft.graph.sendMail | docs |
For additional information about this sample, see Get started with Microsoft Graph in a Python app.
To install and configure the samples, see the instructions in Installing the Python REST samples. Note that the samples in this repo require User.Read, Mail.Send, SecurityEvents.Read.All, and SecurityEvents.ReadWrite.All permissions.
After you've completed those steps and have received admin consent for your app, you'll be able to run the sample.py sample as covered below.
-
Provide your Administrator your Application Id and the Redirect URI that you used in the previous steps. The organization’s Admin (or other user authorized to grant consent for organizational resources) is required to grant consent to the application.
-
As the tenant Admin for your organization, open a browser window and craft the following URL in the address bar: https://login.microsoftonline.com/common/adminconsent?client_id=APPLICATION_ID&state=12345&redirect_uri=REDIRECT_URL Where APPLICATION_ID is the application ID and REDIRECT_URL is the Redirect URL values from the App V2 registration portal after clicking on your application to view its properties.
-
After logging in, the tenant Admin will be presented with a dialog like the following (depending on which permissions the application is requesting):
-
When the tenant Admin agrees to this dialog, he/she is granting consent for all users of their organization to this application.
- At the command prompt:
python sample.py - In your browser, navigate to http://localhost:5000
- Choose Sign in with Microsoft and authenticate with a Microsoft *.onmicrosoft.com identity.
By default, the top 5 alerts from each security API provider will be selected. But you can select to retrieve 1, 5, 10, or 20 alerts from each provider.
After you've selected your choices, click on Get alerts. A REST call will be sent to the Microsoft Graph, and a table with all the received alerts will be displayed below the form:
In the next section you'll see a "Manage Alerts" form where you can update lifecycle properties for a specific alert - by alert ID. Once the alert is updated the metadata of the original alert is displayed above the updated alert.
Finally, the app enables sending an email notification of the latest alert to be sent from the signed in user's email account that contains information about the alert including the alert ID that allows viewing the alert.
This sample uses delegated permissions to send mail on behalf of the currently authenticated user, identified as 'me' in Graph API calls. You can also send mail on behalf of other users, if you have administrator consent for the appropriate application permissions. See the Microsoft Graph permissions reference for more information about Graph's permission model.
These samples are open source, released under the MIT License. Issues (including feature requests and/or questions about this sample) and pull requests are welcome. If there's another Python sample you'd like to see for Microsoft Graph, we're interested in that feedback as well — please log an issue and let us know!
This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.
Your feedback is important to us. Connect with us on Stack Overflow. Tag your questions with [Microsoft-Graph-Security].
Documentation:
- Use the Microsoft Graph to integrate with Security API
- Microsoft Graph List alerts documentation
- Microsoft Graph permissions reference
Samples:
- Python authentication samples for Microsoft Graph
- Sending mail via Microsoft Graph from Python
- Working with paginated Microsoft Graph responses in Python
- Working with Graph open extensions in Python
Packages:
Copyright (c) 2018 Microsoft Corporation. All rights reserved.