SALES: 1-800-867-1380

Adding Sign-On to Your Web Application Using Azure AD

Updated: May 12, 2014

This sample is outdated. Its technology, methods, and/or user interface instructions have been replaced by newer features. To see an updated sample that builds a similar application, see WebApp-OpenIDConnect-DotNet.


This walkthrough will show you how to use Azure AD for implementing web single sign-on in an ASP.NET application. The instructions will focus on taking advantage of the directory tenant associated with your Azure subscription, as that constitutes the obvious choice of identity providers for Line of Business (LoB) applications in your own organization.

A web single sign-on solution typically entails configuring a web application to outsource its authentication functions to one external entity, commonly referred to as Identity Provider (IdP). In concrete terms, this means that the application will be configured to redirect unauthenticated requests to the IdP, according to some sign-on protocol such as SAML-P, WS-Federation or OpenID Connect.

The authority (or IdP) handles the authentication experience, and it usually requires the web application to be already known via some provisioning process. Upon successful authentication, the browser gets redirected back to the web app along with a security token carrying information about the incoming user; the application validates the token, typically via some identity-aware middleware, and if the check succeeds the user is considered authenticated and is signed in.

That high-level description applies to Azure AD as well. This document will show you how to use Visual Studio 2012 and the Windows Identity Foundation (WIF) classes in the .NET Framework 4.5 to configure an MVC 4 application to use a web sign-on protocol. It will show you how to provision the same application in an Azure AD tenant, and how to configure the application’s sign-on settings to connect to that tenant. At the end of the walkthrough, you will have a functioning web application fully configured for organizational single sign-on.

The goal of this walkthrough is to help you understand how Azure AD operates: that requires going beyond the direction for putting together the simplified solution here described. Besides providing you with the concrete instructions to build a working sample, the document will also introduce artifacts and concepts that will be useful for you to get to know Azure AD and understand how to take advantage of its features beyond the specific scenario discussed here. Those extra sections, formatted as box notes, aren’t strictly necessary for executing the walkthrough; however, if you are interested in using Azure AD in your own solutions, it is recommended that you read those parts as well.

This tutorial portion of this document is organized in the following sections:

  • Prerequisites: This section lists all the requirements that must be met for you to complete the walkthrough.

  • Solution Architecture: This section provides a high level introduction of how a Web SSO solution for LoB (Line of Business) applications look like. We’ll examine the functional components that make SSO happen, setting up the wireframe that you’ll later flesh out by following the document’s instructions.

  • Working with Your Azure AD Directory Tenant: This section introduces Azure AD tenants and the features that will come into play in the scenario. It will also briefly describe the main elements of the Active Directory section of the Azure Management Portal.

  • Connecting the Application to Azure AD: This section shows you how to use the Identity and Access Tools for Visual Studio 2012 for enabling web single sign-on in the MVC application, and tie the authentication settings to the specific Azure AD tenant of choice.

  • Advanced Topics: This section goes beyond the basics, digging deeper in some key topics and covering some of the other tasks you might need to perform to move your application to the next level.

This following prerequisites are required to complete this tutorial:

If you have questions or need help, see Preparing for Azure AD Solutions and Scenarios

Single Tenant Application Architecture

This walkthrough focuses on the following scenario: a developer has a web application that he plans to deploy in the cloud, and he only wants users from an Azure Active Directory tenant to be allowed access. To accomplish this, he will need to:

  1. Register the web app in your Azure AD tenant. Once the app is known, Azure AD will accept users’ requests to authenticate against it.

  2. Add something in front of your app, so that:

    1. Unauthenticated requests can be blocked and redirected toward the correct Azure AD tenant for user authentication

    2. Users who authenticated with Azure AD can be recognized and granted access

We will implement the first step by working with the Azure Management Portal. You will learn how to provision a new Azure AD tenant within your Azure subscription, and how to operate the Azure AD Management Portal features to register an application.

Step #2 can be implemented using a variety of high level protocols meant to allow authentication operations across organizational boundaries, or even the Internet.

In the .NET platform, the second step boils down to configuring the classes that .NET offers out of the box for working with claims-based identity and federated authentication. Those classes are collectively known as Windows Identity Foundation (WIF), and they include HTTP modules and config settings which can be used to add the interception layer performing the redirection and authentication tasks introduced in #2. Visual Studio 2012 offers tools to help you to automatically configure web apps to use WIF to outsource authentication to external authorities which support specific web SSO protocols such as WS-Federation; this walkthrough will show you how to use such tools with Azure AD.

Azure Active Directory is the service that provides the identity backbone of Microsoft offerings such as Office 365 and Windows Intune. If you subscribe to these services and you want to reuse the directory tenant associated with that service, create a new Azure subscription and use the Add User feature to add an administrator from that tenant. This walkthrough will not provide detailed guidance about that process.

Every subscription has an Azure AD tenant and an associated directory. If the tenant was generated automatically, the directory will be named Default directory, but you can change the name. In this part of the walkthrough, we will add a user to the directory and then add an application.

When a directory tenant is created, it is configured to store users and credentials in the cloud. For detailed instructions about how to integrate your directory tenant with your on-premises deployment of Windows Server Active Directory, see Directory Integration.

If you have questions or need help, see Preparing for Azure AD Solutions and Scenarios

The Azure AD scenarios and solutions (and our code samples and sample applications) require a user account in the domain of your Azure Active Directory. If you try to sign in to the applications with a Microsoft account, such as a,, or account, the sign in fails. If you already have a user with an account in your Active Directory domain, such as a account, you can use it to sign in to this scenario. Otherwise, you need to create a new user.

  1. Go to the Microsoft Azure Management Portal (, sign in, and then click Active Directory. (Troubleshooting tip: "Active Directory" item is missing or not available)

  2. If your directory is named "Default Directory", add a directory, such as "ContosoEngineering". To add a directory, at the bottom of the Active Directory page, click Add and follow the instructions to add a new directory.

  3. Double-click the directory and then click Domains. When you create your user accounts, use the domain name that appears on the page. For example, if your domain is, create user names in that domain, such as

  4. To create a user account in the domain, click Users. (If you don't see a Users tab, double-click the directory name. A Users tab appears on each directory-specific page.) At the bottom of the page, click Add User.

  5. Select New user in your organization. Add a user in your new domain, such as, and then click the checkmark at the bottom of the page.

    Enter the user name and domain
  6. On the User Profile page, assign an organizational role to the user. For testing, it's best to have at least one user with the Global Administrator role and one user with the User role.

    Enter the user role

In the last step, the Azure Management Portal generates a temporary password that the user uses to sign in for the first time. When the first sign-in is complete, the user must change the temporary password. Be sure to save the temporary password, because we’ll need it to test the scenario.

At this point we have a directory tenant with a valid user to provide an authentication authority in our web single sign-on scenario.

Temporary Password

  1. Let’s begin our work on the application bits. Open Visual Studio, click New Project and pick ASP.NET MVC 4 Web Application. In the New ASP.NET MVC 4 Project window, select Intranet Application, make sure the view engine is set to Razor, then click OK. In this walkthrough we’ll use ExpenseReport as the project name.

    This walkthrough assumes that your Visual Studio installation is configured with its default settings. If you changed some of the basic configurations (such as where web applications are hosted at development time) you’ll have to adjust the instructions accordingly.

    New Project in Visual Studio

    You can apply the instructions in this walkthrough to any existing VS 2012 web application, MVC or Web Forms, provided that you don’t have any logic which significantly alters the ASP.NET request processing pipeline. For simplicity, however, here we are building a new project from scratch.

    This walkthrough provides detailed instructions on how to set up a .NET solution, however the same results can be achieved when targeting other platforms and programming stacks. Azure AD uses open protocols in its web sign-on features, and every major platform features libraries and tools supporting such protocols. The detailed steps will have to be adjusted to accommodate the syntax and practices of every stack, however the high level task subdivision will apply across the board.

    Visual Studio creates a new MVC project for you, already configured to run on IIS Express: we will not add further functionality to it, as the defaults are enough for demonstrating how to add web sign-on. The only exception to that is the endpoint used by the application. By default, Visual Studio configures your application to serve content through HTTP: however that would not be suitable for establishing secure sessions, given that it would leave communications unprotected and allow potential attackers to steal cookies and tokens. This is not mandatory during the development phase, as Azure will not strictly enforce use of HTTPS. It is, however, always good practice.

  2. IIS Express makes it very easy to enable HTTPS directly from Visual Studio. Select your project in the Solution Explorer, then in the Properties pane, switch SSL Enabled to True.

    You will see that the SSL URL, previously empty, will be populated with a new address. Select it and copy it on the clipboard.

    Copy SSL URL

  3. Now we need to let Visual Studio know that we always want to use the HTTPS endpoint during debug. Go back to the Solution Explorer, right-click on the project and choose Properties. Choose the Web tab on the left, scroll down to the Use Local IIS Web server option and paste the HTTPS URL in the Project Url field. Save settings (CTRL+S) and close the property tab.

    Change Project URL

    At this point we have an application that is suitable to be configured to leverage Azure AD for sign-on. The next step will be to let your Azure AD tenant know about this specific app.

  1. Minimize Visual Studio and go back to the Active Directory tab in the Azure Management Portal. Earlier in the walkthrough we worked in the Users area; we’ll now work in the Applications area. At the top of the page, click Applications.

    Integrated Apps

    This area lists the applications that are registered in your directory tenant. We say that an application is registered in a tenant when:

    • The application has an entry in the directory, which describes its main coordinates: name, associated endpoints, and so on. More details later.

    • The application itself has been granted permission to perform some operation on the current directory tenant: the operations range from requesting a sign-on token to the ability to query the directory. Once again, more details later.

    No application can take advantage of Azure AD without having been registered: this is both for security reasons (only apps that the administrator approves of should be allowed) and practical considerations (interaction with Azure AD entails use of specific open protocols, which in turn require the knowledge of key parameters describing the app).

  2. Given that we just created this directory tenant from scratch, the list of registered applications is still empty. In fact, the first entry is going to be for the application we just created in Visual Studio: this section will be entirely about registering it as an app.

    Given that this is the very first app, start the process by clicking the Add button on the Azure Management Portal command bar at the bottom of the screen. Then you will be prompted with the screen below:

    Tell Us About your App

    The process of registering one app through the Azure Management Portal is structured as a classic wizard, in which subsequent screens break down the gathering of the required information according to your choices.

    The figure above shows the first of such screens. The options offered are straightforward:

    • Display name: the text entered here is used as human-readable moniker to refer to the app whenever a user -- be it an administrator managing the registered apps list or a customer deciding to grant directory access to the app – needs to do something about it. There is more info about this in the Developing Multi-Tenant Web Applications with Azure AD paper.

    • Access type: this set of radio buttons allows you to specify what operations the app should be allowed to perform against the directory tenant. For the purposes of this tutorial, in which our goal is to simply configure web sign-on with our app, the proper choice is Single sign-on.

      Other papers will delve deeper in the topic of application permissions; however here we’ll briefly touch on the principles behind it in case you want to know what happens behind the scenes.

      Azure AD represents applications using an entity called ServicePrincipal. As the name suggests, those are analogous to the more familiar user principals but meant to be used for describing applications.

      The act of registering an application is, in practice, the creation of a ServicePrincipal for the application in the tenant of the directory instance the app is meant to have access to.

      The access level that should be granted to a given application is determined by the roles the corresponding ServicePrincipal belongs to. In this walkthrough you don’t need to, but if you were to choose read and write access levels then the registration flow would add some extra steps to gather more info, such as which keys to use for authenticating when performing such queries: in that case, the keys would too be stored in the ServicePrincipal describing the application. The Using the Graph API to Query Azure AD topic has more information about this.

      The permissions granted through the application registration process have effect only when accessing the directory itself; they do not determine access policies for other Azure resources such as SQL Azure databases, Management Portal sections and similar.

  3. Once entered the application’s name and chosen the Single sign-on access type, click on the arrow on the lower right corner to move to the next screen.

    App Properties In this screen the Azure Management Portal gathers important coordinates which the service needs to drive the sign-in protocol flow. Here there’s what you need to enter:

    • APP URL: this parameter represents the address of your web application. In this example, this corresponds to https://localhost:44341/, the address assigned by IIS Express to your application. If you followed the instructions exactly until now you should still have it in the clipboard, ready to be pasted. The value you entered will work for the duration of the development phase: once you’ll deploy your application to its target staging or production environment, you'll have to come back to the Management Portal and modify the address to match the new application’s location. Later in the walkthrough we’ll discuss how to do that.

      Azure AD needs to know your application’s address so that, after a user successfully authenticated on Azure AD’s pages, it can redirect the flow back to your application.

      It is mandatory to provide this address beforehand: if Azure AD would redirect authentication flows to any address, it would make it easier for attackers to hijack authentication flows and steal tokens. Registering the URL of your application in advance guarantees that authentication tokens meant for your app will be sent only to your app.

    • APP ID URI: this parameter represents the identifier of your web application. Azure AD uses this value at sign-on time, to determine that the authentication request is meant to enable a user to access this particular application - among all the ones registered - so that the correct settings can be applied.

    The APP ID URI must be unique within the directory tenant. A good default value for it is the APP URL value itself, however with that strategy the uniqueness constraint is not always easy to respect: developing the app on local hosting environments such as IIS Express and the Azure Fabric Emulator tend to produce a restricted range of addresses that will be reused by multiple developers or even multiple projects from the same developer. One possible strategy is to append something to the APP URI value as a differentiator.

    Also note. The APP ID URI is a URI, and as such it does not have to correspond to any network addressable endpoint. That means that you can choose something that has nothing to do with the APP URL: in fact, although in this tutorial we are working with a brand-new application you will occasionally register existing applications which might already have their own APP ID URI (in the sign-on protocol used here, WS-Federation, APP ID URI is called realm) and in that case you’ll likely want to use it here. In the Developing Multi-Tenant Web Applications with Azure AD topic we will highlight some extra constraints that the multi-tenancy introduces.

  4. Once you entered APP URL and APP ID URI you can click on the checkbox button on the lower right corner.

    Quick Start That concludes the registration process, your app has now its own entry in the directory tenant and Azure AD is ready to handle web authentication on its behalf.

    The screen informing you of the successful registration provides you with the information you need to configure your web application to use Azure AD for sign-on. Namely: the Enable single sign-on with Azure AD section contains a couple of settings that you’ll need to paste back in Visual Studio.

    Keep your browser open on this page and switch back to Visual Studio for the next task of the walkthrough.

Now that Azure AD is ready to issue authentication tokens for your application, the last step to enable web sign-on is to configure the application itself to handle requests with the right authentication protocol. The protocol enforcement is what allows the application to invoke Azure AD - and specifically your directory tenant - to take care of user authentication at the beginning of a user’s work session with the app.

It’s important to understand some of the background information on authentication mechanics when using web sign-on protocols. You will find more details in the advanced section.

The project template we have chosen is the MVC 4 Intranet application. That template normally relies on Windows integrated authentication to ensure that the app’s user is authenticated. That mechanism operates at the network level: it is applied to any services published on the intranet, without the need of adding any authentication logic to the application itself.

When you deploy an application outside of your intranet, as it is the case for cloud apps, you can no longer rely on network-level authentication. The most common strategy for dealing with authentication in those cases includes adding some kind of middleware in front of your application, which re-creates at higher level the necessary authentication check. The extra layer can take care of intercepting unauthenticated requests, enforcing authentication protocols, redirecting users to authenticate off-application, returning to the app info about the authenticated user, managing sessions and in general all the tasks that are necessary for access control.

This strategy is consistently applied in the industry across all the choices of platforms, development stacks and sign-on protocols; what goes on the wire and the programming model will vary, but the general pattern remains largely the same.

In this walkthrough we are going to connect the application to Azure AD via the WS-Federation protocol: this is only one of the possible choices for implementing Web SSO, SAML-P being the other most common choice.

The .NET Framework 4.5 supports WS-Federation natively: all the classes needed for enforcing the protocol flow, processing authentication and handling sessions in the context of ASP.NET applications are present in the box.

In a nutshell: .NET 4.5 offers a set of HttpModules which are meant to be instantiated in the application’s HTTP pipeline. Those modules are designed to refer to well-known configuration sections, which contain the protocol coordinates of both the application and the authenticating authority (in this case, your Azure AD tenant). As requests flow in, the modules examine them and enforce the authentication protocol as appropriate: for example, upon receiving an unauthenticated request the modules will read the Azure AD tenant’s coordinates from config, use them to compose a WS-Federation sign-in message and use it to automatically redirect the user to authenticate with Azure AD.

The subset of classes in the .NET Framework 4.5 dedicated to claims based identity related tasks is known as Windows Identity Foundation (WIF). Applications targeting earlier versions of the framework (3.5 and 4.0) can also implement the steps described in this walkthrough, by taking advantage of an earlier version of WIF which was released out of band as a standalone library (download here). However note that the step by step instructions would differ, given that the two versions are not fully compatible (the classes live in different namespaces) and that you’d have to use tooling for different Visual Studio versions (2008 and 2010, download here).

Visual Studio 2012 offers point and click tools which can help you to configure applications to use WS-Federation for web sign-on: you can use the tool’s UI to provide few key information about the authority you want to trust for authentication, and the tool will emit the corresponding configuration entries. In this walkthrough you will have to write very little code, thanks to the fact that the tooling will auto-generate most of it for you.

  1. Now that you know how we are going to implement web sign-on, let’s use the Identity and Access Tool to configure your application. In Solution Explorer, right-click on your applications’ project, then click Identity and Access… from the context menu.

    Identity and Access Visual Studio will show the dialog depicted below.

    Identity and Access Providers You will do all your work in the Providers tab, the one currently shown. For the purpose of this walkthrough, we will ignore all the options we don’t need for the task at hand.

  2. The tool lists various authority types you can use to outsource authentication. In our specific case, we are interested in using a Business Identity Provider: click on the corresponding entry, second option from the top.

    Identity and Access Configure As you select the option, the corresponding UI elements are displayed in the panel below. The information requested by those control matches exactly with the entries displayed at the end of the application registration process described in the earlier section. Here there’s what you have to enter, from the bottom to the top:

    • Enter the APP ID URI (realm) of your application: This is the identifier of your application, as you defined it during the registration. Switch back to the browser window showing the Management Portal, copy the corresponding value from the Update your code with your App ID URI field and paste it here.

    • Enter the path to the STS metadata document : The “STS metadata document” is a file containing a machine-readable description of the authority you want to connect to: the tool will consume it to determine the value of parameters that are essential to the sign-on flow (more details below). Every Azure AD tenant exposes one such document; its location is provided at the end of the registration process. Switch to the Management Portal, copy the corresponding value from the app registration page, switch back to the tool and paste the path in this field.

      As you paste in the textbox the path to the metadata document, the tool will display a warning about a certificate being invalid. That is due to the fact that the metadata document is signed with a self-signed certificate, and should not be cause for concern.

    Press OK. The tool will reach out to the specified metadata document, read the authority’s coordinates (address of the endpoints to be used for sign-on; X.509 certificate to be used for verifying the signature of authentication tokens; format and version of the issued authentication tokens; and so on) and use that info to generate and add to the web.config the entries that are necessary to connect the application to Azure AD.

The following list describes the main entries added to the web.config by the tool. For a more detailed description, please refer to the advanced section of the document.

  • <section> entries for system.identityModel and These are necessary for the config to understand the identity-specific config settings.

  • <authorization> settings in <system.web>: The tool automatically change the existing ASP.NET authentication settings to require that every request to the app must be authenticated. This enforces the so called “blanket redirect” behavior, in which every unauthenticated request gets redirected to the authentication authority (as opposed to having parts of the app available to unauthenticated users). Such behavior is the default in LoB applications, where authentication is often silent given that the user is already signed in with the authority. If the developer wants to change this behavior to provide authentication requirements on a case by case basis, they can simply change <authorization> settings accordingly.

  • WSFederationAuthenticationModule (FAM) and SessionAuthenticationModule (SAM) in <system.webServer/modules>: Those entries add in the application’s HTTP pipeline the HttpModules which take care of enforcing the use of WS-Federation for authentication. The FAM is the module responsible for protocol enforcement: sign-on requests, token validation sign out management are the main flows it is responsible for. The SAM handles sessions: specifically, it generates session cookies, validates them and enforce their presence at every request, handles session’s length, and so on. Their behavior is driven by the config element described below.

  • The <system.identitymodel/identityConfiguration> section: This element determines the behavior of the app during the authentication phase. For example: in the sub-element ValidatingIssuerNameRegistry it stores the list of authorities that are trusted for providing authentication services, by recording their names and the certificates they use for signing.

  • The <> section: This section provides the coordinates that are necessary for driving WS-Federation flows: the address of the authority to be used for sign-on requests, the identifier of the app itself to be included in requests, and so on.

The auto-generated config is all you need for taking advantage of Azure AD for web sign-on: you don’t need to write any authentication-specific code in the application itself. If you want to access user identity’s information you can easily do so by querying the claims in the current principal. For example, say that you’d like to access the first and last names of your current user. You will be able to do so using the following code, without the need of knowing anything about how authentication took place:

using System.Security.Claims;

namespace ExpenseReport.Controllers
  public class HomeController : Controller
    public ActionResult Index()
      ClaimsPrincipal cp = ClaimsPrincipal.Current;
      string fullname = 
             string.Format("{0} {1}", cp.FindFirst(ClaimTypes.GivenName).Value,
      ViewBag.Message = string.Format("Dear {0}, welcome to the Expense Note App", 
      return View();

Starting from .NET 4.5, every identity in .NET is represented with a ClaimsPrincipal. In this case, the current ClaimsPrincipal has been constructed during the validation of an authentication token generated by Azure AD and presented by the user at sign-on time.

Every ClaimsPrincipal contains a collection of claims, attributes describing the current user as asserted by the authority that authenticated him/her. In our walkthrough, the claims in the principal are the ones issued in the token by Azure Active Directory: for a complete list of the available claims please refer to the online documentation.

Azure AD issues a fixed set of claims for the authenticated users. Below there’s a quick reference of all the claims you can expect from Azure AD; you can find a complete description in the documentation.


Type Value in Sample Description


Unique, immutable, non-reusable, directed identifier of the authenticated user for the current application


Identifier for the user in the directory. Useful for directory queries about the user.


Identifier of the directory tenant


Given name of the user


UPN of the user


Last name of the user

Identifier of the authority that authenticated the user, as expressed in the web sign-on protocol (in this case, WS_Federation)

At this point your application has all you need to demonstrate web sign-on with Azure AD, however it is not complete yet. There are at least other two important features you’ll want to add: support for sign out and automatic refresh of the authority’s protocol coordinates.

The next two sections will detail how to add those two features: it is recommended that you go through those as well before moving to the “Running your App” section.

The web sign-on protocols in use today often include provisions for performing distributed sign out operations: those are flows in which not only the current application cancels its current user’s session, but it also reaches out to the authority to signal that a sign out command should be propagated to all the other applications’ sessions that might have been established by the same authority. WS-Federation is no exception, and offers a complete sign out flow that is fully implemented in WIF's object model. In this subsection we will discuss how to add distributed sign out capabilities to the sample application: that boils down to providing the right hookups in the user experience to trigger the signout flow, and to generate the appropriate signout message to be set to your Azure AD tenant.

  1. Begin by adding a SignOut controller to the application. You can easily do so by locating the Controllers folder under the project in Solution Explorer, right-click on it and choose Add, then click Controller. Name it SignOutController, choose Empty MVC Controller (it is usually the default setting), and then click Add.

  2. We’ll need to use classes from some new assemblies, hence we’ll have to add references to those. Again in Solution Explorer, right-click on the References node, choose Add Reference…, type in the Search Assemblies field, and select the corresponding assembly from the main list. Press OK.

  3. Go back to the newly created SignOutController.cs file. Add to the using directives the following entries:

    using System.IdentityModel.Services;
    using System.IdentityModel.Services.Configuration;
    Now change the implementation of the SignOutController class as follows:

    public ActionResult Index()
        return View("SignOut");
    public void SignOut()
         WsFederationConfiguration fc = 
         string request = System.Web.HttpContext.Current.Request.Url.ToString();
         string wreply = request.Substring(0, request.Length - 7);
         SignOutRequestMessage soMessage = 
                         new SignOutRequestMessage(new Uri(fc.Issuer), wreply);
         soMessage.SetParameter("wtrealm", fc.Realm);
    Here there’s a quick explanation of what the code does.

    • The first method, Index(), serves request of the form https://localhost:44341/SignOut. That is the address of a view you will add in few steps later in the walkthrough. Its purpose it to signal a successful sign-out, and we will use it as such in the next method.

    • The SignOut() method serves request of the form https://localhost:44341/SignOut/SignOut, and contains the main sign out logic.

    • The first line retrieves the object that WIF uses for keeping track of the WS-Federation settings in the web.config: we will need it to craft a sign out message tailored to the current application.

      Referring to the config values, as opposed to hardcode values or sourcing them from custom repositories, is usually good practice given that it makes your code adaptive and aligned with the rest of the protocol settings: the logic will keep working no matter how many times settings are changed in the config file, before and after deployment.

    • The second and third lines create the return address we want the authority to use at the end of the sign out flow. We want that address to point to the View discussed earlier: hence, the code obtains the URL of the current request and eliminates the trailing ‘SignOut’. Deriving the address from the request guarantees that it correctly resolves for the client, whereas obtaining the address from the hosting layer might result in internal ports issues when using a load balancer.

    • The fourth line uses WIF to craft a WS-Federation sign-out message, passing in the authority’s URL and the return address defined one line before. You could easily create the message directly in its wire form, however using the WIF object model will help you to write more concise code and ignore most of the syntax details. If you are interested in seeing how a sign out message looks like, make sure to capture an HTTP trace when you’ll run the app in a later section or consult the specification here.

    • The fourth line adds to the message the identifier of the current app, as recorded in the realm attribute of the <wsFederation> configuration element.

    • The fifth line uses the SAM (described earlier in the autogenerated config description) to clean up the local session: that includes deleting the session cookie generated at sign-on time, and any local resource cleanup that might be necessary.

      The sample application demonstrated here does not do much, but your real applications might allocate resources during a user’s session. If that is the case, you can take advantage of the SAM’s events SigningOut and SignedOut by adding corresponding event handlers in the Global.asax file to clean up whatever resources should be disposed upon closing a session.

The view used here is going to be very simple: as mentioned, its purpose is just to create a meaningful return point for the sign out flow.

  1. In the Solution Explorer, right-click on the Views node and add a SignOut folder.

  2. In that folder, add a view by right-clicking the folder and clicking Add, then click View. Call the new view SignOut as well. Put some placeholder presentation code in the View file (SignOut.cshtml) to signal that signout took place. For example:

        ViewBag.Title = "SignOut";
    <h2>You have successfully signed out</h2>
  3. As you might you might recall from the former section, we configured the application to handle authentication via blanket redirects. That means that, if we try to access this View after a successful sign out (as we are meant to) we will be immediately redirected to Azure AD to sign in again! To avoid that behavior, you can use the <location> element in the web.config to create one exception to the authentication policy.

    Locate the first occurrence of the <system.web> element, and just above it paste the following snippet:

      <location path="SignOut">
            <allow users="*" />
    That tells ASP.NET that the SignOut path can be accessed by anyone, including unauthenticated users. This arrangement will allow you to see this view rendered in your browser even upon successful sign out.

  1. Now that the app has the capability of signing out, all that’s left is surfacing the feature to the user experience. Here there’s a very simple way of doing so: open _layout.cshtml from the Views\Shared path in the solution explorer. Search for the string “Hello,” to locate the code which takes care of rendering the login info at the top of the typical MVC 4 layout, then modify the login section as follows:

    <section id="login">
      @if (Request.IsAuthenticated)
        <text> Hello, <span class="username">@User.Identity.Name</span>! 
      @Html.ActionLink("Signout","SignOut", "SignOut")</text>
      else {
        <text>  You are not authenticated </text>

That will add a sign out command on the right of the logged user’s greeting, so that a sign out action can be triggered from any view.

The Identity and Access Tool configured your application to accept tokens coming from your Azure AD tenant of choice. In order to do so, it cached in the web.config the necessary protocol coordinates for connecting to the intended Azure AD endpoints. Moreover, it saved key information used at authentication time to validate that the incoming token actually originated from your Azure AD tenant: those are the issuer name representing your tenant and the public key (in form of X.509 certificate) that should be used to verify the token’s signature.

It is common security practice to regularly renew cryptographic keys, and Azure AD signing keys are no exception: at fixed time intervals the old keys will be retired, and new ones will take their place in the issuer’s signing logic and in your tenant’s metadata document. In case of emergency keys might be renewed off-cycle, with little or no warning.

Every time the signing key is rolled, your application settings must be changed accordingly: following the approach shown in the walkthrough until now, that would mean re-running the tool to read the new metadata document and refresh the web.config entries.

To minimize downtime, it is a good idea to add self-healing logic directly in the application so that you can consume the metadata document programmatically and react to key rolling without the need of operator’s intervention. Below there’s an example of how to implement such feature.

  1. Use Solution Explorer, as described earlier in the document, to add a reference to the assembly System.IdentityModel.

  2. Add the following using directives to the Global.asax file:

    using System.Configuration;
    using System.IdentityModel.Tokens;
  3. Then add the following method to the Global.asax file:

    protected void RefreshValidationSettings()
        string configPath = AppDomain.CurrentDomain.BaseDirectory + "\\" + "Web.config";
        string metadataAddress = 
        ValidatingIssuerNameRegistry.WriteToConfig(metadataAddress, configPath);
    The logic here is very simple. The ValidatingIssuerNameRegistry is the class used by the Identity and Access Tool to record information about which authorities are trusted, and what keys should be used to verify the tokens they issue. WriteToConfig is a static method that reads the issuer settings from a metadata document (in this case retrieved from config, where it was stored by the tool’s first run, by the method’s second line) and uses it to create or update the corresponding config section of the file at the path specified (constructed from the current AppDomain in the first line of the method).

  4. To insert RefreshValidationSettings() in the application’s lifecycle, invoke it from Application_Start() as shown below.

    protected void Application_Start()
    Calling RefreshValidationSettings from Application_Start guarantees that the web.config will be modified in a safe time, whereas if you’d do that later in the app’s lifecycle you’d risk triggering a refresh.

There are some extra precautions you need to apply when auto-refreshing the validation keys from the application. The main threat you need to mitigate is DNS hijacking, where an attacker uses malware to point you to a malicious metadata document and induce your app to trust the wrong keys.

If you don’t override the .NET defaults for handling HTTP requests, the above scenario is already mitigated thanks to the fact that metadata documents are hosted on HTTPS endpoints. A DNS hijacking can redirect requests to a malicious endpoint, but such endpoint cannot pass the HTTPS server validation: not actually owning the domain on which metadata docs are hosted, the attacker cannot obtain an issued certificate for it, hence the client will be able to detect an issue with the server and avoid being misdirected.

Occasionally some development scenarios will require you to turn off HTTPS validation (typically via the ServicePoint class). If you use the automatic metadata refresh logic shown in this section, it is critical that you restore the HTTPS validation settings before deploying your application in production.

  1. We are now finally able to observe the application in action. Press F5: a browser window will open, attempting to access the URL specified in the project settings in the "Create an MVC App” section.

    First, you will get a certificate error. This is expected behavior, click Continue to this website (not recommended). Do not ignore this error in a production application, but it’s acceptable for the purposes of this walkthrough.

    CertificateError If you keep an eye on the address bar, you might observe for a brief moment the app’s URL; however the FAM module in front of the app immediately recognizes the call as unauthenticated, reads what to do from the config and triggers the sign-in redirect to Azure AD. The URL address bar is replaced by the one of the authority, and the user is prompted to authenticate via the Azure AD UI.

    The new user account you created earlier cannot be used to manage your Azure subscription if you initially signed in to the Management Portal using a Microsoft Account. If you attempt to navigate back to the Management Portal after you have signed in to the application as the new user, you will get an error message. Instead, you must sign in to the Management Portal using the account you used to create your directory tenant. If you initially signed in to the Management Portal using an Azure AD account and if the new user you created earlier was given the Global Administrator role, this new user can manage your Azure subscription.

    Sign in to AAD
  2. Enter the credentials of the user you created in your Azure tenant in the first section of the walkthrough. Press the Sign in button.

    You might recall that when you created the user in your Azure AD tenant the Management Portal assigned to it a temporary password. You have to authenticate using that password: however, given that such password was meant to be temporary, during this very first sign-in operation you will be asked to choose a proper user password before being able to move forward with the authentication flow. Once you’ll be done with that, the normal sign-in flow to the app will be restored.

    Application Home Page As the authentication successfully takes place, WIF processes the claims from the incoming authentication token, which in turn are used by the simple display code we added in the home controller. From now on you can navigate through the site without the need of authenticating again: every postback will carry the session cookie handled by the SAM module.

  3. To observe what happens when you terminate the session, click on the Signout link on the top right corner. You’ll observe the redirects we coded earlier, which will eventually land on the view below.

    Sign Out To verify that you are actually signed out, click on any other UI element: the authentication cycle will start over.

The walkthrough portion of the document showed you the essential steps you need to perform to add web sign-on to your web application. The rest of the document will go beyond the basics, digging deeper in some key topics and covering some of the other tasks you might need to perform to move your application to the next level.

In this section you will learn how to modify your application’s settings to deploy and run it in Azure Websites. The application remains largely unchanged: the only things requiring attention are accommodating for your app’s new address and session management.

This part of the document requires you to have an Azure Website to target for your application’s deployment. If you already have one website available, you can use it; if you don’t, please refer to this document for learning how to create and publish an Azure Website. If you follow the tutorial in that document, please stop right after having downloaded the publishing profile: there are a couple of things we need to adjust before deploying the application.

Adjust the application’s settings in the Azure Management Portal

If you recall the section about application registration, you’ll remember that one key parameter defining your application in the Azure AD UI is the URL of the application itself. The walkthrough steps until now assumed the local IIS express as the app’s location, however a deploy to Azure Websites means that the application’s URL will change and that the settings in Azure AD will have to reflect that.

  1. Navigate back to the Management Portal; select the Active Directory tab on the left; click on your directory tenant; choose the Applications header; click on the entry corresponding to the application you’ve been working with. Click on the Configure header; you’ll navigate to a screen that will allow you to modify the application’s settings you entered at creation time. For the sake of this tutorial, ignore the top areas of the screen and scroll down to the single sign-on section.

    Single Sign-On
  2. Locate the REPLY URL text box, and enter there the address of your target Azure Website (for example, That will let Azure AD to return tokens to your Azure Website location upon successful authentication (as opposed to the development time location you used earlier in the thread). Once you updated the value, hit SAVE in the command bar at the bottom of the screen.

You might have noticed that the APP ID URI is still using the localhost-based value you created earlier in the document.

Technically, as long as the identifier is in URI form and unique across all the apps in the current directory tenant, for the kind of apps discussed here any value will work; which is why the main instructions do not include updating that value.

However for manageability purposes you might want to modify the APP ID URI to carry a value that is more representative of your application. A typical example would be some derivative of the reply URL value.

Note that, if you change the APP ID URI value, you’ll need to apply more extensive changes to the app before deploying. More details later.

Prepare the Application to Run in Azure Websites

The web sign-on configuration is for the most part cloud-ready: there is only one change you need to apply, largely due to Azure Websites’ features.

The web sign-on process results in the creation of a session cookie, which gets sent at every request from the authentication instant on. The session cookie is created by the WIF middleware, and by default it is signed and encrypted via DPAPI (see this document for background information) in order to avoid abuses from the client (such as changing the list of claims to elevate privileges). However IIS settings in the Azure Websites prevent the use of DPAPI for protecting sessions, hence you need to change the way in which WIF secures the associated cookie. The .NET Framework 4.5 offers an alternative out of the box, which leverages the MachineKey (see documentation here) and works without issues in Azure Websites.

The Identity and Access Tool makes this change a very simple one.

  1. Right-click on the project in Solution Explorer, choose Identity and Access… and select the Configuration tab. You’ll see something to the effect of the following screenshot:

    Identity and Access Azure Websites
  2. Simply check the Enable web farm ready cookies flag and press OK. The tool will take care of adding the necessary elements in web.config (in practice, substitute the default class SessionSecurityTokenHandler with MachineKeySessionSecurityTokenHandler) to switch to MachineKey as cookie protection method.

    If in the former step you did change the APP ID URI in the Azure Management Portal, you can use this UI to easily apply those changes to your project: just paste the APP ID URI value in the top two text fields and hit OK. The tool will apply those changes in the right places in the config file.

    Optionally, you might want to consider temporarily turning off the ASP.NET custom errors messaging, by adding the entry <customErrors mode="Off" /> in the <system.web> section of the web.config file. That will help you to troubleshoot should you stumble in issues at deployment time, however please make sure to turn those back on before moving to production: attackers might use the detailed error messages to probe your app for openings, and customError will prevent that from happening.

That’s all you need to do for preparing your application to run as Azure Website. Use your publish settings to deploy the application, then open a browser, navigate to the address of your app and follow the same flow discussed in the app testing section of the walkthrough: given that we designed all custom logic to be location independent, you’ll be able to perform the same operations you experienced on premises.

The Identity and Access Tool automatically generates the config settings that are necessary for your app to integrate with your Azure AD tenant via WS-Federation. In the best case, you never need to actually see those settings; however there are occasions in which you want to alter the default behavior, or you need to troubleshoot a problem. In those cases, finding your way through the WIF config settings can help.

The WIF classes and method used in the web sign-in flow are fully documented in MSDN; here we will present an annotated version of the web.config after the Identity and Access Tool modified it. For your convenience, we also included the changes derived from the section on publishing to Azure Websites.

For the sake of clarity, the document includes the full Web.config source; however, only the sections relevant to WIF are annotated.

<?xml version="1.0" encoding="utf-8"?>
  For more information on how to configure your ASP.NET application, please visit
    <!-- For more information on Entity Framework configuration, visit -->
    <section name="entityFramework" type="System.Data.Entity.Internal.ConfigFile.EntityFrameworkSection, EntityFramework, Version=, Culture=neutral, PublicKeyToken=b77a5c561934e089" requirePermission="false" />

No comments for the above config.

<section name="system.identityModel" type="System.IdentityModel.Configuration.SystemIdentityModelSection, System.IdentityModel, Version=, Culture=neutral, PublicKeyToken=B77A5C561934E089" />
    <section name="" type="System.IdentityModel.Services.Configuration.SystemIdentityModelServicesSection, System.IdentityModel.Services, Version=, Culture=neutral, PublicKeyToken=B77A5C561934E089" />

In the above config, this area loads the classes that ASP.NET needs in order to read and interpret the config sections used by WIF to model the WS-Federation flow and authentication settings.

    <add key="webpages:Version" value="" />
    <add key="webpages:Enabled" value="false" />
    <add key="PreserveLoginUrl" value="true" />
    <add key="ClientValidationEnabled" value="true" />
    <add key="UnobtrusiveJavaScriptEnabled" value="true" />

No comments for the above config.

    <add key="ida:FederationMetadataLocation" value="" />
    <add key="ida:Issuer" value="" />
    <add key="ida:ProviderSelection" value="productionSTS" />

For the above config, those appSettings entries are captured by the Identity and Access Tool, to keep track of important settings (such as the address of the metadata document, which we used in the key rollover section) that would not be saved elsewhere.

  <location path="FederationMetadata">
        <allow users="*" />
  <location path="SignOut">
        <allow users="*" />

For the above config, those two <location> elements carve two areas in the web application that can be accessed without authentication requirements (see below). The FederationMetadata section is created by the Identity and Access Tool: the tool creates a metadata document describing the application, which can be used by authorities to provision the app. You added the SignOut section yourself as part of the instructions on how to implement web Sign out.

    <authentication mode="None" />
    <compilation debug="true" targetFramework="4.5" />
    <httpRuntime targetFramework="4.5" requestValidationMode="4.5" />
    <!--Commented by Identity and Access VS Package-->
    <!--<authentication mode="Windows" />-->
      <deny users="?" />

For the above config, by default, the Identity and Access Tool sets the ASP.NET authentication and authorization settings so that every part of the web app (apart from the exceptions above) requires users to be authenticated before serving requests. While that is usually appropriate for LoB apps, at times developers want to retain areas which can be accessed anonymously: if that is the case for you, change the settings here accordingly.

        <add namespace="System.Web.Helpers" />
        <add namespace="System.Web.Mvc" />
        <add namespace="System.Web.Mvc.Ajax" />
        <add namespace="System.Web.Mvc.Html" />
        <add namespace="System.Web.Optimization" />
        <add namespace="System.Web.Routing" />
        <add namespace="System.Web.WebPages" />
    <customErrors mode="Off" />
    <machineKey decryptionKey="998D0533DD570FDCA86A945893F0B2BFC0E1F3645E148F35" validationKey="E739C2EA4B4470820308DA71D81160F22C0D9CD3C97709CB0679E55FDCC2D35B35563D56102F254FB4908644ECB53B3898948F54AAC4A5F0C44754A5A997B79A" />
    <validation validateIntegratedModeConfiguration="false" />
      <remove name="ExtensionlessUrlHandler-ISAPI-4.0_32bit" />
      <remove name="ExtensionlessUrlHandler-ISAPI-4.0_64bit" />
      <remove name="ExtensionlessUrlHandler-Integrated-4.0" />
      <add name="ExtensionlessUrlHandler-ISAPI-4.0_32bit" path="*." verb="GET,HEAD,POST,DEBUG,PUT,DELETE,PATCH,OPTIONS" modules="IsapiModule" scriptProcessor="%windir%\Microsoft.NET\Framework\v4.0.30319\aspnet_isapi.dll" preCondition="classicMode,runtimeVersionv4.0,bitness32" responseBufferLimit="0" />
      <add name="ExtensionlessUrlHandler-ISAPI-4.0_64bit" path="*." verb="GET,HEAD,POST,DEBUG,PUT,DELETE,PATCH,OPTIONS" modules="IsapiModule" scriptProcessor="%windir%\Microsoft.NET\Framework64\v4.0.30319\aspnet_isapi.dll" preCondition="classicMode,runtimeVersionv4.0,bitness64" responseBufferLimit="0" />
      <add name="ExtensionlessUrlHandler-Integrated-4.0" path="*." verb="GET,HEAD,POST,DEBUG,PUT,DELETE,PATCH,OPTIONS" type="System.Web.Handlers.TransferRequestHandler" preCondition="integratedMode,runtimeVersionv4.0" />

No comments for the above config.

      <remove name="FormsAuthentication" />
      <add name="WSFederationAuthenticationModule" type="System.IdentityModel.Services.WSFederationAuthenticationModule, System.IdentityModel.Services, Version=, Culture=neutral, PublicKeyToken=b77a5c561934e089" preCondition="managedHandler" />
      <add name="SessionAuthenticationModule" type="System.IdentityModel.Services.SessionAuthenticationModule, System.IdentityModel.Services, Version=, Culture=neutral, PublicKeyToken=b77a5c561934e089" preCondition="managedHandler" />

For the above config, the entries in this section insert in the SP.NET pipeline the HTTPModules which implement the core protocol and session handling features.The WSFederationAuthenticationModule (FAM) enforces WS-Federation, by valudating incoming tokens and generating sign-on messages to the authority in accordance to the protocol’s specifications. The SessionAuthenticationModule (SAM) creates and validates session cookies, in concert with the FAM.

    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
        <assemblyIdentity name="System.Web.Helpers" publicKeyToken="31bf3856ad364e35" />
        <bindingRedirect oldVersion="" newVersion="" />
        <assemblyIdentity name="System.Web.Mvc" publicKeyToken="31bf3856ad364e35" />
        <bindingRedirect oldVersion="" newVersion="" />
        <assemblyIdentity name="System.Web.WebPages" publicKeyToken="31bf3856ad364e35" />
        <bindingRedirect oldVersion="" newVersion="" />
        <assemblyIdentity name="WebGrease" publicKeyToken="31bf3856ad364e35" />
        <bindingRedirect oldVersion="" newVersion="" />
    <defaultConnectionFactory type="System.Data.Entity.Infrastructure.LocalDbConnectionFactory, EntityFramework">
        <parameter value="v11.0" />

No comments for the above config.

        <add value="https://localhost:44342/ShiungZZZ" />

For the above config, <system.identityModel> wraps all the WIF classes-specific settings.Its first child element, IdentityConfiguration, provides a protocol-independent description of the application’s behavior. The AudienceUris list provides all the values that WIF will consider as acceptable scopes in incoming tokens for the current applications; typically, those correspond to the application’s realm (or APP ID URI, in Azure AD parlance). An incoming token must declare that its intended recipient is one of the values listed here; if that is not the case, WIF will assume that this is a stolen token and will refuse the call.

      <issuerNameRegistry type="System.IdentityModel.Tokens.ValidatingIssuerNameRegistry, System.IdentityModel.Tokens.ValidatingIssuerNameRegistry">
        <authority name="">
            <add thumbprint="3A38FA984E8560F19AADC9F86FE9594BB6AD049B" />
            <add name="" />

For the above config, the ValidatingIssuerNameRegistry element contains the list of the acceptable issuer name-signature check key tuples.In this walkthrough, the settings will reflect the values associated to your Azure AD tenant: this element guarantees that no other issuer, including other Azure AD tenants owned by other companies, can gain access to your application.

<certificateValidation certificateValidationMode="None">

For the above config, this element turns off the certificate validation in the WIF pipeline. This measure is necessary in the Azure AD case, given that a self-signed certificate is used: short of installing the certificate itself in the local certificate store, a chain or a peer validation would fail.Please note: this does not really diminish security for the Azure AD authentication, given that the ValidatingIssuerNameRegistry guarantees the correct certificate will be used; however, if you are using WIF in the same app for trusting other issuers please be warned that those settigns would extend to those as well.

        <add type="System.IdentityModel.Services.Tokens.MachineKeySessionSecurityTokenHandler, System.IdentityModel.Services, Version=, Culture=neutral, PublicKeyToken=b77a5c561934e089" />
        <remove type="System.IdentityModel.Tokens.SessionSecurityTokenHandler, System.IdentityModel, Version=, Culture=neutral, PublicKeyToken=b77a5c561934e089" />

This section allows you to manipulate the collection of classes which WIF uses for processing incoming security tokens (the so called token handlers). It can be used to influence the behavior of individual handlers, or to add and remove handler types. In this case, the tool removed the default session handler (which is based on DPAPI and cannot work on Azure Websites) and substitutes it with one that works with the MachineKey.

      <cookieHandler requireSsl="false" />
      <wsFederation passiveRedirectEnabled="true" issuer="" realm="https://localhost:44342/ExpenseReport" requireHttps="false" />

For the above config, the <> is used to store WS-Federation-specific coordinates.

The wsFederation element, in particular, is here used to record the WS-Federation sign-on endpoint of your Azure AD tenant; the realm (APP ID URI) of the app, to be sent as identifier at sign-on time; and other flags influencing WIF’s local behavior, such as if 401 errors from the app should always trigger a sign-in message to the authority (passiveRedirectEnabled) or if transactions on clear HTTP should eb allowed.

This element can be used to specify many more protocol parameters: those are just the absolute minimum for the sign-on flow to function.

This document focuses on a fairly narrow task, connecting a.NET application to Azure AD to perform web sign-on via WS-Federation. There are many more scenarios you can tackle, using a variety of different open protocols, leveraging any programming stack on any modern platform or working directly at the protocol level on the wire.

In the section about deploying the app to Azure you saw that the Management Portal offers you the chance of changing many more aspects of your application’s registration settings: you will get to know most of those extra controls in the next walkthrough in the series. Here we will just briefly mention how you can obtain the information you need should you choose to interact with Azure AD at the protocol level, for web sign-on or any other of the flows it supports.

  1. Open the Azure Management Portal in a browser window, and navigate to the Applications header in the Azure AD section. You will notice that the command bar at the bottom of the screen contains one entry: View Endpoints. Click on it.

    App endpoints The dialog lists all of the endpoints you can use to interact with your Azure AD tenant programmatically. Here there’s a brief explanation for all the entries:

    • Federation Metadata Document: The location of the metadata document describing the Azure AD tenant as a web sign-on authority. As you have seen in the walkthrough, in the section about automatic refresh of keys, this document contains WS-Federation metadata coordinates; it also contains the SAML protocol metadata in the same package. For more information, see Federation Metadata.

    • WS-Federation Sign-On Endpoint: The entry point for all WS-Federation transactions. This is the endpoint you used in the walkthrough for both sign-on and sign out flows. For more information, see WS-Federation Endpoint URL.

    • SAML-P Sign-On Endpoint: The endpoint used for implementing sign-on flows in the SAML protocol. For more information, see SAML Protocol Metadata and Endpoints.

    • SAML-P Sign-Out Endpoint: The endpoint used for implementing sign out flows in the SAML protocol. For more information, see SAML Protocol Metadata and Endpoints.

    • Azure AD Graph Endpoint: Queries to retrieve directory info stored in the current Azure AD tenant must be addressed to this endpoint, using the Graph API syntax. For more details, see Using the Graph API to Query Azure AD.

    • OAuth2 Token Endpoint: This endpoint is used for server to server authentication flows: for example, it can be used for obtaining access tokens for invoking the Graph endpoint. For more information, see OAuth 2.0 (Preview Version).

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

© 2014 Microsoft