Microsoft Secure Tech Accelerator
Apr 03 2024, 07:00 AM - 11:00 AM (PDT)
Microsoft Tech Community
Automate and manage Azure AD tasks at scale with the Microsoft Graph PowerShell SDK
Published Jun 02 2021 09:00 AM 118K Views

Howdy folks,

 

We’ve heard from customers that having a great PowerShell experience is critical in helping manage your identity needs at scale from automating tasks through scripts to managing users in bulk. Today we wanted to share the investments we’re making with PowerShell that will help you save time with administrative tasks. These will be focused on, but not limited to, high-use scenarios such as user, group, and application management and role-based access controls (RBAC).

 

If you’re using the Azure AD PowerShell or MSOnline PowerShell modules to manage Azure AD, we encourage you to try the Microsoft Graph PowerShell SDK. The Microsoft Graph PowerShell SDK is where all our current and future investments are being made.

 

Derrick Kimani, a program manager in the Identity Division drives our PowerShell initiatives, and his guest blog below will take you through our current and future investments in PowerShell. As always, please share your feedback in the comments below.

 

Best Regards,

Alex Simons (Twitter: @Alex_A_Simons)

Corporate Vice President Program Management

Microsoft Identity Division

 

 --------------------------------------------------------

 

Hi everyone – 

 

I’m excited to share our investments in PowerShell that make it easier to manage your identity needs and critical tasks. Today, thousands of customers use PowerShell for a wide range of tasks from monitoring and tracking data changes to managing cloud applications at scale.

 

Manage Azure AD with the Microsoft Graph PowerShell SDK

Last year, we announced end of support plans for Azure Active Directory (Azure AD) Graph API in favor of Microsoft Graph. Microsoft Graph offers a single endpoint to access Microsoft 365 data. The Microsoft Graph includes all the previous Azure AD APIs and APIs from several other Microsoft services like Teams, Exchange, Intune, and more. Since the announcement last year, we’ve added more Azure AD APIs in Microsoft Graph such as: Advanced Query Support, Device Management, and Cloud communication.

 

The Microsoft Graph PowerShell SDK acts as an API wrapper for the Microsoft Graph API, exposing the entire API set for use in PowerShell. Over the coming months, we will provide usability enhancements, documentation, examples, and additional improvements to the Microsoft Graph PowerShell SDK, where we will create compound commands that map more closely to the specific tasks and scenarios admins would like to automate.

 

As Alex stated above, the Microsoft Graph PowerShell SDK is where all our current and future investments are being made and is the best choice for future-proofing your scripts. With broad Microsoft 365 support, full cross-platform support, and an up-to-date release cycle with the Microsoft Graph API, the Microsoft Graph PowerShell SDK will become our recommended module for administering Azure AD. It is open source and available cross-platform on PowerShell 7 and above.  

 

Our plan with PowerShell moving forward is as follows:
  • As new Identity APIs are added to Microsoft Graph, they will continue to be made available through the Microsoft Graph PowerShell SDK.
  • We will provide usability enhancements, documentation, examples, and additional improvements to the Microsoft Graph PowerShell SDK on an ongoing basis.
  • Our Identity-related investments in the Microsoft Graph PowerShell SDK will be focused on, but not limited to, high-use scenarios such as user, group, and application management and role-based access controls (RBAC).

Our eventual goal is that every Azure AD feature has an API in Microsoft Graph so you can administer Azure AD through the Microsoft Graph API or Microsoft Graph PowerShell SDK. If you’re using other PowerShell modules to manage Azure AD, such as the Azure AD PowerShell or MSOL, we encourage you to start using Microsoft Graph PowerShell SDK.

 

While many customers use the Azure AD PowerShell to manage users, groups, applications, and service principals, we have stopped investing in new features for this module, and it will not be updated to work with PowerShell 7.

 

To get started using the Microsoft Graph PowerShell SDK, review our updated documentation and check out the GitHub wiki to find information on Microsoft Graph-based modules. We will continue to enhance samples and documentation in the coming months. The Microsoft Graph PowerShell SDK is open-source and we encourage the PowerShell scripting community to contribute to improving our identity modules. Anyone in the identity community is welcome to deliver improvements through the same open-source contribution process used by the API engineering teams.

 

Azure PowerShell Module & CLI

In the longer term, we’re also exploring how to align the Microsoft Graph PowerShell SDK with the Azure PowerShell Module and CLI to deliver a consistent and unified terminal experience.

The Azure PowerShell modules are a set of cmdlets for managing Azure resources directly from the PowerShell command line, which can include tasks such as provisioning virtual machines, databases, and networks. While we recommend that you use the Microsoft Graph PowerShell SDK for your Azure AD needs, the Azure PowerShell Module does support a small set of cmdlets to help manage identity features such as AzADUser, AzADGroup and AzADApplication. These modules are supported on Windows PowerShell 5.1 and PowerShell 7.x and above.

 

We’d love to hear your feedback or suggestions on how we can improve Azure AD management within Microsoft Graph PowerShell SDK. If you have feedback or suggestions for any new modules, be sure to comment below. 

 

Best,

Derrick Kimani 

Program Manager

Microsoft Identity Division

 

 

Learn more about Microsoft identity:

25 Comments
Iron Contributor

Thank you for taking the time to publish and clarify the current roadmap.

 

Specifically in regards to users of the AzureAD module (clarify if I am wrong):

  1. Their stated roadmap is to migrate to the Microsoft Graph SDK, there will not be an equivalent "AzureAD" module that will be rewritten to use MS Graph SDK
  2. Some commandlets in Az are expected to be the "friendly" cmdlets, however today as far as I can tell these still use the legacy AzureAD Graph API, will these be updated to use MS Graph SDK? These will also be very limited compared to what is currently offered in the AzureAD module.
  3. There will be no other development of "friendly" cmdlets, the Graph SDK will primarily be the autogenerated cmdlets, with guidance coming in the form of documentation and examples.

My concern is that the Graph SDK has been stated to be just that, a software SDK for powershell developers to develop against the graph SDK. This leaves "normal" administrators in a difficult position. Is Microsoft expecting that the "Az" small friendly command set is all that will be invested in making the SDK available to bridge the gap for these administrators?

 

If so, then is Microsoft expecting there to be community led efforts to build modules that translate the SDK direct calls into more "friendly" commands normally associated with the AzureAD module? If so then that may be a major problem, as a standard AzureAD administrator-level user will look at the new graph SDK commands, consider them extremely difficult to use or unintuitive, and stay on the AzureAD module or bail entirely to use a different solution.

@JGrote  #3 is incorrect.  The Identity engineering team is committed to continuing to invest in improving the "friendliness" of cmdlets available for managing AzureAD through the MS Graph SDK module. We want to ensure the community can participate and contribute in this effort, but that doesn't preclude our continued ownership for the end user experience.

 

I share your concern that if we don't do a good job here of making the MS Graph SDK module an experience at least as good as the AzureAD module (and hopefully better), we're doing a disservice to our customers.  I don't think we get to great overnight, but I believe we have a sustainable framework in place for continuous improvement.

Iron Contributor

@RicLewisIdentity Thank you for the response!

Since the MS Graph SDK modules are generally autogenerated with AutoRest, will there be a roadmap or vision for this plan? For instance, will these be enhancing the autorest commands with a bunch of extra "calculated parameters" that do friendlier things, or will it be a new "overlay" set of commands that use the "raw" commands on the backend? Will these be bundled into separate modules (e.g. Microsoft.Graph.AzureADFriendlyCommands) to deliniate their "bespoke" crafting so people know what's been "made with love" vs what's a raw SDK API autogeneration?

A follow-up blog post on what to at least tacitly expect here would be welcome, so the community can provide feedback. Again thank you for all the hard work that the identity team performs, the graph Powershell SDK has been very useful to provide a solid type system against which to perform graph tasks.

Copper Contributor

Thank you very much for provide this information about the roadmap.

Do you think as a consequence of moving to Graph API, we will have the option to restrict powershell access?

Thank you

 

 

Copper Contributor

I am trying to convert my MSOL and AZUREAD scripts to Microsoft.Graph and most cannot be replaced as the functionality doesn't exist. For example, is there a way to get a user's password expiry date from Microsoft.Graph ?

Microsoft

For instance, will these be enhancing the autorest commands with a bunch of extra "calculated parameters" that do friendlier things, or will it be a new "overlay" set of commands that use the "raw" commands on the backend?

 

@JGrote  we're still developing the practices for how to structure this, but if you're interested in seeing and contributing to the work-in-progress, take a look at one example, the Azure AD entitlement management cmdlets we're working on, in the folder https://github.com/microsoftgraph/msgraph-sdk-powershell/tree/dev/src/Identity.Governance/Identity.G...  These for entitlement management will be included into a future version of the Microsoft.Graph.Identity.Governance module, and I expect that customizations to other feature's cmdlets would ship in the same module as the auto-generated cmdlets.  These enhancements to the auto-generated cmdlets includes both

For example, there is also now an ask to have a cmdlet to show the available access packages and who the approvers are which could then exported to CSV.  

Iron Contributor

@Mark Wahl Thank you Mark for the detail. May I suggest that, if at least the "bespoke" modules are not going to be done, that the documentation at least have an index of "non-direct-REST" commands, since the sheer list of commands will be overwhelming for a new user and they'll probably want to zone in on the "friendly" commands at first.

 

Thanks again for all your hard work.

Brass Contributor

While I understand your intention of focusing your efforts on the Microsoft Graph PowerShell SDK, would it be too much to ask you to spend some time merging Pull requests for the Azure AD module when the PRs are coming from the community? Pull requests · Azure/azure-docs-powershell-azuread (github.com)

 

My understanding is that we will continue using both the AzureAD and the MSOnline modules for a little while, and any improvement made to their documentation should help people all around the globe. 

Brass Contributor

Great update :)


Litle tip on how to display all the 6578:stareyes: functions:

get-command -Module microsoft.graph.*
Steel Contributor

Hmm... it's quite frustrating that you never quite finish the job?

  • We all started out writing PowerShell for the MSOL modules, and some stuff *still* requires that (like managing MFA)
  • Then we all switched to the Azure AD modules, then the Azure AD modules which use MS Graph (like Get-AzureADMSGroup etc)
  • Now we all have to switch to dedicated MS Graph modules...

Since each of these changes involves rewriting automation scripts, how long will it be until you decide to change everything again? My colleagues and I are quite tired of updating scripts to keep existing functionality when the previous modules work just fine...

Bronze Contributor

Perhaps this requires some more studying, but at the moment I'm getting an impression that the modules/CMDLets will be gone. I only could guess the reasons for this: Either those has been too hard to keep up to date by you, those has caused too much load on your cloud, or something else like Python has bites PS from left and right.

 

Like @ChrisAtMaf mentioned earlier, we - as customers - highly appreciate continuity on the management tools. But can this really be a news to you?

 

It is also interesting to know, how the support would be in a future. But also what is its readiness to replace other modules. Do you have a project page which list the CMDLets which are already applied, and which still requires old modules? Or will the future be so, that some work can be done by the Graph SDK, but for few issues we still need to carry the old modules with us.

Iron Contributor

Can you please reconcile these incongruent statements:
"Last year, we announced end of support plans for Azure Active Directory (Azure AD) Graph API in favor of Microsoft Graph."

"While we recommend that you use the Microsoft Graph PowerShell SDK for your Azure AD needs, the Azure PowerShell Module does support a small set of cmdlets to help manage identity features such as AzADUser, AzADGroup and AzADApplication."

Get-AzAdUser uses the legacy AzureAD API, you can see this if you turn on debugging stream output, you can clearly see it makes graph.windows.net calls. Will the AzAD cmdlets be updated to graph.microsoft.com?

Iron Contributor

Building on @ChrisAtMaf 's comment above—how does your team plan to avoid history repeating itself with this endeavor quickly losing momentum and getting abandoned, where for example the Graph PowerShell SDK plateaus at ~90% of the functionality of the AzureAD module, and the AzureAD module with ~90% of the functionality of the MSOL module, leaving us in a position where we require all three modules long-term? The AzureAD module also had good intentions to replace the MSOL module, but that momentum died very quickly.

 

The AzureAD module has been neglected for quite some time, while all along still being considered the current and future module, with no comment on PowerShell 7 support, new releases but the release notes page now one year out of date despite multiple people flagging that issue and receiving acknowledgement, etc. Just being put on life support long before this post that acknowledges its end-of-life, and us being left with a poorly supported module for over a year with no ownership from Microsoft.

 

There also seems to be significant issues in how the Graph PowerShell SDK is structured, with some native API functionality being broken in the PowerShell SDK due to "translation layer" issues, and subsequent finger-pointing between teams for over six months. Example: Missing cmdlet: Remove-MgGroupMember. Curious how these underlying issues plan to be addressed—as this is exactly the kind of thing that would lead to that future where the Graph PowerShell SDK plateaus at ~90% and has to get put out of its misery a few years later.

Brass Contributor

Couldn't agree more with @ians-uleth comments. 

Microsoft

@ChrisAtMaf  @JGrote  @Petri X @ians-uleth @chriswest-jnctn We acknowledge the inconsistencies across our PowerShell offering. Our platform has gone through significant changes, all aimed at offering more to our customers. With the advent of MS graph, we have invested more in customer experience. Currently, there is an ongoing effort to migrate the missing cmdlets and functionality in MSOL and AAD onto the MS graph PowerShell Module. For AzAD cmdlets they will be updated to work with MS Graph API. AAD will continue to be around for at least two more years, but with no more upgrades, i.e., to PowerShell 7, as the focus will be the Ms graph module. We are working on migration documentation that maps cmdlets in MSOL and AAD against the MS graph module to assist in migration. We will also introduce tools that will help in the migration, and we will communicate in a follow-up blog post soon.

Iron Contributor

@dkimani thank you so very much, this kind of pointed clarification is exactly what we were hoping the initial blog post would be. We look forward to the follow-up blog post with the specific planned roadmap and thank you again for your hard work, we are aware it is no easy undertaking with such a vast api surface but nevertheless it is a necessity to ensure the PowerShell community can continue to be a first class citizen in the Azure and O365 space.

Brass Contributor

I sincerely appreciate the hard work that developers do. That said, it is a shame that this is the 3r iteration of a API to interact with Azure, AzureAD and O365. I also hope that the data returned by MSOL CMDLETS makes it to this new API as many attributes of that data did not make it to the AzureAD powershell module (for example). 

Copper Contributor

Ability to get/set default authentication method for MFA, please!  We can currently manipulate auth methods but can't change the default one, which makes it hard to migrate away from phone-based MFA to Authenticator.  Or a way to force delete the default.  Thanks!

Copper Contributor

I recently looked at the various PowerShell offerings for integrating with AzureAD, having previously used both MSOL and AzureAD integrations. I looked at the Microsoft Graph PowerShell SDK but at the time it was not suitable for me (I can't recall why, but I needed to create/update/delete AAD users, retrieve/restore deleted users, so probably in this area), so I wrote my own MSGraph PowerShell class instead. This works really well and I can extend it really easily for extra functions (like Groups, etc.) as I need to. The only thing missing is Exchange Online management in MS Graph (like adding/removing email addresses to/from users). I'd be very interested to hear when this is going to come onboard.

Happy to share my PowerShell MS Graph class if anyone wants it.

 

BTW I am managing 500,000 users in AzureAD using PowerShell, using MSOL (project initiated at the time only v1 of the PowerShell CmdLets were available).

I am now also managing 100,000 users in AzureAD using PowerShell using MSGraph (project initiated end of 2020).

When embarking on these projects I looked at the various offerings (SDK, modules, etc.) and currently MSGraph with a custom PowerShell class is the only way I can:

  • Create/update/delete users
  • Access the recycle bin (and restore users)
  • Update custom attributes (schema extension) and Extension Attributes
  • But still no Exchange Online functionality, e.g. add/remove email addresses
Copper Contributor

Many good comments here, including the 'roadmap' of how we will manage the environment, and the critical comments about abandoned efforts with MSOL and AzureAD.

My perspective is that Microsoft is chasing another "shiny ball" to create a new tool: MS Graph (well, a newer version of this tool).   It seems like new leader was hired, came in, and stopped work on (older/existing) projects, and moved onto their own project - of which, MS Graph is the most recent??   I get it - technology changes and we adapt; but as a system admin for 25 years, I can attest to the avalanche of changes that have come, and most all have definitely been welcomed and a huge benefit for the user population as a whole. 

 

However, it is not only frustrating and very annoying to know that this 3rd iteration has left a degree of 'incomplete solutions' in it's wake (aka, MSOL and Azure AD).  There is little confidence gained by some in this community, that we will see MS Graph completed before it is replaced by the next 'shiny ball' - and then we (as admins) will have a handful of different tools that are necessary to execute our jobs.  

 

So in short, I would like to emphasize that Graph should not be an API/SDK for developers.  Everyday admins are not developers and we just need a complete set of tools that manages the environment that WE THE CUSTOMER are buying from Microsoft.   I apologize for raining on this announcement - but it is hard to evangelize the next great thing, when the historical perspective tells us you will not finish before you move on to something else.   But good luck - we really are counting on you.

Copper Contributor

Can I suggest that an appropriate banner/disclaimer/etc. be placed on the Azure-AD documentation so that psuedo-admins (i.e. those that are NOT following this space as closely) are alerted to this guidance/recommendation without having to comb through articles/blogs?  Or perhaps at least on the most commonly accessed docs pages, such as perhaps Connect-AzureAD?  https://docs.microsoft.com/en-us/powershell/module/azuread/connect-azuread?view=azureadps-2.0 

Copper Contributor

@dkimani Are you able to clarify the below point for me please? 

 

"AAD will continue to be around for at least two more years, but with no more upgrades, i.e., to PowerShell 7, as the focus will be the Ms graph module."

 

The article Azure Active Directory (Azure AD) Graph to Microsoft Graph migration FAQ - Microsoft Graph | Microso... states that "Azure AD Graph has been on a deprecation path since June 30, 2020, and will be retired on June 30, 2022. After June 30, 2022, your apps will no longer receive responses from the Azure AD Graph endpoint."

 

Surely this means that the AzureAd module will be unusable from this date, as the AAD Graph endpoint will no longer respond to any requests?

Copper Contributor

Excellent question @wturner123! The module can be around but if the cmdlets won't work, what is the point of it...

Microsoft

wturner123 LockTar The statement is correct, however, We will give customers ample time to migrate from Powershell. We are working on an extension period of AAD graph API usage to allow Powershell to continue working. More details to be communicated soon on migration documentation and tools.
.

Copper Contributor

 

Microsoft - You guys do a good job of trying to keep everyone up to date and to try to not break things.  But things are constantly breaking\deprecated.  I know it's the nature of the beast.  But the deadlines keep changing and the notifications and details keep changing. And there are so many acronyms\terms and changing dates, it is easy to lose track of what is going on and "when" "what" might (or might not) be deprecated. 

 

And if writing code on these platforms\modules is only a part of an IT staff user's job responsibilities then they likely won't be tracking or understanding the changes and notifications as much as someone fully immersed in it (like you guys at Microsoft).  I am sure it is all very clear for Microsoft Engineers who are neck deep in this stuff every day.  But, for a lot of us, we have other responsibilities besides development on these platforms\modules.  And it is hard to keep track of it all.  Not an easy problem for Microsoft or their user community.

 

But I have a general idea\suggestion and then a few specific ideas.  Something like this seems do-able.  I hope you give it some consideration.

 

Wild General Idea

 

In addition to publishing detailed (later to be outdated) articles and notifications, would it be possible to communicate deprecation dates through the SDK, platform, app, or module itself?  Here are some ideas below. I offer these as ideas\suggestions that I hope might help, everyone.

 

Wild Idea #1 

 

Implement a mechanism in which we (Developers\Admins) are required to add or provide contact information (work email address\phone-texts?) within the 365 platform, SDK, app, or module, etc. itself.  Using Microsoft PowerShell Graph module as an example, maybe the Connect-MgGraph could require that a "Module Lifespan Notification Email" value already exist within a designated field in the 365 admin console.  If there is no value there, then Connect-MgGraph would not connect and then tell the user\developer why.  Or it could require the value as a parameter upon calling the Connect-MgGraph command.  Maybe something like: PS> Connect-MgGraph -LifespanNotificationEmail "email address removed for privacy reasons” And\or maybe offer text message to a phone number.  Something like: PS> Connect-MgGraph -LifespanNotificationTextPhone "xxx-xxx-xxxx".    If you offer both we could select both (or just one).  Using both would be something like:  

PS> Connect-MgGraph -LifespanNotificationEmail "email address removed for privacy reasons" -LifespanNotificationTextPhone "xxx-xxx-xxxx"

If we don't want to get notification every single time, add a parameter of -LifespanNotificationFrequency "Daily\Weekly\Monthly\Quarterly” value.

And if we want a repeated (same) notification to stop sending after a number of times: -LifespanNotificationsRepeatsStopAfter {integer value}

Then you guys could post a new deprecation or "Lifespan" date and notification that would be queried from this and then emailed and\or texted to the email address\phone from Microsoft.  Now this idea puts load on Microsoft for having to send out the notifications.  I think idea #2 is better.

 

Wild Idea #2

 

Create a command within the MgGraph module platform Like: Get-MgGraph-DeprecationDate and Get-MgGraph-DeprecationNotice.  These commands would query the date and notification that you guys update as they change (date gets moved back).  Then at least we could use these commands in our code\scripts to monitor the situation EVERY TIME THE CODE RUNS if we choose to.  Then, if the Get-MgGraph-DeprecationDate returns a date that is within a minimum number of days (a minimum that we set for ourselves in our code) we can have the code then call Get-MgGraph-DeprecationNotice and use that notification (and the date) to notify ourselves in whatever manner we want to.  We can code it to send us an email, send a text message, fire a flare off in the office (not recommended), zap us with an electric dog collar (also not recommended), or an automated cattle prod in our chair (also not recommended).  Whatever works for us.

 

Wild Idea #3

 

You could use Connect-MgGraph from idea #1 above like Get-MgGraph-DeprecationDate from #2 above.  What if Connect-MgGraph always returned an MgGraph-DeprecationDate?  Doing this forces IT developers to at least recognize and (if they are smart) check that date value for what it is.  Then their code could check that date and if it is within a certain timeframe then the code could call Get-MgGraph-DeprecationNotice to get more information.  Then we can use that information to notify ourselves however we want (see recommended and non-recommended notification methods in #2 above).

...

Note: Ideas #2 and #3 could even be written and released in production code to provide notification when the situation is detected.

 

Summary

In summary, I think it would help everyone (including Microsoft) if DeprecationDate and DepreciationNotification could be monitored as needed within the code itself for that platform\module\etc.  I think forcing the information back to the calling code like in idea #3 above is worth consideration also.  Thank you.

-Todd Albers

Version history
Last update:
‎Aug 19 2021 04:23 PM
Updated by: