I’ve been digging quite in depth the Azure Active Directory Applications lately and although, a lot of information is already available on the web, it is hard to find a resource that summarizes it all. So, here are the key aspects of AAD Applications that are the most important things to know to understand the high level concepts and have a clear overview of what you can get out of AAD Applications..
Purpose of AAD Applications
The purpose is clearly to manage authentication and authorization to SaaS services such as SharePoint Online, PowerBI, Yammer, Office 365 Unified APIs, Outlook etc..and to offer a coherent way to interact with all these online services.
OAuth and OpenID. Two well known and heavily used protocols. OpenID is an extra layer on top of OAuth that brings more information retrievable as Claims.
Two types of tokens : Access Tokens & Refresh Tokens. Access Tokens usually obtained as a JWT (Json Web Token) are valid for one hour and can only be used to consume the resource for which they were requested. So an Acces Token obtained to consume SharePoint Online cannot be reused to consume MyFiles. The Access Token must be added to every further HTTP request that consumes the resource on the form of an Authorization HTTP header that holds the value of Bearer <access token>. Beware that should anyone in the world be in possession of this token, he will interact with the target resource on your behalf. So be sure not to leak such information.
Refresh Tokens are valid for 90 days max and allow to get new Access Tokens for any resource for a given user. If the Refresh Token is expired, the end user must login again in order to get a new Refresh Token. The Authorization grant flow allows to get a new Refresh Token and the Refresh Token grant flow allows your application to get a fresh Access Token for a user without the need to re-authenticate (via the Authorization Grant).
Refresh Tokens may be stored in a database and/or in any storage system in a safely manner. As for Access Tokens, if a Refresh Token gets discovered by an unattended third party, it could be an open door to harm your environment. So, store them with caution. Access Tokens should never be stored and should only be used to consume resources during the lifetime of a session.
App-Only Calls (Client Credentials grant)
App-Only calls are suitable for machine to machine (or service to service) communication where no end user is ever involved. The puprose of such communication is to allow an application to pull/put resources from/to any SaaS service supported by AAD. App-Only calls only return Access Tokens, there is no Refresh Token involved. Only a few steps are required to enable App-Only calls:
- Create an AAD Application
- Add one or more services to the list of permissions of this App. In the list of available SaaS applications, you’ll see two kind of information. Application and Delegate permissions. SaaS that have 0 application permissions cannot make App-Only calls. So be sure to select the appropriate applications and to configure the corresponding permissions
- You must create a certificate, export its public key (.cer) and add it to the AAD Application’s manifest.
- From the application that makes App-Only calls, you must have the .pfx (private key) part in order to initiate a communication with the AAD Application.
Storing sensitive information such as Keys and Secrets
Secrets and keys are often used with AAD Applications. A way to avoid disclosing them to developers is to store them into Azure Key Vault. A key manager can generate and store those keys. For each key/secret, Azure Key Vault will create a Resource URI that can be used by the application to get the information when it needs it. Providing you do not allow debugging in production, developers should never see the value of keys and secrets. Not only is it more secure but it is also more manageable, particularly when you need to update the secrets. Indeed, you’ll be able to change the value but keep the same Resource URI, so applications won’t need to change anything in code nor in the web.config files.
Whenever you want to get an Access Token, you must specify the Resource for which you want that token. Some of these resources are discoverable while others not. The discovery service helps you finding the discoverable resources as you could guess it. Here is a table that summarizes the current resources and endpoints, whether they are discoverable or not and whether they support App-Only calls or not.
|Notes||https://onenote.com/||https://www.onenote.com/api/beta||Not Tested||Not Tested|
Tip : never forget to add the trailing slash (/) character in the ResourceID.
(*) For the MyFiles (OneDrive For Business), the endpoint is …/me so the App Only call can be made but since the App isn’t a user, the /me doesn’t mean anything. Trying to use the /me endpoint with an App-Only Access Token leads to errors such as the below one:
message=User ‘i:0i.t|00000003-0000-0ff1-ce00-000000000000|app@sharepoint’ doesn’t exist in UPA by UPN or SID, and user with this SID was not found in AD.
So, today, if you want to address other user’s OneDrive for Business as an App, you must request the App Only token for the MyFiles resource but you should use the SharePoint traditional way of accessing documents, meaning the SharePoint APIs when using that token. Note that Microsoft is working on a common API between OneDrive and OneDrive For Business ( https://dev.onedrive.com/odb-preview/release-notes.htm ) but they’re not there yet. Today, I wouldn’t recommend using the App-Only calls with the MyFiles resource.
Regarding CORS, Microsoft allows any method and all origins. This means that only authentication with an Access Token is feasible because when wanting to forward browser credentials, the server must authorize Access-Control-Allow-Credentials but that can only be done with a specific origin and not with all origins such as “*”. The only allowed HTTP headers are accept and Authorization (to pass the token).
As shown in the above table, Yammer cannot be used with the App-Only calls. On top of that, Yammer has its own Apps system. If you want to know more about the differences between those systems, go read my comparison.
SharePoint is a very rich platform, certainly the richest in the current Microsoft SaaS offer. As there are many possibilities, go read my blog post about SharePoint Add-Ins vs AAD Apps vs SharePointOnlineCredentials to have more clarity on that. As a tip, you can also have a look at Using CSOM with Azure Active Directory Apps
Hopefully, this recap that is certainly not exhaustive, will be helpful to you.