Developing Modern Applications using OAuth and Active Directory Federation Services
Updated: April 9, 2014
Applies To: Windows Server 2012 R2
Developing Modern Applications using OAuth and Active Directory Federation Services
With the release of Windows Server 2012 R2, Active Directory Federation Services introduces support for the OAuth open standard for authorization. This will enable enterprise and ISV application developers to leverage their familiarity with OAuth in order to write applications that rely on AD FS as an authorization backend. This document will show you how to create several applications that can take advantage of using the new OAuth support.
Overview
The following walkthrough will demonstrate many aspects of developing applications with ADFS. It includes:
How to develop a WPF rich-client application that is authorized to call a web API secured by AD FS on behalf of an Active Directory user.
How to develop a Windows Store application that is authorized to call a web API secured by AD FS on behalf of an Active Directory user.
Authorization for the WPF and Windows Store Application is handled by using the OAuth 2.0 authorization code grant type, and AD FS issues refresh tokens that make it possible to minimize the frequency that a user needs to re-enter their credentials.
Important
The following documentation provides examples for developing a WPF application and a Windows Store application to authenticate with an instance of AD FS. If you are looking to develop an IOS or Application see the following:
For an example of developing a Windows Store application and a REST Web Service using Azure AD see Securing a Windows Store Application and REST Web Service Using Windows Azure AD (Preview) For additional information on OAuth 2.0 in Azure AD see: OAuth 2.0 in Azure AD.Technologies Used in this Walkthrough
The following is a list with a brief description of the technologies that this walkthrough uses and demonstrates:
Active Directory Federation Services - AD FS provides simplified, secured identity federation and Web single sign-on (SSO) capabilities for end users who want to access applications within an AD FS-secured enterprise, in federation partner organizations, or in the cloud. In Windows Server® 2012 R2, AD FS includes a federation service that acts as an identity provider (authenticates users to provide security tokens to applications that trust AD FS) or as a federation provider (consumes tokens from other identity providers and then provides security tokens to applications that trust AD FS). For more information see Active Directory Federation Services Overview.
OAuth 2.0 - OAuth is an open standard for authorization. The OAuth 2.0 authorization framework enables a third-party application to obtain limited access to an HTTP service, either on behalf of a resource owner by orchestrating an approval interaction between the resource owner and the HTTP service, or by allowing the third-party application to obtain access on its own behalf. Each token grants access to a specific site (e.g., a video editing site) for specific resources (e.g., just videos from a specific album) and for a defined duration (e.g., the next 2 hours). This allows a user to grant a third party site access to their information stored with another service provider, without sharing their access permissions or the full extent of their data. For more information see The OAuth 2.0 Authorization Framework.
Windows Azure Active Directory Authentication Library (ADAL) - ADAL is a library, built on .Net 4.0, offering a simple programming model for Windows Azure Active Directory (WAAD) and Active Directory Federation Services (AD FS) for Windows Server 2012 R2 in client applications. Its main purpose is to help developers easily obtain access tokens from Windows Azure Active Directory (WAAD) and Windows Server Active Directory Federation Services for Windows Server 2012 R2, which can then be used for requesting access to protected resources such as REST services. For more information see Windows Azure AD Authentication Library for .NET.
Windows Azure Authentication Library for Windows Store Apps Preview - The Windows Azure Authentication Library for Windows Store Preview enables Windows Store application developers to easily authenticate users to Windows Azure AD and obtain access tokens for securing API calls. For more information see Windows Azure Authentication Library for Windows Store.
Scenario Description
Contoso is a medium-size furniture manufacturer. The developers for Contoso have been exploring building a new MVC5 ToDoList Web API and client applications that can use this API. However they want to be able to restrict access to the users of their on-premises Active Directory instance and use Active Directory as their Identity Provider. The developers already have a good understanding of OAuth and would like to leverage this for authentication.
To demonstrate the use of a native client with AD FS, we will build a WPF and Windows Store application using Windows Azure Authentication Library that allows a user to authorize access to a REST service with their AD account.
As part of the walkthrough we will also build a simple service that the client can call. The service provides a central location for a user to save their ToDo List, this service can be hosted on-premises or in the cloud.
The following diagram shows the canonical flow of how this solution will work.
.png "Canonical flow")
Our client requests a JWT token from our AD FS instance. AD FS requests that the user sign-in with their Active Directory username and password.
After verifying the user, AD FS issues the token and returns the token to the client.
The client then creates an Authorization header from the token and adds this to the header of an HTTP request and sends it to the ToDoListService Web API.
The token presented by the client to the ToDoListService Web API is a bearer token. The ToDoListService Web API validates the signature of the token to ensure it was issued by AD FS, checks to see if the token is still valid and hasn’t expired and may possibly also validate other claims (such as the ‘upn’ claim) in the token. At this point, the client is either authorized and the information they requested is sent in the response or they are unauthorized and no data will be sent.
Pre-requisites for this Solution
The following is a list of pre-requisites that are required for implementing this solution.
Windows Server 2012 R2 – One test machine, DC1 runs the Windows Server 2012 R2 operating system. For a free trial see Download the Evaluation: Windows Server 2012 R2.
Windows 8.1 Enterprise – Our CLIENT1 test machine, which is used to develop the Web API and our client applications uses the Windows 8.1 Enterprise operating system. For a free trial, see Download Windows 8.1 Enterprise Evaluation.
Visual Studio 2013 – This is the development environment for creation of the applications and API. For more information, trials, and free versions see Visual Studio.
Visual Studio 2013 Update 2 RC – This is the first update to include the authentication template for on-premises use with AD FS. Visual Studio 2013 Update 2 RC
Windows Azure SDK 2.2 – This is an update to the Windows Azure SDK. Windows Azure SDK 2.2
Internet access for test machines – The test machines, particularly the CLIENT1 development machine, will require access to the internet to obtain NuGet packages, a Windows Store Developer license, Visual Studio Update 2 RC, and Windows Azure SDK 2.2..
A Microsoft account – A Microsoft account will be required for obtaining a developer license for creating a Windows Store Application. For more information see Sign-up for a Microsoft account.
Outline of Sections
The remainder of this document is organized into the following sections: