If you hit a problem with either the sample or your own adapter, you’ll probably wish to debug to see what’s going on.  You’ll need to attach your debugger to the AD FS process Microsoft.IdentityServer.ServiceHost.exe.  

If you are using Visual Studio 2012 you can do this locally or remotely.

Tips for remote debugging in Visual Studio 2012

• Install the VS 2012 remote debugging components on the AD FS test machine
• After installation, the first time you run “Remote Debugger” it will configure the remote debugging components on the test STS (including the correct firewall settings)
• On the dev box:
• Ensure the configured list of symbols file locations (Debug->Options and Settings->Debugging->Symbols) contains an entry that points to the location of your pdb file
• Ensure the version of the dll and pdb match and match the source
• Ensure you are running VS 2012 as elevated (run as administrator from Start page)
• Start remote debugging by choosing menu option Debug...Attach to process... and select the AD FS service as shown below
• Specify the remote machine and port in the Qualifier (you can get the port from the UI of the Remote Debugger itself)
• Ensure Attach to: is set to Managed (v4.5, v4.0) code (this will require elevation)
• Once attached, find your dll in the Modules window and ensure the symbols are loaded

Finally, initiate a login (for example, by opening the IDP initiated signon html page) and sign in as a valid Active Directory user.

Additional / Troubleshooting Information

Get PublicKeyToken value for sn signed assembly (cmd line)

C:\> sn.exe –T MFAAdapter.dll

Add assembly to GAC on AD FS server (cmd line)

C:\>.\gacutil.exe /if .\MFAAdapter.dll

View assembly in the GAC (cmd line)

C:\> .\gacutil.exe /l mfaadapter

Remove assembly from GAC (cmd line)

If you need to remove and replace the assembly with an updated version, use ‘gacutil /u …’ to remove assemblies from the GAC, and’ gacutil /if …’ to add the new one.  (You may need to increment the version (in Visual Studio prior to build) in order for the dll to be truly replaced)

First, use the following command to find the fully qualified strong name of the entry:

C:\>.\gacutil.exe /l mfaadapter

Then, use the following command to remove it from the GAC:

gacutil /u “<output from the above command>”

Example:

C:\>.\gacutil /u “mfaadapter, Version=1.0.0.0, Culture=neutral, PublicKeyToken=2ed0b0f386e8e3a4”

Unregister provider (PowerShell)

PS C:\> Unregister-AdfsAuthenticationProvider –Name “MyMFAAdapter”

• Note that the value you pass for “Name” is the same value as “Name” you provided to the Register-AdfsAuthenticationProvider cmdlet.  It is also the “Name” property that is output from Get-AdfsAuthenticationProvider.
• Note that before unregistering a provider, must remove the provider from the AdfsGlobalAuthenticationPolicy (either by clearing the checkboxes you checked in AD FS admin MMC snapin or by using PSH)
• Note that the AD FS service must be restarted after this operation

Re-register provider with config data (PowerShell)

PS:\> Register-AdfsAuthenticationProvider –TypeName YourTypeName –Name “MyMFAAdapter2” –ConfigurationFilePath “C:\sources\configData.txt”

• Note that the AD FS service must be restarted after this operation

In Part 1, we created a basic adapter implementation and added it to an AD FS server.  We can get the MFA forms page, but we cannot yet authenticated because we have not yet put the correct logic in our TryEndAuthentication implementation.  So let’s add that.  Back to our code...

Recall our TryEndAuthentication implementation:

public IAdapterPresentation TryEndAuthentication(IAuthenticationContext authContext, IProofData proofData, HttpListenerRequest request, out Claim[] outgoingClaims)
 {
 //return new instance of IAdapterPresentationForm derived class
 outgoingClaims = new Claim[0];
 return new MyPresentationForm();
 
 }

Let’s update it so it doesn’t always return MyPresentationForm().  For this we’ll create one simple utility method within our class:

static bool ValidateProofData(IProofData proofData, IAuthenticationContext authContext)
 {
 if (proofData == null || proofData.Properties == null || !proofData.Properties.ContainsKey("ChallengeQuestionAnswer"))
 {
 throw new ExternalAuthenticationException("Error - no answer found", authContext);
 }
 
 if ((string)proofData.Properties["ChallengeQuestionAnswer"] == "adfabric")
 {
 return true;
 }
 else
 {
 return false;
 }
 }

Then, update TryEndAuthentication as below:

public IAdapterPresentation TryEndAuthentication(IAuthenticationContext authContext, IProofData proofData, HttpListenerRequest request, out Claim[] outgoingClaims)
 {
 outgoingClaims = new Claim[0];
 if (ValidateProofData(proofData, authContext))
 {
 //authn complete - return authn method
 outgoingClaims = new[] 
 {
 // Return the required authentication method claim, indicating the particulare authentication method used.
 new Claim( "https://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod", 
 "https://example.com/myauthenticationmethod1" )
 };
 return null;
 }
 else
 {
 //authn not complete - return new instance of IAdapterPresentationForm derived class
 return new MyPresentationForm();
 }
 }

Now you will have to update the adapter on the test box.  It is a little painful (i apologize for that) because you have to undo the AD FS policy, then un-register from AD FS and restart AD FS, then remove the dll from the GAC, then add the new dll to the GAC, then register it in AD FS, restart AD FS, and re-configure AD FS policy.  I will walk you through it...

Deploy and configure the updated adapter on your test AD FS machine

Clear AD FS Policy

Clear all MFA related checkboxes in the MFA UI, shown below, then click OK.

Unregister provider (PowerShell)

PS C:\> Unregister-AdfsAuthenticationProvider –Name “YourAuthProviderName”

Example:

PS C:\> Unregister-AdfsAuthenticationProvider –Name “MyMFAAdapter”

• Note that the value you pass for “Name” is the same value as “Name” you provided to the Register-AdfsAuthenticationProvider cmdlet.  It is also the “Name” property that is output from Get-AdfsAuthenticationProvider.
• Note that before unregistering a provider, must remove the provider from the AdfsGlobalAuthenticationPolicy (either by clearing the checkboxes you checked in AD FS admin MMC snapin or by using PSH)
• Note that the AD FS service must be restarted after this operation

Remove assembly from GAC (cmd line)

To remove assembly from GAC

First, use the following command to find the fully qualified strong name of the entry:

C:\>.\gacutil.exe /l <yourAdapterAssemblyName>

Example:

C:\>.\gacutil.exe /l mfaadapter

Then, use the following command to remove it from the GAC:

.\gacutil /u “<output from the above command>”

Example:

C:\>.\gacutil /u “mfaadapter, Version=1.0.0.0, Culture=neutral, PublicKeyToken=e675eb33c62805a0, processorArchitecture=MSIL”

Add the updated assembly to GAC (cmd line)

Make sure you paste the updated dll locally first :)

C:\>.\gacutil.exe /if .\MFAAdapter.dll

View assembly in the GAC (cmd line)

C:\> .\gacutil.exe /l mfaadapter

Register your provider in AD FS

PS C:\>$typeName = "MFAadapter.MyAdapter, MFAadapter, Version=1.0.0.1, Culture=neutral, PublicKeyToken=e675eb33c62805a0, processorArchitecture=MSIL”

PS C:\>Register-AdfsAuthenticationProvider -TypeName $typeName -Name “MyMFAAdapter1”

Restart the AD FS service

Create policy using the AD FS Management snapin

1)      Open the AD FS Management Snapin (from Server Manager Tools menu)

2)      Click Authentication Policies at left

3)      In the center pane, under Multi-Factor Authentication, click the blue Edit link to the right of Global Settings.

4)      Under Select additional authentication methods at the bottom of the page, check the box for your provider’s AdminName. Click Apply.

5)      To provide a “trigger” to invoke MFA using your adapter, under Locations check both “Extranet” and “Intranet”, for example. Click OK.

Authenticate with MFA using your adapter

Finally, perform the steps below to test your adapter:

• Ensure the  AD FS global Primary authentication type is configured as Forms Authentication for both Extranet and Intranet (this makes your demo easier to authenticate as a specific user)
  • In the AD FS snapin, under Authentication Policies, in the Primary Authentication area, click Edit next to Global Settings
    • Or just click the Primary tab from the Multi-factor policy UI
• Ensure Forms Authentication is the only option checked for both the Extranet and the Intranet authentication method.  Click OK.
• Open the IDP initiated signon html page (https://<fsname>/adfs/ls/idpinitiatedsignon.htm) and sign in as a valid AD user in your test environment
• Enter credentials for primary authentication
• You should see the MFA forms page with example challenge text appear. 
  • if you have more than one adapter configured, you will see the MFA choice page with your friendly name

You should see a successful signin when entering “adfabric” at the MFA authentication page.

Also check out these excellent blogs from my colleague at Microsoft.

Welcome to the Build your own external authentication provider walk-through for AD FS in Windows Server 2012 R2!

This article provides a step by step walk through to get you started building your provider.  The example we will build is for educational purposes only.  It's the most minimal, bare bones implementation possible to expose the required elements of the model.  There is no actual authentication back end, error processing, or configuration data.  But it is enough to get you started, so let's begin!

Setting up the development box

This walk-through uses Visual Studio 2012.  The project can be built using any development environment that can create a .NET class for Windows.

The project must target .NET 4.5 because the BeginAuthentication and TryEndAuthentication methods use the type System.Security.Claims.Claim, part of .NET Framework version 4.5.

There is one reference required for the project:

Create the provider

In Visual Studio 2012: Choose File->New->Project...

Select Class Library and be sure you are targeting .NET 4.5:

Make a copy Microsoft.IdentityServer.Web.dll from %windir%\ADFS on a Windows Server 2012 R2 machine on which AD FS has been installed and paste it in your Project folder on your development machine.

In Solution Explorer, right click References and Add Reference...

Browse to your local copy of Microsoft.IdentityServer.Web.dll and Add...

Click OK to confirm the new reference:

You should now be setup to resolve all of the types required for the provider. 

Add a new class to your project (Right click your project, Add...Class...) and give it a name like MyAdapter, shown below:

In the new file MyAdapter.cs, replace the existing code with the following:

 using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Text;
 using System.Threading.Tasks;
 using System.Globalization;
 using System.IO;
 using System.Net;
 using System.Xml.Serialization;
 using Microsoft.IdentityServer.Web.Authentication.External;
 using Claim = System.Security.Claims.Claim;
 
 namespace MFAadapter
 {
 class MyAdapter : IAuthenticationAdapter
 {
 
 }
 }

Now you should be able to F12 (right click – Go To Definition) on IAuthenticationAdapter to see the set of required interface members.  Now we will do a simple implementation of these.

Replace the entire contents of your class with the below.

namespace MFAadapter
 {
 class MyAdapter : IAuthenticationAdapter
 {
 public IAuthenticationAdapterMetadata Metadata
 {
 //get { return new <instance of IAuthenticationAdapterMetadata derived class>; }
 }
 
 public IAdapterPresentation BeginAuthentication(Claim identityClaim, HttpListenerRequest request, IAuthenticationContext authContext)
 {
 //return new instance of IAdapterPresentationForm derived class
 
 }
 
 public bool IsAvailableForUser(Claim identityClaim, IAuthenticationContext authContext)
 {
 return true; //its all available for now
 
 }
 
 public void OnAuthenticationPipelineLoad(IAuthenticationMethodConfigData configData)
 {
 //this is where AD FS passes us the config data, if such data was supplied at registration of the adapter
 
 }
 
 public void OnAuthenticationPipelineUnload()
 {
 
 }
 
 public IAdapterPresentation OnError(HttpListenerRequest request, ExternalAuthenticationException ex)
 {
 //return new instance of IAdapterPresentationForm derived class
 
 }
 
 public IAdapterPresentation TryEndAuthentication(IAuthenticationContext authContext, IProofData proofData, HttpListenerRequest request, out Claim[] outgoingClaims)
 {
 //return new instance of IAdapterPresentationForm derived class
 
 }
 
 }
 }

We’re not ready to build yet...just two more interfaces to go :)
Add two more classes to your project: one will be for the metadata, and the other for the presentation form.  You can add these within the same file as the class above.

 class MyMetadata : IAuthenticationAdapterMetadata
 {
 
 }
 
 class MyPresentationForm : IAdapterPresentationForm
 {
 
 }
 

Now we will add the required members for each.

First, the metadata (with some hopefully helpful inline comments)

class MyMetadata : IAuthenticationAdapterMetadata
 {
 //Returns the name of the provider that will be shown in the AD FS management UI (not visible to end users)
 public string AdminName
 {
 get { return "My Example MFA Adapter"; }
 }
 
 //Returns an array of strings containing URIs indicating the set of authentication methods implemented by the adapter 
 /// AD FS requires that, if authentication is successful, the method actually employed will be returned by the
 /// final call to TryEndAuthentication(). If no authentication method is returnd, or the method returned is not
 /// one of the methods listed in this property, the authentication attempt will fail.
 public virtual string[] AuthenticationMethods 
 {
 get { return new[] { "https://example.com/myauthenticationmethod1", "https://example.com/myauthenticationmethod2" }; }
 }
 
 /// Returns an array indicating which languages are supported by the provider. AD FS uses this information
 /// to determine the best language\locale to display to the user.
 public int[] AvailableLcids
 {
 get
 {
 return new[] { new CultureInfo("en-us").LCID, new CultureInfo("fr").LCID};
 }
 }
 
 /// Returns a Dictionary containg the set of localized friendy names of the provider, indexed by lcid. 
 /// These Friendly Names are displayed in the "choice page" offered to the user when there is more than 
 /// one secondary authentication provider available.
 public Dictionary<int, string> FriendlyNames
 {
 get
 {
 Dictionary<int, string> _friendlyNames = new Dictionary<int, string>();
 _friendlyNames.Add(new CultureInfo("en-us").LCID, "Friendly name of My Example MFA Adapter for end users (en)");
 _friendlyNames.Add(new CultureInfo("fr").LCID, "Friendly name translated to fr locale");
 return _friendlyNames;
 }
 }
 
 /// Returns a Dictionary containing the set of localized descriptions (hover over help) of the provider, indexed by lcid. 
 /// These descriptions are displayed in the "choice page" offered to the user when there is more than one 
 /// secondary authentication provider available.
 public Dictionary<int, string> Descriptions
 {
 get 
 {
 Dictionary<int, string> _descriptions = new Dictionary<int, string>();
 _descriptions.Add(new CultureInfo("en-us").LCID, "Description of My Example MFA Adapter for end users (en)");
 _descriptions.Add(new CultureInfo("fr").LCID, "Description translated to fr locale");
 return _descriptions; 
 }
 }
 
 /// Returns an array indicating the type of claim that that the adapter uses to identify the user being authenticated.
 /// Note that although the property is an array, only the first element is currently used.
 /// MUST BE ONE OF THE FOLLOWING
 /// "https://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"
 /// "https://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"
 /// "https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
 /// "https://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid"
 public string[] IdentityClaims
 {
 get { return new[] { "https://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn" }; }
 }
 
 //All external providers must return a value of "true" for this property.
 public bool RequiresIdentity
 {
 get { return true; }
 }
}

Next, the presentation form:

 class MyPresentationForm : IAdapterPresentationForm
 {
 /// Returns the HTML Form fragment that contains the adapter user interface. This data will be included in the web page that is presented
 /// to the cient.
 public string GetFormHtml(int lcid)
 {
 string htmlTemplate = Resources.FormPageHtml; //todo we will implement this
 return htmlTemplate;
 }
 
 /// Return any external resources, ie references to libraries etc., that should be included in 
 /// the HEAD section of the presentation form html. 
 public string GetFormPreRenderHtml(int lcid)
 {
 return null;
 }
 
 //returns the title string for the web page which presents the HTML form content to the end user
 public string GetPageTitle(int lcid)
 {
 return "MFA Adapter";
 }
 
 
 }
 

Note the ‘todo’ for the Resources.FormPageHtml element above.  We will get to that, but first let's add the final required return statements, based on our newly implemented types, to our initial MyAdapter class.  To do this, add the yellow highlighted items below to your existing IAuthenticationAdapter implementation:

class MyAdapter : IAuthenticationAdapter
 {
 public IAuthenticationAdapterMetadata Metadata
 {
 //get { return new <instance of IAuthenticationAdapterMetadata derived class>; }
 get { return new MyMetadata(); }
 }
 
 public IAdapterPresentation BeginAuthentication(Claim identityClaim, HttpListenerRequest request, IAuthenticationContext authContext)
 {
 //return new instance of IAdapterPresentationForm derived class
 return new MyPresentationForm();
 }
 
 public bool IsAvailableForUser(Claim identityClaim, IAuthenticationContext authContext)
 {
 return true; //its all available for now
 }
 
 public void OnAuthenticationPipelineLoad(IAuthenticationMethodConfigData configData)
 {
 //this is where AD FS passes us the config data, if such data was supplied at registration of the adapter
 
 }
 
 public void OnAuthenticationPipelineUnload()
 {
 
 }
 
 public IAdapterPresentation OnError(HttpListenerRequest request, ExternalAuthenticationException ex)
 {
 //return new instance of IAdapterPresentationForm derived class
 return new MyPresentationForm();
 }
 
 public IAdapterPresentation TryEndAuthentication(IAuthenticationContext authContext, IProofData proofData, HttpListenerRequest request, out Claim[] outgoingClaims)
 {
 //return new instance of IAdapterPresentationForm derived class
 outgoingClaims = new Claim[0];
 return new MyPresentationForm();
 }
 
 }

Now for the resource file containing the html fragment. 

Create a new text file in your project folder with the following contents:

<div id="loginArea">
 <form method="post" id="loginForm" >
 <!-- These inputs are required by the presentation framework. Do not modify or remove -->
 <input id="authMethod" type="hidden" name="AuthMethod" value="%AuthMethod%"/>
 <input id="context" type="hidden" name="Context" value="%Context%"/>
 <!-- End inputs are required by the presentation framework. -->
 <p id="pageIntroductionText">This content is provided by the MFA sample adapter. Challenge inputs should be presented below.</p>
 <label for="challengeQuestionInput" class="block">Question text</label>
 <input id="challengeQuestionInput" name="ChallengeQuestionAnswer" type="text" value="" class="text" placeholder="Answer placeholder" />
 <div id="submissionArea" class="submitMargin">
 <input id="submitButton" type="submit" name="Submit" value="Submit" onclick="return AuthPage.submitAnswer()"/>
 </div>
 </form>
 <div id="intro" class="groupMargin">
 <p id="supportEmail">Support information</p>
 </div>
 <script type="text/javascript" language="JavaScript">
 //<![CDATA[
 function AuthPage() { }
 AuthPage.submitAnswer = function () { return true; };
 //]]>
 </script></div>

Then, select Project->Add Component... Resources file and name the file Resources and click Add:

Then, within the Resources.resx file, choose Add Resource...Add existing file.  Navigate to the text file (containing the html fragment) that you saved above.   

Ensure your GetFormHtml code resolves the name of the new resource correctly by the resources file (.resx file) name prefix followed by the name of the resource itself:

public string GetFormHtml(int lcid)
{
 string htmlTemplate = Resources.MfaFormHtml; //Resxfilename.resourcename
 return htmlTemplate;
}
 

You should now be able to build. 

Build the adapter

The adapter should be built into a strongly named .NET assembly that can be installed into the GAC in Windows.  To achieve this in a Visual Studio project:

1. Right click your project name in Solution Explorer and click Properties
2. On the Signing tab, check Sign the assembly and choose <New...> under Choose a strong name key file:  Enter a key file name and password and click OK.  Then ensure Sign the assembly is checked and Delay sign only is unchecked.  The properties Signing page should look like the below:

Then build the solution.

Deploy the adapter to your AD FS test machine

Before an external provider will be invoked by AD FS, it must be registered in the system.  Adapter providers MUST provide an installer which performs the necessary installation actions including installation in the GAC, and the installer SHOULD support registration in AD FS.  If that is not done, the administrator will need to execute the PowerShell steps below.  These steps can be used in the lab to enable testing and debugging.

Prepare the test AD FS machine

You’ll need to perform the following steps to get your test box ready

Copy files and add to GAC

1)      Ensure you have a Windows Server 2012 R2 machine or virtual machine

2)      Install the AD FS role service and configure a farm with at least one node.

For detailed steps to setup a federation server in a lab environment, see the guidance on Technet.

3)      Copy the Gacutil.exe tools to the server

Gacutil.exe can be found in %homedrive%\Program Files (x86)\Microsoft SDKs\Windows\v8.0A\bin\NETFX 4.0 Tools\ on a Windows 8 machine.  You will need the gacutil.exe file itself as well as the 1033 and en-US other localized resource folder below the NETFX 4.0 Tools location

4)      Copy your provider file(s) (one or more strong name signed dll files) to the same folder location as gacutil (the location is just for convenience)

5)      Add your dll file(s) to the GAC on each AD FS federation server in the farm:

Example: using command line tool GACutil.exe to add a dll to the GAC: 

C:\>.\gacutil.exe /if .\<yourdllname>.dll

To view the resulting entry in the GAC:

C:\>.\gacutil.exe /l <yourassemblyname>

Register your provider in AD FS

Once the above pre-requisites are met, open a PowerShell command window on your federation server and enter the following commands (note that if you are using federation server farm that uses Windows Internal Database, you must execute these commands on the primary federation server of the farm):

1)      Register-AdfsAuthenticationProvider –TypeName YourTypeName –Name “AnyNameYouWish” [–ConfigurationFilePath (optional)]

Where YourTypeName is your .NET strong type name: "YourDefaultNamespace.YourIAuthenticationAdapterImplementationClassName, YourAssemblyName, Version=YourAssemblyVersion, Culture=neutral, PublicKeyToken=YourPublicKeyTokenValue, processorArchitecture=MSIL"

This will register your external provider in AD FS, with the Name you provided as AnyNameYouWish above

2)      Restart the AD FS service (using the Windows Services snapin for example)

3)      Get-AdfsAuthenticationProvider

This shows your provider as one of the providers in the system

Example powershell command line:

PS C:\>$typeName = "MFAadapter.MyAdapter, MFAadapter, Version=1.0.0.0, Culture=neutral, PublicKeyToken=e675eb33c62805a0, processorArchitecture=MSIL”

PS C:\>Register-AdfsAuthenticationProvider -TypeName $typeName -Name “MyMFAAdapter”

PS C:\>net stop adfssrv

PS C:\>net start adfssrv

If you have the device registration service enabled in your AD FS environment, also execute the following: 

PS C:\>net start drs

To verify the registered provider, use the command below:

PS C:\>Get-AdfsAuthenticationProvider

This shows your provider as one of the providers in the system

Create AD FS policy that invokes your adapter

Create policy using the AD FS Management snapin

1)      Open the AD FS Management Snapin (from Server Manager Tools menu)

2)      Click Authentication Policies at left

3)      In the center pane, under Multi-Factor Authentication, click the blue Edit link to the right of Global Settings.

4)      Under Select additional authentication methods at the bottom of the page, check the box for your provider’s AdminName. Click Apply.

5)      To provide a “trigger” to invoke MFA using your adapter, under Locations check both “Extranet” and “Intranet”, for example. Click OK. (To configure triggers per relying party, see Create policy using PowerShell below.)

6)      Check the results using PSH

First use Get-AdfsGlobalAuthenticationPolicy. You should see your provider Name as one of the AdditionalAuthenticationProvider values

Then use Get-AdfsAdditionalAuthenticationRule. You should see the rules for Extranet and Intranet configured as a result of your policy selection in the admin UI

Create policy using PowerShell

To configure MFA policy using PowerShell, use the following steps:

First, enable the provider in global policy:

PS C:\>Set-AdfsGlobalAuthenticationPolicy -AdditionalAuthenticationProvider “YourAuthProviderName”

Note that the value provided for the AdditionalAuthenticationProvider parameter corresponds to the value you provided for the “Name” parameter in the Register-AdfsAuthenticationProvider cmdlet above and to the “Name” property from Get-AdfsAuthenticationProvider cmdlet output. 

Example powershell command to enable provider:

PS C:\>Set-AdfsGlobalAuthenticationPolicy –AdditionalAuthenticationProvider “MyMFAAdapter”

Next, configure global or relying party specific rules to trigger MFA:

Example 1: Powershell command to create global rule to require MFA for External requests:

PS C:\>Set-AdfsAdditionalAuthenticationRule –AdditionalAuthenticationRules '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" );'

Example 2: Powershell command to create MFA rules to require MFA for external requests to a specific relying party.  (Note that individual providers cannot be connected to individual relying parties in AD FS in Windows Server 2012 R2).

PS C:\>$rp = Get-AdfsRelyingPartyTrust –Name <Relying Party Name>

PS C:\>Set-AdfsRelyingPartyTrust –TargetRelyingParty $rp –AdditionalAuthenticationRules '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" );'

Authenticate with MFA using your adapter

Finally, perform the steps below to test your adapter:

• Ensure the  AD FS global Primary authentication type is configured as Forms Authentication for both Extranet and Intranet (this makes your demo easier to authenticate as a specific user)
  • In the AD FS snapin, under Authentication Policies, in the Primary Authentication area, click Edit next to Global Settings
    • Or just click the Primary tab from the Multi-factor policy UI
• Ensure Forms Authentication is the only option checked for both the Extranet and the Intranet authentication method.  Click OK.
• Open the IDP initiated signon html page (https://<fsname>/adfs/ls/idpinitiatedsignon.htm) and sign in as a valid AD user in your test environment
• Enter credentials for primary authentication
• You should see the MFA forms page with example challenge questions appear. 
  • if you have more than one adapter configured, you will see the MFA choice page with your friendly name from above

You now have a working implementation of the interface (though granted it does not do much yet!), but you can at least see how the model works. For example, try setting break points in the BeginAuthentication as well as the TryEndAuthentication.  Notice how BeginAuthentication is executed when the user first enters the MFA form, whereas TryEndAuthentication is triggered at each Submit of the form.

But wait – our example adapter will never successfully authenticate!  This is because nothing in our code returns null for TryEndAuthentication.  So let’s add that in part 2...

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.