Ah, the authentication dance. To be clear this isn’t really about Office 365 or the Office 365 APIs, but they rely on Azure AD 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.
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.
In SharePoint, Office 365 and Azure AD, 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 Azure AD. 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 Azure AD, 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 Azure AD’s private certificate, anyone who trusts Azure AD (such as Offie 365) can verify it came from Azure AD by comparing the public version of the certificate.
You may have heard in the last six months or so people talk about the Azure AD App Model… this is what they are referring to where this is the fact that you are authenticating & obtaining an access token from Azure AD. 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 Azure AD 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 Azure AD use Azure’s access token endpoint to obtain access tokens. Apps can be registered and managed through the Azure AD application UX. But apps created in either one are both stored within the same directory in Azure AD… 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 Azure AD 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, Azure AD 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 Azure AD tenant that was responsible for the authentication of the user (tid=[guid]) and the ID of the application in Azure AD (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 login].
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 Azure AD 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 Azure AD & 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 Azure AD 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 Azure AD. 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.