Microsoft Secure Tech Accelerator
Apr 03 2024, 07:00 AM - 11:00 AM (PDT)
Microsoft Tech Community
IT Pros can now easily connect to Microsoft Graph Security with the PowerShell Module!
Published Apr 05 2019 09:51 AM 40.3K Views
Microsoft

We now have a new PowerShell module for the Microsoft Graph Security API that makes it easier for IT Pros to connect with the API from a PowerShell console. This module is available on the PowerShell gallery, thanks to a community contribution from the Microsoft Cloud Security’s Customer Experience Engineering team.

 

The Microsoft Graph Security API connects multiple security solutions to enable easier correlation of alerts, provide access to rich contextual information, simplify automations and investigations. This empowers organizations to quickly gain insights and take actions across their security products, while reducing the cost and complexity of building and maintaining multiple integrations. For further details on integrating with the Microsoft Graph Security API, learn about the API and access the schema.

 

Getting Started

Use this module to get access to security alerts and Secure Score information in your Azure Active Directory (Azure AD) tenant across different security products. Refer to the documentation for further details.

  1. Ensure you have PowerShell v5 or above (standard on Windows 10).
  2. Register your application for this PowerShell Module in Azure AD in user-delegated mode. As part of this,

    a. Select 'Add Platform' (under Platforms)

    b. Select 'Native Application' 

    c. Retain redirect URI as 'urn:ietf:wg:oauth:2.0:oob' - this is needed for desktop application redirect to work. 

  3. Configure permissions and be sure to add the SecurityEvents.ReadWrite.All permission to your application. Get your Azure AD tenant administrator to grant tenant administrator consent to your application. This is a one-time activity unless permissions change for the application.
  4. Open your PowerShell terminal as an administrator and install the module by running the Install-Module MicrosoftGraphSecurity command as shown in the diagram below:

*If this is your first time installing a module, you will be prompted to install the Nuget Package Provider.  

Install PowerShell ModuleInstall PowerShell Module

Authentication

You’ll need to authenticate before you can start getting and updating data from Microsoft Graph Security API. Authentication will be triggered upon initial data access or when authentication expires.

  1. Enter Get-GraphSecurityAlert
  2. Enter your username and the application ID (from the application registration process in getting started section) when prompted, as illustrated below. AuthenticationAuthentication
  3.  Enter your password when prompted. Upon successful authentication, the connection with Microsoft Graph Security API is established and you will get a list of alerts.

     

    User Scenarios

    This covers a representative set of scenarios. Refer to the documentation for the complete list of supported PowerShell command line switches associated with each command to tailor this for your scenario.

     

    Get latest alerts for Security Management

    You can get top alerts using this module by the command Get-GraphSecurityAlert -top 1. This returns the recent most alert received from each of the security products running in your Azure AD tenant supported by the Microsoft Graph Security API. This enables you to correlate recent suspicious patterns raised by different security products. Get alerts for security managementGet alerts for security management

    Investigate alerts associated with a user

    You can add multiple command line switches to get alerts across different security products filtered by user principal name, for example,

     

    Get-GraphSecurityAlert -userPrincipalName <enter the value> -severity medium -Verbose | select title, status, description, assignedTo, severity, userStates

     

    as illustrated below. This enables initial investigations where suspicious user activities reported by different security products can be plotted to understand where to plan the next level of investigations. Investigate alertsInvestigate alerts

    Customize get alerts to your scenario

    Run the Get-GraphSecurityAlert -<ctrlkey><space> command to get a list of all properties that you can filter to get your alerts as illustrated in the following diagram. Navigate to know supported types for each of these switches using your arrow keys. For example, in the diagram below we can see -Version switch expects a string type value. You can build your commands using different property values available to get alerts based on your scenario for customized security management and investigations. List of switches for Get-GraphSecurityAlertList of switches for Get-GraphSecurityAlert

    Update alerts for better security management

    You can update alerts by the Set-GraphSecurityAlert -id <enter the value> command. You can update the status of the alert to resolved as shown in this example below or even assign an alert for investigation or tag alerts to filter those as needed for better security management.

    Run the Set-GraphSecurityAlert -<ctrlkey><space> command to get a list of all properties that you can use to build your update alert command. Update alertUpdate alert

    Get Secure Score for understanding security posture

    You can also get secure score information by the Get-GraphSecuritySecureScore command as illustrated below to get details on the security posture of your organization and to determine what remediations are needed to improve the score over time.

    Run the Get-GraphSecuritySecureScore -<ctrlkey><space> command to get a list of all switches that you can use to build your secure score command. Get Secure ScoreGet Secure Score

    Closing

    Try out the new Microsoft Graph Security API PowerShell module and provide your feedback by filing a GitHub issue in the PowerShell module repo.    

 

11 Comments
Brass Contributor

Please provide details instructions how to register this thing Smiley Sad

Can you please provide more details on these steps including screen shots??

 

  1. Register your application for this PowerShell Module in Azure AD in user-delegated mode.
  2. Configure permissions and be sure to add the SecurityEvents.ReadWrite.All permission to your application. Get your Azure AD tenant administrator to grant tenant administrator consent to your application. This is a one-time activity unless permissions change for the application.

There are a plethora of articles on creating App Registrations in AAD out there. Try this one from the 30 days of Microsoft Graph series https://developer.microsoft.com/en-us/graph/blogs/30daysmsgraph-day-9-azure-ad-applications-on-v2-en...

This the key difference will be using the Delegated Permissions rather than App Permissions and the specific permissions you request 

Did all that and get "AADSTS50011: The reply url specified in the request does not match the reply urls configured for the application:"

That suggest that the reply url you make the request to AAD with doesn't match what you configured in the app registration

"That suggest that the reply url you make the request to AAD with doesn't match what you configured in the app registration" - I still don;t get it?? I made the request via a PowerShell console, where do I set the reply address there? Also teh app registration URL's I entered don;t matter do they as I want to use the PowerShell console?? Again, I don't understand how I configure an app registration for a PowerShell console.

The way the OAuth flow works providing a matching redirect uri is required, so yes, they matter a great deal in the auth flow, they don't actaully need to be working URLs, just valid URIs

 

Upon inspecting the script that is used under the hood you need to configure the redirect uri in the AAD Application as urn:ietf:wg:oauth:2.0:oob, as this has been hardcoded.

 

 

Ok, that seems to have done the trick here, although I can't add it as a web request I have been able to add that another way and test that it works. Really appreciate that. I'm going to blog about this and make it easier for people who aren't devs to follow! But again, thanks.

Microsoft

Apologize for the clarity issues and inconvenience caused with the application registration process. The links in the steps point to the Azure Active Directory official documentation that has screenshots, but then I observed that the native app registration step is missing in that documentation. To get unblocked with this as part of 'Register your application' step:

a. Select 'Add Platform' (under Platforms)

b. Select 'Native Application' 

c. Retain redirect URI as 'urn:ietf:wg:oauth:2.0:oob' - this is needed for desktop application redirect to work. 

Proceed with remaining registration steps.

 

We've updated the GitHub repo https://github.com/Microsoft/MicrosoftGraphSecurity to reflect these steps and I'll update the blogpost to include this step as well. Thanks!

 

 

@Preeti_Krishna  Here is my step by step blog post that will probably help others in getting this working - https://blog.ciaops.com/2019/04/17/using-interactive-powershell-to-access-the-microsoft-graph/

This looks like basic auth prompt. Am I correct?

Version history
Last update:
‎May 11 2021 02:03 PM
Updated by: