Connecting to and Using the Azure MFA Web Service SDK Server SOAP API with Powershell

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)
  • here is a great guide
• 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
  • here is a great guide
• 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 MFA Web Service SDK Server API Operations.

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.

See the gist on github.

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.

See the gist on github.

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 below to retrieve all the info about them.

See the gist on github.

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 🙂

See the gist on github.

Full script snippets below.

See the gist on github.

Hope that helps someone else.

Follow Darren on Twitter @darrenjrobinson