Forum Widgets
Latest Discussions
Authorization and Microsoft Graph Security API
Understanding authorization when calling the Microsoft Graph Security API High-level summary: Security data accessible via the Microsoft Graph Security API is very sensitive and is protected using both permissions (aka scopes) and Azure AD (AAD) roles. Microsoft Graph Security API supports two types of application authorization: Application-level authorization, where there is no signed-in user (e.g. a SIEM scenario). Here the permissions/scopes granted to the application determine authorization. Note: this option can also support cases where Role-Based Access Control (aka RBAC) is managed by the application. User delegated authorization, where a user who is a member of the AAD tenant is signed in. Here the user must be a member of an AAD Limited Admin role - either Security Reader or Securty Administrator, in addition to the application having been granted the required permissions We distinguish between two types of client applications: the Microsoft Graph Explorer, and custom client applications. If calling from Graph Explorer: The AAD tenant admin must explicitly grant consent for the requested permissions to the Graph Explorer application The user must be a member of the Security Reader Limited Admin role in AAD (either Security Reader or Security Administrator) Note: Graph Explorer does not support application-level authorization If calling from a custom/your own application: The AAD tenant admin must explicitly grant consent to your application. This is required both for application-level authorization as well as for user delegated authorization If using user delegated authorization, the user must be a member of the Security Reader or Security Administrator Limited Admin role in AAD The following section contains a detailed technical explanation of using the Authorization mechanisms. Managing authorization in Microsoft Graph Security API client applications Security data provided via the Microsoft Graph Security API is sensitive and must be protected by appropriate authentication and authorization mechanisms. To register and create a client application that can access the Microsoft Graph Security API, the following steps must be performed: Who Action Application developer or owner Register application as an enterprise application Tenant Admin Grant permissions to the application Tenant Admin Assign Limited Administrator roles to users Application developer Sign-in as the user and use application to access Graph Security API To clarify: Application registration only defines which permissions the application needs in order to run. It does NOT grant these permissions to the application. The Azure AD tenant administrator MUST explicitly grant the permissions to the application. This MUST be done per tenant and performed every time the application permissions are changed in the application registration portal. Let’s assume we have: an application: App, two AAD tenants: T1 and T2, and two scopes, or permissions: P1 and P2. Application App registered to require permission P1 When users in tenant T1 get an AAD token for this application, the token does not contain any permissions (see next bullet) The AAD Admin of tenant T1 explicitly grants permissions to the application App. From this moment on, when users in tenant T1 get an AAD token for App, it will contain permission P1 When users in tenant T2 get an AAD token for application App, the token does not contain any permissions - because the admin of tenant T2 did not yet grant permissions to App. The procedure of granting permission must be performed per tenant and per application The application App has its registration changed to now require permissions P1 and P2 When users in tenant T1 get an AAD token for App, it only contains permission P1. Permissions granted to an application are recorded as snapshots of what was granted - they do not change automatically after the application registration (permission) changes The admin of tenant T2 grants permissions P1 and P2 to the application App. From this moment on, when users in tenant T2 get AAD token for App, the token will contain permissions P1 and P2 Note: for the same application (App), the AAD token for the application in tenant T1 and that for the application in tenant T2 contain different permissions, since the tenant admins each granted different permissions to the application (App) To make App work again in tenant T1, the admin of tenant T1 must explicitly grant permissions P1 and P2 to the application (App) Register an Application in v2.0 endpoint Reference link What you need: Application Name: a string used for the application name Redirect URL: where the authentication response from AAD is sent to. To begin with, you can use the test client web app homepage. Required Permissions: the permissions that your application requires to be able to call Microsoft Graph What you need to do: Go to https://apps.dev.microsoft.com/ and sign in. Note: there is no need to be a tenant admin. You will be redirected to “My applications” list Click the “Add an app” button, and enter an Application Name to create a new application It will navigate to the registration page for the new application. Click “Add Platform”, choose “Web”. In the Redirect URL, enter the Redirect URL. Go to section “Microsoft Graph Permissions” and under “Delegated Permissions”, click the “Add” button. A popup dialog appears; choose required permissions (aka scopes). See this document for detailed scopes. The Microsoft Graph Security API requires “SecurityEvents.Read.All” scope for GET queries, and “SecurityEvents.ReadWrite.All” scope for PATCH/POST queries. Scroll down to the bottom of the page and click on the “Save” button What to save for future steps: Application Id Redirect URL List of required permissions Granting Permissions to an Application Application registration only defines which permission the application requires - it does not grant these permissions to the application. An Azure AD tenant administrator must explicitly grant these permissions by making a call to the admin consent endpoint. Reference link What you need: Application Id: the application ID from application registration portal Redirect URL: the string you set in the application registration portal for authentication response What you need to do: In a text editor, create following URL string: https://login.microsoftonline.com/common/adminconsent?client_id=<Application Id>&state=12345&redirect_uri=<Redirect URL> In a web browser, navigate to this URL, and sign-in as a tenant administrator; the popup dialog shows the list of permission the application requires, as specified in the application registration portal. Click “OK” to grant the application these permissions. Note: this step grants permissions to the application - not to users. This means that all users belonging to the AAD tenant that using this application will be granted these permissions - even non-admin users Assigning AAD roles to users Once an application is granted permissions, everyone with access to the application (i.e. members of the AAD tenant) will receive the granted permissions. To further protect sensitive security data, the Microsoft Graph Security API also requires users be assigned the Azure AD Security Reader role. Reference links: admin role assign roles What you need: A tenant admin must perform this step What you need to do: The admin must: Sign-in to azure portal (http://portal.azure.com) In the menu, select Azure Active Directory > Users Select the name of the desired user Select Manage > Directory role Select “Limited administrator”, check the checkbox “Security reader” Click on the “Save” button to save the change Create an authentication code Reference link What you need: Application ID: the application ID from application registration portal Redirect URL: where the authentication response from AAD is sent to. To begin, you can use http://localhost or the test client web app homepage Application Key (optional): the key of the application, used when developing an application that will use application-only authentication code (i.e. will not support user delegated authentication) What you need to do: There are code samples demonstrating on how to get authentication tokens for in various kinds of applications, authentication libraries are also provided. Type of applications Authentication Library Desktop apps - iOS MSAL.framework: Microsoft Authentication Library Preview for iOS Desktop apps - Android Microsoft Authentication Library (MSAL) Desktop apps - .Net Microsoft Authentication Library (MSAL) Web apps - JavaScript SPA Microsoft Authentication Library for JavaScript Preview Web apps - .Net Web Server OpenIdConnection, Cookies, SystemWeb Web apps - NodeJS Web App If the applications do not use any of the existing libraries, please follow this doc Get a code from AAD. The query to call contains parameter for Application ID, Redirect URl and required permissions. Use the code to get an access token If you use OpenId Connect library, please see this doc and call app.UseOpenIdConnectAuthentication() Note: In the library, when requesting user delegated authentication tokens, the parameter for the library is “Requested Scopes”. Use “User.Read” for this parameter instead of using whatever the registered application requires. The “Requested Scopes” parameter does NOT affect the permissions contained in the returned authentication tokens, since these are determined by the permissions that the tenant admin granted the application. Using .Net MSAL library as example: var accessToken = (await client.AcquireTokenAsync(scopes)).AccessToken; Note that scopes in above example should be minimum permission such as “User.Read”. However the returned access token can contains scopes such as “User.Read.All” or “User.ReadWrite.All” which were granted by tenant admin for current user tenant. What You receive: A token (string) is returned by AAD that contains your authentication info and the permissions required by the application. Assign this token to the HTTP header as a bearer token, as in the code below: request.Headers.Authorization = new AuthenticationHeaderValue("bearer", accessToken); Microsoft Graph will validate the information contained in this token and grant, or reject, access. To view claims contained in the returned token, use NuGet library System.IdentityModel.Tokens.Jwt. JwtSecurityTokenHandler tokenHandler = new JwtSecurityTokenHandler(); var securityToken = tokenHandler.ReadToken(accessToken) as JwtSecurityToken; In case you encounter an Authentication failure The response from Microsoft Graph contains a header called client-request-id, which is a GUID. If access is denied, please specify this GUID when seeking support, so we can help investigate the cause of this authentication failure.
Retrieve alerts for a certain date (range)?
Is it possible to retrieve alerts for a certain date? My script gets a lot of alerts (for example 'Anonymous IP address' alerts), so I want to limit the amount of data. I tested the filtering using the Graph Explorer: (https://developer.microsoft.com/en-us/graph/graph-explorer) Example 1) https://graph.microsoft.com/v1.0/security/alerts?$filter=Severity eq 'High' This is working fine; the returned data is limited to High severity alerts. Example 2) I changed #1 to https://graph.microsoft.com/v1.0/security/alerts?$filter=eventDateTime eq '2019-07-20T15:58:31Z' In know that there is an item in the example data set that should match, but the query failed (Invalid filter clause). So I am looking for another way to get the most recent alert (of just today or date range), for example with something like a sort of 'like' operator: $filter=eventDateTime like '2019-07-23' Ofcource I can filter afterwards, but retrieving less data would better to speed up the processing of the alerts. Any suggestions? Thanks.Use the new NextJS sample to integrate with Microsoft Graph Security
We are happy to announce a new NextJS sample, contributed by Olli Vanhoja, Head of Security - ZEIT. Olli is also a member of the judging panel for the ongoing Microsoft Graph Security Hackathon. The NextJS sample is a new addition to the existing set of Microsoft Graph Security samples. Use this sample to build your own integrations with Microsoft Graph Security. This sample uses the Microsoft Graph Security JavaScript SDK to create a server-less Next.js application. The application authenticates with Microsoft Azure Active Directory (AAD) and retrieves security alerts using the Microsoft Graph Security API. This sample is built around the ZEIT Now deployment model, as it utilizes Now builders and deployment routes, but it is portable to any server-less environment. Try the Microsoft Graph Security samples and please share your feedback by filing a GitHub issue or by engaging on the Microsoft Graph Security API tech community or StackOverflow.
401 Unauthorized when accessing /messages api using client credentials grant flow
I have a mailbox in on prem exchange server (which is in hybrid mode) abc@onprem.com and i am trying to access this via graph api (/messages). This works perfectly if i do this in graph explorer, but fails when i do via postman. Required application permission is given in Azure app registration portal. Implementation/postman uses grant_type as client_credentials with certificate and this works perfectly for cloud users. Response of API { 'error': { 'innerError': { 'date': '2019-02-28T14:17:45', 'request-id': '6a85f8c3-4e13-4cf0-84b2-ddc934241afd' }, 'message': '', 'code': 'UnknownError' }} IIS Logs Added some headers like www-authenticate for logging and found that below is the error in IIS Log for on prem. 2019-03-04 04:05:13 172.31.10.98 GET /api/V2.0/Users('abc@onprem.com')/Messages &CorrelationID=;&cafeReqId=2823c302-3c84-4847-b586-accced4b6dd5; 443 - 20.190.145.177 PostmanRuntime/7.6.0 - 401 0 0 332 Bearer+eyJ0 blah blah.....blah blah.....hSd mail.onprem.com - - - Bearer+client_id="00000002-0000-0ff1-ce00-000000000000",+token_types="app_asserted_user_v1+service_asserted_app_v1",+authorization_uri="https://login.windows.net/common/oauth2/authorize",+error="invalid_token" 2000001;reason="This+token+profile+'V1S2SAppOnly'+is+not+applicable+for+the+current+protocol.";error_category="invalid_token" What would be reason for this authentication failure ? Is there something worng with client credentials grant flow (in graph explorer as we sign in and do query auth flow might not be client credentials) ? For graph explorer calls i see cs-username like `S-1-5-21-1392771109-4043059535-3934338706-1147` in IIS Log which doesn't come for postman calls. We are using self signed certificate on exchange server , can this lead to this issue ? If so wondering how everything is working from graph explorer.How to authenticate a script without user interaction?
Hi, I want to get started with the Graph API. I am interested in automation, so all the 'Getting Started' documentation is not helpful, because it relies on user interaction during the authentication. I registered an app and granted it the User.Read.All API permission (type:application) and I created a client secret / application password. Now I'm stuck. Does anybody have a sample Python script that authenticates? And maybe even gets a list of users?
