Most of the APIs nowadays incorporate OAuth 2.0 authentication. It is not as complicated as it may seem at times, provided the right links and documentation are found. Microsoft APIs are extremely helpful and useful, but to access them from a third party application is when it’s needed, for the entire process of registration and access token retrieval, to be followed; to comply with the OAuth authentication in place.

For office365 (2016) APIs the links that would help access these APIs would be of the format https://outlook.office.com/api/{version}/me/…

me – represents the logged in user
{version} – v2.0 or v1.0
/- events (for outlook calendar API)

The first step, as hundreds of websites mentions, is to register the application. To be a little more comprehensive on this point, I would like to mention that it is not required to deploy any kind of code or application into the registration portal.
https://apps.dev.microsoft.com is free if you have access to a Microsoft office account.
The registration process is a way of letting Microsoft know that a particular app is going to access its APIs. It is a good practice to name the app appropriately as it will appear on the screen when the application, that is being developed, navigates to the login page.

Application id is the client id that is needed to be provided in the headers when requests are made for authorization code and access token.

Clicking on Generate new password will provide a client secret. New key pairs can be generated as often as needed, but in case the developed application is deployed in a client environment, these details will have to be provided at the very beginning and there would be little chance for frequent changes. Therefore, as client secrets will be displayed just one time it is advisable to make a note of it. These are generally valid for two years.
Add platform button lets choose which type of application is going to be developed.

Definitely both can be selected (one at a time).

The most important step while registration is to take extra care when the redirect-URI is added. This is where Microsoft will send the access and refresh token after authentication.
Redirect-URIs are very crucial and it is to be made absolutely sure that the links provided are available in the application and requests and responses to those links can be monitored. Multiple URIs can be added here as well.
(N.B.- Uris in the format http://localhost:8080 are accepted, however any URI with a different system name appearing in place of localhost will not be accepted.)

OAuth 2.0 is two-step authentication. The first layer sends an authorization code, which could be referred to as a part of the key to the second layer which gives the access token.

To get the part of the key it is required to execute a get request for the authorization code.
The link to which the request is sent to https://login.microsoftonline.com/common/oauth2/v2.0/authorize.
The request header must contain: –

Response-type = code (always code for receiving authorisation code)
Client-id = your client id
Redirect-URI = URI which is available in your application and also registered with Microsoft dev portal for the  same client id
Scope = what functions your app will be performing
(eg: openid offline_access profile https://outlook.office.com/mail.readwrite https://outlook.office.com/mail.send)

This get request will take the application to the Microsoft login page wherein a valid Microsoft user name and password will have to be provided and necessary permissions must be granted. Completion of this step will redirect the application to the redirect URI with an authorization code.

This authorization code can be captured from the query string parameters of the request.
The next step is to obtain the access token which can be done by sending a post request to https://login.microsoftonline.com/common/oauth2/v2.0/token.
The post request for access token should contain: –

Grant-type = authorisation-code (captured from last request)
Scope= same as previous request
Redirect-uri=needs to be same as previous url or else this would give an error
Client-id=same client-id
Client-secret=the client secret that had been noted down

Sharing of client-secret is deemed as an offence and hence no website will ever share that detail and hence the registration process becomes even more pivotal.
Java code snippet to form the post request: –

List<NameValuePair> pairs = new ArrayList<NameValuePair> ();
pairs.add (new BasicNameValuePair (“grant_type,”authorization_code”));
pairs.add (new BasicNameValuePair (“code, authorisation code));
pairs.add (new BasicNameValuePair (“scope, scope mentioned in get request for auth code));
pairs.add (new BasicNameValuePair (“redirect_uri, your redirect uri);
pairs.add (new BasicNameValuePair (“client_id”, your client id);
pairs.add (new BasicNameValuePair (“client_secret”, your client secret));

HttpPost post = new HttpPost(https://login.microsoftonline.com/common/oauth2/v2.0/token);
HttpEntity postParams = new UrlEncodedFormEntity(pairs);
post.setHeader(“Content-Type”,”application/x-www-form-urlencoded”);
post.setEntity(postParams);

This post request will again redirect the application to the redirect uri mentioned and this time the response content will contain the access token and the refresh token.
The access tokens for different APIs have a different expiration time and for Microsoft APIs, they are mostly valid for an hour. To avoid the pain of logging in again and again refresh tokens can be used to keep retrieving fresh access tokens. The refresh tokens look similar to the authorization code and the post request for an access token using refresh token are the same except that grant-type is needed to be set to refresh-token and in place of authorization code the refresh token should be mentioned.

Once the access token is received, the authentication procedure is complete and these tokens can be used to access the endpoint APIs. The tokens can be saved to a file or a variable for the required function.
Requests to different APIs can vary widely, however, it is of utmost importance that the request header contains: -authorization = Bearer your-access-token, to perform the necessary actions.
( eg: post.setHeader(“authorization” ,”Bearer “+access-token);).

Key Points: –

• 1. Registration of application.
  2. Get a request to authorization API to receive authorization code.
  3. Post request to access token API to receive access token and refresh token.
  4. Post or get (depending on requirement) to the endpoint API using the access token received.