Merge branch 'main' into doc-improvement-app-catalog

Author: JarbasHorst

.gdn/.gdnbaselines

@@ -0,0 +1,31 @@
+{
+  "hydrated": true,
+  "properties": {
+    "helpUri": "https://eng.ms/docs/microsoft-security/security/azure-security/cloudai-security-fundamentals-engineering/security-integration/guardian-wiki/microsoft-guardian/general/baselines",
+    "hydrationStatus": "This file does not contain identifying data. It is safe to check into your repo. To hydrate this file with identifying data, run `guardian hydrate --help` and follow the guidance."
+  },
+  "version": "1.0.0",
+  "baselines": {
+    "default": {
+      "name": "default",
+      "createdDate": "2024-08-26 12:06:54Z",
+      "lastUpdatedDate": "2024-08-26 12:06:54Z"
+    }
+  },
+  "results": {
+    "b3d46ea406a66acd0fa8b1130ec9be5b501ad4a933d98ce70193c68771b6e7be": {
+      "signature": "b3d46ea406a66acd0fa8b1130ec9be5b501ad4a933d98ce70193c68771b6e7be",
+      "alternativeSignatures": [
+        "79e125fb7927450b0ebb02d6b3ddb03d7a6a971e21dfdc1c246ba8fd39f0969e"
+      ],
+      "target": "update-permissions-reference.ps1",
+      "line": 170,
+      "memberOf": [
+        "default"
+      ],
+      "tool": "psscriptanalyzer",
+      "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
+      "createdDate": "2024-08-26 12:06:54Z"
+    }
+  }
+}

.gdn/.gdnsuppress

@@ -0,0 +1,31 @@
+{
+  "hydrated": true,
+  "properties": {
+    "helpUri": "https://eng.ms/docs/microsoft-security/security/azure-security/cloudai-security-fundamentals-engineering/security-integration/guardian-wiki/microsoft-guardian/general/suppressions",
+    "hydrationStatus": "This file does not contain identifying data. It is safe to check into your repo. To hydrate this file with identifying data, run `guardian hydrate --help` and follow the guidance."
+  },
+  "version": "1.0.0",
+  "suppressionSets": {
+    "default": {
+      "name": "default",
+      "createdDate": "2024-08-26 12:06:54Z",
+      "lastUpdatedDate": "2024-08-26 12:06:54Z"
+    }
+  },
+  "results": {
+    "b3d46ea406a66acd0fa8b1130ec9be5b501ad4a933d98ce70193c68771b6e7be": {
+      "signature": "b3d46ea406a66acd0fa8b1130ec9be5b501ad4a933d98ce70193c68771b6e7be",
+      "alternativeSignatures": [
+        "79e125fb7927450b0ebb02d6b3ddb03d7a6a971e21dfdc1c246ba8fd39f0969e"
+      ],
+      "target": "update-permissions-reference.ps1",
+      "line": 170,
+      "memberOf": [
+        "default"
+      ],
+      "tool": "psscriptanalyzer",
+      "ruleId": "PSAvoidUsingConvertToSecureStringWithPlainText",
+      "createdDate": "2024-08-26 12:06:54Z"
+    }
+  }
+}

.github/workflows/cloud-support.yml

@@ -37,7 +37,7 @@ jobs:
       run: dotnet build --configuration Release
     - name: Install hidi
       run: dotnet tool install microsoft.openapi.hidi -g
-    - name: Create metadata output director
+    - name: Create metadata output directory
       run: |
         mkdir openapi
         cd openapi
@@ -55,21 +55,22 @@ jobs:
         ./transforms/csdl/transform.ps1 -xslPath preprocess_csdl.xsl -inputPath ../../schemas/beta-Mooncake.csdl -outputPath ../../transformed_beta-Mooncake.csdl -addInnerErrorDescription $true -removeCapabilityAnnotations $false -csdlVersion v1.0
     - name: Transform CSDL with hidi
       working-directory: ./metadata
+      shell: pwsh
       env:
         SETTINGS: ./conversion-settings/openapi.json
       run: |
-        hidi transform --cs transformed_v1.0-Prod.csdl -o ../openapi/v1.0/Prod.yml --co -f Yaml --sp $SETTINGS
-        hidi transform --cs transformed_v1.0-Fairfax.csdl -o ../openapi/v1.0/Fairfax.yml --co -f Yaml --sp $SETTINGS
-        hidi transform --cs transformed_v1.0-Mooncake.csdl -o ../openapi/v1.0/Mooncake.yml --co -f Yaml --sp $SETTINGS
-        hidi transform --cs transformed_beta-Prod.csdl -o ../openapi/beta/Prod.yml --co -f Yaml --sp $SETTINGS
-        hidi transform --cs transformed_beta-Fairfax.csdl -o ../openapi/beta/Fairfax.yml --co -f Yaml --sp $SETTINGS
-        hidi transform --cs transformed_beta-Mooncake.csdl -o ../openapi/beta/Mooncake.yml --co -f Yaml --sp $SETTINGS
+        hidi transform --cs transformed_v1.0-Prod.csdl -o ../openapi/v1.0/Prod.yml --co -f Yaml --sp $Env:SETTINGS
+        hidi transform --cs transformed_v1.0-Fairfax.csdl -o ../openapi/v1.0/Fairfax.yml --co -f Yaml --sp $Env:SETTINGS
+        hidi transform --cs transformed_v1.0-Mooncake.csdl -o ../openapi/v1.0/Mooncake.yml --co -f Yaml --sp $Env:SETTINGS
+        hidi transform --cs transformed_beta-Prod.csdl -o ../openapi/beta/Prod.yml --co -f Yaml --sp $Env:SETTINGS
+        hidi transform --cs transformed_beta-Fairfax.csdl -o ../openapi/beta/Fairfax.yml --co -f Yaml --sp $Env:SETTINGS
+        hidi transform --cs transformed_beta-Mooncake.csdl -o ../openapi/beta/Mooncake.yml --co -f Yaml --sp $Env:SETTINGS
     - name: Run cloud support tool
       env:
         TOOL: ./tool/src/bin/Release/net8.0/CheckCloudSupport
       run: |
-        $TOOL --open-api ./openapi/v1.0 --api-docs ./docs/api-reference/v1.0/api --remove-old-includes
-        $TOOL --open-api ./openapi/beta --api-docs ./docs/api-reference/beta/api --remove-old-includes
+        $TOOL --open-api ./openapi/v1.0 --api-docs ./docs/api-reference/v1.0/api --overrides ./docs/api-reference/cloud.api.overrides.json --excludes ./docs/api-reference/cloud.exclusions.json --remove-old-includes
+        $TOOL --open-api ./openapi/beta --api-docs ./docs/api-reference/beta/api --overrides ./docs/api-reference/cloud.api.overrides.json --excludes ./docs/api-reference/cloud.exclusions.json --remove-old-includes
     - name: Get token
       id: get_token
       uses: microsoftgraph/get-app-token@v1.0.4

.github/workflows/permissions-reference-gen.yml

@@ -23,7 +23,7 @@ jobs:
       with:
         path: docs
 
-    - name: Run PowerShell script
+    - name: Run PowerShell script to update permissions
       shell: pwsh
       run: | 
         $ClientId = "${{ secrets.GRAPH_CLIENT_ID }}"
@@ -38,22 +38,46 @@ jobs:
         application-id: ${{ secrets.APPLICATION_ID }}
         application-private-key: ${{ secrets.APPLICATION_PRIVATE_KEY }}
 
-    - name: Commit updates and open a pull request
+    - name: Commit updates from service principal
       working-directory: ./docs
       shell: pwsh
       env:
-       GH_TOKEN: ${{ steps.get_token.outputs.app-token }}
+        GH_TOKEN: ${{ steps.get_token.outputs.app-token }}
       run: |
         $status = git status --porcelain
         if ($status -eq $null) {
           Write-Host "No changes to commit." -ForegroundColor Green
-        } else {
-          $timestamp = Get-Date -Format FileDateTimeUniversal
+        }
+        else {          
           git config user.email "GraphTooling@service.microsoft.com"
           git config user.name "Microsoft Graph DevX Tooling"
-          git checkout -b permissions-reference/$timestamp
           git add .
           git commit -m "Update permissions reference"
-          git push --set-upstream origin permissions-reference/$timestamp
-          gh pr create --base main --title "Automated permissons reference update" --body "Scheduled permissions reference update" --reviewer "FaithOmbongi","msewaweru" --label "ready for content review"
+        } 
+    
+    - name: Run PowerShell script to correct errors in permissions descriptions
+      shell: pwsh
+      run: | 
+        ./docs/correct-permissions-reference-errors.ps1
+    
+    - name: Commit errors correction and open a pull request
+      working-directory: ./docs
+      shell: pwsh
+      env:
+       GH_TOKEN: ${{ steps.get_token.outputs.app-token }}
+      run: |
+        $status = git status --porcelain
+        if ($status -eq $null) {
+          Write-Host "No changes to commit." -ForegroundColor Green
+        } else { 
+          $dateToday = Get-Date -Format 'yyyy-MM-dd'
+          $branchName = "permissions-reference/$dateToday" 
+          $prTitle = "${dateToday}: Automated permissions reference update"
+          
+          git add .
+          git commit -m "Correct errors in permissions reference"
+          git checkout -b $branchName
+          git push --set-upstream origin $branchName
+          
+          gh pr create --base main --title $prTitle --body "Scheduled permissions reference update" --reviewer "FaithOmbongi,msewaweru" --label "ready for content review"
         }

.vscode/settings.json

@@ -1,5 +1,19 @@
-{
-    "githubPullRequests.ignoredPullRequestBranches": [
-        "main"
-    ]
+{
+    "githubPullRequests.ignoredPullRequestBranches": [
+        "main"
+    ],
+    "json.schemas": [
+        {
+            "fileMatch": [
+                "cloud.api.overrides.json"
+            ],
+            "url": "https://raw.githubusercontent.com/microsoftgraph/msgraph-cloud-support/main/schema/api.overrides.schema.json"
+        },
+        {
+            "fileMatch": [
+                "cloud.exclusions.json"
+            ],
+            "url": "https://raw.githubusercontent.com/microsoftgraph/msgraph-cloud-support/main/schema/cloud.exclusions.schema.json"
+        }
+    ]
 }

api-reference/beta/api/accesspackageassignmentrequest-resume.md

@@ -1,6 +1,6 @@
 ---
 title: "accessPackageAssignmentRequest: resume"
-description: "Resume accessPackageAssignmentRequest objects."
+description: "Resume a user's access package request after waiting for a callback from a custom extension."
 ms.localizationpriority: medium
 author: "vikama-microsoft"
 ms.subservice: "entra-id-governance"
@@ -12,7 +12,9 @@ Namespace: microsoft.graph
 
 [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
 
-In [Microsoft Entra entitlement management](../resources/entitlementmanagement-overview.md), when an access package policy has been enabled to call out a custom extension and the request processing is waiting for the callback from the customer, the customer can initiate a resume action. It is performed on an [accessPackageAssignmentRequest](../resources/accesspackageassignmentrequest.md) object whose **requestStatus** is in a `WaitingForCallback` state.
+Resume a user's access package request after waiting for a callback from a custom extension.
+
+In [Microsoft Entra entitlement management](../resources/entitlementmanagement-overview.md), when an access package policy has been enabled to call out a custom extension and the request processing is waiting for the callback from the customer, the customer can initiate a resume action. It's performed on an [accessPackageAssignmentRequest](../resources/accesspackageassignmentrequest.md) object whose **requestStatus** is in a `WaitingForCallback` state.
 
 [!INCLUDE [national-cloud-support](../../includes/global-us.md)]
 
@@ -22,6 +24,9 @@ Choose the permission or permissions marked as least privileged for this API. Us
 <!-- { "blockType": "permissions", "name": "accesspackageassignmentrequest_resume" } -->
 [!INCLUDE [permissions-table](../includes/permissions/accesspackageassignmentrequest-resume-permissions.md)]
 
+> [!IMPORTANT]
+> App-only access can be authorized *without* granting the `EntitlementManagement.ReadWrite.All` application permission to the caller. Instead, assign the caller an [Entitlement Management role](/entra/id-governance/entitlement-management-delegate), where `Access package assignment manager` is the least privileged role supported for this operation. For more information on how to assign an Entitlement Management role, see [Create unifiedRoleAssignment](../api/rbacapplication-post-roleassignments.md#example-4-create-a-role-assignment-with-access-package-catalog-scope) or [Delegate access governance to access package managers in entitlement management](/entra/id-governance/entitlement-management-delegate-managers#as-a-catalog-owner-delegate-to-an-access-package-manager).
+
 ## HTTP request
 
 > [!NOTE]

api-reference/beta/api/appcatalogs-list-teamsapps.md

@@ -1,7 +1,7 @@
 ---
 title: "List teamsApp"
 description: "List apps from the Microsoft Teams app catalog."
-author: "nkramer"
+author: "MSFTRickyCastaneda"
 ms.localizationpriority: medium
 ms.subservice: "teams"
 doc_type: apiPageType

api-reference/beta/api/application-list-owners.md

@@ -1,19 +1,19 @@
 ---
-title: "List owners"
-description: "Retrieve a list of owners (directoryObject objects) for an application."
+title: "List owners of an application"
+description: "Retrieve a list of owners for an application."
 author: "sureshja"
 ms.localizationpriority: medium
 ms.subservice: "entra-applications"
 doc_type: apiPageType
 ---
 
-# List owners
+# List owners of an application
 
 Namespace: microsoft.graph
 
 [!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
 
-Retrieve a list of owners for an application that are [directoryObject](../resources/directoryobject.md) objects.
+Retrieve a list of owners for an application that are [directoryObject](../resources/directoryobject.md) types.
 
 [!INCLUDE [national-cloud-support](../../includes/all-clouds.md)]
 
@@ -25,8 +25,6 @@ Choose the permission or permissions marked as least privileged for this API. Us
 
 [!INCLUDE [limited-info](../../includes/limited-info.md)]
 
-
-
 ## HTTP request
 
 You can address the application using either its **id** or **appId**. **id** and **appId** are referred to as the **Object ID** and **Application (Client) ID**, respectively, in app registrations in the Microsoft Entra admin center.
@@ -37,7 +35,7 @@ GET /applications(appId='{appId}')/owners
 ```
 
 ## Optional query parameters
-This method supports the [OData Query Parameters](/graph/query-parameters) to help customize the response.
+This method supports the `$count`, `$expand`, `$filter`, `$orderby`, `$search`, `$select`, and `$top` [OData query parameters](/graph/query-parameters) to help customize the response. Some queries are supported only when you use the **ConsistencyLevel** header set to `eventual` and `$count`. For more information, see [Advanced query capabilities on directory objects](/graph/aad-advanced-queries).
 
 ## Request headers
 | Name           | Description                |
@@ -51,54 +49,20 @@ Don't supply a request body for this method.
 
 If successful, this method returns a `200 OK` response code and collection of [directoryObject](../resources/directoryobject.md) objects in the response body.
 ## Example
-##### Request
-The following example shows a request.
+### Request
+The following example shows a request that uses the **appId** alternate key to query the owners of an application.
 
-# [HTTP](#tab/http)
 <!-- {
   "blockType": "request",
   "name": "application_get_owners"
 }-->
 ```msgraph-interactive
-GET https://graph.microsoft.com/beta/applications/{id}/owners
+GET https://graph.microsoft.com/beta/applications(appId='bbec3106-565f-4907-941e-96b4dbfef21c')/owners
 ```
 
-# [C#](#tab/csharp)
-[!INCLUDE [sample-code](../includes/snippets/csharp/application-get-owners-csharp-snippets.md)]
-[!INCLUDE [sdk-documentation](../includes/snippets/snippets-sdk-documentation-link.md)]
-
-# [CLI](#tab/cli)
-[!INCLUDE [sample-code](../includes/snippets/cli/application-get-owners-cli-snippets.md)]
-[!INCLUDE [sdk-documentation](../includes/snippets/snippets-sdk-documentation-link.md)]
-
-# [Go](#tab/go)
-[!INCLUDE [sample-code](../includes/snippets/go/application-get-owners-go-snippets.md)]
-[!INCLUDE [sdk-documentation](../includes/snippets/snippets-sdk-documentation-link.md)]
-
-# [Java](#tab/java)
-[!INCLUDE [sample-code](../includes/snippets/java/application-get-owners-java-snippets.md)]
-[!INCLUDE [sdk-documentation](../includes/snippets/snippets-sdk-documentation-link.md)]
-
-# [JavaScript](#tab/javascript)
-[!INCLUDE [sample-code](../includes/snippets/javascript/application-get-owners-javascript-snippets.md)]
-[!INCLUDE [sdk-documentation](../includes/snippets/snippets-sdk-documentation-link.md)]
-
-# [PHP](#tab/php)
-[!INCLUDE [sample-code](../includes/snippets/php/application-get-owners-php-snippets.md)]
-[!INCLUDE [sdk-documentation](../includes/snippets/snippets-sdk-documentation-link.md)]
-
-# [PowerShell](#tab/powershell)
-[!INCLUDE [sample-code](../includes/snippets/powershell/application-get-owners-powershell-snippets.md)]
-[!INCLUDE [sdk-documentation](../includes/snippets/snippets-sdk-documentation-link.md)]
-
-# [Python](#tab/python)
-[!INCLUDE [sample-code](../includes/snippets/python/application-get-owners-python-snippets.md)]
-[!INCLUDE [sdk-documentation](../includes/snippets/snippets-sdk-documentation-link.md)]
-
----
-
-##### Response
-The following example shows the response. Note: The response object shown here might be shortened for readability.
+### Response
+The following example shows the response. It shows only the **id** property as populated while other properties as `null`. This is because the caller did not have permissions to read users in the tenant. 
+>**Note:** The response object shown here might be shortened for readability.
 <!-- {
   "blockType": "response",
   "truncated": true,
@@ -110,11 +74,32 @@ HTTP/1.1 200 OK
 Content-type: application/json
 
 {
-  "value": [
-    {
-      "id": "id-value"
-    }
-  ]
+    "@odata.context": "https://graph.microsoft.com/beta/$metadata#directoryObjects",
+    "@microsoft.graph.tips": "Use $select to choose only the properties your app needs, as this can lead to performance improvements. For example: GET applications(appId=<key>)/owners?$select=deletedDateTime",
+    "value": [
+        {
+            "@odata.type": "#microsoft.graph.user",
+            "id": "ce4770b3-70b2-4a38-a242-76631e9f7408",
+            "businessPhones": [],
+            "displayName": null,
+            "givenName": null,
+            "jobTitle": null,
+            "mail": null,
+            "mobilePhone": null,
+            "officeLocation": null,
+            "preferredLanguage": null,
+            "surname": null,
+            "userPrincipalName": null
+        },
+        {
+            "@odata.type": "#microsoft.graph.user",
+            "id": "858a9c90-38b3-4e78-b915-234aece712c4",
+        },
+        {
+            "@odata.type": "#microsoft.graph.user",
+            "id": "7585d967-f300-43de-b817-7119a6404c5e",
+        }
+    ]
 }
 ```
 

api-reference/beta/api/application-post-calls.md

@@ -31,7 +31,7 @@ This API supports the following PSTN scenarios:
 + P2P call between bot and another peer (Teams user, PSTN), bot invites another Teams user.
 + Bot join the scheduled meeting and then invite PSTN.
 
-+ [!INCLUDE [national-cloud-support](../../includes/global-only.md)]
+[!INCLUDE [national-cloud-support](../../includes/global-only.md)]
 
 ## Permissions
 

api-reference/beta/api/application-upsert.md

@@ -18,7 +18,7 @@ Create a new [application](../resources/application.md) object if it doesn't exi
 > [!IMPORTANT]
 > Using PATCH to set [**passwordCredential**](../resources/passwordcredential.md) is not supported. Use the [addPassword](./application-addpassword.md) and [removePassword](./application-removepassword.md) methods to update the password or secret for an application.
 
-[!INCLUDE [national-cloud-support](../../includes/global-only.md)]
+[!INCLUDE [national-cloud-support](../../includes/all-clouds.md)]
 
 ## Permissions
 Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions [only if your app requires it](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference).