Skip to content

Latest commit

 

History

History
106 lines (68 loc) · 7.83 KB

noninteractive.md

File metadata and controls

106 lines (68 loc) · 7.83 KB

Non-interactive Permissions

Running ScubaGear in a non-interactive (automated) fashion requires an application with a service principal identity that has been assigned various permissions and roles, depending upon which M365 products are being tested, and associated with a certificate.

Note

While there are many ways to authenticate with a service principal, ScubaGear only authenticates via a certificate identified by its certificate thumbprint.

Overview

These are the following steps that must be completed:

  • Create a service principal
  • Create a certificate
  • Associate the certificate with the service principal
  • Determining the thumbprint of the certificate

Service Principal

Configuring a service principal is beyond the scope of these instructions, but Microsoft has documentation that may help:

Note

Take note of the AppId and the name of your tenant, as these values will be required to execute ScubaGear in non-interactive mode.

The minimum permissions and roles that must be assigned to the service principal are listed in the table below.

Important

Permissions that have "write" privileges are included in the Power Platform and SharePoint permissions list below. Those permissions are the minimum required by ScubaGear to be able to read admin center configurations for those two services and is a limitation of the underlying APIs of these services. ScubaGear itself does not exercise the use of the write privileges for its assessments.

Product API Permissions Role API Name API APPID
Entra ID Directory.Read.All Microsoft.Graph 00000003-0000-0000-c000-000000000000
Policy.Read.All
PrivilegedAccess.Read.AzureADGroup
PrivilegedEligibilitySchedule.Read.AzureADGroup
RoleManagement.Read.Directory
RoleManagementPolicy.Read.AzureADGroup
User.Read.All
Defender for Office 365 Global Reader
Exchange Online Exchange.ManageAsApp Global Reader Office 365 Exchange Online1 00000002-0000-0ff1-ce00-000000000000
Power Platform (see below)
SharePoint Online Sites.FullControl.All SharePoint1 00000003-0000-0ff1-ce00-000000000000
Microsoft Teams Global Reader

Note

Additional details necessary for GCC High non-interactive authentication are detailed in this section below.1

Certificate Thumbprint

Microsoft has documentation that shows how to get the thumbprint of a certificate using PowerShell.

Once the service principal and certificate thumbprint have been created, ScubaGear's dependencies can be installed.

Power Platform

Power Platform requires additional, one-time setup.

Registration

The application associated with the service principal must be manually registered to Power Platform via interactive authentication with an administrative account before ScubaGear is executed. Microsoft explains the limitations of service principals with Power Platform.

To register the service principal, execute these commands:

# Login interactively with a tenant admin for Power Platform
Add-PowerAppsAccount `
  -Endpoint prod `
  -TenantID 22f22c70-de09-4d21-b82f-af8ad73391d9

Note

When testing GCC tenants, use -Endpoint usgov.

# Register the service principal, giving it the
# same permissions as a tenant admin
New-PowerAppManagementApp -ApplicationId abcdef0123456789abcde01234566789

Note

These commands must be run from an account with the Power Platform Administrator or Global Administrator roles.

Certificate Location

It's helpful to note the following details:

  • Power Platform has a hardcoded expectation that the certificate is located in Cert:\CurrentUser\My.

  • MS Graph has an expectation that the certificate is located either in the client's Cert:\CurrentUser\My or Cert:\LocalMachine\My certificate stores.

Additional GCC High details

This section contains additional, non-interactive authentication details that are required to successfully run ScubaGear against a GCC High tenant.

Defender in GCC High

When running ScubaGear to assess Defender for Office 365 in a GCC High tenant, the Exchange.ManageAsApp must be added as an application permission from both the Microsoft Exchange Online Protection and the Office 365 Exchange Online APIs. This is mentioned in a GCC High application manifest writer's note in this section of the Exchange Online App Only Auth MS Learn documentation.

SharePoint in GCC High

When running ScubaGear to assess SharePoint Online in a GCC High tenant, the Sites.FullControl.All application permission must be added from the GCC High-unique Office 365 SharePoint Online API rather than the commercial-unique SharePoint API located in commercial/government community cloud tenants.