Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Connect the Zero Trust Assessment to the Microsoft 365 and Azure services you want to assess. Use interactive sign-in for a user-run assessment or certificate authentication for app-only access without storing user credentials. Prepare the module and service permissions before connecting.
These instructions describe the development connector. App-only support and connection options can differ between published packages.
Prerequisites
- Completion of the assessment installation.
- The interactive user access or application permissions and roles for the services and resource scopes to assess.
- For app-only access, an app registration and a certificate with its private key available to the assessment machine, as described in the certificate procedure in the following section.
Connect interactively
Choose the tenant explicitly to reduce the risk of assessing the wrong organization.
Activate eligible roles through Microsoft Entra Privileged Identity Management before connecting. Arrange consent separately from the assessment user's runtime roles.
Connect to the tenant you want to assess, replacing the example domain:
Connect-ZtAssessment -Tenant contoso.onmicrosoft.comComplete the service prompts and review the connection status messages. Services authenticate separately, but cached sessions and single sign-on can reduce prompts. SharePoint interactive authentication uses the system browser.
Reconnect after changing access or context. Use
-Forcewhen you need to refresh existing connections.
-Tenant is an alias for -TenantId and accepts a tenant GUID or verified domain name for interactive sign-in. If you don't include this parameter, Microsoft Graph uses an organizations context and derives the tenant from sign-in.
Consent is requested when the application lacks the required grants. New scopes can require consent again.
Select services and connection options
By default, Connect-ZtAssessment connects to all available services. Select services only after considering the effect on assessment coverage.
Identify the services you want to assess:
Service selector Underlying command GraphConnect-MgGraph.AzureConnect-AzAccount.AipServiceConnect-AipService.SharePointOnlineConnect-SPOService.ExchangeOnlineConnect-ExchangeOnline.SecurityComplianceConnect-IPPSSession.Use
-Serviceto select services. For example,Connect-ZtAssessment -Tenant contoso.onmicrosoft.com -Service Graph,Azureselects Graph and Azure. The connector adds Graph first if it isn't already connected.Review connection outcomes before running the assessment. Skipping Azure limits Infrastructure, Network, and security operations (SecOps) coverage, not just audit and sign-in log export checks.
Use these additional options when needed:
| Option | Purpose or constraint |
|---|---|
-Force |
Refresh existing connections after access or context changes. |
-SharePointAdminUrl |
Supply the tenant admin URL if the connector can't infer it. |
-UserPrincipalName |
Supply the user identity for Security & Compliance. |
-Environment, -ExchangeEnvironmentName |
Select cloud environments. Use the values documented by Get-Help Connect-ZtAssessment -Full. |
-UseDeviceCode |
Not an all-service unattended mode. Security & Compliance doesn't support that flow in this connector. SharePoint and Azure Information Protection (AIP) have their own authentication behavior. |
Connect with an application certificate
Authorize the application identity at each service, not just the person who configures it.
Register an application in the target tenant. Record its application/client ID and tenant GUID.
Configure and grant consent for the app-only permissions. Assign workload and Azure resource roles to the service principal.
Upload the certificate's public key to the app registration. Install the corresponding certificate and private key in the local user's certificate store on the assessment machine. For Exchange, follow the certificate-provider requirements in the app-only authentication guide.
If connecting to SharePoint, provide an exportable private key. The current connector passes a temporary certificate file into its Windows PowerShell compatibility session. Protect the key and follow any temporary-file cleanup warning.
Connect with the client ID, tenant GUID, and certificate thumbprint. Replace the placeholders with your values:
Connect-ZtAssessment -ClientId '<application-id>' -TenantId '<tenant-guid>' -Certificate '<certificate-thumbprint>' -Service AllReview each service's connection status and any authorization errors before running the assessment.
Both -ClientId and -TenantId are required with -Certificate. Don't combine certificate authentication with -UseDeviceCode. For cross-service app-only connections, use the tenant GUID rather than assuming every service accepts a domain name. The connector resolves the initial .onmicrosoft.com domain for Exchange and Security & Compliance.
App-only coverage depends on the package, dependency versions, permissions, and commands used by individual checks. Missing connections produce service-related skips; other authorization errors can appear in test diagnostics. Review those outcomes before treating an unattended run as complete.