renames, minor refactoring and updates to readme

Author: Kalyan Krishna

5-WebApp-AuthZ/5-1-Roles/Controllers/AccountController.cs

@@ -33,8 +33,12 @@ public IActionResult AccessDenied()
             return View();
         }
 
+        /// <summary>
+        /// Fetches all the groups a user is assigned to.  This method requires the signed-in user to be assigned to the 'DirectoryViewers' approle.
+        /// </summary>
+        /// <returns></returns>
         [AuthorizeForScopes(Scopes = new[] { GraphScopes.DirectoryReadAll })]
-        [Authorize(Policy = AppPolicies.DirectoryViewersOnly)]
+        [Authorize(Policy = AuthorizationPolicies.AssignmentToDirectoryViewerRoleRequired)]
         public async Task<IActionResult> Groups()
         {
             string[] scopes = new[] { GraphScopes.DirectoryReadAll };

5-WebApp-AuthZ/5-1-Roles/Controllers/HomeController.cs

@@ -19,8 +19,7 @@ public class HomeController : Controller
         private readonly ITokenAcquisition tokenAcquisition;
         private readonly WebOptions webOptions;
 
-        public HomeController(ITokenAcquisition tokenAcquisition,
-                              IOptions<WebOptions> webOptionValue)
+        public HomeController(ITokenAcquisition tokenAcquisition, IOptions<WebOptions> webOptionValue)
         {
             this.tokenAcquisition = tokenAcquisition;
             this.webOptions = webOptionValue.Value;
@@ -56,6 +55,23 @@ public async Task<IActionResult> Profile()
             return View();
         }
 
+        /// <summary>
+        /// Fetches and displays all the users in this directory. This method requires the signed-in user to be assigned to the 'UserReaders' approle.
+        /// </summary>
+        /// <returns></returns>
+        [AuthorizeForScopes(Scopes = new[] { GraphScopes.UserReadBasicAll })]
+        [Authorize(Policy = AuthorizationPolicies.AssignmentToUserReaderRoleRequired)]
+        public async Task<IActionResult> Users()
+        {
+            // Initialize the GraphServiceClient.
+            Graph::GraphServiceClient graphClient = GetGraphServiceClient(new[] { GraphScopes.UserReadBasicAll });
+
+            var users = await graphClient.Users.Request().GetAsync();
+            ViewData["Users"] = users.CurrentPage;
+
+            return View();
+        }
+
         private Graph::GraphServiceClient GetGraphServiceClient(string[] scopes)
         {
             return GraphServiceClientFactory.GetAuthenticatedGraphClient(async () =>
@@ -72,17 +88,5 @@ public IActionResult Error()
             return View(new ErrorViewModel { RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier });
         }
 
-        [AuthorizeForScopes(Scopes = new[] { GraphScopes.UserReadBasicAll })]
-        [Authorize(Policy = AppPolicies.UserReadersOnly)]
-        public async Task<IActionResult> Users()
-        {
-            // Initialize the GraphServiceClient.
-            Graph::GraphServiceClient graphClient = GetGraphServiceClient(new[] { GraphScopes.UserReadBasicAll });
-
-            var users = await graphClient.Users.Request().GetAsync();
-            ViewData["Users"] = users.CurrentPage;
-
-            return View();
-        }
     }
 }

5-WebApp-AuthZ/5-1-Roles/Infrastructure/AppRoles.cs

@@ -6,17 +6,27 @@
 namespace WebApp_OpenIDConnect_DotNet.Infrastructure
 {
     /// <summary>
-    /// Contains a list of all the Azure Ad app roles this app works with
+    /// Contains a list of all the Azure AD app roles this app depends on and works with.
     /// </summary>
-    public static class AppRoles
+    public static class AppRole
     {
+        /// <summary>
+        /// User readers can read basic profiles of all users in the directory.
+        /// </summary>
         public const string UserReaders = "UserReaders";
+
+        /// <summary>
+        /// Directory viewers can view objects in the whole directory.
+        /// </summary>
         public const string DirectoryViewers = "DirectoryViewers";
     }
 
-    public static class AppPolicies
+    /// <summary>
+    /// Wrapper class the contain all the authorization policies available in this application.
+    /// </summary>
+    public static class AuthorizationPolicies
     {
-        public const string UserReadersOnly = "UserReadersOnly";
-        public const string DirectoryViewersOnly = "DirectoryViewersOnly";
+        public const string AssignmentToUserReaderRoleRequired = "AssignmentToUserReaderRoleRequired";
+        public const string AssignmentToDirectoryViewerRoleRequired = "AssignmentToDirectoryViewerRoleRequired";
     }
 }

5-WebApp-AuthZ/5-1-Roles/README-incremental-instructions.md

@@ -176,6 +176,13 @@ public static IServiceCollection AddMicrosoftIdentityPlatformAuthentication(this
                 // Use the groups claim for populating roles
                 options.TokenValidationParameters.RoleClaimType = "roles";
             });
+
+            // Adding authorization policies that enforce authorization using Azure AD roles.
+            services.AddAuthorization(options => 
+            {
+                options.AddPolicy(AuthorizationPolicies.AssignmentToUserReaderRoleRequired, policy => policy.RequireRole(AppRole.UserReaders));
+                options.AddPolicy(AuthorizationPolicies.AssignmentToDirectoryViewerRoleRequired, policy => policy.RequireRole(AppRole.DirectoryViewers));
+            });
         // [removed for] brevity
 }
 
@@ -198,7 +205,7 @@ The following files have the code that would be of interest to you.
 
 1. Startup.cs
 
-1. In the `ConfigureServices` method of `Startup.cs', add the following line:
+1. In the `ConfigureServices` method of `Startup.cs', add the following lines:
 
      ```CSharp
             // This is required to be instantiated before the OpenIdConnectOptions starts getting configured.
@@ -211,16 +218,23 @@ The following files have the code that would be of interest to you.
 1. In the `HomeController.cs`, the following method is added with the `Authorize` attribute with the name of the app role **UserReaders**, that permits listing of users in the tenant.
 
     ```CSharp
-        [Authorize(Roles = AppRoles.UserReaders )]
+        [Authorize(Policy = AuthorizationPolicies.AssignmentToDirectoryViewerRoleRequired)]
         public async Task<IActionResult> Users()
         {
      ```
 
 1. In the `ConfigureServices` method of `Startup.cs', the following line instructs the asp.net security middleware to use the **roles** claim to fetch roles for authorization:
 
      ```CSharp
-                // The claim in the Jwt token where App roles are available.
-                options.TokenValidationParameters.RoleClaimType = "roles";
+    // The claim in the Jwt token where App roles are available.
+    options.TokenValidationParameters.RoleClaimType = "roles";
+
+     // Adding authorization policies that enforce authorization using Azure AD roles.
+    services.AddAuthorization(options => 
+    {
+        options.AddPolicy(AuthorizationPolicies.AssignmentToUserReaderRoleRequired, policy => policy.RequireRole(AppRole.UserReaders));
+        options.AddPolicy(AuthorizationPolicies.AssignmentToDirectoryViewerRoleRequired, policy => policy.RequireRole(AppRole.DirectoryViewers));
+    });
      ```
 
 1. A new class called `AccountController.cs` is introduced. This contains the code to intercept the default AccessDenied error's route and present the user with an option to sign-out and sign-back in with a different account that has access to the required role.
@@ -234,7 +248,7 @@ The following files have the code that would be of interest to you.
 1. The following method is also added with the `Authorize` attribute with the name of the app role **DirectoryViewers**, that permits listing of roles and groups the signed-in user is assigned to.
 
     ```CSharp
-        [Authorize(Roles = AppRoles.DirectoryViewers)]
+        [Authorize(Policy = AuthorizationPolicies.AssignmentToUserReaderRoleRequired)]
         public async Task<IActionResult> Groups()
         {
      ```

5-WebApp-AuthZ/5-1-Roles/README.md

@@ -100,7 +100,7 @@ There is one project in this sample. To register it, you can:
 1. In PowerShell run:
 
    ```PowerShell
-      cd .\AppCreationScripts\
+   cd .\AppCreationScripts\
    .\Configure.ps1
    ```
 
@@ -251,16 +251,20 @@ public static IServiceCollection AddMicrosoftIdentityPlatformAuthentication(this
                 // Use the groups claim for populating roles
                 options.TokenValidationParameters.RoleClaimType = "roles";
             });
+
+            // Adding authorization policies that enforce authorization using Azure AD roles.
+            services.AddAuthorization(options => 
+            {
+                options.AddPolicy(AuthorizationPolicies.AssignmentToUserReaderRoleRequired, policy => policy.RequireRole(AppRole.UserReaders));
+                options.AddPolicy(AuthorizationPolicies.AssignmentToDirectoryViewerRoleRequired, policy => policy.RequireRole(AppRole.DirectoryViewers));
+            });
         // [removed for] brevity
 }
 
-/*
 // In code..(Controllers & elsewhere)
-    [Authorize(Policy = DirectoryViewersOnly")] // In controllers
+[Authorize(Policy = AuthorizationPolicies.AssignmentToDirectoryViewerRoleRequired)]
 // or
-    User.IsInRole("UserReaders"); // In methods
-*/
-
+User.IsInRole("UserReaders"); // In methods
 ```
 
 ## About the code
@@ -306,33 +310,30 @@ This project was created using the following command.
             // 'http://schemas.microsoft.com/ws/2008/06/identity/claims/role' instead of 'roles'
             // This flag ensures that the ClaimsIdentity claims collection will be built from the claims in the token
             JwtSecurityTokenHandler.DefaultMapInboundClaims = false;
+
+            // Adding authorization policies that enforce authorization using Azure AD roles.
+            services.AddAuthorization(options => 
+            {
+                options.AddPolicy(AuthorizationPolicies.AssignmentToUserReaderRoleRequired, policy => policy.RequireRole(AppRole.UserReaders));
+                options.AddPolicy(AuthorizationPolicies.AssignmentToDirectoryViewerRoleRequired, policy => policy.RequireRole(AppRole.DirectoryViewers));
+            });
      ```
 
-1. Still in the `ConfigureServices` method of `Startup.cs`, we created the policies that wraps the authorization requirements in it. It is a good practice to wrap your authorization rules in policies, even if it is just one role, because policies are easily expandable, support unit tests, can have multiple requirements, can be code based and [more](https://docs.microsoft.com/en-us/aspnet/core/security/authorization/policies?view=aspnetcore-3.1):
+1. In the `ConfigureServices` method of `Startup.cs', the following line instructs the asp.net security middleware to use the **roles** claim to fetch roles for authorization:
 
-    ```CSharp
-        services.AddAuthorization(options => 
-        {
-            options.AddPolicy(AppPolicies.UserReadersOnly, policy => policy.RequireRole(AppRoles.UserReaders));
-            options.AddPolicy(AppPolicies.DirectoryViewersOnly, policy => policy.RequireRole(AppRoles.DirectoryViewers));
-        });
-    ```
+     ```CSharp
+     // The claim in the Jwt token where App roles are available.
+     options.TokenValidationParameters.RoleClaimType = "roles";
+     ```
 
-1. In the `HomeController.cs`, the following method is added with the `Authorize` attribute with the name of the policy created to check the app role **UserReaders**, that permits listing of users in the tenant.
+1. In the `HomeController.cs`, the following method is added with the `Authorize` attribute with the name of the policy that enforces that the signed-in user is present in the app role **UserReaders**, that permits listing of users in the tenant.
 
     ```CSharp
-        [Authorize(Policy = AppPolicies.UserReadersOnly)]
+        [Authorize(Policy = AuthorizationPolicies.AssignmentToUserReaderRoleRequired)]
         public async Task<IActionResult> Users()
         {
      ```
 
-1. In the `ConfigureServices` method of `Startup.cs'`, the following line instructs the asp.net security middleware to use the **roles** claim to fetch roles for authorization:
-
-     ```CSharp
-                // The claim in the Jwt token where App roles are available.
-                options.TokenValidationParameters.RoleClaimType = "roles";
-     ```
-
 1. A new class called `AccountController.cs` is introduced. This contains the code to intercept the default AccessDenied error's route and present the user with an option to sign-out and sign-back in with a different account that has access to the required role.
 
     ```CSharp
@@ -341,10 +342,10 @@ This project was created using the following command.
         {
      ```
 
-1. The following method is also added with the `Authorize` attribute with the name of the policy created to check the app role **DirectoryViewers**, that permits listing of roles and groups the signed-in user is assigned to.
+1. The following method is also added with the `Authorize` attribute with the name of the policy that enforces that the signed-in user is present in the app role **DirectoryViewers**, that permits listing of roles and groups the signed-in user is assigned to.
 
     ```CSharp
-        [Authorize(Policy = AppPolicies.DirectoryViewersOnly)]
+        [Authorize(Policy = AuthorizationPolicies.AssignmentToDirectoryViewerRoleRequired)]
         public async Task<IActionResult> Groups()
         {
      ```
@@ -384,7 +385,7 @@ In the left-hand navigation pane, select the **Azure Active Directory** service,
 
 ## Next steps
 
-- Learn how to use app groups. [Add authorization using security groups & groups claims to a Web app that signs-in users with the Microsoft identity platform](../../5-WebApp-AuthZ/5-2-Groups/README.md).
+- Learn how to use app groups. [Add authorization using security groups & groups claims to a Web app thats signs-in users with the Microsoft identity platform](../../5-WebApp-AuthZ/5-2-Groups/README.md).
 
 ## Learn more
 

5-WebApp-AuthZ/5-1-Roles/Startup.cs

@@ -61,11 +61,11 @@ public void ConfigureServices(IServiceCollection services)
                 options.TokenValidationParameters.RoleClaimType = "roles";
             });
 
-            // Creating policies that wraps the authorization requirements
+            // Adding authorization policies that enforce authorization using Azure AD roles.
             services.AddAuthorization(options => 
             {
-                options.AddPolicy(AppPolicies.UserReadersOnly, policy => policy.RequireRole(AppRoles.UserReaders));
-                options.AddPolicy(AppPolicies.DirectoryViewersOnly, policy => policy.RequireRole(AppRoles.DirectoryViewers));
+                options.AddPolicy(AuthorizationPolicies.AssignmentToUserReaderRoleRequired, policy => policy.RequireRole(AppRole.UserReaders));
+                options.AddPolicy(AuthorizationPolicies.AssignmentToDirectoryViewerRoleRequired, policy => policy.RequireRole(AppRole.DirectoryViewers));
             });
 
             services.AddControllersWithViews(options =>

5-WebApp-AuthZ/5-1-Roles/WebApp-OpenIDConnect-DotNet.csproj

@@ -19,7 +19,7 @@
 
   <ItemGroup>
     <PackageReference Include="Microsoft.AspNetCore.Authentication.AzureAD.UI" Version="3.0.0" />
-    <PackageReference Include="Microsoft.Graph" Version="1.14.0" />
+    <PackageReference Include="Microsoft.Graph" Version="1.21.0" />
   </ItemGroup>
 
   <ItemGroup>

Microsoft.Identity.Web/Microsoft.Identity.Web.csproj

@@ -56,6 +56,6 @@
     <PackageReference Include="Microsoft.AspNetCore.Authentication.AzureAD.UI" Version="3.0.0" />
     <PackageReference Include="Microsoft.AspNetCore.Authentication.AzureADB2C.UI" Version="3.0.0" />
     <PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="3.0.1" />
-    <PackageReference Include="Microsoft.Identity.Client" Version="4.7.1" />
+    <PackageReference Include="Microsoft.Identity.Client" Version="4.8.0" />
   </ItemGroup>
 </Project>