Share via

External authentication providers in AD FS in Windows Server 2012 R2: Overview

  • Article

Introduction

Welcome to the external authentication providers overview for AD FS in Windows Server 2012 R2.

This article provides you with the high level information, adapter requirements, and interface and method specs to help you understand the model and get you started toward building an adapter.  

For those of you interested in getting directly to the walk-through, go directly here .  For more conceptual information, read on.

Multi Factor Authentication as part of Conditional Access policies

Multi factor authentication is one of the key elements of conditional access policies in AD FS in Windows Server 2012 R2.  Multi factor authentication has traditionally meant using a Smart Card or other second factor with AD based authentication such as Windows Integrated Authentication.  This type of MFA can impose client side requirements such as smart card drivers, USB ports or other client hardware or software that cannot always be expected with BYOD client devices.  Because of this, AD FS in Windows Server 2012 R2 introduced a new pluggable authentication provider concept focused on flexibility, integration with AD FS policy, and consistent user experience.

Primary and Secondary Authentication

Previous versions of AD FS have supported authenticating users against Active Directory using any of the following methods:

  • Windows integrated authentication
  • Username and password
  • Client certificate (client TLS, including Smart Card authentication)

The above methods are still supported in Windows Server 2012 R2, but are now called “primary authentication” because we have introduced a new feature called secondary or “additional” authentication.  This is where  external authentication providers can plug in.

Secondary authentication occurs immediately after primary authentication and authenticates the same AD user.  Once primary authentication is complete and successful, AD FS invokes the external authentication handler.  This handler invokes additional authentication providers, either the in-box AD FS provider for certificate authentication or external MFA providers configured on the system, based on protocol inputs and policy.  AD FS passes the primary authenticated user’s identity to the additional authentication provider, which performs the authentication and hands the result back.  At this point, AD FS continues executing the authentication/authorization policy and issues the token accordingly.

Secondary authentication is performed by two key methods of the adapter: BeginAuthentication and TryEndAuthentication.  AD FS calls these methods as part of the authentication process, as shown in the diagrams below (click the individual images for higher resolution).

1) Primary authentication works as it always has:

 

2) Secondary authentication is triggered and BeginAuthentication provides initial form to user:

3) Form post back from client initiates TryEndAuthentication flow

 

Requirements for External Adapters

This section describes some of the key aspects of the implementation that are important for the adapter developer to understand.

Adapter Requirements

The adapter must implement the interfaces listed below (which you can see in more detail in the walk-through). 

 

  • IAuthenticationAdapter: top level adapter that contains the key authentication methods
  • IAuthenticationAdapterMetadata: defines adapter metadata including its name and the type(s) of authentication it supports
  • IAdapterPresentationForm (derived from IAdapterPresentation): creates the form html for the web interface

 

Implementation of the above interfaces will in turn require that you reference and use the following interface types.

  • IProofData: carries the user-provided proof data, such as answers to challenge questions, one time password, or PIN from MFA provider.
  • IAuthenticationContext: carries authentication context data across multiple round-trips to the user

In addition to the above, you must construct, at minimum, an html fragment for the web user interface that includes the required hidden elements documented in the walk-through.

 

Adapter Metadata

Metadata is the means by which an external authentication provider tells AD FS of its capabilities.  Metadata is read by AD FS at the time the adapter is registered.

Adapter metadata contains several elements which developers must be sure to select carefully:

AuthenticationMethods[]

This metadata member is an array of URI strings that indicates the authentication types offered by the external provider.  Multiple types can be defined, and at least one type from this list must be returned by the adapter to AD FS upon successful authentication.

AdminName

This single string is the name of the authentication provider, used by AD FS in the administrative UI shown below.  This name is not customizable by the administrator.  Note that this string describes the provider itself, not an individual authentication method as the provider can support multiple specific authentication methods.

FriendlyNames

A dictionary, indexed by LCID, of friendly names of the authentication provider, for use in the "method choice” page, shown below.  This text must be specified by the adapter to refer to their provider in a friendly way that is consumable by the end user.  The adapter should provide a description for each locale supported (specified in the AvailableLcids metadata member).  The AD FS framework will decide on the correct LCID, based on the locale of the client.

Descriptions

A list of localized descriptions of the authentication method, indexed by LCID.  These strings are not currently used in the AD FS UI, but they are visible to the administrator via PowerShell.  The adapter should provide a description for each lcid specified in the AvailableLcids metadata member.

Authentication itself

The adapter performs authentication by implementing two key methods: BeginAuthentication and TryEndAuthentication.  AD FS calls these methods as part of the authentication process, as shown in the diagrams above.

Upon successful authentication via TryEndAuthentication, the provider must return one claim with claim type https://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod that contains as its value the type of authentication performed.  This method must be one of the AuthenticationMethods[] declared via IAuthenticationAdapterMetadata.

Web user interface

The adapter provides html presentation information to AD FS via the IAdapterPresentationForm interface. This contains as one of its members a string of html that AD FS will include in the user-facing authentication pages.

Required form elements

There are two hidden form elements AD FS requires external providers to include within the required html string.  These are shown below:

<input id="authMethod" type="hidden" name="AuthMethod" value="%AuthMethod%"/>

<input id="context" type="hidden" name="Context" value="%Context%"/>

Invoking additional authentication

There are two ways to configure AD FS in Windows Server 2012 R2 to invoke multi factor authentication: policy configuration or via the protocol token request.

Via policy

AD FS in Windows Server 2012 R2 introduces a new rule set called “additional authentication rules” that are used for triggering additional (including external) authentication providers. As with many other settings in AD FS, you can set these rules at a global level or at the relying party trust level.

As part of the new rule set, AD FS introduces a new claim type and value to refer to "multi factor" (primary plus additional) authentication.  When this claim type and value is generated via an additional authentication rule, AD FS will invoke the external authentication handler, and hence the provider(s) configured on the system. If more than one provider is enabled in AD FS, the user will see a method choice page that presents the friendly name of each provider and allows the user to select one by clicking on it.

Via protocol

Relying parties can cause AD FS to invoke additional authentication by sending the special “MFA claim” value via protocol parameters within the WS-Federation or SAML protocols.

WS Federation request parameter

Use the following request protocol parameter and value for WS-Federation requests:

wauth=https://schemas.microsoft.com/claims/multipleauthn

SAML Protocol request parameter

Use the following request protocol element for SAML 2.0 requests:

samlp:AuthnContextClassRef with value https://schemas.microsoft.com/claims/multipleauthn

Claims issued by AD FS

In either of the above cases, AD FS issues the a special "MFA claim" to assert that MFA was done:

Claim type: https://schemas.microsoft.com/claims/authnmethodsreferences

Value: https://schemas.microsoft.com/claims/multipleauthn

Note: AD FS issues an additional claim of type https://schemas.microsoft.com/claims/authnmethodsreferences for each individual authentication type performed, both primary and additional.

Next steps

Now that you know some of the mechanics, you can get started building your provider using my step-by-step walk through here.

Also visit my colleague Ramiro's blog for a deep dive on AD FS multi-factor authentication policy.