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 and Exchange Online.
SYNTAX
Connect-Maester [-SendMail] [-SendTeamsMessage] [-Privileged] [-UseDeviceCode] [[-Environment] <String>]
[[-AzureEnvironment] <String>] [[-ExchangeEnvironmentName] <String>] [[-TeamsEnvironmentName] <String>]
[[-Service] <String[]>] [[-TenantId] <String>] [[-GraphClientId] <String>]
[-ProgressAction <ActionPreference>] [<CommonParameters>]
DESCRIPTION
Use this cmdlet to connect to Microsoft Graph and the Microsoft 365 services that Maester can assess. It attempts to connect to all services by default: Microsoft Graph, Azure, Exchange Online, and Microsoft Teams.
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 to all Microsoft services that Maester is able to assess: Microsoft Graph, Azure, Exchange Online, Exchange Online Security & Compliance, and Microsoft Teams.
EXAMPLE 2
Connect-Maester -Service Graph,Teams
Connects to Microsoft Graph and Microsoft Teams.
EXAMPLE 3
Connect-Maester -Service Azure,Graph
Connects to Microsoft Graph and Azure.
EXAMPLE 4
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 5
Connect-Maester -SendMail
Connects to Microsoft Graph with the Mail.Send scope.
EXAMPLE 6
Connect-Maester -SendTeamsMessage
Connects to Microsoft Graph with the ChannelMessage.Send scope.
EXAMPLE 7
Connect-Maester -Privileged
Connects to Microsoft Graph with additional privileged scopes such as RoleEligibilitySchedule.ReadWrite.Directory that are required for querying global admin roles in Privileged Identity Management.
EXAMPLE 8
Connect-Maester -Environment USGov -AzureEnvironment AzureUSGovernment -ExchangeEnvironmentName O365USGovGCCHigh
Connects to US Government environments for Microsoft Graph, Azure, and Exchange Online.
EXAMPLE 9
Connect-Maester -Environment USGovDoD -AzureEnvironment AzureUSGovernment -ExchangeEnvironmentName O365USGovDoD
Connects to US Department of Defense (DoD) environments for Microsoft Graph, Azure, and Exchange Online.
EXAMPLE 10
Connect-Maester -Environment China -AzureEnvironment AzureChinaCloud -ExchangeEnvironmentName O365China
Connects to China environments for Microsoft Graph, Azure, and Exchange Online.
EXAMPLE 11
Connect-Maester -GraphClientId 'f45ec3ad-32f0-4c06-8b69-47682afe0216'
Connects using a custom application with client ID f45ec3ad-32f0-4c06-8b69-47682afe0216
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 admin 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 Azure and EXO. Default is Graph.
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/en-us/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
-ProgressAction
{{ Fill ProgressAction Description }}
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.