Moving from Old Modules to the Microsoft Graph SDK for PowerShell
Update: This article describes a script to generate a report showing the MFA status for accounts and highlights administrative accounts that aren’t MFA-enabled.
Their future focus for PowerShell access to Azure AD data is the Microsoft Graph SDK for PowerShell. The only definite drop-dead date affecting the older modules is June 30, 2022, when Microsoft moves to a new license management platform. At this point, any cmdlet which retrieves license information for user accounts will cease working. Any scripts used for tenant license management that haven’t been updated now require urgent attention.
I have an MFA status script written in 2018. The script uses the MSOL cmdlets to check and report the “strong authentication methods” for each user account. The state of multi-factor authentication has moved on since 2018 to accommodate new methods like FIDO2 keys and passwordless authentication. These methods aren’t handled by the MSOL cmdlets. It’s therefore time to take a different approach.
Given Microsoft’s direction to use the Microsoft Graph SDK for PowerShell for Azure AD access, it seems like this is the right path to follow. I’ve done a reasonable amount with the SDK and have written several articles to report my progress. For example, here’s how to generate a licensing report for a tenant.
Not a Perfect SDK
The SDK is not perfect. Essentially, its cmdlets are wrappers around Graph API queries. If you’re used to dealing with Graph APIs, the SDK cmdlets will be second nature. If not, it will take time to become familiar.
Getting acquainted isn’t helped by the poor state of the documentation for the SDK cmdlets. Microsoft uses automatic text generation tools to create the documentation from source code. The result is often as useful as a snowball in a desert, especially in terms of practical examples and explanations about inputs. Again, if you know the Graph APIs, you probably won’t be surprised at what you find in the documentation, but the current state of the documentation is no credit to Microsoft and a barrier to adoption.
Steps in the Creation of the Report
The aim is to create a report showing the authentication methods used by Azure AD accounts and highlight accounts which might attention (hopefully, by enabling multi-factor authentication). According to a recent Microsoft report, only 22% of Microsoft 365 accounts use multi-factor authentication. Although this marks an improvement over the past, it’s still far too low a percentage. Perhaps people don’t know about recent improvements Microsoft has made in MFA processing to make it easier for people to use.
The script I wrote to create the report does the following:
Connects to the Graph endpoint with the following permissions: UserAuthenticationMethod.Read.All, Directory.Read.All, User.Read.All, Auditlog.Read.All. If the service principal for the SDK doesn’t have administrat9or consent of any permission, it must be granted at this point.
Set the Graph profile to beta to make sure that we have access to all the user account data.
Call the Get-MgUser cmdlet to fetch the set of Azure AD member accounts. The set returned excludes guest accounts but includes the accounts used for shared and resource mailboxes. To focus solely on licensed member accounts, you could apply a filter to look for accounts with at least one assigned license.
Loop through each account to check its authentication methods. To ensure that only active accounts are checked, the script calls the Get-MgAuditLogSignIn cmdlet to look for a sign-in record. This check can only go back 30 days.
For each active account, call the Get-MgUserAuthenticationMethod cmdlet to return the authentication methods used by the account. An account can use all the valid authentication methods from passwordless to the Microsoft authenticator app. The first time an account uses a method, Azure AD adds it to the list used by the account.
For each method, retrieve some information.
Report the results of checking each method.
After processing all user accounts, create a list of users for which an authentication method is available and check each account to see if one of the strong (MFA) methods is noted.
Create a final report and output it to a CSV file.
Figure 1 shows an example of the kind of output generated.
Figure 1: Authentication methods report for Azure AD accounts
You can download the script from GitHub. As always, the code is intended to illustrate a principal rather than being a fully-baked solution.
Automating the Check
A script like this is a good candidate for execution by an Azure Automation runbook. It can be run on a schedule and the results emailed to administrators for action. Getting a weekly or monthly reminder to improve the security posture of the organization by increasing the percentage of well-protected accounts can only be a good thing, can’t it?
Learn how to exploit the data available to Microsoft 365 tenant administrators through the Office 365 for IT Pros eBook. We love figuring out how things work.
Hi Tony!
What does the script detect to advise the administrator to check the account? What is it based on? Thank you!
Loading...
Tony, I need to create a daily report of MFA phone’s that have been updated. Is it possible to query those events in the audit log using a script – perhaps similar to what you have posted for this?
{"id":null,"mode":"button","open_style":"in_modal","currency_code":"EUR","currency_symbol":"\u20ac","currency_type":"decimal","blank_flag_url":"https:\/\/office365itpros.com\/wp-content\/plugins\/tip-jar-wp\/\/assets\/images\/flags\/blank.gif","flag_sprite_url":"https:\/\/office365itpros.com\/wp-content\/plugins\/tip-jar-wp\/\/assets\/images\/flags\/flags.png","default_amount":100,"top_media_type":"featured_image","featured_image_url":"https:\/\/office365itpros.com\/wp-content\/uploads\/2022\/11\/cover-141x200.jpg","featured_embed":"","header_media":null,"file_download_attachment_data":null,"recurring_options_enabled":true,"recurring_options":{"never":{"selected":true,"after_output":"One time only"},"weekly":{"selected":false,"after_output":"Every week"},"monthly":{"selected":false,"after_output":"Every month"},"yearly":{"selected":false,"after_output":"Every year"}},"strings":{"current_user_email":"","current_user_name":"","link_text":"Virtual Tip Jar","complete_payment_button_error_text":"Check info and try again","payment_verb":"Pay","payment_request_label":"Office 365 for IT Pros","form_has_an_error":"Please check and fix the errors above","general_server_error":"Something isn't working right at the moment. Please try again.","form_title":"Office 365 for IT Pros","form_subtitle":null,"currency_search_text":"Country or Currency here","other_payment_option":"Other payment option","manage_payments_button_text":"Manage your payments","thank_you_message":"Thank you for supporting the work of Office 365 for IT Pros!","payment_confirmation_title":"Office 365 for IT Pros","receipt_title":"Your Receipt","print_receipt":"Print Receipt","email_receipt":"Email Receipt","email_receipt_sending":"Sending receipt...","email_receipt_success":"Email receipt successfully sent","email_receipt_failed":"Email receipt failed to send. Please try again.","receipt_payee":"Paid to","receipt_statement_descriptor":"This will show up on your statement as","receipt_date":"Date","receipt_transaction_id":"Transaction ID","receipt_transaction_amount":"Amount","refund_payer":"Refund from","login":"Log in to manage your payments","manage_payments":"Manage Payments","transactions_title":"Your Transactions","transaction_title":"Transaction Receipt","transaction_period":"Plan Period","arrangements_title":"Your Plans","arrangement_title":"Manage Plan","arrangement_details":"Plan Details","arrangement_id_title":"Plan ID","arrangement_payment_method_title":"Payment Method","arrangement_amount_title":"Plan Amount","arrangement_renewal_title":"Next renewal date","arrangement_action_cancel":"Cancel Plan","arrangement_action_cant_cancel":"Cancelling is currently not available.","arrangement_action_cancel_double":"Are you sure you'd like to cancel?","arrangement_cancelling":"Cancelling Plan...","arrangement_cancelled":"Plan Cancelled","arrangement_failed_to_cancel":"Failed to cancel plan","back_to_plans":"\u2190 Back to Plans","update_payment_method_verb":"Update","sca_auth_description":"Your have a pending renewal payment which requires authorization.","sca_auth_verb":"Authorize renewal payment","sca_authing_verb":"Authorizing payment","sca_authed_verb":"Payment successfully authorized!","sca_auth_failed":"Unable to authorize! Please try again.","login_button_text":"Log in","login_form_has_an_error":"Please check and fix the errors above","uppercase_search":"Search","lowercase_search":"search","uppercase_page":"Page","lowercase_page":"page","uppercase_items":"Items","lowercase_items":"items","uppercase_per":"Per","lowercase_per":"per","uppercase_of":"Of","lowercase_of":"of","back":"Back to plans","zip_code_placeholder":"Zip\/Postal Code","download_file_button_text":"Download File","input_field_instructions":{"tip_amount":{"placeholder_text":"How much would you like to tip?","initial":{"instruction_type":"normal","instruction_message":"How much would you like to tip? Choose any currency."},"empty":{"instruction_type":"error","instruction_message":"How much would you like to tip? Choose any currency."},"invalid_curency":{"instruction_type":"error","instruction_message":"Please choose a valid currency."}},"recurring":{"placeholder_text":"Recurring","initial":{"instruction_type":"normal","instruction_message":"How often would you like to give this?"},"success":{"instruction_type":"success","instruction_message":"How often would you like to give this?"},"empty":{"instruction_type":"error","instruction_message":"How often would you like to give this?"}},"name":{"placeholder_text":"Name on Credit Card","initial":{"instruction_type":"normal","instruction_message":"Enter the name on your card."},"success":{"instruction_type":"success","instruction_message":"Enter the name on your card."},"empty":{"instruction_type":"error","instruction_message":"Please enter the name on your card."}},"privacy_policy":{"terms_title":"Terms and conditions","terms_body":null,"terms_show_text":"View Terms","terms_hide_text":"Hide Terms","initial":{"instruction_type":"normal","instruction_message":"I agree to the terms."},"unchecked":{"instruction_type":"error","instruction_message":"Please agree to the terms."},"checked":{"instruction_type":"success","instruction_message":"I agree to the terms."}},"email":{"placeholder_text":"Your email address","initial":{"instruction_type":"normal","instruction_message":"Enter your email address"},"success":{"instruction_type":"success","instruction_message":"Enter your email address"},"blank":{"instruction_type":"error","instruction_message":"Enter your email address"},"not_an_email_address":{"instruction_type":"error","instruction_message":"Make sure you have entered a valid email address"}},"note_with_tip":{"placeholder_text":"Your note here...","initial":{"instruction_type":"normal","instruction_message":"Attach a note to your tip (optional)"},"empty":{"instruction_type":"normal","instruction_message":"Attach a note to your tip (optional)"},"not_empty_initial":{"instruction_type":"normal","instruction_message":"Attach a note to your tip (optional)"},"saving":{"instruction_type":"normal","instruction_message":"Saving note..."},"success":{"instruction_type":"success","instruction_message":"Note successfully saved!"},"error":{"instruction_type":"error","instruction_message":"Unable to save note note at this time. Please try again."}},"email_for_login_code":{"placeholder_text":"Your email address","initial":{"instruction_type":"normal","instruction_message":"Enter your email to log in."},"success":{"instruction_type":"success","instruction_message":"Enter your email to log in."},"blank":{"instruction_type":"error","instruction_message":"Enter your email to log in."},"empty":{"instruction_type":"error","instruction_message":"Enter your email to log in."}},"login_code":{"initial":{"instruction_type":"normal","instruction_message":"Check your email and enter the login code."},"success":{"instruction_type":"success","instruction_message":"Check your email and enter the login code."},"blank":{"instruction_type":"error","instruction_message":"Check your email and enter the login code."},"empty":{"instruction_type":"error","instruction_message":"Check your email and enter the login code."}},"stripe_all_in_one":{"initial":{"instruction_type":"normal","instruction_message":"Enter your credit card details here."},"empty":{"instruction_type":"error","instruction_message":"Enter your credit card details here."},"success":{"instruction_type":"normal","instruction_message":"Enter your credit card details here."},"invalid_number":{"instruction_type":"error","instruction_message":"The card number is not a valid credit card number."},"invalid_expiry_month":{"instruction_type":"error","instruction_message":"The card's expiration month is invalid."},"invalid_expiry_year":{"instruction_type":"error","instruction_message":"The card's expiration year is invalid."},"invalid_cvc":{"instruction_type":"error","instruction_message":"The card's security code is invalid."},"incorrect_number":{"instruction_type":"error","instruction_message":"The card number is incorrect."},"incomplete_number":{"instruction_type":"error","instruction_message":"The card number is incomplete."},"incomplete_cvc":{"instruction_type":"error","instruction_message":"The card's security code is incomplete."},"incomplete_expiry":{"instruction_type":"error","instruction_message":"The card's expiration date is incomplete."},"incomplete_zip":{"instruction_type":"error","instruction_message":"The card's zip code is incomplete."},"expired_card":{"instruction_type":"error","instruction_message":"The card has expired."},"incorrect_cvc":{"instruction_type":"error","instruction_message":"The card's security code is incorrect."},"incorrect_zip":{"instruction_type":"error","instruction_message":"The card's zip code failed validation."},"invalid_expiry_year_past":{"instruction_type":"error","instruction_message":"The card's expiration year is in the past"},"card_declined":{"instruction_type":"error","instruction_message":"The card was declined."},"missing":{"instruction_type":"error","instruction_message":"There is no card on a customer that is being charged."},"processing_error":{"instruction_type":"error","instruction_message":"An error occurred while processing the card."},"invalid_request_error":{"instruction_type":"error","instruction_message":"Unable to process this payment, please try again or use alternative method."},"invalid_sofort_country":{"instruction_type":"error","instruction_message":"The billing country is not accepted by SOFORT. Please try another country."}}}},"fetched_oembed_html":false}
Hi, Tony! Great post!
What is the meaning of MFAStatus = “Check!”?
Thank you!
It’s just setting a status value to advise the administrator to check this account. You can set it to whatever you like.
Hi Tony!
What does the script detect to advise the administrator to check the account? What is it based on? Thank you!
Tony, I need to create a daily report of MFA phone’s that have been updated. Is it possible to query those events in the audit log using a script – perhaps similar to what you have posted for this?
What precisely do you need to do? I don’t understand from your description.