All you need to know about Azure Active Directory Applications in a few lines

Hi,

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.

Protocols

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.

Tokens

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.

Discovery Service

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.

Name ResourceID EndPoint Disoverable App-Only available
Yammer http://www.yammer.com/ https://api.yammer.com/api/v1.0 No No
PowerBI https://analysis.windows.net/powerbi/api https://api.powerbi.com/beta/tenant/datasets No No
MyFiles https://tenant-my.sharepoint.com/ https://tenant-my.sharepoint.com/_api/v1.0/me Yes (*)
RootSite https://tenant.sharepoint.com/ https://tenant.sharepoint.com/_api Yes Yes
Directory https://graph.windows.net/ https://graph.windows.net/eyskens.onmicrosoft.com/ Yes Yes
Notes https://onenote.com/ https://www.onenote.com/api/beta Not Tested Not Tested
Contacts https://outlook.office365.com/ https://outlook.office365.com/api/v1.0 Yes Yes
Mail https://outlook.office365.com/ https://outlook.office365.com/api/v1.0 Yes Yes
Calendar https://outlook.office365.com/ https://outlook.office365.com/api/v1.0 Yes Yes

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.

ADALJS

ADALJS is the JavaScript library that enables getting tokens directly in JavaScript. Some SaaS such as SharePoint Online are CORS enabled so they can be consumed directly by JavaScript. In other words, if we have any web site somewhere in any technology, we can use ADALJS (an AAD App is also required of course) to get Access Tokens to consume remote resources such as SharePoint Online. Getting a token in JavaScript implies that the Implicit Grant be available. To do so, you must download your AAD Application’s manifest, set the oauth2AllowImplicitFlow property to true and reupload the manifest to overwrite the previous one.
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).

Yammer’s specials

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’s specials

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.

Happy Coding!

Advertisements

About Stephane Eyskens

Office 365, Azure PaaS and SharePoint platform expert
This entry was posted in Azure Active Directory, Office 365, SharePoint Online, Yammer and tagged , , , , , . Bookmark the permalink.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s