Connect-Maester
Overview
Connect-Maester is a helper command that simplifies the process of authenticating to the services required to run Maester tests including Microsoft Graph PowerShell, Azure PowerShell and Exchange Online PowerShell.
While Connect-Maester will handle the most common interactive authentication scenarios, it does not replicate all of the authentication options available in the respective modules.
The Connect-Maester command is completely optional if your current PowerShell session is already connected to Microsoft Graph using Connect-MgGraph.
Examining the code for Connect-Maester will reveal that it simply calls Connect-MgGraph.
What this means is that you can use Connect-MgGraph directly if you prefer to have more control over the authentication process. See the Connect-MgGraph: Microsoft Graph authentication documentation for more information on all the options available including the use of certificates, secrets, managed identities, different clouds and more.
Using Connect-Maester
Connect to Microsoft Graph
To connect to Microsoft Graph, use the following command:
Connect-Maester
Running Connect-Maester is the same as running the following:
Connect-MgGraph -Scopes (Get-MtGraphScope)
Approval required when connecting
Global Reader and other non-admin accounts can't consent to the Microsoft Graph permissions that Maester requests. When they run Connect-Maester, they see an Approval required prompt for Microsoft Graph Command Line Tools, and the connection then fails with User canceled authentication.
Approving this request from Admin consent requests in the Entra admin center can fail with AADSTS70011: ... openid scope is required. Instead, ask a Global Administrator or Privileged Role Administrator to grant consent in one of these ways.
Option 1: Grant consent for the organization (recommended)
The admin runs the following command, signs in, and selects Consent on behalf of your organization before selecting Accept.
Connect-MgGraph -Scopes (Get-MtGraphScope)
Add the same switches you use with Connect-Maester, such as -SendMail or -Privileged, to Get-MtGraphScope. If you connect with -TenantId or -Environment, add those to Connect-MgGraph too, for example:
Connect-MgGraph -Scopes (Get-MtGraphScope -SendMail) -TenantId '<tenant-id>' -Environment USGov
Afterwards, run Connect-Maester again with your own account. If the connection fails after an approval prompt, Connect-Maester prints these commands with your switches already filled in.
Option 2: Use a custom app registration
Create an app registration with the Maester delegated permissions and grant admin consent. Then connect with its client ID. See Connect using a custom application.
Connect-Maester -GraphClientId '<application-client-id>'
Keep any other parameters you normally use, such as -TenantId, -Environment, -SendMail or -Privileged.
Send Mail and Teams message
Connects to Microsoft Graph with the Mail.Send scope in addition to the default Maester scopes. This allows you to use the required permission to send email when using the Send-MtMail command or when using Invoke-Maester -MailRecipient [email protected]
Connect-Maester -SendMail
This is the same as running
Connect-MgGraph -Scopes (Get-MtGraphScope -SendMail)
The same applies to the -SendTeamsMessage in Connect-Maester.
Privileged scope
Maester is designed to require read-only access to a tenant to run tests.
However, certain tests like Test-MtExoMoeraMailActivity require privileged permission scopes to call certain APIs. If the permission is not granted, the specific test will be skipped.
Connecting with privileged scopes is optional. To connect with privileged scopes, use the -Privileged switch:
Connect-Maester -Privileged
Device code
The -DeviceCode switch allows you to sign in using the device code flow. This will open a browser window to prompt for authentication and is useful on Windows when you want to avoid single signing on as the current user.
Connect-Maester -UseDeviceCode
Connect to SharePoint Online (optional)
Maester includes SharePoint Online security tests that use the PnP PowerShell module.
Install the PnP PowerShell module if you haven't already:
Install-Module PnP.PowerShell -Scope CurrentUser
A dedicated Entra ID app registration configured for PnP interactive login is required. The easiest way to create one is to follow the official PnP app registration guide and run Register-PnPEntraIDAppForInteractiveLogin, which outputs the Client ID you will supply to -SharePointClientId. For the Maester-specific SharePoint permission setup, see Grant permissions to SharePoint Online.
Connect to SharePoint Online together with Microsoft Graph (the admin URL is auto-discovered from your tenant's initial domain):
Connect-Maester -Service Graph,SharePointOnline -SharePointClientId '<Client ID>'
If auto-discovery does not work (e.g. in government or custom-domain tenants), supply the admin URL explicitly:
Connect-Maester -Service Graph,SharePointOnline -SharePointClientId '<Client ID>' -SharePointAdminUrl 'https://contoso-admin.sharepoint.com'
If the PnP PowerShell module is not installed or there is no active connection, all SharePoint Online tests are skipped automatically.
Connect to Azure, Exchange Online, Copilot Studio and Teams
Connect-Maester also provides options to connect to Azure, Copilot Studio (via the Dataverse API), Exchange Online and Teams for running tests that use the Azure PowerShell, Dataverse OData API, Exchange Online PowerShell or Teams PowerShell modules.
The -All switch can be used to connect to all the services used by the Maester tests. This includes Microsoft Graph, Azure, Copilot Studio (Dataverse), Exchange Online, Security Compliance, Microsoft Teams, and SharePoint Online.
If -SharePointClientId is not provided, the SharePoint Online connection is skipped.
Connect-Maester -Service All
When it finishes, Connect-Maester shows a summary of each service it tried. A service is Connected, Skipped (for example, no Dataverse environment or no -SharePointClientId), Failed (with the first line of the error), or Not installed (with the command to install the module).
Service Status Details
------- ------ -------
Microsoft Graph Connected [email protected]
Azure Connected [email protected]
Dataverse Skipped No environment found, set DataverseEnvironmentUrl in maester-config.json
Exchange Online Connected [email protected]
Security & Compliance Connected [email protected]
Microsoft Teams Connected [email protected]
SharePoint Online Skipped -SharePointClientId was not provided
For more details on each connection, run Connect-Maester with -Verbose.
Run Connect-Maester -Verbose to see the step-by-step messages for each connection, including the full error when a service fails.
If you need to connect to just a subset of the services you can specifiy them using the -Service parameter.
Connect-Maester -Service Azure,Graph,Teams
Connect to Copilot Studio (via Dataverse)
To run the Copilot Studio Security Tests (MT.1113–MT.1122), connect with the Dataverse service:
Connect-Maester -Service Graph,Dataverse
This uses Az.Accounts to authenticate and obtain a Dataverse access token for the Copilot Studio environment configured in maester-config.json.
Connect to GitHub (optional)
Maester includes optional GitHub security tests that require an active GitHub organization connection. GitHub is not included in Connect-Maester -Service All because it is not a Microsoft 365 service. Add GitHub explicitly when you want to run GitHub tests.
For interactive sessions, the preferred option is the Maester GitHub App. It uses GitHub OAuth device flow, so you do not need to create, paste, or store a personal access token for day-to-day interactive use.
Connect-Maester -Service Graph,GitHub -GitHubOrganization '<github-organization>'
You can also connect only to GitHub:
Connect-Maester -Service GitHub -GitHubOrganization '<github-organization>'
The first time you connect, Maester opens the GitHub device authorization page and shows a code to enter. If the Maester GitHub App is not installed or approved for the organization, Maester explains why the app is needed and asks before opening the install page. A GitHub organization owner may need to install or approve the app for the organization.
You can avoid typing the organization every time by setting GitHubOrganization in maester-config.json:
{
"GlobalSettings": {
"GitHubOrganization": "contoso"
}
}
Then connect with:
Connect-Maester -Service Graph,GitHub
For automation, use a GitHub token instead of the interactive GitHub App device flow. Connect-Maester checks MAESTER_GITHUB_TOKEN first and then GH_TOKEN.
$env:MAESTER_GITHUB_TOKEN = '<token>'
Connect-Maester -Service Graph,GitHub -GitHubOrganization '<github-organization>'
Use a token that can read organization membership and organization administration settings. For example, use a classic PAT with admin:org, or a fine-grained token with Organization Members: read and Organization Administration: read.
Use Disconnect-Maester or Disconnect-MtGitHub to clear the in-memory GitHub session when you are finished.
Connect to Azure DevOps (optional)
Maester includes an optional set of Azure DevOps security tests (AZDO.*).
These tests require the community ADOPS PowerShell module and an active connection to your Azure DevOps organization.
Connecting to Azure DevOps is not part of Connect-Maester and must be done separately:
Install-Module ADOPS -Scope CurrentUser
Connect-ADOPS -Organization <your-organization>
If the ADOPS module is not installed or there is no active connection, the Azure DevOps tests are skipped automatically.
See the installation guide for prerequisites and permissions, and the Azure DevOps tests for Maester blog post for the full list of available tests.
Connect to US Government, US DoD, China and Germany and other clouds
Connect-Maester also provides options to connect to the US Government, China and Germany clouds for Microsoft Graph, Azure and Exchange Online.
US Government
Connect-Maester -Environment USGov -AzureEnvironment AzureUSGovernment -ExchangeEnvironmentName O365USGovGCCHigh
US Department of Defense (DoD)
Connect-Maester -Environment USGovDoD -AzureEnvironment AzureUSGovernment -ExchangeEnvironmentName O365USGovDoD
China
Connect-Maester -Environment China -AzureEnvironment AzureChinaCloud -ExchangeEnvironmentName O365China
Germany
Connect-Maester -Environment Germany
Connect using a custom application
You can use Connect-Maester to connect to Microsoft Graph using a custom application by specifying the -GraphClientId parameter. This is useful if you wish to use a custom application for Maester instead of using the default Graph PowerShell application.
Connect-Maester -GraphClientId 'f45ec3ad-32f0-4c06-8b69-47682afe0216'
To learn more about how to create a custom application for Microsoft Graph PowerShell see Use delegated access with a custom application for Microsoft Graph PowerShell.