December 2010

Volume 25 Number 12

Microsoft Azure - Re-Introducing the Microsoft Azure Access Control Service

By Vittorio Bertocci | December 2010

If you’re looking for a service that makes it easier to authenticate and authorize users within your Web sites and services, you should take another look at the Azure Access Control service (ACS for short), as some significant updates are in the works (at the time of this writing).

Opening up your application to be accessed by users belonging to different organizations—while maintaining high security standards—has always been a challenge. That problem has traditionally been associated with business and enterprise scenarios, where users typically live in directories. The rise of the social Web as an important arena for online activities makes it increasingly attractive to make your application accessible to users from the likes of Windows Live ID, Facebook, Yahoo and Google.

With the emergence of open standards, the situation is improving; however, as of today, implementing these standards directly in your applications while juggling the authentication protocols used by all those different entities is a big challenge. Perhaps the worst thing about implementing these things yourself is that you’re never done: Protocols evolve, new standards emerge and you’re often forced to go back and upgrade complicated, cryptography-ridden authentication code.

The ACS greatly simplifies these challenges. In a nutshell, the ACS can act as an intermediary between your application and the user repositories (identity providers, or IP) that store the accounts you want to work with. The ACS will take care of the low-level details of engaging each IP with its appropriate protocol, protecting your application code from having to take into account the details of every transaction type. The ACS supports numerous protocols such as OpenID, OAuth WRAP, OAuth 2.0, WS-Trust and WS-Federation. This allows you to take advantage of many IPs.

Outsourcing authentication (and some of the authorization) from your solution to the ACS is easy. All you have to do is leverage Windows Identity Foundation (WIF)—the extension to the Microsoft .NET Framework that enhances applications with advanced identity and access capabilities—and walk through a short Visual Studio wizard. You can usually do this without having to see a single line of code!

Does this sound Greek to you? Don’t worry, you’re not alone; as it often happens with identity and security, it’s harder to explain something than actually do it. Let’s pick one common usage of the ACS, outsourcing authentication of your Web site to multiple Web IPs, and walk through the steps it entails.

Outsourcing Authentication of a Web Site to the ACS

Let’s start by taking a vanilla Web site and enabling users to log in using a Google account.

Before we get started, let’s make sure we have the prerequisites covered. Here’s what we need:

  • Visual Studio 2010
  • Windows Identity Foundation Runtime
  • Windows Identity Foundation SDK and one of the following: Windows 7, Windows Server 2008, Windows Server 2008 R2 or Windows Vista SP1

Although it’s not a hard requirement, having IIS on the machine will help; if you don’t have IIS installed, you’ll have to adjust the steps of the walkthrough here and there.

While Visual Studio requires no introduction, it will probably help to expand a bit on WIF (pronounced “dub-IF”), and why it’s a prerequisite. (For a thorough explanation of WIF, see “Programming Windows Identity Foundation” [Microsoft Press, 2010]).

WIF is an extension to the .NET Framework that provides you with a new model for dealing with authentication and user identity, a model that decouples your application from the details of how authentication takes place. Traditional authentication systems (such as the ASP.NET Membership provider APIs) force you to cope with the details of how authentication takes place. This requires you to use low-level APIs to deal with low-level constructs such as passwords, certificates and the like. WIF changes all this by offering a handy abstraction that allows you to specify an external entity to handle user authentication. With Forms-based authentication, you specify a given page—typically login.aspx—where requests are redirected whenever the caller is not yet authenticated. With WIF, you can enlist an external entity—an IP—to be invoked whenever a user needs authentication. The ways in which the IP is chosen at design time and engaged at run time follow well-known protocols. WIF takes care of discovering which protocols should be used and enforcing communication policies accordingly. Once again, this is much easier to show than to explain.

Create the Initial Solution

Open up Visual Studio. Create a new Web site by selecting File | New | Web Site. Let’s create a new ASP.NET Web site—but first, be sure that you’ve selected the Web location as “HTTP” and configured the URL so that it’s running in IIS (see Figure 1).This will ensure a smooth run when using the WIF tools. If you have HTTPS available on your Web server, it’s a good idea to use it; although not strictly necessary for this walkthrough, it’s highly recommended on production systems and will save you some warnings from WIF.

image: Selecting an ASP.NET Web Site with HTTP as the Location

Figure 1 Selecting an ASP.NET Web Site with HTTP as the Location

When you hit F5, you’ll see that you have a basic ASP.NET Web site, and by clicking the “Log In” link you’ll get prompted to enter a username and password. This is what we’re going to change—instead of using a username and password and handling authentication directly in the Web site, we’re going to use WIF to outsource authentication to the ACS. The ACS will in turn allow us to open up access to external IPs.

Configure an ACS Project

To begin, we need to create a project in the Azure LABS portal. The LABS portal is an environment set up specifically for allowing the community to access early bits. There’s no cost associated with Azure LABS, but there are also no service-level agreements or guarantees.

Open your browser and go to You’ll be prompted to log in with a Windows Live ID. Once logged in, you’ll need to create a new project—click the “create a project” link. You’ll have to choose a project name—select something appropriate and click OK. Once complete, you’ll see an active project name (“acsdemoproject” in our example)—click it (see Figure 2).

image: Creating a Project in the Azure LABS Portal

Figure 2 Creating a Project in the Azure LABS Portal

Before you can outsource authentication to the ACS, you need to define a service namespace. Think of the service namespace as providing you with your own slice of the Azure LABS environment and—for the ACS—the unique component for all the URIs of the resources you’ll use when interacting with the ACS from your application. Everything contained within the service namespace is yours to control. Click “Add Service Namespace,” specify a name, choose a zone—in LABS you can only select “United States (South/Central)”—and click Create. Note that the URIs used by Azure are available on the public Internet and are meant to uniquely identify services; hence you must choose a namespace that hasn’t been picked by anybody else.

It’ll take a few moments, but after your service namespace activates, you’ll be able to click the “Access Control” link to start configuring the ACS for your Web site.

Now you’ve made it to the management portal, where you can configure the ACS for your Web sites (see Figure 3).

image: The Azure Access Control Service Management Portal

Figure 3 The Azure Access Control Service Management Portal

Click the “Manage” button to get started. The management portal provides some guided steps to walk you through the process of getting started, and that’s just what we’re going to do.

Choosing the Identity Providers You Want

Click the “Identity Providers” link. Here we want to configure the various social IPs we want to leverage from within your application. Windows Live ID is present in the list by default; let’s add support for Google accounts.

Click the “Add Identity Provider” link, which will show a list of providers. Click the “Add” button next to Google. You can specify a custom image URL for the IP, but go ahead and just click “Save.” Just like that, we’ve added Google as a recognized source of user identities.

Getting the ACS to Recognize Your Web Site

Now that our IPs have been configured, we need to provide information to the ACS about our Web site. In identity jargon, we often refer to applications as “Relying Parties,” an expression that refers to the fact that the application relies on one or more IPs to take care of authentication on their behalf. The ACS UI is consistent with this terminology.

Click the “Relying Party Applications” URL, and then “Add Relying Party Application.” Let’s specify the following information:

  • Name: My Website
  • Realm: https://localhost/Website/
  • Return URL: https://localhost/Website/
  • Token format: SAML 2.0
  • Token signing: Use service namespace certificate (typical)

The Token Format field deserves at least a short explanation (we’ll spend more time on the topic later in the article). A token is an artifact—typically an XML fragment or something in another serialization format—used by IPs to indicate that a successful authentication operation took place. Once a user authenticates, using whatever system the IP chooses, the user’s browser will be redirected to the ACS carrying a token that certifies the user has been recognized. The token format and protocol used will be determined according to the IP. The ACS will examine the token and, if it finds it satisfactory (more about this later), will emit a new token of its own and send it back to your application. The settings you change in this step determine which token format you wish the ACS to use for communicating back to your application. The ACS is capable of emitting three types of tokens—SAML2.0, SAML1.1 and SWT—representing different trade-offs between expressive power, security, applicability for certain client types and so on. Just pick SAML2.0 here; the details aren’t imperative at this point.

It’s important that the realm corresponds to the URL for the Web site we created earlier. Once the authentication with the IP of choice takes place, the ACS will redirect the user back to your Web site using the URL you specify here. Note that, by default, “Create New Rule Group” is selected—we’ll leverage this in the next step. Click “Save” once you’re done and return to the management portal.

Adding Rules

Rules are interesting constructs that give you fine-grained control over user identity information. The scenario we’re enabling right now, however, doesn’t require the explicit use of rules in order to enable sign-on from multiple IPs. Therefore, we’ll postpone all explanations about what rules are to a later section in the article, where they’ll actually come in handy; here we’ll just go with the default settings.

Click the “Rule Groups” link. You should see the rule group created when we added the relying party application (“Default Rule Group for My Website”). Select this rule group, click the “Generate Rules” link, confirm that both Google and Windows Live ID are selected, and then click the “Generate” button—that’s all you need to do in regard to rules in this scenario.

Collecting the WS-Federation Metadata Address

At this point, we’re finished configuring the ACS. However, before we jump back to Visual Studio, let’s grab some information from the Application Integration page. Click the “Application Integration” link and copy the “WS-Federation Metadata” URL—we’re going to use this with WIF to set up our Web site to leverage.

Without going into too much detail, the WS-Federation Metadata document is a machine-readable description of how the ACS handles authentication. Your application will need it in order to be configured to outsource authentication to the ACS.

Configuring the Web Site to Use the ACS

Return to Visual Studio and your Web site. We now want to 
leverage WIF to outsource authentication to the ACS, which will in turn enable Google accounts to access our application. In the Solution Explorer, right-click the Web site project and select “Add STS Reference.” This will launch the Federation Utility wizard, which will configure the Web site to use WIF as the authentication mechanism and the ACS as the authenticating authority. STS stands for “Security Token Service,” which indicates a special kind of Web service or Web page that offers an entry point for requesting tokens; usually every IP or token issuer uses one.

 You can just click “next” most of the time; the steps in which you’ll have to enter information are precious few. Advance to the “Security Token Service” step, and specify “Use an existing STS.” Paste the federation metadata URL you copied from the ACS portal (see Figure 4).

image: Starting the Federation Utility Wizard in Visual Studio

Figure 4 Starting the Federation Utility Wizard in Visual Studio

From there, leave the defaults, click through to the end and select Finish. The wizard will add all the required WIF assemblies, add some files to your Web site and (most importantly) update your web.config with the information required to engage with the ACS at authentication time.

Testing the Authentication Flow

It’s finally time to give your newly secured Web site a spin! Hit F5. You’ll immediately be redirected to the Home Realm Discovery page, which offers the user the chance to pick among the IPs we configured earlier in the ACS management portal (see Figure 5).

image: The Home Realm Discovery Page

Figure 5 The Home Realm Discovery Page

After you select Google and enter your Google account credentials, you’ll see an approval page that requires you to allow the ACS project access—this is important to understand, as it’s not your Web site that’s requesting permission, but instead the ACS (see Figure 6).

image: The Azure Access Control Service Asking for Permission to Get Information from Google

Figure 6 The Azure Access Control Service Asking for Permission to Get Information from Google

Once you’ve allowed the ACS the access it requires, you’ll get redirected back to the Web site (see Figure 7). That’s it—you’re logged in!

image: Success! Logging in to the Web Site

Figure 7 Success! Logging in to the Web Site

If you want to verify that the same experience would work with Windows Live ID, the other IP configured in your namespace, all you need to do is close the browser, hit F5 again and at the Home Realm Discovery page pick Windows Live ID instead of Google.

If you have any experience in enabling authentication protocols on Web sites, you know that, traditionally, adding an IP means studying its protocols and API, writing fairly challenging code and testing, testing, testing before getting it right. And every additional IP requires the same, plus the extra complication of understanding from the request which protocol is being used.

Here, we didn’t need to do any of that; in fact, you may have noticed that we didn’t write a single line of code. If we want to add extra identity providers, all we’ll need to do is go through a couple of screens on the ACS management portal, with no impact whatsoever on the application itself. If the IPs evolve their protocols, the ACS will change its code to accommodate the new conditions, and our application won’t even know anything changed at all.

The ACS: Structure and Features

Now that you’ve had a chance to experience firsthand the power of the ACS, you’re ready for a brief overview of what the ACS really is and what makes it tick. This will require a bit of theory, but you’ll discover that you already learned most of what you need to know while walking through the scenario described earlier.

The ACS operates according to the principles of claims-based identity. The main idea behind claims-based identity is that every entity in an identity transaction plays one or more canonical roles, taken from a short list of four: subject, identity provider (IP), relying party (RP) and federation provider (FP). In the walkthrough, you’ve seen all those in action. The interaction among those entities boils down to requesting, obtaining and forwarding security tokens, as shown in Figure 8.

image: Requesting, Obtaining and Forwarding Security Tokens

Figure 8 Requesting, Obtaining and Forwarding Security Tokens

The subject is the role played by the user—that is, the entity that needs to be authenticated. The IP is the entity that stores the account for the subject: username, credentials, attributes and so on. The IP uses one or more STSes for exposing its authentication capabilities and for issuing tokens. The RP is the application that the subject wants to use. Those three roles are enough for describing the most basic case: the subject obtains a token from an IP that the RP trusts, uses that token with the RP and the authentication is done.

One thing we didn’t cover during the walkthrough is that the tokens aren’t just representing the successful outcome of the authentication operation, but they’re also used to transport attributes describing the user: name, e-mail address roles and anything else that the RP needs to know and that the IP makes available. If you recall the properties of signed security tokens, you’ll see how those attributes can’t be tampered with and are cryptographically guaranteed to come from a specific IP. That means that one RP can choose to consider valid the attributes it receives according to how much it trusts the IP that originated them. Think of real-life situations in which you need to prove something—for example, that you actually live at a certain address. Companies often ask you to provide a utility bill, mainly because they trust the utility company more than they trust you. The information is the same (the address), but the IP that produced it makes all the difference.

When an attribute is issued as part of a security token, we call that attribute a claim. This concept is so important that it gives the name to the entire approach, and practically everything the ACS does revolves around claims. We just need to get another concept out of the way and then we’ll go in the details.

Although you could use the subject-RP-IP roles for modeling every system, in practice it’s not very handy. If one RP trusts multiple IPs, as was the case in our scenario, the model would require the RP to maintain multiple relationships, handle different protocols and so on. This is where the fourth role, the FP, comes into play. An FP is an intermediary between one or more RPs and one or more IPs, as shown in Figure 9.

image: The Federation Provider as an Intermediary

Figure 9 The Federation Provider as an Intermediary

The FP trusts multiple IPs, behaving like an application and expecting tokens from the IPs. In turn, the RP trusts the FP; to that purpose the FP exposes its own STS, which issues tokens for the RP. The FP takes care of the details of engaging with the various IPs, while always presenting to the RP the same façade, so IPs can be on-boarded and de-provisioned without affecting the RP. The FP can also transform the claims coming from different IPs to make them more useful for the RP. It can normalize different incoming claim types, add extra claims such as roles or permissions, and so on.

As you may have guessed by now, the ACS plays the role of the FP, as illustrated in Figure 10.

image: The Azure Access Control Service Playing the Role of Federation Provider

Figure 10 The Azure Access Control Service Playing the Role of Federation Provider

When you create a service namespace, you get your very own full-featured FP in the cloud. Out of the box, that FP includes four different STS endpoints, all offering different protocols that are suitable for different application types: WS-Federation for signing in to Web sites; WS-Trust for invoking SOAP Web services; OAuth WRAP and OAuth 2 for REST Web services; and Web APIs in general. Those are the endpoints you use to configure your application to outsource authentication.

The ACS is already pre-configured to trust various Web IPs, as we’ve seen, and it facilitates the experience of choosing among them by providing pages or embeddable code for them. In addition to that, the ACS is able to establish trust with commercial IPs such as Active Directory Federation Services 2.0 (AD FS 2.0), which expose STS endpoints themselves. In practice, the ACS exposes the counterpart of the “Add STS reference” functionality you’ve seen when configuring your Web site to trust the ACS. Using AD FS 2.0 as an IP is extremely interesting, as it allows you to reuse user accounts whenever you want, including those in Azure-hosted applications that would traditionally be valid only on-premises. Another interesting feature of business IPs is that they usually provide much richer claims sets that can be used for adding sophisticated identity-driven logic in the token processing.

The ACS allows you to describe your claims transformation login in the form of rules, a simple but powerful mechanism. For example, you can assign a role to a user as simply as entering something along the lines of “if the incoming name identifier claim has value X, please add an output claim of type role and value Y.”

All of the functionality discussed here can be accessed through the management portal you used in the walkthrough; alternatively, there’s an OData-based management service that gives you full control on the ACS settings while integrating with your existing processes.

As trite as it may sound, we did barely scratch the surface of what the ACS can do for you. We invite you to check out the hands-on lab in the identity developer training kit and the Azure training kit for exploring more scenarios in greater detail. If you want to simplify access management for your Web site, Web service or Web API, the ACS can help!

Vittorio Bertocciis a senior architect evangelist in the Developer and Platform Evangelism team and a member of the extended engineering team that produces Microsoft claims-based platform components. He’s responsible for identity evangelism for the .NET developer community and drove initiatives such as the Identity Developer Training Kit and the IdElement show on Channel 9. He recently wrote “Programming Windows Identity Foundation” (Microsoft Press, 2010).

Wade Wegneris a senior technical evangelist at Microsoft, responsible for influencing and driving Microsoft’s technical strategy for Azure. You can reach him through his blog at or on Twitter at

*Thanks to the following technical expert for reviewing this article:*Kent Brown