Merge pull request #84914 from PramodKumarHK89/patch-1

app role claim clarification.

Author: ktoliver

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

@@ -173,9 +173,12 @@ Because these are _application permissions_, not delegated permissions, an admin
 
 The **Status** column should reflect that consent has been **Granted for \<tenant name\>**.
 
-## Use app roles in your web API
+<a name="use-app-roles-in-your-web-api"></a>
+## Usage scenario of app roles
 
-Once you've defined app roles and assigned them to a user, group, or application, your next step is to add code to your web API that checks for those roles when the API is called. That is, when a client app requests an API operation you've decided requires authorization, your API's code must verify the scopes are in the access token presented in the client app's call.
+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.
 
 To learn how to add authorization to your web API, see [Protected web API: Verify scopes and app roles](scenario-protected-web-api-verification-scope-app-roles.md).
 

articles/active-directory/develop/scenario-protected-web-api-verification-scope-app-roles.md

@@ -20,7 +20,7 @@ ms.custom: aaddev
 
 This article describes how you can add authorization to your web API. This protection ensures that the API is called only by:
 
-- Applications on behalf of users who have the right scopes.
+- Applications on behalf of users who have the right scopes and roles.
 - Daemon apps that have the right application roles.
 
 The code snippets in this article are extracted from the following code samples on GitHub:
@@ -277,29 +277,20 @@ public class TodoListController : ApiController
     }
 ```
 
-Instead, you can use the [Authorize(Roles = "role")] attributes on the controller or an action (or a razor page).
+
+Instead, you can use the [Authorize(Roles = "access_as_application")] attributes on the controller or an action (or a razor page).
 
 ```CSharp
-[Authorize(Roles = "role")]
+[Authorize(Roles = "access_as_application")]
 MyController : ApiController
 {
     // ...
 }
 ```
 
-But for this, you'll need to map the Role claim to "roles" in the Startup.cs file:
-
-```CSharp
- services.Configure<OpenIdConnectOptions>(OpenIdConnectDefaults.AuthenticationScheme, options =>
- {
-    // The claim in the Jwt token where App roles are available.
-    options.TokenValidationParameters.RoleClaimType = "roles";
- });
-```
-
-This isn't the best solution if you also need to do authorization based on groups.
+[Role-based authorization in ASP.NET Core](/aspnet/core/security/authorization/roles) lists several approaches to implement role based authorization. Developers can choose one among them which suits to their respective scenarios.
 
-For details, see the web app incremental tutorial on [authorization by roles and groups](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/tree/master/5-WebApp-AuthZ).
+For working samples, see the web app incremental tutorial on [authorization by roles and groups](https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2/tree/master/5-WebApp-AuthZ).
 
 ### [ASP.NET Classic](#tab/aspnet)
 
@@ -340,9 +331,13 @@ For a full version of `ValidateAppRole` for ASP.NET Core, see [_RolesRequiredHtt
 
 ---
 
-### Accepting app-only tokens if the web API should be called only by daemon apps
+### Verify app roles in APIs called on behalf of users
+
+Users can also use roles claims in user assignment patterns, as shown in [How to add app roles in your application and receive them in the token](howto-add-app-roles-in-azure-ad-apps.md). If the roles are assignable to both, checking roles will let apps sign in as users and users sign in as apps. We recommend that you declare different roles for users and apps to prevent this confusion.
 
-Users can also use roles claims in user assignment patterns, as shown in [How to: Add app roles in your application and receive them in the token](howto-add-app-roles-in-azure-ad-apps.md). If the roles are assignable to both, checking roles will let apps sign in as users and users to sign in as apps. We recommend that you declare different roles for users and apps to prevent this confusion.
+If you have defined app roles with user/group, then roles claim can also be verified in the API along with scopes. The verification logic of the app roles in this scenario remains same as if API is called by the daemon apps since there is no differentiation in the role claim for user/group and application. 
+
+### Accepting app-only tokens if the web API should be called only by daemon apps
 
 If you want only daemon apps to call your web API, add the condition that the token is an app-only token when you validate the app role.