Background
A colleague and I are validating a number of scenarios for a customer who is looking to deploy Azure MFA Server. One of the requirements from an Identity Management perspective is the ability to interact with the MFA Server for user information. That led us on the exploration of what was possible and how best to approach it.
The title of this post has pretty much given it away as to how. But why ? As Azure MFA Server is a product that Microsoft have acquired through the acquisition of Phone Factor, the usual methods of interacting with applications and services in the Microsoft Stack don’t apply. There is practically no information on how to use Powershell to interact with Azure MFA Server. So this blog post details what we’ve learned and how we have been able to get information out of Azure MFA Server using Powershell.
This post covers;
- Connecting to the Azure MFA Web Service SDK
- Searching for users in the MFA Database
- Returning information about users in the MFA Database
- Making a test call to a users phone via the MFA Server
Prerequisites
There are a number of prerequisites that I’m not covering here as you can quickly locate many guides to installing/configuring Azure MFA Server.
- You’ll need to have an Azure MFA environment (obviously)
- Download the Azure MFA Web Service SDK
- to get the SDK follow the process detailed here
- Install and Configure the Azure MFA Web Service SDK
- If you aren’t using a Public SSL Cert on the Azure MFA Web Service SDK Server you will need to export the certificate from the Azure MFA Web Service SDK Server and import it to the Trusted Root Certificate Store on the workstation you’ll be using Powershell on to connect to the MFA environment.
Connecting to the Azure MFA Web Service SDK
Now that you’ve met the prerequisites listed above you can use Powershell to connect to the API. The URL is the DNS name of the Azure MFA Web Service SDK Server following by the SDK SOAP endpoint. eg. https://mfa.yourdomain.com.au/MultiFactorAuthWebServiceSdk/PfWsSdk.asmx?WSDL
Try out the URL in your browser and using an account that exists in the MFA Server authenticate to the Azure MFA Web Service SDK Server. If it is setup correctly (including your SSL certificate) you will see the following.
https://dl.dropboxusercontent.com/u/76015/BlogImages/AzureMFASDK/SDK%20Connect.png
The simple script below will perform the same thing, but via Powershell. Update for your domain, username, password and URL for your MFA Web Service SDK Server.
Searching for users in the MFA Database
Now that we’ve setup a web services proxy connection to the MFA Web Service SOAP API endpoint we can start getting some info out of it. Searching for users uses the ‘FindUsers_4’ call. It has many parameters that can be set to alter the results. I’ve gone simple in this one and used ‘*’ as the criteria to return all users in the MFA Database. Alter for your purposes.
Returning information about users in the MFA Database
Using a slightly different criteria to the Search criteria above I returned one entry and set the $mfauser variable to them. I then use that in the GetPhone, GetUserSettings & GetUserDevices calls as shown belown to retrieve all the info about them.
Making a test call to a users phone via the MFA Server
Finally rather than just consuming information from the MFA environment let’s actually trigger something. Selecting an identity from our test environment that had the mobile phone number of a colleague associated with it, I triggered MFA Server to call them to authorize their session (which they hadn’t obviously requested). I may have done this a few times from the other side of the room watching with amusement as their phone rang requesting authentication approval 🙂
Full script snippets below.
Hope that helps someone else.
Follow Darren on Twitter @darrenjrobinson
Nice. finally I can export the users to a CSV file
Hope the PS module will be ready soon anyway
You can export them from the File menu\export users
Great work! Thanks for sharing!
By the way, I can export/manipulate data with your steps above, but I cannot invoke a 2ndary verification. Keep getting the following error: MFA Call Result Description: Direct SDK Not Allowed when Calling Method. I am using the 7.3 version. Any idea what I may be doing wrong?
Darren, thank you again for sharing. In case someone else has the same error, here is what I did.
Not sure if this is an issue with the newer versions, but using an AuthenticationType of pfsdk does NOT work and triggers the “Direct SDK Not Allowed when Calling Method” error. I just removed the explicit assignment of $initiatingAuthenticationType =”pfsdk” in your code and then called the pfauth_4 function like:
$result = $wsp.PfAuthUser_4([string]$mfauser, $AuthenticationType,…..
This creates a value of #authType=unspecified, but the 2nd factor is completed :).
Cheers!
Thx Ivan. Microsoft have definitely made some changes. Thx for providing an updated method to test integration.
Hi Darren & Kloud team, another extremely helpful post. Setting the benchmark as usual.
99.9% there for me on SDK ver 6.3.1. Small adjusts:
1. set an int value for $tagMatchType to return results via FindUsers_4 call: $tagMatchType = value__ = 3 worked for ‘allUsers’. Values 0,1,2,3,
2. Strip .value from $userDevices for list devices in above.
Many thanks again.
SDK support being depreciated by MS I also see. What gives? How else are we supposed to tap into this proprietary PF database with on prem server deployment, even if we don’t want to trigger mfa call via cloud service post Nov 2018?
Regards, Leigh.
Great article…Would you know if there is a way to find out ‘last used date’ for a token. We are trying to determine how many users have been using their company issued hardware tokens.
Hi Darren,
Do you have any idea why does it give me this error when I try the Enable operator?
Cannot find an overload for “Enable” and the argument count: “3”.
I try with the following command:
$result = $proxy.Enable([string]$username,[bool]$sendEmail, [ref]$errorcode)
regards,
Gabe
Hm. Looks like the modifyusername parameter is not optional. When I add it, it works.