Enterprise Mobility and Security Blog


Howdy folks,

It's another big news day!

Today we're announcing the public preview of a converged programming model for Microsoft account and Azure AD Identities. This is the first publicly visible step in our long-term efforts to merge the Microsoft Account and Azure AD Cloud identity services. If you are a developer, this will make it WAY easier for you to write applications that work with both Microsoft Account and Azure AD Accounts.

As many of you who follow the blog know, our team runs both the Microsoft Account cloud service for consumers and the Azure Active Directory cloud service for organizations.

Between these two systems, we manage hundreds of millions of active online users and perform billions of authentications a day. But previously, to take advantage of these identities, application developers have had to integrate differently with each system.

We've been getting a TON of requests from third party developers like you to make it simple and consistent to develop apps that work with both systems so we're really excited to turn this preview on for you.

In addition, with today's challenging security climate (for example this recent news), it's getting harder and harder to run a cloud identity system that that is secure from attack.

By taking advantage of Microsoft Accounts and Azure AD as your identity subsystem, you can hand a big chunk of the responsibility for protecting these users over to us knowing they'll be protected by the millions of dollars we invest each year protecting Windows, Office 365, Azure, and Xbox users.

Stuart Kwan, a lead PM on the developer experience team, is going to walk you through what you can do with this preview and how to kick the tires yourself.

As always, keep the feedback coming!

Best Regards,

Alex Simons (Twitter: @Alex_A_Simons)

Director of Program Management

Microsoft Identity and Security Services Division



Hi everyone,

Until now, building an application that worked with both personal and business accounts from Microsoft required integrating with two different technology stacks. Not only that, you had to have separate buttons in your app where your user needed to choose, up front, to sign-in with a personal account or a work or school account.

With the v2 app model preview, it is possible to sign-in both personal and work users with a single button. Let's take a quick look at the end user's experience. We begin with your application, with the addition of a "Sign-in with Microsoft" button.

We're using the Microsoft brand because end users don't know about Azure or Azure Active Directory. But they do know that Windows, Outlook, OneDrive, Xbox, and Office 365 are services from Microsoft and they need an account from Microsoft to sign-in there.

When the user clicks the button, they come to a consolidated sign-in page:

The user enters their username. Under the covers we figure out if the username corresponds to a personal account or a work account. Then we take the user to the right page to enter their password. Today this may involve a redirect – in the future we'll optimize this out.

For example, if you enter the username of a personal account:


 Or, if you enter the username of a work or school account:

It is also possible for a user to have a personal account and a work account that have the same username. In that case we ask the user to pick which one they want to use to sign-in:

 After the user signs in, if it's the first time the user has visited your application they are asked to consent:

After the user signs-in, your application receives a uniform set of claims about the user regardless of account type. This works for both web and mobile applications. That's it! With one sign-in button your app can reach hundreds of millions of users.

The secret sauce is a new app model that we are adding to Azure AD. We call this the v2 app model. The v2 app model supports OAuth 2.0 and OpenID Connect 1.0 and normalizes requests and responses across Microsoft account and Azure AD. Now I'll tell you more about how to build an application that uses this model.

How to Build an App Using the v2 App Model

Everything you need to know to build an application using the v2 app model can be found in this overview article in the Azure AD developer guide. Here's a quick tutorial.

The first step is to register your application. We've taken this opportunity to create a new portal to simplify the registration process. For now, this portal only works for the v2 app model. Go to https://apps.dev.microsoft.com and sign-in with either a personal account or a work or school account.

(Yes, you may notice that to sign-in to the registration portal you have to choose to sign-in with a personal account or a work account! I'll explain more about this later.) Click to add an application and give it a name. The basic registration is complete, and your application has an ID.

 Let's say this particular application will consist of a web site, REST API, and iOS application. Next you would register each of these platforms. Click Add Platform, select Web, enter your web app's redirect URI (the location where authentication responses will be posted), and click Save at the bottom of the page.

To add the iOS application, click Add Platform and select Mobile Application:

If you've built apps that use Azure AD before, you'll notice that you no longer need to make separate registrations for a native client and a back end service. If it's one logical app – native client, web and web API – then it can all be represented by a single application ID. We've also simplified native client registration by defaulting to the standard redirect URI "urn:ietf:wg:oauth:2.0:oob".

That's all it takes to get registered! The links in the portal take you to the developer guide where you will find quick start samples for several languages. For now let's take a look at what happens at the protocol level. We've listened carefully to your feedback on our implementation of OAuth 2.0 and OpenID Connect 1.0 and made some updates in the v2 app model. Here's what an OpenID Connect request looks like when signing a user in to my sample application (line split for readability):

GET https://login.microsoftonline.com/common/oauth2/v2.0/authorize









(The values of state and nonce are opaque to the identity system – these values are inserted and interpreted by your app, or in this case the .Net OWIN OpenID Connect middleware that generated the request.)

Notice the "v2.0" in the path that denotes the v2 app model. The most important difference from the current app model is the usage of the scope parameter:

  • Previously you had to declare what permissions your app needed at registration time. With v2, you request permissions at run time using the scope parameter. This allows your app to ask for permissions incrementally as they are needed, instead of requiring a user to consent to everything up front.
  • The service determines the target of the token using the scope parameter instead of the resource parameter. The resource parameter is no longer required.
  • To receive a refresh token, your app must specify the offline_access scope.

In this preview an application can request tokens that target the Outlook REST API (in the above example by requesting scope=https://outlook.office.com/Calendars.Read) or the app itself (by requesting scope=openid). In future releases we'll add support for calling other Microsoft APIs, and for you to define scopes in your application that other parties can call.

Here's what a response looks like (line split for readability):

POST https://localhost:44327/ HTTP/1.1






And, peering into the id_token from the response:


typ: "JWT",

alg: "RS256",

x5t: "GvnPApfWMdLRi8PDmisFn7bprKg"



ver: "2.0",

iss: "https://login.microsoftonline.com/9188040d-6c67-4c5b-b112-36a304b66dad/v2.0",

aud: "49210253-0ba1-4a9a-a424-616999fab620",

exp: 1437852898,

iat: 1437766498,

c_hash: "9lVK1T23caFomiR5ecAEiQ",

nonce: "635733632666222015.ZWUyZWI5N2YtMDYzOC00MmEzLThmNmQtMDMxZDI0MzhhMzRkYzRiN2U5YjYtZThkNS00MGQ2LTkwNTAtMzU4OWMyOGI2ODY1",

name: "Stuart Kwan",

preferred_username: "<redacted>",


tid: "9188040d-6c67-4c5b-b112-36a304b66dad"


An important thing to note is we've switched to the standard preferred_username claim to convey the user's username. Previously we sent this in the upn claim. Yes, I've redacted my username to protect the innocent. 🙂

We've published preview versions of the Active Directory Authentication Library (ADAL) and our server-side SDKs that take care of the protocol details for you. For the .Net version of ADAL this means we have two versions in preview simultaneously – the v3 version that uses the current app model, and the experimental v4 version that uses the v2 app model. In the developer guide you can find links to libraries for .Net, Windows Universal, iOS, Android, and Node.js. We're working hard to get an updated JavaScript library out as well.

Not every scenario you can do today with Azure AD or with Microsoft account is supported in this preview. For example, applications that were registered in the Azure portal under the current app model don't work with the v2 endpoint. And v2 applications registered in the new portal don't work with the current protocol endpoint. You can find an up to date list of supported scenarios in the developer guide.

Calling the Outlook API

Microsoft Outlook's team has also done a ton of work to consolidate their personal and business APIs into a single API. Now you can sign a user in and access their calendar, contacts, and email with a single piece of code, no matter if the user is accessing their personal or business inbox. Our friends at Baydin have updated their Boomerang Outlook extension to take advantage of this – you can check that out here. For more information on building applications using the consolidated Outlook REST API, check out the Outlook dev center. We're working hard to light up more of the Office REST APIs this way.

What's Next

We have two big, long term goals for this work. The first is to make programming to Microsoft services simple by having a single authentication model and a unified REST API. The second is to transition Microsoft's own applications to this improved sign-in experience. For largely historical reasons Microsoft's own applications handle personal and work accounts slightly differently, and we need to do more work before they can use the v2 app model. This is the reason, by the way, that the registration portal does not use the v2 app model yet. In the coming months you can monitor this blog for announcements as we expand the list of supported scenarios.

While we experiment with the v2 app model, the protocols, SDKs, and tools of the current app model remain fully supported. We're working on how apps written to the current app model can evolve to the v2 model. For example, we want people who have apps registered in Microsoft account and Azure AD in the current model to be able to take full advantage of the new registration portal.

We'd love to hear your feedback! Don't forget to visit the one stop topic in the Azure AD developer guide. We monitor stackoverflow (tags: azure-active-directory or adal) for your questions as you develop your apps. Or if you have a feature suggestion, please post it in the Azure Active Directory User Voice site and put "AppModelv2:" in the title of your idea. For us, it's all about protecting users and helping them sign-in to your applications.

Stuart Kwan (Twitter: @stuartkwan)

Principal Program Manager

Azure Active Directory