• 6 min read

Introducing a New Capability in the Windows Azure AD Developer Preview: the Windows Azure Authentication Library

Last month we announced the Developer Preview of Windows Azure Active Directory (Windows Azure AD) which kicked off the process of opening up Windows Azure Active Directory to developers outside of…

Last month we announced the Developer Preview of Windows Azure Active Directory (Windows Azure AD) which kicked off the process of opening up Windows Azure Active Directory to developers outside of Microsoft. You can read more about that initial release here.

Today we are excited to introduce the Windows Azure Authentication Library (referred to as AAL in our documentation), a new capability in the Developer Preview which gives .NET developers a fast and easy way to take advantage of Windows Azure AD in additional, high value scenarios, including the ability to secure access to your application’s APIs and the ability to expose your service APIs for use in other native client or service based applications.

The AAL Developer Preview offers an early look into our thinking in the native client and API protection space.  It consists of a set of NuGet packages containing the library bits, a set of samples which will work right out of the box against pre-provisioned tenants, and essential documentation to get started.

Before we start, I want to note that developers can of course write directly to the standards based protocols we support in Windows Azure AD (WS-Fed and OAuth today and more to come). That is a fully supported approach.  The library is another option we are making available for developers who are looking for a faster & simpler way to get started using the service.

In the rest of the post we will describe in more detail what’s in the preview, how you can get involved and what the future might look like.

What’s in the Developer Preview of the Windows Azure Authentication Library

The library takes the form of a .NET assembly, distributed via NuGet package. As such, you can add it to your project directly from Visual Studio (you can find more information about NuGet here).

AAL contains features for both .NET client applications and services. On the client, the library enables you to:

  • Prompt the user to authenticate against Windows Azure AD directory tenants, AD FS 2.0 servers and all the identity providers supported by Azure AD Access Control (Windows Live ID, Facebook, Google, Yahoo!, any OpenID provider, any WS-Federation provider)
  • Take advantage of username/password or the Kerberos ticket of the current workstation user for obtaining tokens programmatically
  • Leverage service principal credentials for obtaining tokens for server to server service calls

The first two features can be used for securing solutions such as WPF applications or even console apps. The third feature can be used for classic server to server integration.

The Windows Azure Authentication Library gives you access to the feature sets from both Windows Azure AD Access Control namespaces and Directory tenants. All of those features are offered through a simple programming model. Your Windows Azure AD tenant already knows about many aspects of your scenario: the service you want to call, the identity providers that the service trusts, the keys that Windows Azure AD will use for signing tokens, and so on. AAL leverages that knowledge, saving you from having to deal with low level configurations and protocol details. For more details on how the library operates, please refer to Vittorio Bertocci’s post here.

To give you an idea of the amount of code that the Windows Azure Authentication Library can save you, we’ve updated the Graph API sample from the Windows Azure AD Developer Preview to use the library to obtain the token needed to invoke the Graph. The original release of the sample contained custom code for that task, which accounted for about 700 lines of code. Thanks to the Windows Azure Authentication Library, those 700 lines are now replaced by 7 lines of calls into the library.

On the service side, the library offers you the ability to validate incoming tokens and return the identity of the caller in form of ClaimsPrincipal, consistent with the behavior of the rest of our development platform.

Together with the library, we are releasing a set of samples which demonstrate the main scenarios you can implement with the Windows Azure Authentication Library. The samples are all available as individual downloads on the MSDN Code via the following links:

To make it easy to try these samples, all are configured to work against pre-provisioned tenants. They are complemented by comprehensive readme documents, which detail how you can reconfigure Visual Studio solutions to take advantage of your own Directory tenants and Windows Azure AD Access Control namespaces.

If you visit the Windows Azure Active Directory node on the MSDN documentation, you will find that it has been augmented with essential documentation on AAL.

What You Can Expect Going Forward

As we noted earlier, the Developer Preview of AAL offers an early look into our thinking in the native client and API protection space. To ensure you have the opportunity to explore and experiment with native apps and API scenarios at an early stage of development, we are making the Developer Preview available to you now. You can provide feedback and share your thoughts with us by using the Windows Azure AD MSDN Forums. Of course, because it is a preview some things will change moving forward. Here are some of the changes we have planned:

More Platforms

The Developer Preview targets .NET applications, however we know that there are many more platforms that could benefit from these libraries.

For client applications, we are working to develop platform-specific versions of AAL for WinRT, iOS, and Android. We may add others as well. For service side capabilities, we are looking to add support for more languages.  If you have feedback on which platforms you would like to see first, this is the right time to let us know!

Convergence of Access Control Namespace and Directory Tenant Capabilities

As detailed in the first Developer Preview announcement, as of today there are some differences between Access Control namespaces and Directory tenants. The programming model is consistent across tenant types: you don’t need to change your code to account for it. However, you do get different capabilities depending on the type of tenant. Moving forward, you will see those differences progressively disappear.

Library Refactoring

The assembly released for the Developer Preview is built around a native core. The reason for its current architecture is that it shares some code with other libraries we are using for adding claims based identity capabilities to some of our products. The presence of the native core creates some constraints on your use of the Developer Preview of the library in your .NET applications. For example, the “bitness” of your target architecture (x86 or x64) is a relevant factor when deciding which version of the library should be used. Please refer to the release notes in the samples for a detailed list of the known limitations.  Future releases of the Windows Azure Authentication Library for .NET will no longer contain the native core.

Furthermore, in the Developer Preview, AAL contains both client and service side features. Moving forward, the library will contain only client capabilities. Service side capabilities such as token validation, handling of OAuth2 authorization flows and similar features will be delivered as individual extensions to Windows Identity Foundation, continuing the work we begun with the WIF extensions for OAuth2.

Windows Azure Authentication Library and Open Source

The simplicity of the Windows Azure Authentication Library programming model in the Developer Preview also means that advanced users might not be able to tweak things to the degree they want. To address that, we are planning to release future drops of AAL under an open source license. So developers will be able to fork the code, change things to fit your needs and, if you so choose, contribute your improvements back to the mainline code.

The Developer Preview of AAL is another step toward equipping you with the tools you need to fully take advantage of Windows Azure AD. Of course we are only getting started, and have a lot of work left to do. We hope that you’ll download the library samples and NuGets, give them a spin and let us know what you think!

Finally, thanks to everyone who has provided feedback so far! We really appreciate the time you’ve taken and the depth of feedback you’ve provided. It’s crucial for us to assure we are evolving Windows Azure AD in the right direction!

–  By Alex Simons, Director of Program Management, Active Directory Division