# Connect-Maester

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.

Source: https://maester.dev/docs/commands/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

```powershell
Connect-Maester [-SendMail] [-SendTeamsMessage] [-Privileged] [-IncludePreview] [-UseDeviceCode]
 [[-Environment] <String>] [[-AzureEnvironment] <String>] [[-ExchangeEnvironmentName] <String>]
 [[-TeamsEnvironmentName] <String>] [[-Service] <String[]>] [[-ServiceSetting] <Hashtable>]
 [[-TenantId] <String>] [[-GraphClientId] <String>] [[-ClientTimeout] <Double>]
 [[-SharePointClientId] <String>] [[-SharePointAdminUrl] <String>]
 [[-SharePointCertificateThumbprint] <String>] [[-GitHubOrganization] <String>]
 [[-AzureDevOpsOrganization] <String>] [[-ActiveDirectoryForest] <Object>] [[-ActiveDirectoryDomain] <Object>]
 [[-ActiveDirectoryServer] <Object>] [[-ActiveDirectoryCredential] <PSCredential>]
 [[-ActiveDirectoryAuthMode] <String>] [[-ActiveDirectoryTlsMode] <String>]
 [-ActiveDirectorySkipCertificateCheck] [-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, Azure DevOps 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

```powershell
Connect-Maester
```

Connects only to Microsoft Graph by default.

### EXAMPLE 2

```powershell
Connect-Maester -Service Graph,Teams
```

Connects to Microsoft Graph and Microsoft Teams.

### EXAMPLE 3

```powershell
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

```powershell
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

```powershell
Connect-Maester -Service Graph,AzureDevOps -AzureDevOpsOrganization 'contoso'
```

Connects to Microsoft Graph and the Azure DevOps organization 'contoso' for the Azure DevOps (AZDO) tests.
The Azure DevOps connection needs the community ADOPS module (Install-Module ADOPS -Scope CurrentUser), which Maester does not install.
When an Az context exists (for example after Connect-Maester -Service Azure), its access token is passed to Connect-ADOPS; otherwise Connect-ADOPS signs in interactively.
The organization can also be set with AzureDevOpsOrganization in maester-config.json.

### EXAMPLE 6

```powershell
Connect-Maester -Service Azure,Graph
```

Connects to Microsoft Graph and Azure.

### EXAMPLE 7

```powershell
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 8

```powershell
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 9

```powershell
Connect-Maester -SendMail
```

Connects to Microsoft Graph with the Mail.Send scope.

### EXAMPLE 10

```powershell
Connect-Maester -SendTeamsMessage
```

Connects to Microsoft Graph with the ChannelMessage.Send scope.

### EXAMPLE 11

```powershell
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 12

```powershell
Connect-Maester -IncludePreview
```

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

### EXAMPLE 13

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

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

### EXAMPLE 14

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

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

### EXAMPLE 15

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

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

### EXAMPLE 16

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

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

### EXAMPLE 17

```powershell
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 18

```powershell
'
```

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 19

```powershell
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.

### EXAMPLE 20

```powershell
Connect-Maester -Service Graph,CNT.GoogleWorkspace -ServiceSetting @{ 'CNT.GoogleWorkspace' = @{ Domain = 'contoso.com' } }
```

Connects to Microsoft Graph and to the service of an installed Maester Pack, through the pack's connector.
Get-MtConnector lists the services of the installed packs.

## PARAMETERS

### -SendMail

If specified, the cmdlet will include the scope to send email (Mail.Send).

```yaml
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).

```yaml
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.

```yaml
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.

```yaml
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.

```yaml
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.

```yaml
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.

```yaml
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.

```yaml
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.

```yaml
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, Azure DevOps, Dataverse (for Copilot Studio tests), EXO, GitHub, and SharePoint Online.
Default is Graph.
Active Directory, Azure DevOps and GitHub are not included in All and must be explicitly specified.
The service of an installed Maester Pack's connector, such as CNT.GoogleWorkspace, connects through that pack; pack services are never included in All.

```yaml
Type: String[]
Parameter Sets: (All)
Aliases:

Required: False
Position: 5
Default value: Graph
Accept pipeline input: False
Accept wildcard characters: False
```

### -ServiceSetting

Settings for the connectors of Maester Packs, by service: @\{ 'CNT.GoogleWorkspace' = @\{ Domain = 'contoso.com' \} \}.
With one pack service in -Service, the settings can be given directly: @\{ Domain = 'contoso.com' \}.
They win over
Connections.&lt;Service&gt; in maester-config.json and over MAESTER_&lt;SERVICE&gt;_&lt;SETTING&gt; environment variables.

```yaml
Type: Hashtable
Parameter Sets: (All)
Aliases:

Required: False
Position: 6
Default value: @{}
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.

```yaml
Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 7
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

```yaml
Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 8
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.

```yaml
Type: Double
Parameter Sets: (All)
Aliases:

Required: False
Position: 9
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.

```yaml
Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 10
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.

```yaml
Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 11
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.

```yaml
Type: String
Parameter Sets: (All)
Aliases:

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

### -GitHubOrganization

The GitHub organization login name to connect to when Service includes GitHub.

```yaml
Type: String
Parameter Sets: (All)
Aliases:

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

### -AzureDevOpsOrganization

The Azure DevOps organization to connect to when Service includes AzureDevOps, as a name ('contoso') or URL ('https://dev.azure.com/contoso').
Falls back to AzureDevOpsOrganization in maester-config.json.

```yaml
Type: String
Parameter Sets: (All)
Aliases:

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

### -ActiveDirectoryForest

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

```yaml
Type: Object
Parameter Sets: (All)
Aliases:

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

### -ActiveDirectoryDomain

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

```yaml
Type: Object
Parameter Sets: (All)
Aliases:

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

### -ActiveDirectoryServer

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

```yaml
Type: Object
Parameter Sets: (All)
Aliases:

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

### -ActiveDirectoryCredential

The credential used for the Active Directory LDAP connection.

```yaml
Type: PSCredential
Parameter Sets: (All)
Aliases:

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

### -ActiveDirectoryAuthMode

The authentication mode used for the Active Directory LDAP connection.

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

Required: False
Position: 19
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.

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

Required: False
Position: 20
Default value: Auto
Accept pipeline input: False
Accept wildcard characters: False
```

### -ActiveDirectorySkipCertificateCheck

Skip certificate validation for the Active Directory LDAP connection.
Intended for test environments only.

```yaml
Type: SwitchParameter
Parameter Sets: (All)
Aliases:

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

```yaml
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](http://go.microsoft.com/fwlink/?LinkID=113216).

## INPUTS

## OUTPUTS

## NOTES

## RELATED LINKS

[https://maester.dev/docs/commands/Connect-Maester](https://maester.dev/docs/commands/Connect-Maester)