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] [-IncludePreview] [-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>]
 [[-ActiveDirectoryForest] <Object>] [[-ActiveDirectoryDomain] <Object>] [[-ActiveDirectoryServer] <Object>]
 [[-ActiveDirectoryCredential] <PSCredential>] [[-ActiveDirectoryAuthMode] <String>]
 [[-ActiveDirectoryTlsMode] <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.

When it finishes, Connect-Maester shows a summary table with the status of each service it tried (Connected, Skipped, Failed or Not installed) and a short detail. Use -Verbose to see the step-by-step messages for each connection.

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 -IncludePreview

Connects to Microsoft Graph with the additional scopes required by preview tests.

EXAMPLE 12

Connect-Maester -Environment USGov -AzureEnvironment AzureUSGovernment -ExchangeEnvironmentName O365USGovGCCHigh

Connects to US Government environments for Microsoft Graph, Azure, and Exchange Online.

EXAMPLE 13

Connect-Maester -Environment USGovDoD -AzureEnvironment AzureUSGovernment -ExchangeEnvironmentName O365USGovDoD

Connects to US Department of Defense (DoD) environments for Microsoft Graph, Azure, and Exchange Online.

EXAMPLE 14

Connect-Maester -Environment China -AzureEnvironment AzureChinaCloud -ExchangeEnvironmentName O365China

Connects to China environments for Microsoft Graph, Azure, and Exchange Online.

EXAMPLE 15

Connect-Maester -GraphClientId 'f45ec3ad-32f0-4c06-8b69-47682afe0216'

Connects using a custom application with client ID f45ec3ad-32f0-4c06-8b69-47682afe0216

EXAMPLE 16

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 17

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 18

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

-IncludePreview

If specified, the cmdlet will include scopes required by preview tests.

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

-ActiveDirectoryForest

The Active Directory forest DNS name to discover when Service includes ActiveDirectory.

Type: Object
Parameter Sets: (All)
Aliases:

Required: False
Position: 13
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ActiveDirectoryDomain

The Active Directory domain DNS name to discover when Service includes ActiveDirectory.

Type: Object
Parameter Sets: (All)
Aliases:

Required: False
Position: 14
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ActiveDirectoryServer

The Active Directory domain controller to connect to when Service includes ActiveDirectory.

Type: Object
Parameter Sets: (All)
Aliases:

Required: False
Position: 15
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ActiveDirectoryCredential

The credential used for the Active Directory LDAP connection.

Type: PSCredential
Parameter Sets: (All)
Aliases:

Required: False
Position: 16
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-ActiveDirectoryAuthMode

The authentication mode used for the Active Directory LDAP connection.

Type: String
Parameter Sets: (All)
Aliases: AuthMode

Required: False
Position: 17
Default value: Negotiate
Accept pipeline input: False
Accept wildcard characters: False

-ActiveDirectoryTlsMode

The TLS mode used for the Active Directory LDAP connection. Auto tries LDAPS before StartTLS.

Type: String
Parameter Sets: (All)
Aliases: TlsMode

Required: False
Position: 18
Default value: Auto
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.

INPUTS

OUTPUTS

NOTES

https://maester.dev/docs/commands/Connect-Maester