Microsoft MVP Logo

Lately you might you might notice I've been on a bit of a kick with Azure AD in some recent blog posts. In this post I want to talk about some of the different OAuth2 authentication flows that Azure AD supports. Specifically I want to look at three of them:

  • Authorization Code Grant Flow
  • Client Credentials Grant Flow
  • Implicit Grant Flow

One thing is common between all these flows - the ultimate goal is to get an access token that you can use to authenticate with a resource that trusts Azure AD. These three flows give you three options to do that.

Check out my Pluralsight course Office 365 APIs - Overview, Authentication and the Discovery Service, specifically modules 3 & 4, that go deep into the authentication process.

So let's go ahead and get started... in each one I'll explain what it is, why you would need it, when you would use it and where to get some additional information on it... there's four of the "W's" covered!

Authorization Code Grant Flow

I think this is the most common type of authentication flow that we have been using in Azure AD. This flow is common when websites or custom applications leverage Azure AD as a federated authentication provider. When the application needs you to login, or needs an access token to act on your behalf, it redirects you over to Azure AD’s authorization endpoint to authenticate. You login using your email & password and in turn Azure AD redirects you on successful logins back to a specific URL in the app. Included in this redirect is the authorization code, an encoded string that only Azure can read. The app then takes this authorization code, which is fairly short lived expiring in just 10 minutes or so, and can use it to obtain access tokens on your behalf.

One benefit to this model is that the custom application or web site never sees your username & password… all authentication happens over on Azure AD and instead, the application just gets the code that’s a result of this login process, and as such, this is very secure.

Here’s what a typical URL looks like when you are redirected to the Azure AD Authorization endpoint. Notice the response_type parameter is asking for the authorization code in response:

https://login.windows.net/4254573b-5de2-452e-b706-30eed7ce1ebf/oauth2/authorize
?client_id=c0d204d8-1f5b-424e-944c-489cab675586
&resource=https://api.office.com/discovery/
&redirect_uri=https://www.pluralsight.com/a/signin
&response_type=code

And here’s what one of those codes looks like:

AAABAAAAvPM1KaPlrEqdFSBzjqfTGM0mnRFrpFwtqt9Q0H3rYDgLLN_9rSBK-[...]

Once you have the code, when you go to the Azure AD Access Token endpoint you include the authorization code in the body of the request. For example, the access token endpoint is always something like this (depending if the app is single / multi-tenant): https://login.windows.net/4254573b-5de2-452e-b706-30eed7ce1ebf/oauth2/token

The body of the request includes a bunch of stuff, but the two things relevant to this discussion is the authorization code & the grant_type parameter. It tells the access token endpoint "I'm sending you an authorization code in this request":



Today all Office 365 API endpoints and the SharePoint REST API supports this authentication flow.

You can learn more about this flow form the OAuth2 spec, The OAuth 2.0 Authorization Framework / Authorization Code, as well as on the Azure AD documentation, Microsoft Azure / Authentication Protocols / OAuth 2.0 / Authorization Code Grant Flow.

Client Credentials Grant Flow

Next up, let's talk about the client credentials grant flow. This is typically used when you need to get an access token but you don't want to work under the context of a user+app permissions, rather you want to work with just app permissions. This differs from the above flow as in the previous flow your app is impersonating a user where in this case you just run as an application.

This is common in service or daemon related apps. The way this works is the application has it's own credentials that are used to authenticate & obtain an access token form a token issuer. So how does it work? Well, unlike the previous example, we don't need to obtain an access token. Ahead of time we had to create a SSL certificate and register it with our Azure AD app. That cert we register is the public cert. We then, within our app, use the private cert to encrypt a string that we'll send over to the access token endpoint.

Those of you familiar with high-trust or S2S SharePoint apps might be noticing some similarities here... and you're right. It's the same concept.

Take a look at what a request to the access token endpoint for this type of flow:

First, this is going to a specific Azure AD tenant so you can't point to the common endpoint for multi-tenant apps. Then notice the grant_type is now set to client_credentials. The other two values, the client_assertion_type and client_assertion tell the access token that you are making an assertion with an encrypted JWT token that was signed with your private key and this should be used to authenticate the app.

I'll write a bit more about this flow & how to set it up in a future post. Today only the Exchange Online related resources in Office 365 APIs (contacts, calendar & mail) support this type of authentication flow.

You can learn more about this flow form the OAuth2 spec, The OAuth 2.0 Authorization Framework / Client Credentials, as well as on the Azure AD documentation, Microsoft Azure / Authentication Protocols / OAuth 2.0 / Service to Service Calls Using Client Credentials.

Implicit Grant Flow

The last authentication flow I want to talk about is the implicit flow. Like the authorization code flow where the idea is to get an access token to impersonate a user, the implicit flow also gets an access token to impersonate a user. However, instead of requesting an authorization code first, the client is issued the access token directly. This is a common pattern that you would want to use in a fully client-side implementation, such as single page applications (SPA).

This is a relatively new flow that Azure AD is supporting, but it's very powerful. I have a post I'm working on that I'll publish later this week that dives into this a bit more. But suffice to say, it's very very cool... you can now create 100% secure client-side applications without the need of an intermediary. Today the SharePoint Online & Office 365 Files API support this authentication flow but more will follow soon I'm sure.

This was not possible when Scot Hillier built the Research Tracker Sample for Microsoft. In that sample, a SPA is loaded from an Azure AD site but the SPA couldn't authenticate with Azure AD directly, instead it had to call a WebAPI REST service to authenticate and talk to the SharePoint Online REST API on the SPA's behalf. However if we built that same sample today, we could do it without the intermediary.

You can learn more about this flow form the OAuth2 spec, The OAuth 2.0 Authorization Framework / Implicit, as well as on the Azure AD documentation, Microsoft Azure / Authentication Protocols / OAuth 2.0 / Service to Service Calls Using Client Credentials.

Interested in learning more? Check out my course Pluralsight Office 365 APIs - Overview, Authentication and the Discovery Service, specifically modules 3 & 4, that go deep and demonstrate the different authentication flows supported in Azure AD that are leveraged in Office 365.

Comments powered by Disqus