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.

Setting Archive Tier on Azure storage

In my article

Moving to the Cloud – Part 2

I spoke about using Azure Archive storage as a good location for long term data retention. The way that you configure this is basically to set up a storage account as usual and initially configure it as ‘Cool’ storage (since you can’t do Archive storage directly). You then upload files there (typically using Azure Storage Explorer). The final piece of the puzzle is to change the access tier from ‘Cool’ to ‘Archive’ by right mouse clicking on the item.

You can do the same using Azure Storage Explorer.

The challenge becomes when you want to do more than a single file at a time.

You’ll see that you now don’t get the option to set a tier any more once you have two items or more selected. The same happens with Azure Storage Explorer as well.

Thanks to Marc Kean who pointed me in the right direction, the solution lies in changing this programmatically. Marc has a script on his site and I found another on GitHub as well but decided to write my own anyway which you’ll find here:

https://github.com/directorcia/Azure/blob/master/az-blob-tierset.ps1

with mine you’ll need to set the following variable first at the top of the script:

$storageaccountname = “<your storage account name here>”

$storageresourcegroup = “<your storage account resource group name here>”

$storagetier = “<your desired storage tier level here>” # Hot, Cool or Archive

You’ll also need to connect to you Azure account beforehand which you can do with script of mine:

https://github.com/directorcia/Azure/blob/master/az-connect.ps1

My script will, get the storage account via:

$storageaccount = Get-AzStorageAccount -name $storageaccountname -ResourceGroupName $storageresourcegroup

Get the access for that account via

$key = (get-azstorageaccountkey -ResourceGroupName $storageaccount.ResourceGroupName -Name $storageaccount.StorageAccountName).value[0]

Get the context via:

$context = New-AzstorageContext -StorageAccountName $storageaccount.StorageAccountName -StorageAccountKey $key

get the actual container via:

$storagecontainers = get-azstoragecontainer -Context $context

It will then build an array of all the objects in that container. It will then cycle through all these items changing their tier level via:

$blob.icloudblob.SetStandardBlobTier($StorageTier)

This therefore effectively changes all the items in the container to the tier level you select. This is why I like to set up containers for specific tiers rather than intermingling.

Just remember to run this script AFTER you upload your files to swap them to the cheaper Archive tier. You could also use this script to swap them back at a later stage if you need.

Remove known bad emails from tenant

Microsoft has a technology in Exchange Online known as ZAP. It will basically move known malicious emails, even after they may have initially been delivered to a mailbox. You can read more about the the technology here:

Zero-hour auto purge protection against spam and malware

ZAP however, is a ‘reactive’ security technology requiring knowledge of malicious content prior to taking action. There will therefore be cases when malicious content can get delivered to a mailbox, especially if the attack is relative new in the wild, simply because it has not yet been identified. Hopefully, users have been trained so they can report any suspicious material that they do find, as I have detailed here:

Improved security is a shared responsibility

You can also enable an alert that notifies when someone reports an email. When that happens, you may want to check through all the other mailboxes to see whether that malicious email occurs elsewhere. If the payload is indeed malicious, you may wish to take the pro-active step of deleting that bad email from all users inboxes.

You can achieve this using two steps:

1. Create a content search to locate the suspect item in your tenant

2. Use PowerShell to delete the discovered items

Step one is to login to the Microsoft 365 tenant as an administrator and visit the Security and Compliance Center like so:

Select Content Search from under the Search option on the left.

Before you create a new search, you’ll need to find something unique about the item you are searching for.

In the case above, with this dodgy email, I’ll do a search based on the senders email but I could as easily do one on the mis-spelled subject ‘Alart’. All you need is something unique.

If I look in my inbox I can see this email listed as shown.

I create a new Content Search and use the unique criteria in the keywords as shown above.

Below this I can limit where the search is conducted. In this case, I will specify messages, as that is what I am looking for. You can get quite granular here if you need to. Just select Modify and specify the location you wish to search. Remember, the more places you search the longer it will take to return results.

Once you have crafted your search, select Save & run in the lower left. After a short while, you should see the results. In this case, I have only found the one result, which is the item in my inbox. Make sure you check the items that are returned as it is these items that will be deleted! You may need to adjust your search to get exactly the results you wish.

Next, you’ll need to fire up PowerShell and connect to the Microsoft Security and Compliance Center for you tenant. I have a script that you can use here if you have MFA:

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

and if you don’t (shame on you):

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

Once you have successfully connected you need to run the following line of PowerShell:

New-ComplianceSearchAction -SearchName “<Content search query name>” -Purge -PurgeType SoftDelete

for a ‘soft delete’ of the item (i.e. recoverable). Or

New-ComplianceSearchAction -SearchName “<Content search query name>” -Purge -PurgeType HardDelete

for a ‘hard delete’ (i.e. non-recoverable). You’ll also need to change <Content search query name> to match the name you gave the Content Search when you created it.

You should now see a prompt, as shown above, asking you to confirm your actions. Generally, you’ll select Yes to All here.

This will kick off the process of deleting the content you have found. Note, this process is not immediate. It may take a little while to work through all the locations.

When the process is complete, as shown above, that item no longer appears in mailboxes.

That’s how you run your own ZAP!

November Microsoft 365 Webinar resources

Slides from this month’s webinar are at:

November 2019 Microsoft 365 Need to Know Webinar

If you are not a CIAOPS patron you want to view or download a full copy of the video from the session you can do so here:

http://www.ciaopsacademy.com.au/p/need-to-know-webinars

Watch out for next month’s webinar.

Need to Know podcast–Episode 219

We are just past Halloween and it’s time for something that seems to scare most people who administer Microsoft 365. PowerShell. However, to hold your hand while we dive deep we one of the best in business – Elliot Munro from GCITS – to guide you. Also, Brenton and I bring you all the latest news from the fire hose of Microsoft Ignite 2019, so much so that we’ll have more next time. Holey moley, there lots in the episode, so lean back, listen in an enjoy.

This episode was recorded using Microsoft Teams and produced with Camtasia 2019

Take a listen and let us know what you think – feedback@needtoknow.cloud

You can listen directly to this episode at:

https://ciaops.podbean.com/e/episode-219-elliot-munro/

Subscribe via iTunes at:

https://itunes.apple.com/au/podcast/ciaops-need-to-know-podcasts/id406891445?mt=2

The podcast is also available on Stitcher at:

http://www.stitcher.com/podcast/ciaops/need-to-know-podcast?refid=stpr

Don’t forget to give the show a rating as well as send us any feedback or suggestions you may have for the show.

Resources

Elliot Munro

@contactbrenton

@directorcia

Introducing the new Edge and Bing

Microsoft 365 Productivity score

New Office Mobile App

Microsoft Fluid Framework

Introducing Microsoft 365 Business voice to UK and Canada

What’s new in Microsoft Teams from Ignite

Microsoft Endpoint Manager vision

The future of Yammer

Empower your people with Project Cortex

Check off your To-Do tasks in Teams

Security and Compliance announcements from Ignite

Need to Know podcast–Episode 218

I talk to industry veteran and Microsoft MVP Tony Redmond about a variety of topics including Exchange Online, Teams, PowerShell as well as his fantastic Office 365 administration eBook offering. He shares lots of great insights on a variety of Microsoft offerings. Brenton and I also talk about news and updates in the Microsoft Cloud and get you ready for what we are potentially expecting from the upcoming Microsoft Ignite conference. Listen along and get ready for the tsunami from Microsoft Ignite.

This episode was recorded using Microsoft Teams and produced with Camtasia 2019

Take a listen and let us know what you think – feedback@needtoknow.cloud

You can listen directly to this episode at:

https://ciaops.podbean.com/e/episode-218-tony-redmond/

Subscribe via iTunes at:

https://itunes.apple.com/au/podcast/ciaops-need-to-know-podcasts/id406891445?mt=2

The podcast is also available on Stitcher at:

http://www.stitcher.com/podcast/ciaops/need-to-know-podcast?refid=stpr

Don’t forget to give the show a rating as well as send us any feedback or suggestions you may have for the show.

Resources

@12knocksinna = Tony Redmond

@contactbrenton

@directorcia

Tony’s blog

Office 365 for IT Pros eBook

Surface laptops are finally repairable

Microsoft’s cloud earnings

CIAOPS MS-101 online training course now available

New Microsoft partner CSP agreement

Microsoft acquires Mover.io

How to check user sign in history

Tamper protection in Microsoft Defender ATP

End user self service for Power Platform

What is Microsoft 365 Business [VIDEO]

Call of Duty – Modern Warfare

What you need for Windows Virtual Desktop (WVD)

Windows Virtual Desktop (WVD) is now generally available and I’ll be covering off how to set it up in upcoming articles. However, before you even login to your Azure tenant to start setting this up, here’s what you’ll need:

1. A Windows Virtual Desktop license for every user who want to use the service. These come with all Microsoft 365 and Windows E3 and E5 suites.

2. A paid Azure subscription. The majority of the cost of the WVD service will be your Virtual Machine hosts. The cost of these will vary on how many you want to use and how long they run for.

3. Azure Active Directory. The users who access the WVD service need to be in Azure AD. These users can be cloud only or synced from on premises using Azure AD Connect.

4. A Domain Controller (DC). At this point in time the WVD still requires a ‘traditional’ domain controller to allow the VMs to connect to for access. If you only have cloud users then the easiest option to achieve this is to add Azure AD Domain Services. If you already have an on premises Domain Controller (DC) you’ll need a Site to Site (S2S) VPN to link your on premises network to Azure. Note, that if you have an on premises DC that is using Azure AD Connect you can’t just add Azure AD Domain Services because Azure AD Connect doesn’t sync ‘traditional’ DC attributes. So, if you have an on premises DC, even if it is already using Azure AD Connect, you’ll still require a S2S VPN to Azure to allow the WVD service to connect VMs to that domain.

5. Azure AD tenant ID. Each Azure AD has a unique number which you can get from the web interface or via PowerShell. This is because it is possible to have multiple AD’s inside Azure and each can be configured and connected differently. The WVD service will need to know which specific Azure AD to connect to when provisioning.

6. Azure Subscription ID. The costs of the WVD service need to be applied against a unique subscription inside Azure. again, remember it is possible to have multiple independent subscriptions inside an Azure tenant. The WVD setup will need to know which subscription to bill for the service.

7. Azure tenant admin account. This will typically be a global administrator of your Azure environment. This will typically be the user who sets up, configures and manages WVD. They will also typically be an administrator of the domain that is connected to Azure AD.

8. Domain join account. This is an account that has the rights to join machines to the domain. The WVD service will create a number of VMs that need to be connected to the domain so that users on the domain can login to these machines in your WVD environment. You may wish to have a domain join user who is not a global administrator for security reasons but you should also be aware of the potential password requirement differences between your domain user and the Azure admin account. You may wish to use the same Azure admin account as your domain join account. If so, just beware of the password requirement policy for these.

As you can see above, the domain join account has to be at least 12 characters long, plus 3 of the following – 1 lower case character, 1 upper case character, 1 number, a special character. That requirement may be different from what your Azure AD or on premises AD requires. My recommendation would be to create a stand alone domain join account that meets the requirements and is only used for joining machines.

9. Azure Virtual Network (VNET). You’ll need a pre-existing VNET for the WVD machines to connect to. When you implement Azure AD Domain Services or a S2S VPN to connect an on premises DC, you’ll need a VNET. Make sure you understand the IP addressing and subnetting of your Azure VNET when you create it, as changing it later can be very painful.

10. Appropriate skill set. WVD requires a range of skills and understandings including:

– Identity management

– Azure AD

– PowerShell

– Azure IaaS including VNETs, VMs, Storage, etc

– Networking

– Azure backup, imaging, etc

Can you bumble you way through without these? Maybe, but life will be much easier if you do have these skills and really, if you are planning to work in the Microsoft Cloud environment, these should be considered mandatory.

There you have it, ten pre-requisite items to get sorted before you launch into creating a WVD for yourself. Get these sorted prior and your installation will be much smoother!

As I said, I’ll have upcoming articles on how to set this up, so stay tuned.