Merge pull request #189634 from MicrosoftDocs/main

2/24 AM Publish

Author: huypub

articles/active-directory/develop/howto-add-app-roles-in-azure-ad-apps.md

@@ -26,15 +26,12 @@ Another approach is to use Azure AD Groups and Group Claims as shown in the [act
 
 ## Declare roles for an application
 
-You define app roles by using the [Azure portal](https://portal.azure.com). App roles are usually defined on an application registration representing a service, app or API. When a user signs in to the application, Azure AD emits a `roles` claim for each role that the user or service principal has been granted individually to the user and from their group membership. This can be used to implement claim-based authorization. App roles can be assigned [to a user or a group of users](../manage-apps/add-application-portal-assign-users.md). App roles can also be assigned to the service principal for another application, or [to the service principal for a managed identity](../managed-identities-azure-resources/how-to-assign-app-role-managed-identity-powershell.md).
+You define app roles by using the [Azure portal](https://portal.azure.com) during the [app registration process](quickstart-register-app.md). App roles are defined on an application registration representing a service, app or API. When a user signs in to the application, Azure AD emits a `roles` claim for each role that the user or service principal has been granted individually to the user and the user's group memberships. This can be used to implement claim-based authorization. App roles can be assigned [to a user or a group of users](../manage-apps/add-application-portal-assign-users.md). App roles can also be assigned to the service principal for another application, or [to the service principal for a managed identity](../managed-identities-azure-resources/how-to-assign-app-role-managed-identity-powershell.md).
 
 > [!IMPORTANT]
 > Currently if you add a service principal to a group, and then assign an app role to that group, Azure AD does not add the `roles` claim to tokens it issues.
 
-There are two ways to declare app roles by using the Azure portal:
-
-- [App roles UI](#app-roles-ui)
-- [App manifest editor](#app-manifest-editor)
+App roles are declared using the app roles by using[App roles UI](#app-roles-ui) in the Azure portal:
 
 The number of roles you add counts toward application manifest limits enforced by Azure Active Directory. For information about these limits, see the [Manifest limits](./reference-app-manifest.md#manifest-limits) section of [Azure Active Directory app manifest reference](reference-app-manifest.md).
 
@@ -64,66 +61,6 @@ To create an app role by using the Azure portal's user interface:
 
 1. Select **Apply** to save your changes.
 
-### App manifest editor
-
-To add roles by editing the manifest directly:
-
-1. Sign in to the <a href="https://portal.azure.com/" target="_blank">Azure portal</a>.
-1. Select the **Directory + subscription** filter in top menu, and then choose the Azure Active Directory tenant that contains the app registration to which you want to add an app role.
-1. Search for and select **Azure Active Directory**.
-1. Under **Manage**, select **App registrations**, and then select the application you want to define app roles in.
-1. Again under **Manage**, select **Manifest**.
-1. Edit the app manifest by locating the `appRoles` setting and adding your application roles. You can define app roles that target `users`, `applications`, or both. The following JSON snippets show examples of both.
-1. Save the manifest.
-
-Each app role definition in the manifest must have a unique GUID for its `id` value.
-
-The `value` property of each app role definition should exactly match the strings that are used in the code in the application. The `value` property can't contain spaces. If it does, you'll receive an error when you save the manifest.
-
-#### Example: User app role
-
-This example defines an app role named `Writer` that you can assign to a `User`:
-
-```json
-"appId": "8763f1c4-0000-0000-0000-158e9ef97d6a",
-"appRoles": [
-    {
-      "allowedMemberTypes": [
-        "User"
-      ],
-      "displayName": "Writer",
-      "id": "d1c2ade8-0000-0000-0000-6d06b947c66f",
-      "isEnabled": true,
-      "description": "Writers Have the ability to create tasks.",
-      "value": "Writer"
-    }
-  ],
-"availableToOtherTenants": false,
-```
-
-#### Example: Application app role
-
-When available to `applications`, app roles appear as application permissions in an app registration's **Manage** section > **API permissions > Add a permission > My APIs > Choose an API > Application permissions**.
-
-This example shows an app role targeted to an `Application`:
-
-```json
-"appId": "8763f1c4-0000-0000-0000-158e9ef97d6a",
-"appRoles": [
-    {
-      "allowedMemberTypes": [
-        "Application"
-      ],
-      "displayName": "ConsumerApps",
-      "id": "47fbb575-0000-0000-0000-0f7a6c30beac",
-      "isEnabled": true,
-      "description": "Consumer apps have access to the consumer data.",
-      "value": "Consumer"
-    }
-  ],
-"availableToOtherTenants": false,
-```
-
 ## Assign users and groups to roles
 
 Once you've added app roles in your application, you can assign users and groups to the roles. Assignment of users and groups to roles can be done through the portal's UI, or programmatically using [Microsoft Graph](/graph/api/user-post-approleassignments). When the users assigned to the various app roles sign in to the application, their tokens will have their assigned roles in the `roles` claim.
@@ -164,7 +101,7 @@ To assign app roles to an application by using the Azure portal:
 
 The newly added roles should appear in your app registration's **API permissions** pane.
 
-#### Grant admin consent
+### Grant admin consent
 
 Because these are _application permissions_, not delegated permissions, an admin must grant consent to use the app roles assigned to the application.
 
@@ -176,7 +113,7 @@ The **Status** column should reflect that consent has been **Granted for \<tenan
 <a name="use-app-roles-in-your-web-api"></a>
 ## Usage scenario of app roles
 
-If you're implementing app role business logic that signs in the users in your application scenario, first define the app roles in **App registration**. Then, an admin assigns them to users and groups in the **Enterprise applications** pane. These assigned app roles are included with any token that's issued for your application, either access tokens when your app is the API being called by an app or ID tokens when your app is signing in a user. 
+If you're implementing app role business logic that signs in the users in your application scenario, first define the app roles in **App registration**. Then, an admin assigns them to users and groups in the **Enterprise applications** pane. These assigned app roles are included with any token that's issued for your application, either access tokens when your app is the API being called by an app or ID tokens when your app is signing in a user.
 
 If you're implementing app role business logic in an app-calling-API scenario, you have two app registrations. One app registration is for the app, and a second app registration is for the API. In this case, define the app roles and assign them to the user or group in the app registration of the API. When the user authenticates with the app and requests an access token to call the API, a roles claim is included in the access token. Your next step is to add code to your web API to check for those roles when the API is called.
 
@@ -194,13 +131,14 @@ Though you can use app roles or groups for authorization, key differences betwee
 
 Developers can use app roles to control whether a user can sign in to an app or an app can obtain an access token for a web API. To extend this security control to groups, developers and admins can also assign security groups to app roles.
 
-App roles are preferred by developers when they want to describe and control the parameters of authorization in their app themselves. For example, an app using groups for authorization will break in the next tenant as both the group ID and name could be different. An app using app roles remains safe. In fact, assigning groups to app roles is popular with SaaS apps for the same reasons.
+App roles are preferred by developers when they want to describe and control the parameters of authorization in their app themselves. For example, an app using groups for authorization will break in the next tenant as both the group ID and name could be different. An app using app roles remains safe. In fact, assigning groups to app roles is popular with SaaS apps for the very same reasons as it allows the SaaS app to be provisioned in multiple tenants.
 
 ## Next steps
 
 Learn more about app roles with the following resources.
 
 - Code samples on GitHub
+  - [Add authorization using app roles & roles claims to an ASP\.NET Core web app](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/blob/master/5-WebApp-AuthZ/5-1-Roles/README.md)
   - [Add authorization using groups and group claims to an ASP.NET Core web app](https://aka.ms/groupssample)
   - [Angular single-page application (SPA) calling a .NET Core web API and using app roles and security groups](https://github.com/Azure-Samples/ms-identity-javascript-angular-tutorial/tree/main/5-AccessControl)
   - [React single-page application (SPA) calling a Node.js web API and using app roles and security groups](https://github.com/Azure-Samples/ms-identity-javascript-react-tutorial/tree/main/5-AccessControl)

articles/active-directory/manage-apps/toc.yml

@@ -24,8 +24,10 @@
       href: delete-application-portal.md
   - name: Tutorials
     items:
-    - name: List of app integration tutorials
-      href: ../saas-apps/tutorial-list.md
+    - name: Manage access and security
+      href: tutorial-manage-access-security.md
+    - name: Govern and monitor
+      href: tutorial-govern-monitor.md
   - name: Samples
     items: 
     - name: Overview of App Management samples
@@ -86,6 +88,8 @@
   - name: How-to guides
     expanded: false
     items:
+    - name: List of app integration tutorials
+      href: ../saas-apps/tutorial-list.md
     - name: Assign owners
       href: assign-app-owners.md
     - name: Manage access

articles/active-directory/manage-apps/tutorial-govern-monitor.md

@@ -0,0 +1,111 @@
+---
+title: "Tutorial: Govern and monitor applications"
+titleSuffix: Azure AD
+description: In this tutorial, you learn how to govern and monitor an application in Azure Active Directory.
+author: omondiatieno
+manager: CelesteDG
+ms.author: jomondi
+ms.service: active-directory
+ms.subservice: app-mgmt
+ms.topic: tutorial
+ms.date: 02/24/2022
+# Customer intent: As an administrator of an Azure AD tenant, I want to govern and monitor my applications.
+---
+
+# Tutorial: Govern and monitor applications
+
+The IT administrator at Fabrikam has added and configured an application from the [Azure Active Directory (Azure AD) application gallery](overview-application-gallery.md). They also made sure that access can be managed and that the application is secure by using the information in [Tutorial: Manage application access and security](tutorial-manage-access-security.md). They now need to understand the resources that are available to govern and monitor the application.
+
+Using the information in this tutorial, an administrator of the application learns how to:
+
+> [!div class="checklist"]
+> * Create an access review
+> * Access the audit logs report
+> * Access the sign-ins report
+> * Send logs to Azure Monitor
+
+## Prerequisites
+
+- An Azure account with an active subscription. If you don't already have one, [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
+- One of the following roles: Global Administrator, Privileged Role Administrator, Cloud Application Administrator, or Application Administrator.
+- An enterprise application that has been configured in your Azure AD tenant.
+
+## Create an access review
+
+The administrator wants to make sure that users or guests have appropriate access. They decide to ask users of the application to participate in an access review and recertify or attest to their need for access. When the access review is finished, they can then make changes and remove access from users who no longer need it. For more information, see
+[Manage user and guest user access with access reviews](../governance/manage-access-review.md).
+
+To create an access review:
+
+1. Sign in to the [Azure portal](https://portal.azure.com/) with one of the roles listed in the prerequisites.
+1. Go to **Azure Active Directory**, and then select **Identity Governance**.
+1. On the left menu, select **Access reviews**.
+1. Select **New access review** to create a new access review.
+1. In **Select what to review**, select **Applications**.
+1. Select **+ Select application(s)**, select the application, and then choose **Select**.
+1. Now you can select a scope for the review. Your options are:
+    - **Guest users only** - This option limits the access review to only the Azure AD B2B guest users in your directory.
+    - **All users** - This option scopes the access review to all user objects associated with the resource.
+    Select **All users**.
+1. Select **Next: Reviews**.
+1. In the **Specify reviewers** section, in the Select reviewers box, select **Selected user(s) or group(s)**, select **+ Select reviewers**, and then select the user account that is assigned to the application.
+1. In the **Specify recurrence of review** section, specify the following selections:
+    - **Duration (in days)** - Accept the default value of **3**.
+    - **Review recurrence** - select **One time**.
+    - **Start date** - Accept today's date as the start date.
+1. Select **Next: Settings**.
+1. In the **Upon completion settings** section, you can specify what happens after the review finishes. Select **Auto apply results to resource**.
+1. Select **Next: Review + Create**.
+1. Name the access review. Optionally, give the review a description. The name and description are shown to the reviewers.
+1. Review the information and select **Create**.
+
+### Start the access review
+
+After you've specified the settings for an access review, select **Start**. The access review appears in your list with an indicator of its status.
+
+By default, Azure AD sends an email to reviewers shortly after the review starts. If you choose not to have Azure AD send the email, be sure to inform the reviewers that an access review is waiting for them to complete. You can show them the instructions for how to review access to groups or applications. If your review is for guests to review their own access, show them the instructions for how to review access for themselves to groups or applications.
+
+If you've assigned guests as reviewers and they haven't accepted their invitation to the tenant, they won't receive an email from access reviews. They must first accept the invitation before they can begin reviewing.
+
+## Access the audit logs report
+
+The audit logs report combines several reports around application activities into a single view for context-based reporting. For more information, see [Audit logs in Azure Active Directory](../reports-monitoring/concept-audit-logs.md).
+
+To access the audit logs report, select **Audit logs** from the **Activity** section of the Azure Active Directory page.
+
+The audit logs report consolidates the following reports:
+
+- Password reset activity
+- Password reset registration activity
+- Self-service groups activity
+- Office365 Group Name Changes
+- Account provisioning activity
+- Password rollover status
+- Account provisioning errors
+
+## Access the sign-ins report
+
+The Sign-ins view includes all user sign-ins, and the Application Usage report. You also can view application usage information in the Manage section of the Enterprise applications overview. For more information, see [Sign-in logs in Azure Active Directory](../reports-monitoring/concept-sign-ins.md)
+
+To access the sign-in logs report, select **Sign-ins** from the **Monitoring** section of the Azure Active Directory blade.
+
+## Send logs to Azure Monitor
+
+The Azure AD activity logs only store information for a maximum of 30 days. Depending on your needs, you may require extra storage to back up the activity logs data. Using the Azure Monitor, you can archive the audit and sign logs to an Azure storage account to retain the data for a longer time. 
+The Azure Monitor is also useful for rich visualization, monitoring and alerting of data. To learn more about the Azure Monitor and the cost considerations for extra storage, see [Azure AD activity logs in Azure Monitor](../reports-monitoring/concept-activity-logs-azure-monitor.md).
+
+To send logs to your logs analytics workspace:
+
+1. Select **Diagnostic settings**, and then select **Add diagnostic setting**. You can also select Export Settings from the Audit Logs or Sign-ins page to get to the diagnostic settings configuration page.
+1. In the Diagnostic settings menu, select **Send to Log Analytics workspace**, and then select Configure.
+1. Select the Log Analytics workspace you want to send the logs to, or create a new workspace in the provided dialog box.
+1.	Select the logs that you would like to send to the workspace.
+1.	Select **Save** to save the setting.
+
+After about 15 minutes, verify that events are streamed to your Log Analytics workspace.
+
+## Next steps
+
+Advance to the next article to learn how to...
+> [!div class="nextstepaction"]
+> [Manage consent to applications and evaluate consent requests](manage-consent-requests.md)