Loading...

How to use Azure CLI to Generate Documentation for Azure AD Applications?

How to use Azure CLI to Generate Documentation for Azure AD Applications?

Your organization likely has hundreds of Azure AD Applications. And with the constant addition, development and subset of new applications with various access points, it becomes imperative to use a script that streamlines the documentation process and helps creates technical documentation for every registered application. And that’s where the following script steps in.

What is Azure Active Directory?

Azure Active Directory is an Identity and Access Management (IAM) system. It provides a single place to store information about digital identities. You can configure your applications to use Azure AD as the place where user information is stored.

Advantages of generating documentation for Azure AD Applications

  • Improves the experience for developers using your Azure AD Applications
  • Decreases the amount of time spent on-boarding developers and application integration partners.
  • Leads to good maintenance and quicker updates.
  • API permissions, scopes, roles help developers and integration partners to understand the Azure AD Application and know what it can do
  • Decreases the amount of time spent on decoding unexpected errors when using it.

In this article, I have attached a PowerShell script that takes the details of the given Azure AD Applications as input and creates readable markdown documentation that you can share with developers and integration partners using the simple use of Azure’s CLI commands.

Prerequisites

  • Azure CLI
  • Azure AD Applications registered in Azure tenant
  • Azure Application Administrator / Developer role
  • Login to Azure using Azure CLI before executing following script

Note - This code has not been optimized and is for demo purpose. You might need to modify the code as per your requirements.

PowerShell Script

function GetTenantId() {
    $accountDetails = az account list | ConvertFrom-Json
    return $accountDetails.tenantId
}
function GetAadApplications() {
    return (az ad app list --all) | ConvertFrom-Json 
}
function GenerateDocumentation($aadApplications) {
    $progressCountApp = 1;

    ForEach ($appInfo in $aadApplications) {
        Write-Progress -Id 0 -Activity "Generating Documentation for the App: $($appInfo.displayName)" -Status "App $progressCountApp of $($aadApplications.length)" -PercentComplete (($progressCountApp / $aadApplications.length) * 100)
        $outputDocumentPath = -join ($outputFolderPath, "\" , $appInfo.displayName, ".md")
        
        $fragments = @()

        $fragments += "# $($docTitle)`n"
        $fragments += "$($docDescription)`n"

        $fragments += "## App Details"
        $fragments += "| Property  | Value  |"
        $fragments += "| ------ | ------ |"
        $fragments += "|Display Name|$($appInfo.displayName)|"
        $fragments += "|App Id|$($appInfo.appId)|"
        $fragments += "|Publisher Domain|$($appInfo.publisherDomain)|"

        $fragments += "`n## Resource Access"

        ForEach ($resource in $appInfo.requiredResourceAccess) {
            $currentResource = (az ad sp show --id $resource.resourceAppId) | ConvertFrom-Json

            $resourceName = $currentResource.displayName
            if (![string]::IsNullOrEmpty($resourceName)) {
                $fragments += "`n### $($resourceName)"
            }

            if ($resource.resourceAccess) {
                $fragments += "`n_App Roles_"
                $fragments += "| Role  |"
                $fragments += "| ------ |"
    
                $appRoles = (az ad sp show --id $resource.resourceAppId --query "appRoles[].{Value:value, Id:id}") | ConvertFrom-Json
                ForEach ($access in $resource.resourceAccess) {
                    $appRole = ($appRoles | Where-Object { $_.Id -eq $access.id })
                    $appRoleName = $appRole.Value
                    if (![string]::IsNullOrEmpty($appRoleName)) {
                        if (![string]::IsNullOrEmpty($appRoleName)) {
                            $fragments += "|$($appRoleName)|"
                        }
                    }
                }
            }

            if ($resource.oauth2Permissions) {
                $fragments += "`n_OAuth2 Permissions_"
                $fragments += "| Permission  |"
                $fragments += "| ------ |"
                $oauth2Permissions = (az ad sp show --id $resource.resourceAppId --query "oauth2Permissions[].{Value:value, Id:id}") | ConvertFrom-Json    
                ForEach ($oauth2Permission in $resource.oauth2Permissions) {
                    $appOauth2Permission = ($oauth2Permissions | Where-Object { $_.Id -eq $oauth2Permission.id })
                    $appOauth2PermissionName = $appOauth2Permission.Value
                    if (![string]::IsNullOrEmpty($appOauth2PermissionName)) {
                        $fragments += "|$($appOauth2PermissionName)|"
                    }
                }
            }
        }

        $fragments += "`n_report run $(Get-Date)_"  
        $fragments | out-file -FilePath $outputDocumentPath

        $progressCountApp++
    }

    Write-Progress -Id 0 -Activity " " -Status " " -Completed
}

$docTitle = "Azure AD Application Details"
$docDescription = "This is a script generated documentation. For more details contact teamname_GDL@yourcompany.com"
$outputFolderPath = $PSScriptRoot
$aadApplications = GetAadApplications 
GenerateDocumentation $aadApplications

Output

document-aad-applications.png

I would like to thank Jayakumar Balasubramaniam for the support he provided to review and finalize this script.

Published on:

Learn more
Home | Joseph Velliah
Home | Joseph Velliah

Fulfilling God’s purpose for my life

Share post:

Related posts

Announcing: Dynamic Data Masking for Azure Cosmos DB (Preview)

Today marks a big step forward with the public preview of Dynamic Data Masking (DDM) for Azure Cosmos DB. This feature helps organizations pro...

20 hours ago

Use Azure SRE Agent with Azure Cosmos DB: Smarter Diagnostics for Your Applications

We’re excited to announce the Azure Cosmos DB SRE Agent built on Azure SRE Agent; a new capability designed to simplify troubleshooting and im...

20 hours ago

General Availability: Priority-Based Execution in Azure Cosmos DB

Have you ever faced a situation where two different workloads share the same container, and one ends up slowing down the other? This is a comm...

20 hours ago

Announcing Preview of Online Copy Jobs in Azure Cosmos DB: Migrate Data with Minimal Downtime!

We are excited to announce the preview of Online Copy Jobs, a powerful new feature designed to make data migration between containers seamless...

20 hours ago

Azure Developer CLI (azd) Nov 2025 – Container Apps (GA), Layered Provisioning (Beta), Extension Framework, and Aspire 13

This post announces the November release of the Azure Developer CLI (`azd`). The post Azure Developer CLI (azd) Nov 2025 – Container App...

1 day ago

Announced at Ignite 2025: Azure DocumentDB, MCP Toolkit, Fleet Analytics, and more!

Microsoft Ignite 2025 kicked off with a wave of announcements for Azure Cosmos DB and Azure DocumentDB, setting the tone for a week of innovat...

1 day ago

Automating Microsoft Fabric Workspace Creation with Azure DevOps Pipelines

In today’s fast-paced analytics landscape, Microsoft Fabric has become the leader of enterprise BI implementations, one of the fundamental con...

2 days ago

New T-SQL AI Features are now in Public Preview for Azure SQL and SQL database in Microsoft Fabric

At the start of this year, we released a new set of T-SQL AI features for embedding your relational data for AI applications. Today, we have b...

2 days ago
Stay up to date with latest Microsoft Dynamics 365 and Power Platform news!
* Yes, I agree to the privacy policy