Skip to main content
Version: 2.0.1 (preview)

Connect-Maester Advanced

Overview​

There are two main methods of authenticating sessions for use with Maester:

  • Within the Maester module
  • Within the respective modules for the tests

Module Integrations​

The Maester module integrates with the following modules:

  • Microsoft.Graph.Authentication
  • Az.Accounts
  • ExchangeOnlineManagement
  • MicrosoftTeams

Within the Maester module​

tip

Recommended for interactive use

The Maester module includes Connect-Maester to provide coverage for common scenarios. The parameter set options afford a user of the module the ability to test with common interactive methods. The Microsoft Graph API is the default authentication service, and more specifically the Microsoft Graph PowerShell SDK. Coverage for tests shipping with Maester have at least one option available in general.

The objective of the Maester module is not to replace or consolidate the authentication options across the many possible testing sources.

Within the respective modules for the tests​

Recommended for automation use

The Maester module provides a framework for creating, executing, and reporting on configuration state using tests. Each test can rely on one or more sources to perform validation. Each source a test validates may be available without authentication (e.g., Domain Name System) or may require authentication to a specific environment (e.g., Microsoft Graph API).

The recommendation for authenticating to modules necessary to support tests for the most extensibility is to authenticate within those source modules and running Invoke-Maester with the -SkipGraphConnect property.

As an example, connecting to the Microsoft Graph PowerShell SDK module as a managed identity and then running Maester.

Running Connect-Maester is not required to use Invoke-Maester.

Connect-MgGraph -Identity -NoWelcome
Invoke-Maester -SkipGraphConnect -NonInteractive

The following diagram provides a general overview of command dependency relationships. You can extend Maester with your own tests that leverage other modules as may be beneficial. There is no dependency for your own tests to rely on the Connect-Maester capabilities.

You can write tests that expand Maester to validate the configuration state of infrastructure in the cloud, on-premises, and entirely unrelated to Microsoft products.

For use with the Maester tests the following provides an overview of creating the necessary service principal.

Create an Entra Application​

  • Open Entra admin center > Identity > Applications > App registrations
  • Select New registration
  • Enter a name for the application (e.g. Maester DevOps Account)
  • Select Register

Grant permissions to Microsoft Graph​

  • Open the application you created in the previous step
  • Select API permissions > Add a permission
  • Select Microsoft Graph > Application permissions
  • Search for each of the permissions and check the box next to each permission:
    • DeviceManagementConfiguration.Read.All
    • DeviceManagementManagedDevices.Read.All
    • DeviceManagementRBAC.Read.All
    • DeviceManagementServiceConfig.Read.All
    • Directory.Read.All
    • DirectoryRecommendations.Read.All
    • IdentityRiskEvent.Read.All
    • OnPremDirectorySynchronization.Read.All
    • Policy.Read.All
    • Policy.Read.ConditionalAccess
    • PrivilegedAccess.Read.AzureAD
    • Reports.Read.All
    • ReportSettings.Read.All
    • RoleEligibilitySchedule.Read.Directory
    • RoleManagement.Read.All
    • SecurityIdentitiesSensors.Read.All
    • SecurityIdentitiesHealth.Read.All
    • SharePointTenantSettings.Read.All
    • ThreatHunting.Read.All
    • UserAuthenticationMethod.Read.All
  • Optionally, search for each of the permissions if you want to allow privileged permissions:
    • ReportSettings.ReadWrite.All
      • Required to disable report obfuscation
  • Select Add permissions
  • Select Grant admin consent for [your organization]
  • Select Yes to confirm
(Optional) Grant permissions to Exchange Online

(Optional) Grant permissions to Exchange Online​

The Exchange Online Role Based Access Control (RBAC) implementation utilizes service specific roles that apply to an application and the below configuration allows the authorization chain to the App Registration you created in the previous steps.

The Exchange Online permissions are necessary to support tests that validate Exchange Online configurations, such as the CISA tests.

  • Open the application you created in the previous step
  • Select API permissions > Add a permission
  • Select APIs that my organization uses > search for Office 365 Exchange Online > Application permissions
  • Search for Exchange.ManageAsApp
  • Select Add permissions
  • Select Grant admin consent for [your organization]
  • Select Yes to confirm
  • Connect to the Exchange Online Management tools and use the following to set the appropriate permissions:
New-ServicePrincipal -AppId <Application ID> -ObjectId <Object ID> -DisplayName <Name>
New-ManagementRoleAssignment -Role "View-Only Configuration" -App <DisplayName from previous command>
(Optional) Grant permissions to Teams

(Optional) Grant permissions to Teams​

The Teams Role Based Access Control (RBAC) implementation utilizes service specific roles that apply to an application and the below configuration allows the authorization chain to the App Registration you created in the previous steps.

The Teams permissions are necessary to support tests that validate Teams configurations.

  • Open Roles and administrators
  • Search and select Teams Reader
  • Select Add assigment
  • Select No member selected
  • Search for the name of previously created application
  • Select previously created application and select Select to confirm
  • Select Next to confirm
  • Ensure that Active and Permanently assigned are ticked
  • Enter Justification
  • Select Assign to confirm
(Optional) Grant permissions to Azure

(Optional) Grant permissions to Azure​

The Azure Role Based Access Control (RBAC) implementation utilizes Uniform Resource Names (URN) with a "/" separator for heirarchical scoping. There exists resources within the root (e.g., "/") scope that Microsoft retains strict control over by limiting supported interactions. As a Global Administrator you can elevate access to become authorized for these limited interactions.

The Azure RBAC permissions are necessary to support tests that validate Azure configurations, such as the CISA tests.

The following PowerShell script will enable you, with a Global Administrator role assignment, to:

  • Identify the Service Principal Object ID that will be authorized as a Reader (Enterprise app Object ID)
  • Install the necessary Az module and prompt for connection
  • Elevate your account access to the root scope
  • Create a role assignment for Reader access over the Root Scope
  • Create a role assignment for Reader access over the Entra ID (i.e., aadiam provider)
  • Identify the role assignment authorizing your account access to the root scope
  • Delete the root scope role assignment for your account
$servicePrincipal = "<Object ID of the Entra App>"
$subscription = "<Subscription ID>"
Install-Module Az.Accounts -Force
Install-Module Az.Resources -Force
Connect-AzAccount
#Elevate to root scope access
$elevateAccess = Invoke-AzRestMethod -Path "/providers/Microsoft.Authorization/elevateAccess?api-version=2015-07-01" -Method POST

#Assign permissions to Enterprise App
New-AzRoleAssignment -ObjectId $servicePrincipal -Scope "/" -RoleDefinitionName "Reader" -ObjectType "ServicePrincipal"
New-AzRoleAssignment -ObjectId $servicePrincipal -Scope "/providers/Microsoft.aadiam" -RoleDefinitionName "Reader" -ObjectType "ServicePrincipal"

#Remove root scope access
$assignment = Get-AzRoleAssignment -RoleDefinitionId 18d7d88d-d35e-4fb5-a5c3-7773c20a72d9|?{$_.Scope -eq "/" -and $_.SignInName -eq (Get-AzContext).Account.Id}
$deleteAssignment = Invoke-AzRestMethod -Path "$($assignment.RoleAssignmentId)?api-version=2018-07-01" -Method DELETE

Authenticating Across Tenants​

You may have a need to use Maester with multiple tenants. The Maester tests enable you to accomplish this, but it is best to authenticate within the respective modules for the tests you wish to run.

Resource URLs vary by Azure cloud environment

The resource URLs used with Get-AzAccessToken differ depending on your Azure cloud. The examples below use Azure Global (Commercial). Replace them with the appropriate URLs for your environment:

ServiceGlobalUS Gov (GCC High / DoD)China (21Vianet)
Microsoft Graphhttps://graph.microsoft.comhttps://graph.microsoft.ushttps://microsoftgraph.chinacloudapi.cn
Exchange Onlinehttps://outlook.office365.comhttps://outlook.office365.ushttps://partner.outlook.cn
Security & Compliance (IPPS)https://ps.compliance.protection.outlook.comhttps://ps.compliance.protection.office365.ushttps://ps.compliance.protection.partner.outlook.cn

Microsoft Graph PowerShell SDK Module​

The Microsoft Graph PowerShell SDK Module provides many options for authenticating.

If you already have an authenticated Azure context, you can use Get-AzAccessToken to obtain an OAuth token and pass it directly to Connect-MgGraph.

$graphToken = Get-AzAccessToken -ResourceUrl 'https://graph.microsoft.com' -AsSecureString
Connect-MgGraph -AccessToken $graphToken.Token -NoWelcome

Certificate-based authentication​

Below is an example of using a X.509 Certificate private key file, $cert, to authenticate to $tenantId as the $applicationId service principal.

#$applicationId = "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx"
#$tenantId = "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx"
#$b64 = Get-Content .\path\to\cert.pfx -Raw
#$b64 = Get-AzKeyVaultSecret -VaultName $keyVaultName -Name $applicationDisplayName -AsPlainText
#$bytes = [Convert]::FromBase64String($b64)
#$cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($bytes)

Connect-MgGraph -AppId $applicationId -Certificate $cert -TenantId $tenantId -NoWelcome

Microsoft Azure Accounts PowerShell Module​

The Microsoft Azure Accounts PowerShell Module provides many options for authenticating. Below is an example of using a X.509 Certificate private key file to authenticate to $tenantId as the $applicationId service principal.

#$applicationId = "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx"
#$tenantId = "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx"

Connect-AzAccount -ServicePrincipal -ApplicationId $applicationId -TenantId $tenantId -CertificatePath /cert.pfx

Microsoft Exchange Online and Security & Compliance PowerShell Modules​

The Microsoft Exchange Online and Security & Compliance PowerShell Modules provide many options for authenticating.

If you already have an authenticated Azure context (e.g., managed identity, workload identity federation, or Connect-AzAccount), you can use Get-AzAccessToken to obtain OAuth tokens and pass them directly. This eliminates the need for certificate management.

#$clientId = "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx"
#$tenantId = "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx"
#$moera = "contoso.onmicrosoft.com"

# Exchange Online
$outlookToken = ConvertFrom-SecureString -SecureString (Get-AzAccessToken -ResourceUrl 'https://outlook.office365.com' -AsSecureString).Token -AsPlainText -Force
Connect-ExchangeOnline -AccessToken $outlookToken -AppId $clientId -Organization $tenantId -ShowBanner:$false

# Security & Compliance (IPPS)
$isspToken = ConvertFrom-SecureString -SecureString (Get-AzAccessToken -ResourceUrl 'https://ps.compliance.protection.outlook.com' -AsSecureString).Token -AsPlainText -Force
Connect-IPPSSession -AccessToken $isspToken -Organization $moera

Connect-ExchangeOnline accepts the tenant ID as the -Organization value, while Connect-IPPSSession requires the tenant's Microsoft Online Email Routing Address (MOERA), e.g., contoso.onmicrosoft.com.

Certificate-based authentication​

Below is an example of using a X.509 Certificate private key file, $cert, to authenticate to $tenantId as the $applicationId service principal.

These modules don't reference the tenant ID GUID for authentication, they instead use the tenant's Microsoft Online Email Routing Address (MOERA).

#$applicationId = "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx"
#$b64 = Get-Content .\path\to\cert.pfx -Raw
#$b64 = Get-AzKeyVaultSecret -VaultName $keyVaultName -Name $applicationDisplayName -AsPlainText
#$bytes = [Convert]::FromBase64String($b64)
#$cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($bytes)
#$domains = Invoke-MgGraphRequest -Uri https://graph.microsoft.com/v1.0/domains
#$moera = ($domains.value|?{$_.isInitial}).id

Connect-ExchangeOnline -Certificate $cert -AppID $applicationId -Organization $moera -ShowBanner:$false
Connect-IPPSSession -Certificate $cert -AppID $applicationId -Organization $moera -ShowBanner:$false

Microsoft Teams PowerShell Module​

The Microsoft Teams PowerShell Module supports both interactive and non-interactive authentication methods.

Connect-MicrosoftTeams accepts two access tokens via the -AccessTokens parameter: a Microsoft Graph token and a Teams-specific token. This approach works well when you already have an authenticated Azure context.

$graphToken = Get-AzAccessToken -ResourceUrl 'https://graph.microsoft.com' -AsSecureString
$teamsToken = Get-AzAccessToken -ResourceUrl '48ac35b8-9aa8-4d74-927d-1f4a14a0b239' -AsSecureString

$tokens = @(
    (ConvertFrom-SecureString -SecureString $graphToken.Token -AsPlainText -Force),
    (ConvertFrom-SecureString -SecureString $teamsToken.Token -AsPlainText -Force)
)

Connect-MicrosoftTeams -AccessTokens $tokens

The resource URL 48ac35b8-9aa8-4d74-927d-1f4a14a0b239 is the application ID for the Microsoft Teams PowerShell module.

Interactive and certificate-based authentication​

For interactive sessions, you can use the standard login prompt. For non-interactive use with certificates, service principal authentication is supported.

# Interactive
Connect-MicrosoftTeams

# Non-Interactive (Service Principal)
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2("C:\exampleCert.pfx",$password)
Connect-MicrosoftTeams -Certificate $cert -ApplicationId $applicationId -TenantId $tenantId