Ah, the authentication dance. To be clear this isn’t really about Office 365 or the Office 365 APIs, but they rely on Microsoft Entra ID for authentication. With that being said, I find the authentication dance to be the hardest part of working with the Office 365 APIs hence why I’m covering it in a few posts here.
In SharePoint, Office 365 and Microsoft Entra ID, the OAuth 2.0 protocol is used for Authentication. Think of OAuth 2.0 as defining a set of grammar or a vocabulary for authentication. There are various ways you can implement it for different situations but it all usually comes down to the fact you are getting an access token.
Authentication is all based on levels or trusts. For instance, the Office 365 APIs (and Office 365 subsystem) have a trust established with Microsoft Entra ID. This trust essentially says “if you come to me, Office 365, with a token that says you are authenticated, if that token was obtained from Microsoft Entra ID, then I will trust what it says about you.” This trust is done using a digital signature. Once the token, which is just a specially formatted string, is digitally signed with Microsoft Entra ID’s private certificate, anyone who trusts Microsoft Entra ID (such as Offie 365) can verify it came from Microsoft Entra ID by comparing the public version of the certificate.
You may have heard in the last six months or so people talk about the Microsoft Entra ID App Model… this is what they are referring to where this is the fact that you are authenticating & obtaining an access token from Microsoft Entra ID. This differs from the original SharePoint App Model where the trust was with Azure Access Control Service (ACS). That model also uses access tokens in the same way so all the concepts map over just fine. Microsoft is slowly moving away from ACS towards Microsoft Entra ID but they aren’t dropping the older app model anytime soon so don’t freak out! I only mention this as a “see how this compares to the older model".
I don’t think I stated the above very clearly. To be very clear, there are NOT two different app models. Like I said, the SharePoint App Model obtained it’s access tokens via ACS and the registered apps (as well as the app registration) was done through the SharePoint UX. Apps created using Microsoft Entra ID use Azure’s access token endpoint to obtain access tokens. Apps can be registered and managed through the Microsoft Entra ID application UX. But apps created in either one are both stored within the same directory in Microsoft Entra ID… so don’t go thinking there are two different app models. Today we just have two different registration interfaces & ways of obtaining access tokens. Microsoft has expressed a desire to unify & with the pace of Microsoft Entra ID innovations, we may see this quite soon.
What’s in the the Access Token?
So what’s inside this access token that makes it so important? Upon a successful authentication, Microsoft Entra ID returns back to you a string as a JSON Web Token (JWT, pronounced ‘JOT’) that’s base 64 encoded. Dropping that string into a decoder lets you see the contents in clear text… the contents are quite interesting.
Aside from some metadata in the token such as the type of token (typ=JTW) and how it was digitally signed (alg=RSA256), you’ll find information about this like who the issuer is (iss=[https://sts.windows.net/[azure-ad-tenant-id](https://sts.windows.net/[azure-ad-tenant-id)), the id of the Microsoft Entra ID tenant that was responsible for the authentication of the user (tid=[guid]) and the ID of the application in Microsoft Entra ID (appid=[guid]).
The token will also tell you when it is valid, such as what time it was issued (iat=[seconds since January 1, 1970 UTC]), when the token starts being valid (nbf=[seconds since January 1, 1970 UTC]) and when it is valid until (exp=[seconds since January 1, 1970 UTC].
There is also a little information about the user who did the authentication in the family_name, given_name, unique_name= & upn=[email sign in].
Finally there is also an indication in the token that it is valid for use only on a specific endpoint, or resource. If you try to use the token for another resource, the endpoint should check this value and invalidate it. The user can’t change this value in the token because then the digital signature wouldn’t match the signed version and thus the endpoint would know it had been tampered with. Think of this like a key to a door - it will open a specific door, but if you use it on another door it won’t work.
You can learn more about token validation in Microsoft Entra ID by checking out Vittorio’s post on the Principles of Token Validation.
Great, so we know what’s in the token, but there’s one more thing we need to think about… what about the lifetime of the token?
Dealing with the Lifetime of Access Tokens
Tokens are only good for a limited amount of time. You can see how long they are valid by comparing the nbf and exp to get the number of seconds the tokens is good for. As you’d expect, as long as you use the token during that time, its valid.
But what if it is no longer valid? Do you have to go back through the entire authentication handshake to get a new token?
Thankfully no… at least not usually. When you originally get the access token you usually also get a refresh token. The refresh token is like an access token except it’s lifetime is just a little longer than the access token. So, instead of going through authentication handshake again, you can instead ask for a new access token using the refresh token. How long is the refresh token valid for? You don’t really know… it’s not designed to be something you can easily read and figure out.
Obtaining An Access Token
So now you have a bit of an idea how the authentication part works with Microsoft Entra ID & Office 365 as well as how access tokens are used. Armed with this, the next thing you need to learn is how to obtain one of these access tokens! There are actually a few different options for obtaining access tokens and each has their own use cases. In OAuth 2.0 we call these different processes flows. In my next post, that’s what we’ll look at - the different OAuth 2.0 flows supported by Microsoft Entra ID and what scenarios they make sense for.
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 into the authentication process with Microsoft Entra ID. In those modules I explain how the authentication process works and then demonstrate it using just the browser and Fiddler where we can see the raw traffic.