Merge pull request #228824 from omondiatieno/custom-roles

v-regandowner · web-flow · commit 7c6e41ae4e3e · 2023-02-28T12:59:43.000-05:00
update powershell and graph API content
diff --git a/articles/active-directory/manage-apps/configure-permission-classifications.md b/articles/active-directory/manage-apps/configure-permission-classifications.md
@@ -30,7 +30,7 @@ The minimum permissions needed to do basic sign-in are `openid`, `profile`, `ema
 To configure permission classifications, you need:
 
 - An Azure account with an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
-- One of the following roles: An administrator, or owner of the service principal.
+- One of the following roles: A global administrator, or owner of the service principal.
 
 ## Manage permission classifications
 
@@ -57,7 +57,7 @@ You can use the latest [Azure AD PowerShell](/powershell/module/azuread/?preserv
 Run the following command to connect to Azure AD PowerShell. To consent to the required scopes, sign in with one of the roles listed in the prerequisite section of this article.
 
 ```powershell
-Connect-AzureAD -Scopes "Application.ReadWrite.All", "Directory.ReadWrite.All", "DelegatedPermissionGrant.ReadWrite.All".
+Connect-AzureAD -Scopes "Policy.ReadWrite.PermissionGrant".
 ```
 
 ### List the current permission classifications
@@ -134,7 +134,7 @@ You can use [Microsoft Graph PowerShell](/powershell/microsoftgraph/get-started?
 Run the following command to connect to Microsoft Graph PowerShell. To consent to the required scopes, sign in with one of the roles listed in the prerequisite section of this article.
 
 ```powershell
-Connect-MgGraph -Scopes "Application.ReadWrite.All", "Directory.ReadWrite.All", "DelegatedPermissionGrant.ReadWrite.All".
+Connect-MgGraph -Scopes "Policy.ReadWrite.PermissionGrant".
 ```
 
 ### List current permission classifications for an API
@@ -208,9 +208,7 @@ Remove-MgServicePrincipalDelegatedPermissionClassification -DelegatedPermissionC
 
 To configure permissions classifications for an enterprise application, sign in to [Graph Explorer](https://developer.microsoft.com/graph/graph-explorer) with one of the roles listed in the prerequisite section.
 
-You need to consent to the following permissions: 
-
-`Application.ReadWrite.All`, `Directory.ReadWrite.All`, `DelegatedPermissionGrant.ReadWrite.All`.
+You need to consent to the `Policy.ReadWrite.PermissionGrant` permission.
 
 Run the following queries on Microsoft Graph explorer to add a delegated permissions classification for an application.
 
diff --git a/articles/active-directory/manage-apps/custom-security-attributes-apps.md b/articles/active-directory/manage-apps/custom-security-attributes-apps.md
@@ -1,18 +1,20 @@
 ---
-title: Assign, update, list, or remove custom security attributes for an application (Preview) - Azure Active Directory
+title: Manage custom security attributes for an application (Preview) - Azure Active Directory
 description: Assign, update, list, or remove custom security attributes for an application that has been registered with your Azure Active Directory (Azure AD) tenant.
 services: active-directory
 author: omondiatieno
 ms.service: active-directory
 ms.subservice: app-mgmt
 ms.topic: how-to
 ms.workload: identity
-ms.date: 02/20/2023
+ms.date: 02/28/2023
 ms.author: jomondi
 ms.reviewer: rolyon
+zone_pivot_groups: enterprise-apps-all
+
 ---
 
-# Assign, update, list, or remove custom security attributes for an application (Preview)
+# Manage custom security attributes for an application (Preview)
 
 > [!IMPORTANT]
 > Custom security attributes are currently in PREVIEW.
@@ -26,18 +28,25 @@ To assign or remove custom security attributes for an application in your Azure
 
 - Azure AD Premium P1 or P2 license
 - [Attribute Assignment Administrator](../roles/permissions-reference.md#attribute-assignment-administrator)
-- [AzureADPreview](https://www.powershellgallery.com/packages/AzureADPreview) version 2.0.2.138 or later when using PowerShell
+- Make sure you have existing custom security attributes. To learn how to create a security attribute, see [Add or deactivate custom security attributes in Azure AD](../fundamentals/custom-security-attributes-add.md).
+
 
 > [!IMPORTANT]
-> By default, [Global Administrator](../roles/permissions-reference.md#global-administrator) and other administrator roles do not have permissions to read, define, or assign custom security attributes.
+> By default, [Global Administrator](../roles/permissions-reference.md#global-administrator) and other administrator roles don't have permissions to read, define, or assign custom security attributes.
 
-## Assign custom security attributes to an application
+## Assign, update, list, or remove  custom attributes for an application
 
-1. Sign in to the [Azure portal](https://portal.azure.com) or [Azure AD admin center](https://aad.portal.azure.com).
+Learn how to work with custom attributes for applications in Azure AD.
+### Assign custom security attributes to an application
 
-1. Make sure that you have existing custom security attributes. For more information, see [Add or deactivate custom security attributes in Azure AD](../fundamentals/custom-security-attributes-add.md).
 
-1. Select **Azure Active Directory** > **Enterprise applications**. 
+:::zone pivot="portal"
+
+Undertake the following steps to assign custom security attributes through the Azure portal.
+
+1. Sign in to the [Azure portal](https://portal.azure.com) or [Azure AD admin center](https://aad.portal.azure.com).
+
+1. Select **Azure Active Directory**, then select **Enterprise applications**. 
 
 1. Find and select the application you want to add a custom security attribute to.
 
@@ -55,39 +64,39 @@ To assign or remove custom security attributes for an application in your Azure
     - For predefined custom security attribute values, select a value from the **Assigned values** list.
     - For multi-valued custom security attributes, select **Add values** to open the **Attribute values** pane and add your values. When finished adding values, select **Done**.
 
-    ![Screenshot showing assigning a custom security attribute to an application.](./media/custom-security-attributes-apps/apps-attributes-assign.png)
+    ![Screenshot shows how to assign a custom security attribute to an application.](./media/custom-security-attributes-apps/apps-attributes-assign.png)
 
 1. When finished, select **Save** to assign the custom security attributes to the application.
 
-## Update custom security attribute assignment values for an application
+### Update custom security attribute assignment values for an application
 
 1. Sign in to the [Azure portal](https://portal.azure.com) or [Azure AD admin center](https://aad.portal.azure.com).
 
-1. Select **Azure Active Directory** > **Enterprise applications**.
+1. Select **Azure Active Directory**, then select **Enterprise applications**.
 
 1. Find and select the application that has a custom security attribute assignment value you want to update.
 
 1. In the Manage section, select **Custom security attributes (preview)**.
 
 1. Find the custom security attribute assignment value you want to update.
 
-    Once you have assigned a custom security attribute to an application, you can only change the value of the custom security attribute. You can't change other properties of the custom security attribute, such as attribute set or custom security attribute name.
+    Once you've assigned a custom security attribute to an application, you can only change the value of the custom security attribute. You can't change other properties of the custom security attribute, such as attribute set or custom security attribute name.
 
 1. Depending on the properties of the selected custom security attribute, you can update a single value, select a value from a predefined list, or update multiple values.
 
 1. When finished, select **Save**.
 
-## Filter applications based on custom security attributes
+### Filter applications based on custom security attributes
 
-You can filter the list of custom security attributes assigned to applications on the All applications page.
+You can filter the list of custom security attributes assigned to applications on the **All applications** page.
 
 1. Sign in to the [Azure portal](https://portal.azure.com) or [Azure AD admin center](https://aad.portal.azure.com).
 
-1. Select **Azure Active Directory** > **Enterprise applications**.
+1. Select **Azure Active Directory**, then select **Enterprise applications**.
 
 1. Select **Add filters** to open the Pick a field pane.
 
-    If you don't see Add filters, click the banner to enable the Enterprise applications search preview.
+    If you don't see **Add filters**, select the banner to enable the Enterprise applications search preview.
 
 1. For **Filters**, select **Custom security attribute**.
 
@@ -101,25 +110,28 @@ You can filter the list of custom security attributes assigned to applications o
 
 1. To apply the filter, select **Apply**.
 
-## Remove custom security attribute assignments from applications
+### Remove custom security attribute assignments from applications
 
 1. Sign in to the [Azure portal](https://portal.azure.com) or [Azure AD admin center](https://aad.portal.azure.com).
 
-1. Select **Azure Active Directory** > **Enterprise applications**.
+1. Select **Azure Active Directory**, then select **Enterprise applications**.
 
 1. Find and select the application that has the custom security attribute assignments you want to remove.
 
-1. In the Manage section, select **Custom security attributes (preview)**.
+1. In the **Manage** section, select **Custom security attributes (preview)**.
 
 1. Add check marks next to all the custom security attribute assignments you want to remove.
 
 1. Select **Remove assignment**.
 
-## PowerShell
+:::zone-end
+
+:::zone pivot="aad-powershell"
+### PowerShell
 
 To manage custom security attribute assignments for applications in your Azure AD organization, you can use PowerShell. The following commands can be used to manage assignments.
 
-#### Assign a custom security attribute with a multi-string value to an application (service principal)
+### Assign a custom security attribute with a multi-string value to an application (service principal)
 
 Use the [Set-AzureADMSServicePrincipal](/powershell/module/azuread/set-azureadmsserviceprincipal) command to assign a custom security attribute with a multi-string value to an application (service principal).
 
@@ -139,9 +151,9 @@ $attributes = @{
 Set-AzureADMSServicePrincipal -Id 7d194b0c-bf17-40ff-9f7f-4b671de8dc20 -CustomSecurityAttributes $attributes
 ```
 
-#### Update a custom security attribute with a multi-string value for an application (service principal)
+### Update a custom security attribute with a multi-string value for an application (service principal)
 
-Use the [Set-AzureADMSServicePrincipal](/powershell/module/azuread/set-azureadmsserviceprincipal) command to update a custom security attribute with a multi-string value for an application (service principal).
+Provide the new set of attribute values that you would like to reflect on the application. In this example, we're adding one more value for project attribute.
 
 - Attribute set: `Engineering`
 - Attribute: `Project`
@@ -159,7 +171,7 @@ $attributesUpdate = @{
 Set-AzureADMSServicePrincipal -Id 7d194b0c-bf17-40ff-9f7f-4b671de8dc20 -CustomSecurityAttributes $attributesUpdate 
 ```
 
-#### Get the custom security attribute assignments for an application (service principal)
+### Get the custom security attribute assignments for an application (service principal)
 
 Use the [Get-AzureADMSServicePrincipal](/powershell/module/azuread/get-azureadmsserviceprincipal) command to get the custom security attribute assignments for an application (service principal).
 
@@ -168,51 +180,172 @@ Get-AzureADMSServicePrincipal -Select CustomSecurityAttributes
 Get-AzureADMSServicePrincipal -Id 7d194b0c-bf17-40ff-9f7f-4b671de8dc20  -Select "CustomSecurityAttributes, Id"
 ```
 
-## Microsoft Graph API
+:::zone-end
+
+:::zone pivot="ms-powershell"
+
+To manage custom security attribute assignments for applications in your Azure AD organization, you can use Microsoft Graph PowerShell. The following commands can be used to manage assignments.
+
+### Assign a custom security attribute with a multi-string value to an application (service principal)
+
+Use the [Set-AzureADMSServicePrincipal](/powershell/module/azuread/set-azureadmsserviceprincipal) command to assign a custom security attribute with a multi-string value to an application (service principal).
+
+Given the values
+
+- Attribute set: Engineering
+- Attribute: Project
+- Attribute data type: String
+- Attribute value: "Baker"
+
+```powershell
+#Retrieve the servicePrincipal
+
+$ServicePrincipal= (Get-MgServicePrincipal -Filter "displayName eq 'Microsoft Graph'").Id
+
+$params = @{
+CustomSecurityAttributes = @{
+Engineering =@{
+"@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
+ProjectDate ="Baker"
+}
+ }
+ }
+
+Update-MgServicePrincipal -ServicePrincipalId $ServicePrincipal -BodyParameter $params
+```
+
+### Update a custom security attribute with a multi-string value for an application (service principal)
+
+Provide the new set of attribute values that you would like to reflect on the application. In this example, we're adding one more value for project attribute.
+
+```powershell
+$params = @{
+ CustomSecurityAttributes = @{
+Engineering =@{
+"@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
+Project =@(
+ "Baker"
+"Cascade"
+)
+ }
+ }
+ }
+Update-MgServicePrincipal -ServicePrincipalId $ServicePrincipal -BodyParameter $params
+```
+
+### Filter applications based on custom security attributes
+
+This example filters a list of applications with a custom security attribute assignment that equals the specified value.
+
+```powershell
+Get-MgServicePrincipal -CountVariable CountVar -Property "id,displayName,customSecurityAttributes" -Filter "customSecurityAttributes/Engineering/Project eq 'Baker'" -ConsistencyLevel eventual
+```
+
+### Remove custom security attribute assignments from applications
+
+In this example, we remove a custom security attribute assignment that supports multiple values. 
+
+```powershell
+$params = @{
+CustomSecurityAttributes = @{
+Engineering =@{
+"@odata.type" = "#Microsoft.DirectoryServices.CustomSecurityAttributeValue"
+ Project =@(
+ )
+ }
+ }
+ }
+Update-MgServicePrincipal -ServicePrincipalId $ServicePrincipal -BodyParameter $params
+```
+
+
+:::zone-end
 
-To manage custom security attribute assignments for applications in your Azure AD organization, you can use the Microsoft Graph API. The following API calls can be made to manage assignments.
+:::zone pivot="ms-graph"
+
+To manage custom security attribute assignments for applications in your Azure AD organization, you can use the Microsoft Graph API. Make the following API calls to manage assignments.
 
 For other similar Microsoft Graph API examples for users, see [Assign, update, list, or remove custom security attributes for a user](../enterprise-users/users-custom-security-attributes.md#microsoft-graph-api) and [Examples: Assign, update, list, or remove custom security attribute assignments using the Microsoft Graph API](/graph/custom-security-attributes-examples).
 
-#### Assign a custom security attribute with a string value to an application (service principal)
+### Assign a custom security attribute with a multi-string value to an application (service principal)
 
-Use the [Update servicePrincipal](/graph/api/serviceprincipal-update?view=graph-rest-beta&preserve-view=true) API to assign a custom security attribute with a string value to a user.
+Use the [Update servicePrincipal](/graph/api/serviceprincipal-update?view=graph-rest-beta&preserve-view=true) API to assign a custom security attribute with a string value to an application.
 
-- Attribute set: `Engineering`
-- Attribute: `ProjectDate`
+Given the values
+
+- Attribute set: Engineering
+- Attribute: Project
 - Attribute data type: String
-- Attribute value: `"2022-10-01"`
+- Attribute value: "Baker"
+
+```http
+PATCH https://graph.microsoft.com/beta/servicePrincipals/{id}
+Content-type: application/json
+
+{
+    "customSecurityAttributes":
+    {
+        "Engineering":
+        {
+            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
+            "Project@odata.type":"#Collection(String)",
+            "Project": "Baker"
+        }
+    }
+}
+```
+
+### Update a custom security attribute with a multi-string value for an application (service principal)
+
+Provide the new set of attribute values that you would like to reflect on the application. In this example, we're adding one more value for project attribute.
 
 ```http
 PATCH https://graph.microsoft.com/beta/servicePrincipals/{id}
+Content-type: application/json
+
 {
     "customSecurityAttributes":
     {
         "Engineering":
         {
             "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
-            "ProjectDate":"2022-10-01"
+            "Project@odata.type":"#Collection(String)",
+            "Project":["Baker","Cascade"]
         }
     }
 }
 ```
 
-#### Get the custom security attribute assignments for an application (service principal)
+### Filter applications based on custom security attributes
 
-Use the [Get servicePrincipal](/graph/api/serviceprincipal-get?view=graph-rest-beta&preserve-view=true) API to get the custom security attribute assignments for an application (service principal).
+This example filters a list of applications with a custom security attribute assignment that equals the specified value.
 
 ```http
-GET https://graph.microsoft.com/beta/servicePrincipals/{id}?$select=customSecurityAttributes
+GET https://graph.microsoft.com/beta/servicePrincipals?$count=true&$select=id,displayName,customSecurityAttributes&$filter=customSecurityAttributes/Engineering/Project eq 'Baker'ConsistencyLevel: eventual
 ```
 
-If there are no custom security attributes assigned to the application or if the calling principal does not have access, the response will look like:
+### Remove custom security attribute assignments from an application
+
+In this example, we remove a custom security attribute assignment that supports multiple values. 
 
 ```http
+PATCH https://graph.microsoft.com/beta/servicePrincipals/{id}
+Content-type: application/json
+
 {
-    "customSecurityAttributes": null
+    "customSecurityAttributes":
+    {
+        "Engineering":
+        {
+            "@odata.type":"#Microsoft.DirectoryServices.CustomSecurityAttributeValue",
+            "Project":[]
+        }
+    }
 }
 ```
 
+:::zone-end
+
 ## Next steps
 
 - [Add or deactivate custom security attributes in Azure AD](../fundamentals/custom-security-attributes-add.md)
diff --git a/articles/active-directory/manage-apps/manage-app-consent-policies.md b/articles/active-directory/manage-apps/manage-app-consent-policies.md
