For Developers: The first use cases of the converged Microsoft account and Azure Active Directory programming model...

[Alex Simons (AZURE)]

First published on CloudBlogs on Feb, 23 2016
Howdy folks, Today I am excited to tell you that the first set of uses cases supported by the Azure Active Directory v2 authentication endpoint are generally available. With the v2 endpoint, you can now build applications that let users sign in using their Azure AD backed work, or school account, or their Microsoft Account using a single button. Stuart Kwan from our developer experience team is back to tell you about what you can do with the v2 endpoint and what is coming next. As always, we'd love to receive any feedback or suggestions you have. Best regards, Alex Simons (Twitter: @Alex_A_Simons ) Director of Program Management Microsoft Identity and Security Services Division ---------------------------------------- Hi everyone! Federated sign in has many benefits. If you accept sign ins from Microsoft, you can:

• Store fewer passwords in your application and make yourself a less attractive target for attackers,
• Avoid your users having to remember another name and password,
• Give your users a single sign on experience if they are already signed in to Windows 10, Office 365, Outlook.com, OneDrive, or other Microsoft property,
• Seamlessly integrate a user's data such as their calendar or contacts,
• Take advantage of Microsoft's advanced anomalous sign in detection technology, and let us help you defend your user's accounts.

With federated sign in, Microsoft can handle identity management for you. With the Azure Active Directory v2 endpoint, we're making this easier than ever before. Until now, building an application that worked with both Microsoft work and school accounts and Microsoft personal accounts required adding two technology stacks to your application: the Microsoft account stack and the Azure Active Directory stack. We're bringing these two systems together so that you can integrate once and enable both kinds of users to sign in using a single button:

This converged programming model is exposed by the Azure AD v2 authentication endpoint . Today we are excited to announce GA of the first two scenarios supported by the v2 endpoint:

1. Build web, mobile, and PC applications that sign in both work and personal accounts with a single button: If you are building a simple web, mobile or PC app that needs to sign in both kinds of accounts, the v2 endpoint is for you.
2. Call the converged Outlook API: Services across Microsoft are in the process of converging so that a single API can be used for both work and personal accounts. The first converged API is the Outlook API , which enables you to access a user's mail, calendar, and contacts in one way regardless of the type of account. Our friends at Boomerang have taken advantage of this API to write an Outlook extension that helps you manage your email . Check it out! With the converged API, Boomerang was able to write one set of code that works for both personal Outlook.com users and business Office 365 users.

In addition to enabling you to sign in both work and personal accounts, the v2 endpoint has three cool improvements:

1. OAuth 2.0 and OpenID Connect 1.0 implementations that are more in line with others in the industry: We've responded to your feedback and updated our protocol implementations to be more like others in the industry. Our goal is to allow any standards compliant library to work with our service out of the box. You can read more about the changes we've made in our developer guide.
2. Register an application without needing an Azure subscription: To register an app with Azure AD today requires an Azure subscription so you can access the Azure management portal. No subscription is necessary to access the new app registration portal to register an app that works with the v2 endpoint. All you need is a work or personal account, making it simpler to get started.
3. Use a single registration to represent an app that includes a web UX, web API, and mobile clients: In Azure AD v1 you had to register the mobile/native clients of your application separately from your web UX and web API backend. With the v2 endpoint, a single registration with a single app ID can be used to represent both the front and back end of the application.

This release is a first step in combining the programming models of Microsoft account and Azure AD. This release lights up the two new scenarios but does not yet handle all of the scenarios supported by Microsoft account and Azure Active Directory. If your app fits into one of the two new scenarios, then we recommend you use v2. If it does not, we recommend you continue to use the tried and true v1 endpoints of Azure AD and Microsoft account. In time, v2 will superset the functionality of v1 and we'll help all developers move over to v2. Are you ready to get started? Check out the Azure AD v2 endpoint developer guide ! Or you can read on for more details about this first release of the v2 endpoint. Protocol Support - V2 Endpoint Here is a table summarizing all of the protocols and grant types supported by the Azure AD v2 endpoint. The protocols supported by the Azure AD v1 and Microsoft account v1 endpoints are shown for comparison. You can find examples for how to call the v2 endpoint in the v2 endpoint developer guide . Also, the breaking protocol changes we announced earlier are now in effect

Protocol	Scenario	Azure AD v2 Endpoint (work+personal accounts)	Azure AD v1 Endpoint (work accounts only)	Microsoft account v1 Endpoint (personal accounts only)
OpenID Connect 1.0	Web sign in	Y	Y	Y
OAuth 2.0, Authorization Code grant, public client (no secret)	Native client sign in	Can request access tokens to Outlook API only	Y	Y
OAuth 2.0, Authorization Code grant, confidential client (with password secret)	Service to Service(as user)	Can request access tokens to Outlook API only	Y	Y
OAuth 2.0, Authorization Code grant, confidential client (with certificate secret)	Service to Service(as user)	Can request access tokens to Outlook API only	Y	N
OAuth 2.0, Implicit grant	JavaScript Single Page App	Can request access tokens to Outlook API only	Y	Y
OAuth 2.0, Client Credentials grant, password credential	Service to Service(as application)	N (future release)	Y	Y
OAuth 2.0, Client Credentials grant, certificate credential	Service to Service(as application)	N (future release)	Y	N
OAuth 2.0, On Behalf Of token exchange	Service to Service(as user)	N (future release)	Y	N
OAuth 2.0 Device Profile	Native client sign in (with limited UI)	N (future release)	Y	N

As you can see in the table, not every scenario supported by Microsoft account and Azure Active Directory is supported in this release. Here's a summary of the current limitations in the v2 endpoint:

• Registering OAuth scopes. Currently, it is only possible to get access tokens for the Outlook API, where Microsoft has registered the OAuth scopes for that API behind the scenes. There is no way for you to register scopes for your own application yet. What does this mean for you? If your application consists of exactly one backend and multiple mobile/PC clients of the backend, you can use the v2 endpoint. Since in v2 the client and the backend are the same logical app, there is no need to register scopes. Scopes are only needed when one application wants to call another application.
• Server to server scenarios. Two server to server use cases are not yet supported: the On Behalf Of case where a server calls another server under the identity of a user, and the simpler case where a server calls another server under the identity of the app itself.
• Admin consent. In this release, a user can consent to personal scopes. It is not yet possible for an admin to consent on behalf of all users of an organization, or for an admin to consent to admin-level scopes.

Library Support - V2 Endpoint At the same time as we're updating our protocol implementations, we're also updating our open source libraries. As of this announcement, the Active Directory Authentication Libraries (ADAL) that support the v2 endpoint remain in preview. We're planning breaking changes that mean that the next version of the libraries will not be a drop-in replacement for the current preview. As such, we do not recommend using the preview libraries in production. Here's a table that summarizes which libraries are GA for the v2 endpoint and which are still in preview:

Library	Platform	Protocols Employed (V2)	Status (V2)
OpenID Connect Middleware for ASP.Net 4.6	.Net	OpenID Connect 1.0	Supported
OAuth 2.0 Middleware for ASP.Net 4.6	.Net	N/A (Token validation for Web APIs)	Supported
ADAL v4 for .Net	.Net	OAuth 2.0, auth code grant, public clientOAuth 2.0, auth code grant, confidential client	Preview – not GA supported with v2
ADAL v4 for JavaScript	JavaScript	OAuth 2.0, implicit grant	Preview – not GA supported with v2
Azure AD plug in for Passport	Node.js	OpenID Connect 1.0(Plus token validation for Web APIs)	Supported
ADAL for Node.js	Node.js	OAuth 2.0, auth code grant, public clientOAuth 2.0, auth code grant, confidential client	Preview - not GA supported with v2
ADAL v4 for iOS	iOS	OAuth 2.0, auth code grant, public client	Preview – not GA supported with v2
ADAL v4 for Android	Android	OAuth 2.0, auth code grant, public client	Preview – not GA supported with v2

If all you need is a web app supporting work and personal accounts, you can use the .Net OpenID Connect middleware or Azure AD plug-in for Passport and go into production. If you need to get an access token to call the Outlook API, an ADAL library is what you would normally use but all of the ADAL libraries are still in preview. Instead of using a preview library in production, we recommend you do one of three things:

1. Fork the preview ADAL library: Open source! You can make your own fork of the library and update it yourself if you run into issues. We accept contributions if you want to submit back.
2. Use a third party library: Since our contract is with you is at the protocol level, we support your use of third party OAuth and OpenID Connect libraries. You can find an up to date list of libraries that we've tested with the v2 endpoint in the reference section of the v2 developer guide .
3. Code directly to the protocol: This is always an option and is fully supported. You can find protocol documentation in the v2 developer guide . We do not mandate that you use our libraries, but strongly recommend the use of a library when one is available. Mistakes when implementing an authentication protocol can have serious security, privacy, and end user experience ramifications.

What's Next The v2 endpoint is our strategic authentication endpoint, and we have much more work to do. Here are some of the things we're working on:

• Libraries!
• Enabling you to register and manage v1 applications in the new app registration portal.
• Enabling server to server and admin consent scenarios and other new protocol flows on the v2 endpoint.
• Lighting up more converged Microsoft APIs with v2, including the Microsoft Graph.

Paired with the Microsoft Graph, our long term goal is to have one programming model for authentication and one REST API to access data across Microsoft cloud services. In the interim, the v1 authentication endpoints on Azure Active Directory and Microsoft account remain fully supported. We'd love to hear your feedback! Don't forget to visit the v2 endpoint developer guide . We monitor stackoverflow (tags: azure-active-directory and adal ) for your questions as you develop your apps. If you have a feature suggestion, please post it in the Azure Active Directory User Voice site and put "EndPointv2:" in the title of your idea. Happy coding! Stuart Kwan (Twitter: @stuartkwan ) Principal Program Manager Azure Active Directory P.S. We used to refer to the v2 endpoint as the "v2 app model", because the converged system includes more than just protocol updates. For example, the way an application is represented in the system has changed as well. But, this was too easily confused with the app model of the application you are actually building! So, we're referring to the converged system as the Azure AD v2 authentication endpoint from here on out.