Making PowerShell automation easier with the Microsoft Graph

About 2 years ago I released a free PowerShell script that allowed you to check for email forwards on mailboxes in a Microsoft 365 environment. I wrote about that script here:

https://blog.ciaops.com/2018/07/05/powershell-script-to-check-outlook-mail-rules/

This is still the most comprehensive method in my books for checking for all the various type of forwards on a mailbox and I recommend you continue to use the script which you’ll find freely available at:

https://github.com/directorcia/Office365/blob/master/o365-exo-fwd-chk.ps1

As good as that script is, there are still challenges for many people actually using it I have found. This mainly revolves around getting an appropriate PowerShell environment running, installing the Exchange Online PowerShell modules, connecting to Exchange Online with PowerShell and so on. I have detailed how to do all that over the period here but I still find that many struggle to make use of the PowerShell script.

So a new approach is in order. In short, I have a new version of this script that is a single EXE file you can download and use here:

https://github.com/directorcia/Office365/blob/master/graph-mbx-rules.exe

It is important to note that this script does not make any changes to users or their mailboxes, it just reads and reports their mailbox rules using the Microsoft Graph. As yet, it can’t check more exotic things like direct mailbox forwarding or sweep rules, but you gotta start somewhere!

Let me show you how it works.

You’ll need a PC that is running a current version of PowerShell. A Windows 10 PC will work fine. You should also have the AzureAD PowerShell module loaded prior in your environment. To do that, all you need to do is run an elevated PowerShell console and type install-azuread. However, hopefully most people already have this loaded.

Download my new file from:

https://github.com/directorcia/Office365/blob/master/graph-mbx-rules.exe

and copy it anywhere on your machine as shown above. Double click to run the file.

You should now see a window like shown above.

The program will first check for the Azure AD PowerShell module. It will then prompt you to log into your tenant of choice.

You’ll go through your normal login process to a tenant as shown.

Including using MFA if required.

Once logged into the tenant, a new Azure AD application will be created in the tenant with a unique name as shown above. The name in this case is CIAOPS-20200415232309. With the app created in the tenant, appropriate permission are added to that app to allow it to do things like read the list of users, their mailboxes, etc.

After this app has been created and permissions applied to it to allow it to do its work, those changes need to be consented or approved by someone (typically the same user that initially logged into the tenant). Unfortunately, from what I can see, consent can only be managed via the browser. With that in mind, the required URL is copied to the clipboard and you are prompted whether you wish to open the default browser to complete this process. Copying the consent URL to the clipboard allows you to manually paste it to your browser session of choice. This is handy if you are working in multiple tenants currently.

You’ll now be prompted to login to the tenant again, but this time in a browser.

You should then see a list of requested permissions as shown above that you’ll need to accept for this process to complete.

If you look at the top of the dialog to see what is requesting permission you should see the name of the Azure AD application as noted previously. Here again that is CIAOPS-20200415232309.

Also note that there is only one write permissions requested, the majority are only read. Where do these permission come from? To use the Microsoft Graph, for example, to list the email folders for a user you use the command here:

https://docs.microsoft.com/en-us/graph/api/user-list-mailfolders?view=graph-rest-1.0&tabs=http

in which you’ll see to do this you need the permissions:

Mail.ReadBasic.All, Mail.Read, Mail.ReadWrite

I have tried to keep the rights requires as basic as possible but I am using what the Graph provides.

You’ll see that it needs a number of permissions to accomplish this. Basically, I have automated the process I detailed how to do manually before here:

https://blog.ciaops.com/2019/04/17/using-interactive-powershell-to-access-the-microsoft-graph/

After you Accept the permissions, you should be return to the home page of your tenant as shown. If for reason the consent page doesn’t appear or something else strange happens, just paste in the URL and try again. Sometimes web request don’t always work.

If you now return to the program you’ll see that it is prompting you to confirm that you have completed the consent stage. Type Y and press ENTER to continue.

Because the web consent step can take a short while to complete I now wait 10 seconds, just in case, for this to complete.

The program will continue, getting all the information it needs and then starting to report on user mailboxes as shown above.

Once all mailboxes have been checked the Azure AD application created to facilitate this process (here CIAOPS-20200415232309) is deleted from your tenant to leave zero touch.

If you then press any key, the program will complete.

If you now look in the source directory you will see two new text files as shown above.

The first file, graph-mdx-rules.txt is basically a debugging log file that records what happens during the initialisation phase of the program.

The file mbx-rules.txt is basically a copy of the results.

Note, both of these file get overwritten each time the program runs.

Hopefully, this new program makes it much easier to get the information your need. However, because much is automated and simplified, some may be concerned as to what is actually happening behind the scenes. Well, thanks to the wonders of Azure AD you can easily see.

To review the whole process, open you Azure portal and navigate to Azure Active Directory and then Audit logs as you see above.

In there you should find an entry that corresponds to the Azure AD application being added as shown above. Note the name corresponds to the one details previously, here CIAOPS-20200415232309.

You should then see entries where permissions have been added to Azure AD application as shown above.

A bit further along, you’ll see where consent was granted to the Azure AD application as shown above.

Lastly, you’ll also see where that Azure AD application is completely deleted from the environment leaving no fingerprint.

This is a new approach to automation that I believe will work well. There is still a lot of work that needs to be done and there are still some limitations but hopefully, this can be the first of many scripts I create and make available in this simplified way. Thus, I’d love you to try the program and tell me what you think. what works, what doesn’t? What would you like to see and how can it be improved? No matter what it is, I’d love to hear your thoughts, which you can send me directly via email director@ciaops.com.

Look out for more updates and new scripts at my GitHub repository – https://github.com/directorcia/Office365

Viewing and removing OneDrive for Business Sharing with PowerShell

One of the great abilities of OneDrive for Business and SharePoint Online is the ability to quickly and easily share a link to a file with people outside your organisation.

I’m not going to show you how to do this in this article but if you need to see how this is done have a look at:

Share OneDrive files and folders

In the above example you’ll see that the file Employee Engagement Plan.docx has been been shared by the owner with an external user (Lewis Collins).

Somewhere else, you can see that this user (Lewis Collins) has the document open to work on.

One of the benefits of sharing using OneDrive for Business is that the sharing rights can easily be revoked by the original user if desired.

The easiest way to achieve this would be simply to hit the cross next to the external users name in the web interface as shown above.

The original user would then be prompted the Remove the external user, which they would do to remove access.

That all works fine when you have a small number of shared files and a small number of users working with a file. It becomes a lot more problematic when you start scaling to many users as you can see here:

What happens when you need to find just one user to remove sharing from amongst a list of hundreds of users?

PowerShell to the rescue!

1. Connect to SharePoint Online via PowerShell. You can use my script at:

https://github.com/directorcia/Office365/blob/master/o365-connect-mfa-spo.ps1

to do this. You’ll need to know the tenant name prior i.e. the part before the .onmicrosoft.com (e.g. mydomain.onmicrosoft.com)

2. Run the PowerShell command:

Get-spouser -site https://<mydomain>-my.sharepoint.com/personal/<user>_<mydomain>_onmicrosoft_com -limit all

to display of all the users who have access to the specific OneDrive for Business site.

In this list you should find your external user in the format of:

<user@externaldomain.com>#ext#<mydomain>.onmicrosoft.com

This may vary slight but you should also be able to identify the user by their Display name if needed.

3. Run the PowerShell command:

remove-spouser –site https://<mydomain>-my.sharepoint.com/personal/<user>_<mydomain>_onmicrosoft_com  -loginname <user@externaldomain.com>#ext#<mydomain>.onmicrosoft.com

4. Run a sharing report

In the source OneDrive for Business, select the COG in the upper right corner and then the option OneDrive Settings.

Now select More Settings on the left and Run sharing report from the options that appear on the right as shown above.

Nominate a folder for this report to be sent to.

You’ll receive an email when the report is ready. It will be in Excel format as you can see above.

Open the file and do a search for the external email address of the removed users.

The removed users should not appear in the report as expected.

If you now look at the sharing option for file(s) in that OneDrive for Business you should find that the removed user no longer appears, as shown above.

If the external user, who has just been removed, actually has the file open at the moment that access is removed they will see:

and be prompted to Reconnect. If they then attempt to reconnect they will see:

and will be denied access going forward.

Note – This removes that users access to ALL files shared in the OneDrive for Business location, not just for a single file.

I also have another freely available script at:

https://github.com/directorcia/Office365/blob/master/o365-spo-extusr.ps1

that will display a list of all externally shared across your tenant as shown above.

If you do have a situation where you have large numbers of shared files or shared users in OneDrive for Business and you wish to make bulk removal easier, I’d encourage you to look at PowerShell as an option. However, remember, this option will remove ALL sharing for that user(s) across the WHOLE OneDrive for Business.

Branding your Microsoft 365 tenant

Branding is great way to improve the visual look and feel during the login experience but may also help mitigate phishing compromises in a small way by providing uniqueness. It only takes a few moments to brand your tenant and branding will also start showing up in a number of different areas when you use Microsoft 365 services.

This video takes you through that process and shows you how easy it is to set up. a link to the video is here:

https://www.youtube.com/watch?v=PFXzmlypyDM

and the article mentioned in the video is here:

https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/customize-branding

Conditional Access with Microsoft 365

One of the easy ways to protect your environment is to implement Conditional Access which is included with all Microsoft 365 plans. Otherwise, you can add Azure AD P1 to your environment to get this functionality.

This video will take you through the basics of setting up a Conditional Access including how to block access based on location. You’ll see how to create a Named Location, a Conditional Access policy and what it looks like when it is actually applied to a user.

A direct link for the video can be found at:

https://www.youtube.com/watch?v=TcYaRaNqYe4

Unified Audit Logs in Microsoft 365

Here is a quick overview of the tenant Unified Audit Logs in Microsoft/Office 365 and how you can access them as well as use them to search what’s happening in your tenant. This can be very handy if you need to track down what a user is doing or if you need to investigate a security incident.

A direct link to the video can be found at:

https://www.youtube.com/watch?v=c1kId_esv0k

Anti spam policies in Microsoft 365

One of the biggest misunderstanding’s I see around Microsoft/Office 365 is managing anti spam settings. These are done in Exchange Online. Thinks like Office 365 ATP actually perform additional functionality (such as safe list and attachments). Thus, if you want to limit the spam that users receive it is important to ensure you have your anti spam policies correctly configured.

This video will show you how and where to configure both inbound and outbound spam policies as well as some best practice recommendations for both. You’ll find the direct link for the video here:

https://www.youtube.com/watch?v=X9GeUYoRSzc

Introduction to Azure Sentinel

I’ve put together a quick introduction on Azure Sentinel to give you a better idea of what it is all about. I’ll show you how to connect services and create some rules to get you started. I also give you an idea of the costs of using the service (hint, it’s cheap!).

The direct video URL is – https://www.youtube.com/watch?v=XBXeFtrYaFI