View on GitHub

ScubaGear

Automation to assess the state of your M365 tenant against CISA's baselines

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

The table below lists the minimum permissions and roles required for ScubaGear to read configuration data for each supported product.

[!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 never uses these 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 BI Tenant setting required 3      
Power Platform Registration required 2      
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.1
Power Platform service principals require an additional one-time registration step via interactive login, detailed in this section.2
Power BI does not require any API permissions on the App Registration. Instead, it requires a Power BI Admin portal tenant setting, detailed in this section. Adding Tenant.Read.All to the App Registration will cause errors (500 in commercial, 401 in GCC).3

Service Principal Setup

ScubaGear supports two setup approaches:

[!NOTE] The custom PowerShell functions were created exclusively for ScubaGear. They configure service principals with the exact permissions and roles needed for ScubaGear assessments.

Get started with automated setup:

2. Manual Setup (Alternative)

Step 1: Create the Service Principal

Microsoft provides documentation for manual service principal creation:

Step 2: Assign Permissions

Assign the API permissions and roles listed in the table above based on which products you plan to assess.

[!IMPORTANT] Ensure you grant admin consent for all API permissions after adding them.

Step 3: Configure Certificate Authentication

[!IMPORTANT] Certificates must be stored in Cert:\CurrentUser\My due to Power Platform requirements.

  1. Generate a certificate or use an existing one 
     # Example: Create a self-signed certificate for ScubaGear
 $cert = New-SelfSignedCertificate -Subject "CN=ScubaGear-$(Get-Date -Format 'yyyyMMdd')" -CertStoreLocation "Cert:\CurrentUser\My" -KeyExportPolicy Exportable -KeyLength 2048 -NotAfter (Get-Date).AddDays(180)
  2. Associate the certificate with the service principal
  3. Get the certificate thumbprint: 
    # List certificates in the correct location
Get-ChildItem Cert:\CurrentUser\My | Where-Object {$_.Subject -like "*ScubaGear*"} | Select-Object Thumbprint,Subject,NotBefore,NotAfter

Step 4: Note Required Values

Save these values for running ScubaGear:

Continue to the Power Platform Registration section below if you’re assessing Power Platform.

Power BI Tenant Setting

The Power BI Admin portal must be configured to allow service principal access before ScubaGear can retrieve Power BI settings.

[!WARNING] Do not add the Tenant.Read.All permission from the Power BI Service API to the App Registration. This permission conflicts with the tenant setting approach and will result in HTTP 500 errors (commercial) or HTTP 401 errors (GCC). The security group and tenant setting described below is the only required configuration.

[!IMPORTANT] Power BI does not allow adding service principals directly to this setting — the SP must be a member of a security group, and that group must be added to the setting.

Step 1: Create a Security Group

Create a plain security group in Entra ID (without role assignment) and add the service principal as a member.

Step 2: Enable Read-Only Admin API Access

In the Power BI Admin portal:

  1. Navigate to Tenant settings → Admin API settings
  2. Enable “Service principals can access read-only admin APIs”
  3. Under Apply to, select Specific security groups and add the security group from Step 1

[!NOTE] This setting only supports “Specific security groups” — the “Entire organization” option is not available.

Step 3: Verify Access

After enabling the setting, confirm the SP can reach the API:

Invoke-SCuBA -ProductNames powerbi -AppID <app-id> -CertificateThumbprint <thumbprint> -Organization <tenant>.onmicrosoft.com -M365Environment gcc

[!NOTE] For GCC High tenants, use -M365Environment gcchigh. See Power BI in GCC High for additional details.

Power Platform Registration

[!NOTE] This section applies to manual setup methods. Power Platform requires an additional one-time registration step regardless of how you created your service principal.
If you used the automated setup, you can skip to the verification step at the end of this section Verify Registration.

The Service Principal must be registered with Power Platform using interactive authentication before running ScubaGear. This is a limitation of Power Platform service principals.

Registration Steps

Step 1: Interactive Login

# Login interactively with a Power Platform admin account
Add-PowerAppsAccount -Endpoint prod -TenantID "your-tenant-id"

[!NOTE] For GCC tenants: Use -Endpoint usgov
For GCC High tenants: Use -Endpoint usgovhigh

Step 2: Register the Service Principal

# Register the service principal with Power Platform admin permissions
New-PowerAppManagementApp -ApplicationId "your-app-id"

[!IMPORTANT]

  • Replace your-app-id with your actual Application ID
  • This command requires Power Platform Administrator or Global Administrator role
  • This registration only needs to be done once per service principal

Step 3: Verify Registration

After registration, verify Power Platform permissions:

# Should return your AppID under 'applicationId'
Get-PowerAppManagementApp -ApplicationId "your-app-id"

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.

Power BI in GCC High

When running ScubaGear to assess Power BI in a GCC High tenant, the same Power BI Tenant Setting configuration applies — create an Entra security group containing the service principal and add it to the “Service principals can access read-only admin APIs” setting in the Power BI Admin portal. No API permissions need to be added to the App Registration. Use -M365Environment gcchigh when invoking ScubaGear.