Apr 18 2018 10:51 AM - edited May 14 2018 02:03 PM
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:
We distinguish between two types of client applications: the Microsoft Graph Explorer, and custom client applications.
If calling from Graph Explorer:
If calling from a custom/your own application:
The following section contains a detailed technical explanation of using the Authorization mechanisms.
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:
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)
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
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.
Application Id: the application ID from application registration portal
Redirect URL: the string you set in the application registration portal for authentication response
In a text editor, create following URL string:
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
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
A tenant admin must perform this step
The admin must:
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)
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 |
MSAL.framework: Microsoft Authentication Library Preview for iOS |
|
OpenIdConnection, Cookies, SystemWeb |
|
|
If the applications do not use any of the existing libraries, please follow this doc
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.
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;
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.
Oct 15 2018 09:46 AM - edited Oct 15 2018 09:57 AM
Hi,
I'm trying to access the secure score endpoint via my app. The app and user have the required permissions as per this post, however, I am still getting a 403 when attempting to call any of the security endpoints. The app is able to successfully call other graph endpoints.
Is it possible to get more info about exactly why access is denied? The response body just states that the token or user do not have required permissions. An example request id is: "b58137f1-37ea-40fb-93bb-20497b922df6".
The same user is able to make requests to the endpoint just fine using the Graph Explorer app. I have also compared the token permissions in the scp claim and given my app (and token) identical permissions but still, I get 403!
Have been struggling with this for some time now. Seemingly everything is configured correctly. Anything to shed some more light on exactly what is required would be greatly appreciated.
Thanks,
Matt
Oct 15 2018 11:48 AM
Hi Matt,
To access SecureScore, you need to meet the product's Role-Based Access Control (RBAC) - in this case to belong to one of the groups listed below - broken out into Read access and Write access:
(for convenience, listing both required Graph Scopes and AAD Roles):
Read:
Scopes
Roles
Write (Patch):
Scopes:
Roles:
Hope this helps - great if you could confirm after applying the above
Michael
Oct 15 2018 03:08 PM - edited Oct 16 2018 01:10 AM
Hi Michale,
Thanks very much for coming back to me.
So the user and the app appear to have the appropriate roles/permissions. I even went so far as granting the app all possible permissions and giving the user all possible roles. I have created new test users and new app registrations and tried many other things. Still, I'm getting a 403.
This makes me think it's somehow not a problem with permissions but some other configuration issue with the app, ad or tenant. I'm using our companies sandbox tenant, so other engineers are always playing with the config. I plan on trying it out on a different tenant once one becomes available to me.
Are you aware of any configuration other than permissions or roles which might cause a 403 response from this endpoint?
Thanks again.
Matt
Edit 16 Oct '18:
So I have tried another tenant and am facing the same issue...
I think it must be a problem with the configuration of my app since all the users I have tried have access to the secure score via other means (Web portal and Graph explorer app).
The app is a JS SPA using the MSAL-Angular library and the implicit auth flow. The MSAL config is as follows:
consentScopes: [
'User.Read',
'SecurityEvents.Read.All'
],
protectedResourceMap: [
[
'https://graph.microsoft.com/beta/organization',
['User.Read']
],
[
'https://graph.microsoft.com/beta/security/secureScores',
['SecurityEvents.Read.All']
]
]
I have tried many other configurations but this is the simplest I believe should work.
Any ideas what I might be doing wrong?
Thanks again.
Matt
Dec 06 2018 08:35 PM
Hi Brandon,
Yes, App-only AuthNZ is also supported - and covered in the documentation - please note that this approach assumes that Role Based Access Control (RBAC) will be implemented by the calling application.
The Graph Security API GitHub code samples include a C# Auth Helper App that will let you test and see the contents of the Auth token - both for User/Delegated or for App-only (different tabs).
Also make sure you specify the required scopes for App-Only during app registration
Hope this helps
Michael
Dec 08 2018 03:45 PM
Michael,
I appreciate your reply! I was still not able to find a code example of app authenticate. All of the listed example only contain code for user it seems unless I keep over looking something. I might just be misunderstanding something due to inexperience but I appreciate your help thus far
Dec 10 2018 09:20 AM
Hi Brendon,
You can download the Auth Helper sample code here:
https://github.com/microsoftgraph/Graph-Security-API-Auth-Sample
When you compile and run the application, you'll see three tabs in the app's UI:
Select the second, and provide the AppId and AppKey (Secret) - after verifying that you defined App-Only permissions in the app registration (http://apps.dev.microsoft.com)
I hope this solves the issue for you
Michael
Nov 26 2019 06:36 AM
Hey @Michael Shalev, thank you for the insight on api authorizations!
Are there any security implications to be wary of when granting application-level authorization for an application? or is this merely the same authorization level as the delegated privileges but without the need for a user sign-in?
Nov 27 2019 11:19 AM
@jyisas There are significant security considerations when using application auth, specifically: this will bypass role based access control (RBAC) enforcement which is defined and enforced at user level, i.e when User/Delegated auth mode is used.
The recommended practice when using app-level auth would be to enforce necessary access control in the app calling the Graph Security API
Mar 31 2020 04:02 AM
It's unfortunate that there is no option to use the "Security Operator" role just for the implementation use cases where there is only the requirement to read and update (e.g. close) MS Graph Security API security alerts under a delegated permissions scenario. In that case the only option available seems to require the "Security Admin" role to be assigned. At the same time there are also challenges with monitoring and alerting options if we use app-level auth.