AzADServicePrincipalInsights aka AzADSPI

Insights and change tracking on Microsoft Entra ID Service Principals (Enterprise Applications and Applications)

aka links:

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

Content

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

Updates

• 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
    • Service Principal Owned Objects
    • Service Principal AAD RoleAssignments
    • Service Principal AAD RoleAssignedOn
    • Service Principal App RoleAssignedTo
    • Service Principal App RoleAssignments
    • Service Principal Azure RoleAssignments
    • Service Principal Group memberships
  • Fix: NoCsvExport is now working and preventing CSV files from being generated if true.
  • Fix: NoJsonExport is now working and preventing JSON files from being generated if true.
  • Use AzAPICall PowerShell module version 1.1.84
• 20231001
  • fix hardcoded delimiter for export-csv - thanks @cjtous1
• 20230316
  • Use AzAPICall PowerShell module version 1.1.70
• 20221017
  • Use AzAPICall PowerShell module version 1.1.40
    • Issue #10 - Handle error 404 User Assigned Managed Identity / ResourceGroup not found
• 20221014
  • Use AzAPICall PowerShell module version 1.1.38
    • Handle error 405 Support for federated identity credentials not enabled
• 20221008
  • New feature - Managed Identity User Assigned Federated Identity Credentials
  • Rearrange JSON output for Managed Identity associated Azure Resources
• 20221007
  • New feature - Managed Identity User Assigned associated Azure Resources
  • Changed parameter name NoAzureRoleAssignments to NoAzureResourceSideRelations
    • Using NoAzureResourceSideRelations:
      • No (Azure Resource side) RBAC Role assignments collection
      • No (Azure Resource side) Policy assignments collection
      • No (Azure Resource side) Resources collection ('Managed Identity User Assigned associated Azure Resources' feature annul)
  • Azure DevOps pipeline yml - update vmImage ubuntu-20.04 ubuntu-22.04
  • Minor fixes and optimizations
  • Use AzAPICall PowerShell module version 1.1.33
• 20220717
  • Removed identity governance state validation
  • Use AzAPICall PowerShell module version 1.1.18
• 20220630
  • Breaking Change on the Azure side: Instead of RoleManagement.Read.All we require RoleManagement.Read.Directory
• 20220622_1
  • Fix /providers/Microsoft.Authorization/roleAssignmentScheduleInstances AzAPICall errorhandling (error 400, 500)
  • Optimize procedure to update the AzAPICall module
  • Use AzAPICall PowerShell module version 1.1.17
• 20220613_1
  • use AzAPICall module version 1.1.16
  • enhance HiPo Users HTML output
  • minor fixes
• 20220609_1
  • add parameter -CriticalAADRoles (defaults: Global Administrator, Privileged Role Administrator, Privileged Authentication Administrator)
  • add HiPo Users - A HiPo User has direct or indirect ownership on a ServicePrincipal(s) with classified permissions (AppRole, AAD Role, Azure Role, OAuthPermissionGrant)
  • use AzAPICall module version 1.1.13
  • minor fixes
• 20220505_1
  • fix: using:scriptPath variable in foreach parallel (this is only relevant for Azure DevOps and GitHub if you have a non default folder structure in your repository) - thanks Matt :)
• 20220501_1
  • parameter -ManagementGroupId accepts multiple Management Groups in form of an array e.g. .\pwsh\AzADServicePrincipalInsights.ps1 -ManagementGroupId @('mgId0', 'mgId1')
  • new parameter -OnlyProcessSPsThatHaveARoleAssignmentInTheRelevantMGScopes. You may want to only report on Service Principals that have RBAC permissions on Azure resources at and below that Management Group scope(s) (Management Groups, Subscriptions, Resource Groups and Resources)
  • Role assignments on Azure resources - mark those RBAC Role assignments which leverage a RBAC Role definition that can create role assignments as critical
  • updated YAML workflow/pipeline files
  • minor bug fixes
  • performance optimization
• 20220425_2
  • add parameter -ManagementGroupId (if undefined, then Tenant Root Management Group will be used)
  • use AzAPICall module version 1.1.11
• 20220404_1
  • add FederatedIdentityCredentials

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

AzAdvertizer

Also check https://www.azadvertizer.net - AzAdvertizer helps you to keep up with the pace by providing overview and insights on new releases and changes/updates for Azure Governance capabilities such as Azure Policy's Policy definitions, initiatives (Set definitions), aliases and Azure RBAC's Role definitions and resource provider operations.

Azure Governance Visualizer aka AzGovViz

Also check out the Azure Governance Visualizer. The tool is intended to help you to get a holistic overview on your technical Azure Governance implementation by connecting the dots.
It is a PowerShell script that iterates your Azure Tenant's Management Group hierarchy down to Subscription level, it captures most relevant Azure governance capabilities such as Azure Policy, RBAC and Blueprints and a lot more..

• Listed as tool for the Govern discipline in the Microsoft Cloud Adoption Framework (CAF)
• Listed as security monitoring tool in the Microsoft Well Architected Framework (WAF)

Closing Note

Please note that while being developed by a Microsoft employee, AzADServicePrincipalInsights is not a Microsoft service or product. AzADServicePrincipalInsights is a personal/community driven project, there are none implicit or explicit obligations related to this project, it is provided 'as is' with no warranties and confer no rights.