What's the scenario?

Let's say you created your ASP.NET MVC 5 application authenticated with on premises identity with AD FS. Now, you want to allow access to some (if you wanted all of the operations, you can govern that from AD FS MFA policy) of the administrative operations only if the user performed two factor authentication:

Let's start off by letting the application know whether MFA was performed

Step 1: Send the MFA claim to the Relying Party

As I mentioned in part 1 of this tour, AD FS will generate a claim of type https://schemas.microsoft.com/claims/authnmethodsreferences that indicates the methods used when authenticating the user. If we send this claim in the relying party token, we can pivot the authorization of the administrative operations in the application's code.

Let's go to AD FS management console, and pass through the claim to the relying party's issuance transform rules:

One thing that I always do to make sure I get the right claims after setting the rules is try the flow with Fiddler. Since this is a ws-federation application, the token must be in the wresult parameter in the last redirect from AD FS to your relying party's endpoint:

With that, now we are ready to go to the application code.

Step 2: Authorize access based on MFA

The claims set by AD FS are accessible through HttpContext.User as a ClaimsIdentity object in the ASP.NET web application. This means that you can put conditional logic to grant or deny access based on any claim. For this post, I chose to encapsulate the logic using ASP.NET MVC Filtering, creating a custom attribute that derives from the platform's built-in AuthorizeAttribute which looks for a specific claim and value in the ClaimsIdentity, and redirect to an Access Denied view (which I will leave as an exercise for you J) when failing. The code of the attribute is very simple:

public class AuthorizeClaimAttribute : AuthorizeAttribute

{

    public string ClaimType { get; set; }

    public string ClaimValue { get; set; }

    protected override bool AuthorizeCore(HttpContextBase httpContext)

    {

        var user = httpContext.User;

        //Check if the user is not authenticated

        if (user == null)

        {

            throw new AuthenticationException(

"User is not authenticated.");

        }

        //If authenticated, validate this is a claims identity

        if (!(user.Identity is System.Security.Claims.ClaimsIdentity))

        {

            throw new AuthenticationException(string.Format(

"Identity is not ClaimsIdentity. Actual type = '{0}'. ",

                user.Identity.GetType().Name));

        }

        var userClaimsIdentity = user.Identity as System.Security.Claims.ClaimsIdentity;

        bool claimsFound =

            (from c in userClaimsIdentity.Claims

             where (c.Type == ClaimType && c.Value == ClaimValue)

             select c).Any();

        if (claimsFound)

        {

            return false;

        }

        return base.AuthorizeCore(httpContext);

    }

    protected override void HandleUnauthorizedRequest(AuthorizationContext filterContext)

    {

        filterContext.Result = new RedirectToRouteResult(

                new RouteValueDictionary 

                {

                    { "action", "Index" },

                    { "controller", "AccessDenied" },

                    { "errorDetail", string.Format(

"You require the claim '{0}' with value '{1}'", 

this.ClaimType, this.ClaimValue)

}

                });

    }

}

Then, you add this attribute to the methods you want in the controllers:

public class AdminOperationController : Controller

{

    // GET: /AdminOperation/

    [AuthorizeClaim(

            ClaimType = "https://schemas.microsoft.com/claims/authnmethodsreferences", 

            ClaimValue = "https://schemas.microsoft.com/claims/multipleauthn")]

    public ActionResult Index()

    {

        return View();

    }

}

When you try this out, you will see the following when attempting to get to the admin operation:

Nice! So … we are getting an access denied experience for the admin operations if MFA is not issued by AD FS. Now, how do we go about by proving that when MFA is performed, access is indeed allowed?

One more way to engage MFA

In part 1, I described how we can author policy in the server to engage MFA. Well, that is one way to do it.

In addition to this server driven behavior, we also allow request driven behavior for MFA for WS-Federation (via wauth request parameter) and SAML 2.0 (via requestedauthncontext request parameter). The value that must be supplied is https://schemas.microsoft.com/claims/multipleauthn.

If you give a try from the browser https://<<farmName>>/adfs/ls?wa=wsiginin1.0&wtrealm=<<rpidentifier>>&wauth= https://schemas.microsoft.com/claims/multipleauthn, you should see that MFA is engaged.

As a result, then we can get access to the admin operation

Excellent!!. However, this will work for the few users who not only foretells he needs MFA but also happens to know enough of the underlying protocols to know how to craft a request just the right way to get to get his admin task done. It does not sound very user friendly, does it?

Let's make this flow a bit more straightforward.

Step 3: Smoothen the authentication flow with a Step-up experience

One way to improve the admittedly subpar flow I described above is to have the user provide the second factor whenever he attempts an admin operation as opposed to show him an access denied page, which is commonly known as step-up authentication.

Since the AuthorizeClaimAttribute is too generic for any claim type/value that may or may not be related to authentication types, we can derive from AuthorizeClaimAttribute and specialize it to add some STS fallback semantics. Assuming that you configured your ASP.NET Application with Visual Studio 2013 web project templates, then the STS parameters are discoverable via web.config settings.

The code looks like this:

public class AuthorizeAuthenticationMethodAttribute : AuthorizeClaimAttribute

{

    protected override void HandleUnauthorizedRequest(AuthorizationContext filterContext)

    {

        //Validate Assumptions on the input            

        if (string.IsNullOrEmpty(ConfigurationManager.AppSettings["ida:FederationMetadataLocation"]))

        {

            throw new ConfigurationErrorsException(

"The 'ida:FederationMetadata' configuration parameter is missing"

);

        }

        Uri federationMetadataLocation = null;

        if (!Uri.TryCreate(

ConfigurationManager.AppSettings["ida:FederationMetadataLocation"], 

UriKind.Absolute, 

out federationMetadataLocation)

)

        {

            throw new ConfigurationErrorsException(

"The 'ida:FederationMetadataLocation' configuration parameter is not a valid absolute URI"

);

        }

        if (string.IsNullOrEmpty(ConfigurationManager.AppSettings["ida:Realm"]))

        {

            throw new ConfigurationErrorsException(

"The 'ida:Realm' configuration parameter is missing"

);

        }

        //redirect to the STS, requesting MFA, and replying back to the original URL afterwards

        string stsUrl = String.Format(

            "https://{0}/adfs/ls?wa=wsignin1.0&wtrealm={1}&wauth={2}&wreply={3}",

            federationMetadataLocation.Host,

            HttpUtility.UrlEncode(ConfigurationManager.AppSettings["ida:Realm"]),

            HttpUtility.UrlEncode("https://schemas.microsoft.com/claims/multipleauthn"),

            HttpUtility.UrlEncode(filterContext.RequestContext.HttpContext.Request.Url.AbsoluteUri));

        filterContext.Result = new RedirectResult(stsUrl);

    }

}

Then, we revisit our privileged operation to use our new attribute instead:

public class AdminOperationController : Controller

{

     // GET: /AdminOperation/

    [AuthorizeAuthenticationMethod( 

            ClaimType = "https://schemas.microsoft.com/claims/authnmethodsreferences", 

            ClaimValue = "https://schemas.microsoft.com/claims/multipleauthn")]

    public ActionResult Index()

    {

        return View();

    }

}

After you try this out from scratch, you will notice the following flow:

1. User attempts to access to your application
2. User is redirected to AD FS for authentication
3. After supplying credentials, the user can access your application. Note that so far, the user has used one factor of authentication
4. User now attempts to perform an operation that requires multi factor authentication
5. User is redirected to  AD FS for authentication, straight to the second factor challenge. The reason why the first factor is skipped is because the user acquired a single sign on (SSO) cookie that captured a bunch of details, including the fact that a first factor was performed. (The inner details of SSO are a separate topic altogether which deserves a whole post on its own J).
6. After authenticating with the second factor, the user can now access the operation attempted in step 4.
7. Subsequent attempts to access other operations that require MFA access will be seamless as the user now has all the data in the claims identity.

Conclusion:

• By flowing the authenticationmethodsreferences claim to your relying party, you can use it in your application.
• Using the protocol parameters, you can engage MFA from the authentication request.
• Using ASP.NET MVC Authorization Filters, you can make your application require MFA to access parts of the application and handle authorization failures by redirecting back to AD FS.

Now, your turn:

How would you go about decoupling the example above so that:

• In AD FS, you compute a level of assurance claim based on the authentication type(s).
• In the Application code, make the authorization and step-up decisions based upon the level of assurance.
• Tweak the level of assurance calculation so that Smart Card Authentication is also considered a strong level of assurance, even if it is the first factor

In this post, I want to talk about some of the ways in which you can configure AD FS to implement several MFA policies to accomplish different authentication requirements.

Before authoring the policies, you need to prepare your AD FS farm for MFA by registering and enabling at least one MFA authentication provider (such as Windows Azure Multi-Factor Authentication or the built-in X509 Client Cert authentication). Once you configure your farm, then you are ready for the next step and decide how to engage MFA in your applications.

Engaging MFA for a relying party is very similar to way you configure its authorization requirements: using the claims engine and the claims pipeline.

• The claims pipeline now includes a new stage before issuing the token to determine whether or not MFA should be engaged.
• There is a new claim rule set property called 'AdditionalAuthenticationRules' in both the ADFS global properties as well as the Relying Party trust object.

The way all the pieces above work together is depicted in the following diagram:

The sequence goes as follows:

1. The authentication request comes from the browser after a POST action, containing the user credentials (either fresh or SSO), information about the device ( "Device Context" in the diagram), and the request ( "Request Context" in the diagram)
2. The first factor authentication layer (Box A above) validates the identity of the user and the device. The first stage of authentication is completed, and the user attributes, user credentials, device, and request information are converted to claims.
3. The claim acceptance rules of the "Active Directory" claims provider trust (box B) is executed. The output set of this stage is used in subsequent stages (Issuance, Authorization, and … MFA J).
4. Both the Global and Relying Party MFA AdditionalAuthenticationRules claim rule sets are executed. (Box C). If the output claim set of either rule set contains a claim of type "https://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod" and value "https://schemas.microsoft.com/claims/multipleauthn", then MFA will engage.
5. If MFA is engaged, AD FS will call the logic of the MFA provider (box D) to render the web pages to challenge the user, who in turn POSTS the response back. The system also augments the claim set from step 2 above, indicating that MFA was performed (the MFA provider could potentially add more claims to the claim set depending upon its implementation).
6. The Authorization (Box E) and Issuance Transform Rules (Box F) are executed the same way as previous versions of AD FS to produce a permit/deny decision and RP claims respectively.

Now, everything boils down to what claims can we use and what the language allows us to do. While the full list of available claims is quite large, I would like to focus on the claims that can give us the most interesting MFA pivots:

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

  You can use this claim to find out if the user belongs to a specific group. 

• https://schemas.microsoft.com/2012/01/devicecontext/claims/isregistereduser:

  When the value of this claim is true, it means that the user who authenticated is the one who originally registered the device.

  When the value of this claim is false, it means that the user who authenticated is NOT the one who originally registered the device, which could be OK in the case of shared devices.

  If you only care about the device itself being registered, you might want to use the EXISTS operator against this claim

• https://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-endpoint-absolute-path:

  Since MFA is supported only for browser applications, you can use this claim to tell apart browser from non-browser requests, in case you have both kinds of protocols in the same relying party trust, which is the typical case when issuing tokens to a federation provider STS.

• https://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork:

  When the value is false, it means the request came through a web application proxy. When true, it means the request came directly to the STS.

• https://schemas.microsoft.com/2012/12/certificatecontext/* (multiple claim types):

  Claims that represent different fields and extensions of the X509 client certificate when used as an authentication method.

  One interesting use case here is to use the EKU claim (https://schemas.microsoft.com/2012/12/certificatecontext/extension/eku) to ascertain whether the user used a smart card (the exact EKU depends upon the PKI infrastructure of the customer).

• https://schemas.microsoft.com/claims/authnmethodsreferences:

  Used to indicate all authentication methods used to authenticate the user.

  When the MFA rules are executed, this claim will contain the authentication method performed in the first stage.

  When the Authorization or Issuance Transform rule set is executed, this claim will contain both the first and second factor authentication methods, if the MFA occurred (step 5 above).

Knowing that, we can now leverage the whole power of the AD FS Claims Language and Pipeline to go over some MFA Policy examples.

Let's start with the three options we streamlined in the AD FS Management Snap-in: Users/Groups, Devices, and Locations. I pasted the MMC UI for reference:

Scenario 1: MFA for certain groups or users

Per the table above, we use the Group SID claim:

c:[Type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value == "<<Group SID>>"]

=> issue(Type = "https://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod",

Value = "https://schemas.microsoft.com/claims/multipleauthn");

Note that the issuance condition (right side of the => operator). That will always be the same whenever you want to tell AD FS to perform MFA.

Scenario 2: MFA for unregistered (non workplace joined) devices

We can do this in two different ways. One is to require MFA if the user who registered the device is NOT the one who is authenticated using the "isregistereduser" claim (this is the one that the MMC snap-in uses):

c:[Type == "https://schemas.microsoft.com/2012/01/devicecontext/claims/isregistereduser", Value == "false"]

=> issue(Type = "https://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod",

Value = "https://schemas.microsoft.com/claims/multipleauthn");

Alternatively, if you don't need to discriminate between the user who registered the device from the one who is authenticated (for example, shared devices), then you can use the EXISTS operator and check for any of the claims associated with the workplace joined state. I personally use the registrationid claim:

NOT EXISTS([Type == "https://schemas.microsoft.com/2012/01/devicecontext/claims/isregistereduser"])

=> issue(Type = "https://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod",

Value = "https://schemas.microsoft.com/claims/multipleauthn");

Scenario 3: MFA for users coming from outside the corporate network

In this case, we use the "insidecorporatenetworkclaim" the same way we used a Boolean claim in the example above

c:[Type == "https://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value == "false"]

=> issue(Type = "https://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod",

Value = "https://schemas.microsoft.com/claims/multipleauthn");

As I mentioned above, the three scenarios above are the ones exposed in the AD FS management UI.

Now, let's take a look at a few more that require using the claims language directly:

Scenario 4: Tweak the MMC scenarios to be AND instead of OR

Each check box in the management UI corresponds to one rule, which means a logical OR operation when they are put together. For example, when you check both "Unregistered devices" and "Extranet", the rule set will generate two rules, that will look like this:

c:[Type == "https://schemas.microsoft.com/2012/01/devicecontext/claims/isregistereduser", Value == "false"]

=> issue(Type = "https://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod",

Value = "https://schemas.microsoft.com/claims/multipleauthn");

c:[Type == "https://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value == "false"]

=> issue(Type = "https://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod",

Value = "https://schemas.microsoft.com/claims/multipleauthn");

For scenarios that require a logical AND operation between the conditions above me, you should combine them in a single rule and use the … AND … operator. If you want to enable MFA only when coming from extranet with a device that is not joined to the workplace, then the rule might look like this:

[Type == "https://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value == "false"] &&

[Type == "https://schemas.microsoft.com/2012/01/devicecontext/claims/isregistereduser", Value == "false"]

=> issue(Type = "https://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod",

Value = "https://schemas.microsoft.com/claims/multipleauthn");

Scenario 5: MFA and Office 365/Azure Active Directory

Given that MFA is plugged into the authentication pipeline for browser applications, if the MFA claim rules generate the claim that will engage MFA over WS-Trust will cause the request to fail with the following message in the ADFS Admin event log channel, with event ID 325. As you can see, this looks pretty much like an access denied failure.

The Federation Service could not authorize token issuance for caller 'DOMAIN\User'

The caller is not authorized to request a token for the relying party 'urn:dumptoken'. See event 501 with the same Instance ID for caller identity.

This becomes a problem for federation provider scenarios, such as Azure Active Directory and Office 365. In this case, there is a single RP trust to represent both rich clients that use WS-Trust (such as Lync and Outlook), as well as browser based applications (like Sharepoint Online and OWA). In that case, we have to use the claim "x-ms-endpoint-absolute-path" which contains the URL through which the token request came in to AD FS in order to derive the protocol of the request as follows:

• If the URL contains /adfs/ls, then the protocol is either WS-Federation or SAML Protocol. Both of these support MFA.
• If the URL contains /adfs/oauth2, then protocol is OAuth, which also supports MFA. (I added this for the sake of completeness of determining the protocol based on the URL of the request. Office 365 does not use OAuth)

Using the regex operations of the claims language, the condition above looks like this:

[Type == "https://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-endpoint-absolute-path",

Value =~ "(/adfs/ls)|(/adfs/oauth2)"]

You can use this condition with any of the rules we discussed above to craft a more complex policy, using the AND operator. For example, if you want to require MFA for office 365 web applications when coming from extranet, then the rule is:

c:[Type == "https://schemas.microsoft.com/ws/2012/01/insidecorporatenetwork", Value == "false"] &&

c1:[Type == "https://schemas.microsoft.com/2012/01/requestcontext/claims/x-ms-endpoint-absolute-path",

Value =~ "(/adfs/ls)|(/adfs/oauth2)"]

=> issue(Type = "https://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod",

Value = "https://schemas.microsoft.com/claims/multipleauthn");

Scenario 6: Deny authorization to the relying party if MFA was not performed

This one is a bit different from the previous examples because the rule to accomplish this will be in the authorization rule set, instead of the MFA rule set. As I mentioned above, the claim https://schemas.microsoft.com/claims/authnmethodsreferences contains the list of authentications methods performed. It will hold the value https://schemas.microsoft.com/claims/multipleauthn if MFA was performed.

NOT EXISTS([Type == "https://schemas.microsoft.com/claims/authnmethodsreferences",

Value == "https://schemas.microsoft.com/claims/multipleauthn"])

=> issue(Type = "https://schemas.microsoft.com/authorization/claims/deny",

Value = "DenyUsersWithClaim");

Conclusion

As you can see, with the set of claims available and the richness of the claims language, AD FS offers a lot of flexibility when it comes to engage MFA in your browser applications. We only went through a couple of examples, but you can do a lot more!

Stay tuned for more details on MFA on AD FS!.

Now, your turn:

How would you author the policy for an application with the following constraints:

1. Allow single factor authentication (as in, no MFA) from workplace joined devices
2. Skip MFA when using Smart Card if the device is NOT joined to the workplace
3. Do MFA in any other case

Hint: you might need the claim language's add issuance statement

What can you expect from this blog? Well, mostly technical stuff about the products we deliver in our team:

• Deep dives
• Scenario discussions
• Troubleshooting
• Tips and tricks, mostly with .NET code and Windows PowerShell

I hope you find my posts useful.

Cheers!