Merge pull request #244442 from henrymbuguakiarie/ciam-dotnet-maui-rbac

[CIAM] Add app roles to .NET MAUI app and receive them in the ID token (ADO-124246)

Author: v-ccolin

articles/active-directory/external-identities/customers/toc.yml

@@ -202,6 +202,8 @@ items:
                 href: tutorial-desktop-app-maui-sign-in-prepare-app.md
               - name: Sign in and sign out
                 href: tutorial-desktop-app-maui-sign-in-sign-out.md
+              - name: Use role-based access control
+                href: tutorial-desktop-maui-role-based-access-control.md
           - name: .NET WPF
             items:
               - name: Prepare tenant
@@ -219,6 +221,8 @@ items:
             href: tutorial-mobile-app-maui-sign-in-prepare-app.md
           - name: Sign in and sign out
             href: tutorial-mobile-app-maui-sign-in-sign-out.md
+          - name: Use role-based access control
+            href: tutorial-mobile-maui-role-based-access-control.md
       - name: Command-line interface (CLI) app
         items:
           - name: Node.js - sign in users

articles/active-directory/external-identities/customers/tutorial-desktop-app-maui-sign-in-sign-out.md

@@ -47,7 +47,6 @@ The next steps will organize our code so that the `main view` is defined.
 1. Select **Add**.
 1. The _MainView.xaml_ file will open in a new document tab, displaying all of the XAML markup that represents the UI of the page. Replace the XAML markup with the following markup:
 
-
    :::code language="xaml" source="~/ms-identity-ciam-dotnet-tutorial/1-Authentication/2-sign-in-maui/Views/MainView.xaml" :::
 
 1. Save the file.
@@ -69,7 +68,7 @@ The next step is to add the code for the button's `Clicked` event.
 
    :::code language="csharp" source="~/ms-identity-ciam-dotnet-tutorial/1-Authentication/2-sign-in-maui/Views/MainView.xaml.cs" :::
 
-The `MainView` class is a content page responsible for displaying the main view of the app. In the constructor, it retrieves the cached user account using the `MSALClientHelper` from the `PublicClientSingleton` instance and enables the sign-in button, if no cached user account is found. 
+The `MainView` class is a content page responsible for displaying the main view of the app. In the constructor, it retrieves the cached user account using the `MSALClientHelper` from the `PublicClientSingleton` instance and enables the sign-in button, if no cached user account is found.
 
 When the sign-in button is clicked, it calls the `AcquireTokenSilentAsync` method to acquire a token silently and navigates to the `claimsview` page using the `Shell.Current.GoToAsync` method. Additionally, the `OnBackButtonPressed` method is overridden to return true, indicating that the back button is disabled for this view.
 
@@ -84,14 +83,13 @@ The next steps will organize the code so that `ClaimsView` page is defined. The
 1. Select **Add**.
 1. The _ClaimsView.xaml_ file will open in a new document tab, displaying all of the XAML markup that represents the UI of the page. Replace the XAML markup with the following markup:
 
-
    :::code language="xaml" source="~/ms-identity-ciam-dotnet-tutorial/1-Authentication/2-sign-in-maui/Views/ClaimsView.xaml" :::
 
-    This XAML markup code represents the UI layout for a claim view in a .NET MAUI app. It starts by defining the `ContentPage` with a title and disabling the back button behavior. 
-    
-    Inside a `VerticalStackLayout`, there are several `Label` elements displaying static text, followed by a `ListView` named `Claims` that binds to a collection called `IdTokenClaims` to display the claims found in the ID token. Each claim is rendered within a `ViewCell` using a `DataTemplate` and displayed as a centered `Label` within a Grid. 
-    
-    Lastly, there's a `Sign Out` button centered at the bottom of the layout, which triggers the `SignOutButton_Clicked` event handler when clicked.
+   This XAML markup code represents the UI layout for a claim view in a .NET MAUI app. It starts by defining the `ContentPage` with a title and disabling the back button behavior.
+
+   Inside a `VerticalStackLayout`, there are several `Label` elements displaying static text, followed by a `ListView` named `Claims` that binds to a collection called `IdTokenClaims` to display the claims found in the ID token. Each claim is rendered within a `ViewCell` using a `DataTemplate` and displayed as a centered `Label` within a Grid.
+
+   Lastly, there's a `Sign Out` button centered at the bottom of the layout, which triggers the `SignOutButton_Clicked` event handler when clicked.
 
 #### Handle the ClaimsView data
 
@@ -101,7 +99,7 @@ The next step is to add the code to handle `ClaimsView` data.
 
    :::code language="csharp" source="~/ms-identity-ciam-dotnet-tutorial/1-Authentication/2-sign-in-maui/Views/ClaimsView.xaml.cs" :::
 
-   The _ClaimsView.xaml.cs_ code represents the code-behind for a claim view in a .NET MAUI app. It starts by importing the necessary namespaces and defining the `ClaimsView` class, which extends `ContentPage`. The `IdTokenClaims` property is an enumerable of strings, initially set to a single string indicating no claims found. 
+   The _ClaimsView.xaml.cs_ code represents the code-behind for a claim view in a .NET MAUI app. It starts by importing the necessary namespaces and defining the `ClaimsView` class, which extends `ContentPage`. The `IdTokenClaims` property is an enumerable of strings, initially set to a single string indicating no claims found.
 
    The `ClaimsView` constructor sets the binding context to the current instance, initializes the view components, and calls the `SetViewDataAsync` method asynchronously. The `SetViewDataAsync` method attempts to acquire a token silently, retrieves the claims from the authentication result, and sets the `IdTokenClaims` property to display them in the `ListView` named `Claims`. If a `MsalUiRequiredException` occurs, indicating that user interaction is needed for authentication, the app navigates to the claims view.
 
@@ -161,7 +159,7 @@ To create `appsettings.json`, follow these steps:
 Set the **Debug Target** in the Visual Studio toolbar to the device you want to debug and test with. The following steps demonstrate setting the **Debug Target** to _Windows_:
 
 1. Select **Debug Target** drop-down.
-1. Select **Framework** 
+1. Select **Framework**
 1. Select **net7.0-windows...**
 
 Run the app by pressing _F5_ or select the _play button_ at the top of Visual Studio.
@@ -180,5 +178,5 @@ Run the app by pressing _F5_ or select the _play button_ at the top of Visual St
 
 ## Next Steps
 
-- [Customize the default branding](how-to-customize-branding-customers.md).
-- [Configure sign-in with Google](how-to-google-federation-customers.md).
+> [!div class="nextstepaction"] 
+> [Tutorial: Add app roles to .NET MAUI app and receive them in the ID token](tutorial-desktop-maui-role-based-access-control.md)

articles/active-directory/external-identities/customers/tutorial-desktop-maui-role-based-access-control.md

@@ -0,0 +1,76 @@
+---
+title: "Tutorial: Use role-based access control in your .NET MAUI"
+description: This tutorial demonstrates how to add app roles to .NET Multi-platform App UI (.NET MAUI) shell and receive them in the ID token.
+author: henrymbuguakiarie
+manager: mwongerapk
+
+ms.author: henrymbugua
+ms.service: active-directory
+ms.topic: tutorial
+ms.subservice: ciam
+ms.date: 07/17/2023
+---
+
+# Tutorial: Use role-based access control in your .NET MAUI
+
+This tutorial demonstrates how to add app roles to .NET Multi-platform App UI (.NET MAUI) and receive them in the ID token.
+
+In this tutorial, you learn how to:
+
+> [!div class="checklist"]
+>
+> - Access the roles in the ID token.
+
+## Prerequisites
+
+- [Tutorial: Sign in users in .NET MAUI shell app](tutorial-desktop-app-maui-sign-in-sign-out.md)
+- [Using role-based access control for applications](how-to-use-app-roles-customers.md)
+
+## Receive groups and roles claims in .NET MAUI
+
+Once you configure your customer's tenant, you can retrieve your roles and groups claims in your client app. The roles and groups claims are both present in the ID token and the access token. Access tokens are only validated in the web APIs for which they were acquired by a client. The client shouldn't validate access tokens.
+
+The .NET MAUI needs to check for the app roles claims in the ID token to implement authorization in the client side.
+
+In this tutorial series, you created a .NET MAUI app where you developed the [_ClaimsView.xaml.cs_](tutorial-desktop-app-maui-sign-in-sign-out.md#handle-the-claimsview-data) to handle `ClaimsView` data. In this file, we inspect the contents of ID tokens. The value of the roles claim is checked in the following code snippet:
+
+To access the role claim, you can modify the code snippet as follows:
+
+```csharp
+var idToken = PublicClientSingleton.Instance.MSALClientHelper.AuthResult.IdToken;
+var handler = new JwtSecurityTokenHandler();
+var token = handler.ReadJwtToken(idToken);
+// Get the role claim value
+var roleClaim = token.Claims.FirstOrDefault(c => c.Type == "roles")?.Value;
+
+if (!string.IsNullOrEmpty(roleClaim))
+{
+    // If the role claim exists, add it to the IdTokenClaims
+    IdTokenClaims = new List<string> { roleClaim };
+}
+else
+{
+    // If the role claim doesn't exist, add a message indicating that no role claim was found
+    IdTokenClaims = new List<string> { "No role claim found in ID token" };
+}
+
+Claims.ItemsSource = IdTokenClaims;
+```
+
+> [!NOTE] 
+> To read the ID token, you must install the `System.IdentityModel.Tokens.Jwt` package.
+
+If you assign a user to multiple roles, the roles string contains all roles separated by a comma, such as `Orders.Manager, Store.Manager,...`. Make sure you build your application to handle the following conditions:
+
+- Absence of roles claims in the token
+- User hasn't been assigned to any role
+- Multiple values in the roles claim when you assign a user to multiple roles
+
+When you define app roles for your app, it is your responsibility to implement authorization logic for those roles.
+
+## Next steps
+
+For more information about group claims and making informed decisions regarding the usage of app roles or groups, see:
+
+- [Configuring group claims and app roles in tokens](/security/zero-trust/develop/configure-tokens-group-claims-app-roles)
+- [Choose an approach](../../develop/custom-rbac-for-developers.md#choose-an-approach)