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.
Alert Status column not updating properly for "Resolved" MCAS or IPC alerts
Anyone noticed that the "Alert Status" column for MCAS and IPC (Identity Protection) alerts doesn't properly reflect within the API when resolving alerts in the MCAS or Identity Protection portal? Other products seem to work (WDATP, O365 Security & Compliance), however no matter what I do all my MCAS or IPC alerts come through to the API as "status = newAlert" even when I've resolved them all in the MCAS portal.
Receiving notification for deleted non series-master events
Hello, Is it possible to have an information about a deleted occurrence in a series, using the Graph API ? Or is the only solution to retrieve the series-master, fetch all occurrences and find the one who has been deleted by comparing the result with the data stored on our side? I've subscribed to change notifications and it works great if you get an update on an occurrence, e.g. a changed start time for an occurrence. In that case when you call /instances you correctly get an exception for that specific occurrence. On the other hand if you delete an occurrence there is no exception when you call /instances. The corresponding occurrence json object is simply removed from the JSON response in that case. This is not really handy when you get an update. How do you know which occurrence is to be removed? Only way seems to re-import everything. Do you have better suggestions? Thank you for your time.
Paging
To perform paging with the Graph API you are supposed to check for the: @odata:nextLink property in the results. This property will not appear if you set $top=12 or greater. $top=11 or smaller will return the nextLink property. You can test in the Graph Explorer. This will not return the nextLink property: https://graph.microsoft.com/v1.0/security/alerts?$top=12&$filter=createdDateTime%20ge%202018-08-02T22:05:00Z This will return the nextLink property: https://graph.microsoft.com/v1.0/security/alerts?$top=11&$filter=createdDateTime%20ge%202018-08-02T22:05:00Z
