AzADServicePrincipalInsights aka AzADSPI

Insights and change tracking on Microsoft Entra ID Service Principals (Enterprise Applications, Applications / Managed Identities)

aka links:

• aka.ms/AzADSPI
• aka.ms/AzADServicePrincipalInsights

Content

• Content
• Features
• Parameters
• Data
• Prerequisites
  • Permissions
    • Azure
    • Microsoft Entra ID
    • Azure DevOps
  • PowerShell
• Execute as Service Principal / Application
• Preview
• Updates
• AzAdvertizer
• Azure Governance Visualizer aka AzGovViz
• Closing Note

Features

• HTML export
• JSON export
  • Ingest data from the JSON files to an Azure Log Analytics workspace custom table using data collection rule / data collection endpoint. Microsoft Entra Workload ID - Advanced Detections and Enrichment in Microsoft Sentinel
• CSV export (wip)
  • AADRoleAssignments
  • AppRoleAssignments
  • Oauth2PermissionGrants
  • AppSecrets
  • AppCertificates
  • AppFederatedIdentityCredentials
  • MIFederatedIdentityCredentials
  • MI User Assigned associated resources
• Customizable permission classification (permissionClassification.json)
  • sources/resources
    • https://m365internals.com/2021/07/24/everything-about-service-principals-applications-and-api-permissions/ -> What applications are considered critical?
    • https://docs.microsoft.com/en-us/security/compass/incident-response-playbook-app-consent#classifying-risky-permissions -> Classifying risky permissions
    • https://www.youtube.com/watch?v=T-ZnAUt1IP8 -> Monitoring and Incident Response in Azure AD

Parameters

• DebugAzAPICall - Switch to enable AzAPICall debug function for troubleshooting API calls using the AzAPICall module
• ManagementGroupId
  • Option1: The Management Group ID that should be queried for the report. If undefined the Root Management group will be used.
  • Option2: accepts multiple Management Groups in form of an array e.g. .\pwsh\AzADServicePrincipalInsights.ps1 -ManagementGroupId @('mgId0', 'mgId1')
• NoCsvExport - Switch to disable exporting enriched data in CSV format
• CsvDelimiter - The world is split into two kinds of delimiters - comma and semicolon - choose yours (default : ';')
• OutputPath - Define the path where you want the output files to be stored
• SubscriptionQuotaIdWhitelist - Process only Subscriptions with defined QuotaId(s). Example: .\AzADServicePrincipalInsights.ps1 -SubscriptionQuotaIdWhitelist MSDN_,Enterprise_ (default : @('undefined')
• DoTranscript - Switch to enable logging to console output
• HtmlTableRowsLimit Threshold for the HTML output (table formatted) to prevent unresponsive browser issue due to limited client device performance. A recommendation will be shown to download the CSV instead of opening the TF table (default : 20000)
• ThrottleLimitARM - Limit the parallel Azure Resource Manager API requests (default : 10)
• ThrottleLimitGraph - Limit the parallel Graph API requests (default : 20)
• ThrottleLimitLocal - Limit the parallelism of Powershell task to process the results (default : 100)
• SubscriptionId4AzContext - If needed set a specific SubscriptionID as context for the AzAPICall module (default : 'undefined')
• FileTimeStampFormat - Define the time format for the output files (default : 'yyyyMMdd_HHmmss')
• NoJsonExport - Switch to disable exporting enriched data in Json formatted files
• AADGroupMembersLimit - Defines the limit of AAD Group members; For AAD Groups that have more members than the defined limit Group members will not be resolved (default : 500)
• NoAzureResourceSideRelations - Switch to disable the processing of Azure resource side relations
• StatsOptOut - Switch to opt out sending statistics for usage analysis
• ApplicationSecretExpiryWarning - Define warning period for Service Principal secret expiry (default : 14 days)
• ApplicationSecretExpiryMax - Define maximum expiry period for Service Principal secrets (default : 730 days)
• ApplicationCertificateExpiryWarning - Define warning period for Service Principal certificate expiry (default : 14 days)
• ApplicationCertificateExpiryMax - Define maximum expiry period for Service Principal certificates (default : 730 days)
• DirectorySeparatorChar - Set the character for directory seperation (default : [IO.Path]::DirectorySeparatorChar)
• OnlyProcessSPsThatHaveARoleAssignmentInTheRelevantMGScopes - Switch to only report on Service Principals that have a role assigment within the scope of the data collection contaxt
• CriticalAADRoles - Microsoft Entra ID roles that should be considered as highly privileged/critical (default :@('62e90394-69f5-4237-9190-012177145e10', 'e8611ab8-c189-46e8-94e1-60213ab1f814', '7be44c8a-adaf-4e2a-84d6-ab2649e08a13') which are Global Administrator, Privileged Role Administrator, Privileged Authentication Administrator)

Data

• ServicePrincipals by type
• ServicePrincipal owners
• Application owners
• ServicePrincipal owned objects
• Managed Identity User Assigned - associated Azure Resources
• ServicePrincipal AAD Role assignments
• ServicePrincipal AAD Role assignedOn
• Application AAD Role assignedOn
• App Role assignments (API permissions Application)
• App Roles assignedTo (Users and Groups)
• Oauth permission grants (API permissions delegated)
• Azure Role assignments (Azure Resources; Management Groups, Subscriptions, Resource Groups, Resources)
• ServicePrincipal Group memberships
• Application Secrets
• Application Certificates
• Application Federated Identity Credentials
• Managed Identity User Assigned Federated Identity Credentials
• HiPo Users (wip)

Prerequisites

Permissions

Azure

Management Group (Tenant Root Management Group) RBAC: Reader

Microsoft Entra ID

Microsoft Graph API | Application | Application.Read.All
Microsoft Graph API | Application | Group.Read.All
~~Microsoft Graph API | Application | RoleManagement.Read.All~~
Microsoft Graph API | Application | RoleManagement.Read.Directory
Microsoft Graph API | Application | User.Read.All

Azure DevOps

The Build Service Account or Project Collection Build Service Account (which ever you use) requires Contribute permissions on the repository (Project settings - Repos - Security)

PowerShell

Requires PowerShell Version >= 7.0.3

Requires PowerShell Module 'AzAPICall'.
Running in Azure DevOps or GitHub Actions the AzAPICall PowerShell module will be installed automatically.
AzAPICall resources:

GitHub Repository

Execute as Service Principal / Application

#USER: 'Application (client) ID' of the App registration OR 'Application ID' of the Service Principal (Enterprise Application)
#PASSWORD: Secret of the App registration

$pscredential = Get-Credential
Connect-AzAccount -ServicePrincipal -TenantId <tenantId> -Credential $pscredential
.\pwsh\AzADServicePrincipalInsights.ps1

Preview

Updates

• 20250121
  • Fix issue #40 - Use AzAPICall PowerShell module version 1.2.5
  • Try to fix issue #41 - optimize hashtable processing
  • Update ARM REST API versions to latest
• 20240730
  • Fix SkipAzContextSubscriptionValidation check by using NoAzureResourceSideRelations (PR 38)
• 20240419
  • Fix hardcoded ARM API Url using north europe (PR 31)
  • Fix ContentLengthLimitExceeded error when using log ingestion API (PR 32)
• 20240212
  • fix issue 27
• 20240208
  • Contribution from @Cloud-Architekt to ingest data from the JSON files to an Azure Log Analytics workspace custom table using data collection rule / data collection endpoint. Microsoft Entra Workload ID - Advanced Detections and Enrichment in Microsoft Sentinel
    • Ready for Azure DevOps and GitHub; configure in the pipeline/workflow YAML files
  • Change PowerShell parallel handling / batches
  • Optimize array handling / best practices
  • Use AzAPICall PowerShell module version 1.2.0 (support endpoint *.ingest.monitor.azure.com)
• 20231218 - thanks @kaiaschulz
  • Fix scope of subscriptions to process. The ARM entities API may still return subscriptions that are meanwhile delted and therefore should not be processed in the data collection
  • Use AzAPICall PowerShell module version 1.1.86
• 20231217
  • Fix for SP names that contain escapable characters
  • Update GitHub workflows to support webApp publishing thanks @RS-MPersson
  • Use AzAPICall PowerShell module version 1.1.85
• 20231121 - thanks @cjtous1
  • HTML updates
    • Added SPTags & AppTags to the following tables:
      • Service Principals
      • Service Principal AAD RoleAssignments
      • Service Principal App RoleAssignments
      • Service Principal App RoleAssignedTo
      • Service Principal Oauth Permission grants
      • Service Principal Azure RoleAssignments
    • Added AppNotes to the Service Principals table
  • Added the following CSV file exports
    • Service Principals
    • Service Principal Owners
    • Application Owners