How to: Implement Role Based Access Control (RBAC) in a Claims-Aware ASP.NET Application Using WIF and ACS

  • Article

Updated: June 19, 2015

Applies To: Azure

Applies To

  • Microsoft Azure Active Directory Access Control (also known as Access Control Service or ACS)

  • Windows® Identity Foundation (WIF)

  • ASP.NET

Summary

This topic explains how to implement Role Based Access Control (RBAC) authorization in claims-aware ASP.NET web applications using WIF and ACS.

Contents

  • Objectives

  • Overview

  • Summary of Steps

  • Step 1 – Create a Simple Claims Aware ASP.NET Web Application

  • Step 2 – Configure Role Claims in ACS

  • Step 3 – Implement Role Checks in an ASP.NET Web Application

  • Step 4 – Implement a Claims Transformation Using a Custom ClaimsAuthenticationManager

  • Step 5 – Test Your Work

  • Related Items

Objectives

  • Configure role claims using ACS.

  • Transform role claims using the ClaimsAuthenticationManager.

  • Implement role-based access control checks using the IsInRole method and the PrinciaplPermission attributes.

Overview

RBAC is a widely adopted approach for restricting access in applications. In ASP.NET web applications, this approach is implemented using the IsInRole method, the PrincipalPermission attribute, or demands, which have been available since ASP.NET 1.0. You can use claims for authorization, thereby preserving well-established practices while using new technologies, such as WIF and ACS. You can download the WIF runtime and SDK here:

Summary of Steps

  • Step 1 – Create a Simple Claims-Aware ASP.NET Web Application

  • Step 2 – Configure Role Claims in ACS

  • Step 3 – Implement Role Checks in an ASP.NET Web Application

  • Step 4 – Implement a Claims Transformation Using a Custom ClaimsAuthenticationManager

  • Step 5 – Test Your Work

Step 1 – Create a Simple Claims-Aware ASP.NET Web Application

This step shows you how to create a basic ASP.NET web application that will be used as a baseline for implementing RBAC.

To create a simple ASP.NET web application

  1. Start Visual Studio with the "Run as administrator" option. This is required for WIF.

  2. Create a new ASP.NET Empty Web Application.

  3. Add the aspx web form, and then give it a name, for example, default.aspx.

Step 2 – Configure Role Claims in the ACS

This step shows you how to configure role claims on the ACS Management Portal using rule groups. Refer to How to: Implement Token Transformation Logic Using Rules for a complete step-by-step walkthrough.

To configure role claims on the ACS Management Portal

  1. On the Edit Relying Party Application page, scroll down to the Rule Groups section, and then click the link of the desired group. Make sure it is selected.

  2. On the Edit Rule Group page, scroll down to the Rule section, and then click the Add Rule link.

  3. On the Add Claim Rule page, scroll down to the Output claim type section, click the Select type radio button, and then choose the following claim type.

    https://schemas.microsoft.com/ws/2008/06/identity/claims/role

  4. In the Output claim value section, click Enter value, and then enter the following text as a value in the text box:
    User

  5. Optionally, (recommended) add a description, and then click Save.

You have just configured the User role claim that can be added to any token. The scenario could be different depending upon your requirements. For more information about configuring more complex rules, see How to: Implement Token Transformation Logic Using Rules.

Step 3 – Implement Role Checks in an ASP.NET Web Application

This step shows how to implement RBAC.

To implement RBAC in an ASP.NET web page

  1. Add a reference to the Microsoft.IdentityModel assembly.

  2. Open the code behind default.aspx.cs.

  3. Add the following, using declarations.

    using System.Security.Permissions;
using System.Threading;
using Microsoft.IdentityModel.Claims;
using System.Security;

  4. Decorate the Page_Load event handler with the following security demand. This attribute will check if to see if the current user is in the User role. If not, an exception will be thrown.

    [PrincipalPermission(SecurityAction.Demand, Role = "User")]

  5. Add the following code to the body of Page_Load event handler. This is exactly the same as the demand expressed in the code.

    PrincipalPermission p = new PrincipalPermission(null, "User");
   p.Demand();

  6. Add the following code to the body of Page_Load event. As opposed to the previous code, this code does not throw an exception. Instead, IsInRole returns Boolean indicating whether the current user has the specified role.

    if (!User.IsInRole("User"))
                throw new SecurityException("Access is denied.");

  7. The completed code should look similar to the following.

    using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;

using System.Security.Permissions;
using System.Threading;
using Microsoft.IdentityModel.Claims;
using System.Security;

namespace WebIsInRoleACS
{
    public partial class _default : System.Web.UI.Page
    {
        //THIS SHOULD THROW AN EXCEPTION
        [PrincipalPermission(SecurityAction.Demand, Role = "User")]
        protected void Page_Load(object sender, EventArgs e)
        {

            //THIS SHOULD THROW AN EXCEPTION
            PrincipalPermission p = new PrincipalPermission(null, "User");
            p.Demand();

            //THIS RETURNS BOOL
            if (!User.IsInRole("User"))
                throw new SecurityException("Access is denied.");
        }
    }
}

Step 4 – Implement a Claims Transformation Using a Custom ClaimsAuthenticationManager

This is an optional step. This step shows how to transform claims using the ClaimsAuthenticationManager, which is part of the WIF pipeline that runs within the context of the ASP.NET application, as opposed to the claims transformation rules that run on ACS as described in Step 2 – Configure Role Claims in the ACS .

To implement the claims transformation using a custom ClaimsAuthenticationManager

  1. Add the Class Library project to the Visual Studio Solution, and then give it a name, for example, MyClaimsTransformationModule.

  2. Add a reference to the Microsoft.IdentityModel assembly.

  3. Add a reference to the System.IdentityModel assembly.

  4. Create a new class, and then give it a name, for example, ClaimsTransformationModule.

  5. Add the following declarations to the class.

    using Microsoft.IdentityModel.Claims;
using System.Security.Principal;

  6. Derive the class from the ClaimsAuthenticationManager type.

  7. Override its Authenticate method (this is where claims transformation will take place). Your code for the Authenticate method can be based on the following.

    if (incomingPrincipal != null && incomingPrincipal.Identity.IsAuthenticated == true)
{
    //DECIDE ON SOME CRITERIA IF CURRENT USER DESERVES THE ROLE
    //IClaimsIdentity identity = (IClaimsIdentity)incomingPrincipal.Identity;
    ((IClaimsIdentity)incomingPrincipal.Identity).Claims.Add(
        new Claim(ClaimTypes.Role, "Admin"));
}
return incomingPrincipal;

  8. Switch to the ASP.NET application and configure your custom ClaimsAuthenticationManager in its web.config.

      <microsoft.identityModel>
    <service>
      <claimsAuthenticationManager type="MyClaimsTransformationModule.ClaimsTransformationModule, MyClaimsTransformationModule" />

  9. Make sure the new assembly you created can be found by the application; the simplest way is to place it in the application’s bin folder.

Step 5 – Test Your Work

This step shows how to validate that the solution works. To test your solution, press the F5 button. Your ASP.NET web application should run in debug mode (you can add breakpoints to verify the code execution within Visual Studio). First, you should be taken to the authentication page of the identity provider that was configured for federation. After the authentication has completed, you should be redirected back to the Default.aspx page without an exception being thrown, which means that all of the security demands for the User role were satisfied.