Lately you might you might notice I’ve been on a bit of a kick with Microsoft Entra ID in some recent blog posts. In this post I want to talk about some of the different OAuth2 authentication flows that Microsoft Entra ID 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 Microsoft Entra ID. These three flows give you three options to do that.
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 Microsoft Entra ID. This flow is common when websites or custom applications leverage Microsoft Entra ID as a federated authentication provider. When the application needs you to sign in, or needs an access token to act on your behalf, it redirects you over to Microsoft Entra ID’s authorization endpoint to authenticate. You sign in using your email & password and in turn Microsoft Entra ID 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 Microsoft Entra ID and instead, the application just gets the code that’s a result of this sign in process, and as such, this is very secure.
Here’s what a typical URL looks like when you are redirected to the Microsoft Entra ID 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 Microsoft Entra ID 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 Microsoft Entra ID documentation, Microsoft identity platform and OAuth 2.0 authorization code 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 Microsoft Entra ID 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:
Microsoft Entra ID Client Credentials Token Request
First, this is going to a specific Microsoft Entra ID 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 Microsoft Entra ID documentation, Microsoft identity platform and the OAuth 2.0 client credentials flow.
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 Microsoft Entra ID 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 Microsoft Entra ID site but the SPA couldn’t authenticate with Microsoft Entra ID 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 Microsoft Entra ID documentation, Microsoft identity platform and OAuth 2.0 implicit grant flow.