Connect-Maester
SYNOPSIS​
Helper method to connect to Microsoft Graph using Connect-MgGraph with the required permission scopes as well as other services such as Azure, Exchange Online, and GitHub.
SYNTAX​
Connect-Maester [-SendMail] [-SendTeamsMessage] [-Privileged] [-UseDeviceCode] [[-Environment] <String>]
[[-AzureEnvironment] <String>] [[-ExchangeEnvironmentName] <String>] [[-TeamsEnvironmentName] <String>]
[[-Service] <String[]>] [[-TenantId] <String>] [[-GraphClientId] <String>] [[-ClientTimeout] <Double>]
[[-SharePointClientId] <String>] [[-SharePointAdminUrl] <String>]
[[-SharePointCertificateThumbprint] <String>] [[-GitHubOrganization] <String>]
[-ProgressAction <ActionPreference>] [<CommonParameters>]
DESCRIPTION​
Use this cmdlet to connect to Microsoft Graph and the Microsoft 365 services that Maester can assess. By default, it connects to Microsoft Graph. Use -Service All to connect to Microsoft 365 services, including Microsoft Graph, Azure, Exchange Online, Security & Compliance, Microsoft Teams, SharePoint Online, and Dataverse.
Non-Microsoft 365 services such as Active Directory and GitHub are not included in -Service All and must be explicitly specified.
This command is completely optional if you are already connected to Microsoft Graph and other services using Connect-MgGraph with the required scopes.
Connect-MgGraph -Scopes (Get-MtGraphScope)
EXAMPLES​
EXAMPLE 1​
Connect-Maester
Connects only to Microsoft Graph by default.
EXAMPLE 2​
Connect-Maester -Service Graph,Teams
Connects to Microsoft Graph and Microsoft Teams.
EXAMPLE 3​
Connect-Maester -Service Graph,GitHub -GitHubOrganization 'mycompany'
Connects to Microsoft Graph and GitHub. GitHub sign-in is handled by Connect-MtGitHub using the Maester GitHub App device flow by default, including guided organization app install/approval when required. Automation can still use MAESTER_GITHUB_TOKEN or GH_TOKEN.
EXAMPLE 4​
Connect-Maester -Service ActiveDirectory
Validates connectivity to the current Active Directory domain. Active Directory must be explicitly selected and is not included in -Service All.
EXAMPLE 5​
Connect-Maester -Service Azure,Graph
Connects to Microsoft Graph and Azure.
EXAMPLE 6​
Connect-Maester -Service Dataverse,Graph
Connects to Microsoft Graph and the Dataverse API for Copilot Studio security tests. The Dataverse connection uses the Az.Accounts module. The Copilot Studio environment is auto-discovered via the Global Discovery Service, or can be explicitly set with DataverseEnvironmentUrl in maester-config.json.
EXAMPLE 7​
Connect-Maester -UseDeviceCode
Connects to Microsoft Graph and Azure using the device code flow. This will open a browser window to prompt for authentication.
EXAMPLE 8​
Connect-Maester -SendMail
Connects to Microsoft Graph with the Mail.Send scope.
EXAMPLE 9​
Connect-Maester -SendTeamsMessage
Connects to Microsoft Graph with the ChannelMessage.Send scope.
EXAMPLE 10​
Connect-Maester -Privileged
Connects to Microsoft Graph with additional privileged scopes such as RoleEligibilitySchedule.ReadWrite.Directory that are required for querying Global Administrator roles in Privileged Identity Management.
EXAMPLE 11​
Connect-Maester -Environment USGov -AzureEnvironment AzureUSGovernment -ExchangeEnvironmentName O365USGovGCCHigh
Connects to US Government environments for Microsoft Graph, Azure, and Exchange Online.
EXAMPLE 12​
Connect-Maester -Environment USGovDoD -AzureEnvironment AzureUSGovernment -ExchangeEnvironmentName O365USGovDoD
Connects to US Department of Defense (DoD) environments for Microsoft Graph, Azure, and Exchange Online.
EXAMPLE 13​
Connect-Maester -Environment China -AzureEnvironment AzureChinaCloud -ExchangeEnvironmentName O365China
Connects to China environments for Microsoft Graph, Azure, and Exchange Online.
EXAMPLE 14​
Connect-Maester -GraphClientId 'f45ec3ad-32f0-4c06-8b69-47682afe0216'
Connects using a custom application with client ID f45ec3ad-32f0-4c06-8b69-47682afe0216
EXAMPLE 15​
Connect-Maester -ClientTimeout 900
Connects to Microsoft Graph with an HTTP client timeout of 900 seconds. This can be useful for long-running tests in large tenants.
EXAMPLE 16​
'
Connects to Microsoft Graph and SharePoint Online using the specified PnP app registration. The SharePoint admin URL is auto-discovered from the tenant's initial domain via the Graph API. Optionally, specify -SharePointAdminUrl to override the auto-discovered URL (e.g. for custom domain or government cloud tenants).
EXAMPLE 17​
Connect-Maester -Service SharePointOnline -SharePointClientId 'f45ec3ad-32f0-4c06-8b69-47682afe0216' -SharePointAdminUrl 'https://contoso-admin.sharepoint.com'
Connects to SharePoint Online using the specified client ID and admin URL.
PARAMETERS​
-SendMail​
If specified, the cmdlet will include the scope to send email (Mail.Send).
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-SendTeamsMessage​
If specified, the cmdlet will include the scope to send a channel message in Teams (ChannelMessage.Send).
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-Privileged​
If specified, the cmdlet will include the scopes for read write API endpoints. This is currently required for querying Global Administrator roles in PIM.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-UseDeviceCode​
If specified, the cmdlet will use the device code flow to authenticate to Graph and Azure. This will open a browser window to prompt for authentication and is useful for non-interactive sessions and on Windows when SSO is not desired.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False
-Environment​
The environment to connect to. Default is Global. Supported values include China, Germany, Global, USGov, USGovDoD.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 1
Default value: Global
Accept pipeline input: False
Accept wildcard characters: False
-AzureEnvironment​
The Azure environment to connect to. Default is AzureCloud. Supported values include AzureChinaCloud, AzureCloud, AzureUSGovernment.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 2
Default value: AzureCloud
Accept pipeline input: False
Accept wildcard characters: False
-ExchangeEnvironmentName​
The Exchange environment to connect to. Default is O365Default. Supported values include O365China, O365Default, O365GermanyCloud, O365USGovDoD, O365USGovGCCHigh.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 3
Default value: O365Default
Accept pipeline input: False
Accept wildcard characters: False
-TeamsEnvironmentName​
The Teams environment to connect to. Default is O365Default.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 4
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-Service​
The services to connect to such as Active Directory, Azure, Dataverse (for Copilot Studio tests), EXO, GitHub, and SharePoint Online. Default is Graph. Active Directory and GitHub are not included in All and must be explicitly specified.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: 5
Default value: Graph
Accept pipeline input: False
Accept wildcard characters: False
-TenantId​
The Tenant ID to connect to, if not specified the sign-in user's default tenant is used.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 6
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-GraphClientId​
The Client ID of the app to connect to for Graph. If not specified, the default Graph PowerShell CLI enterprise app will be used. Reference on how to create an enterprise app: https://learn.microsoft.com/powershell/microsoftgraph/authentication-commands?view=graph-powershell-1.0#use-delegated-access-with-a-custom-application-for-microsoft-graph-powershell
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 7
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ClientTimeout​
The Microsoft Graph HTTP client timeout in seconds. When omitted, the Microsoft Graph PowerShell SDK default is used.
Type: Double
Parameter Sets: (All)
Aliases:
Required: False
Position: 8
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False
-SharePointClientId​
The Client ID of the PnP Entra ID app for SharePoint Online. Required when Service includes SharePointOnline. Use Register-PnPEntraIDAppForInteractiveLogin to create a dedicated app, or reuse an existing Maester app registration by adding an http://localhost redirect URI and AllSites.FullControl delegated SharePoint permission.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 9
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-SharePointAdminUrl​
The SharePoint admin center URL to connect to when using the SharePointOnline service (e.g. https://contoso-admin.sharepoint.com). If not specified, the URL is auto-discovered from the tenant's initial domain via the Microsoft Graph API.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 10
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-SharePointCertificateThumbprint​
The certificate thumbprint for app-only authentication to SharePoint Online. Use together with -SharePointClientId and -TenantId for non-interactive/automation scenarios. The certificate must be installed in the current user's certificate store.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 11
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-GitHubOrganization​
The GitHub organization login name to connect to when Service includes GitHub.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 12
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
-ProgressAction​
Determines how PowerShell responds to progress updates generated by a script, cmdlet, or provider, such as the progress bars generated by Write-Progress.
Type: ActionPreference
Parameter Sets: (All)
Aliases: proga
Required: False
Position: Named
Default value: None
Accept pipeline input: False
Accept wildcard characters: False
CommonParameters​
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.