A First Look At The New Microsoft Graph Explorer – Part Three

Note: All my blogs on Microsoft Graph API can be found here.

In first two parts of my article series “A First Look at the New Microsoft Graph Explorer”, I explained about different components of Microsoft Graph Explorer. I suggest you to read those two parts first, before reading this third part for better understanding.

You can read the previous parts here:

I will continue the article series with part three where I will explain how to execute the calls to Microsoft Graph API.

The objectives of this article are:

  • Execute some Graph API GET calls using sample account
  • Look at Microsoft Graph API metadata
  • Calling beta API

Execute Graph API GET calls using sample account

Let’s look at some simple GET calls to Microsoft Graph API using the Graph Explorer.

Open the Microsoft Graph Explorer by clicking here.

Check the left section under “Authentication”.

Office Development

It says currently a sample account provided by Microsoft with some test data is being used. You can fire GET calls using this account right away.

If you see the API endpoint address bar you will notice,

Office Development

API endpoint for getting user’s profile is already loaded.

Simply click on “Run Query” button to execute the API call.

Office Development

You will see that the response area of the page is updated with something, like below.

Office Development

The status in the green background indicates that the call was successful with HTTP status code of 200 and executed in 869 mill seconds.

Look at the JSON data in “Response Preview” section.

It has some data of “user” which is the current user provided by Microsoft sample account. If you are logged in with your account, then you will see your data. I will cover the calls after login with your account later.

There is also something more.

Microsoft Graph API metadata

You might be wondering how to find out what data to expect in an API GET call response or what data to pass in an API call POST request. You can read the Graph API documentation or look at the sample queries on left side section, but there is also another way.

Look at the first line of the JSON response,

Office Development

You will see a URL for “@odata.context” property.

Copy the URL and paste in a new tab.

Office Development

You will see it loads an XML file. A big XML file. That’s the OData documentation of the Microsoft Graph API. Microsoft Graph API metadata in other words.

It specifies the different entities and actions along with properties and parameters.

Search for the following in the page- EntityType Name=”user”.

Office Development

You will find the user entity along with its properties and navigation properties. You will also find some more entities, more actions, functions. You can also see the Graph API metadata page directly here,

The following lines are taken from the Microsoft Graph website as it is:

“The metadata allows you to see and understand the Microsoft Graph data model, including the entity types, complex types, and Enums that make up the resources represented in the request and response packets.

You can use the metadata to understand the relationships between entities in Microsoft Graph and establish URLs that navigate between those entities.

Path URL resource names, query parameters, and action parameters and values are not case sensitive. However, values you assign, entity IDs, and other base64-encoded values are case sensitive.”

For the scope of this article, I will not go deeper inside this XML file and will leave it to you to explore more.

Back to the Graph Explorer

If you place your mouse cursor in the API address bar and press back space key and remove everything till “v1.0/” you will see the Graph Explorer will hint you possible API endpoints you can fire,

Office Development

Similarly, if you start typing “me/” then it will show you possible endpoints after “me”

Office Development

Now, type https://graph.microsoft.com/v1.0/organization in the address bar and press “Run Query” button, you will see the logged in user’s organization info,

Office Development

Please note that in Microsoft Graph API “me” and “organization” are the only two aliases in Microsoft Graph API i.e. these two are not the actual objects in Office 365.

If you want to test more GET calls, then you can see list of some GET calls in left section under “Sample Queries”.

Office Development

More GET calls featured scenarios can be found here on Microsoft Graph website,

Office Development

Calling API in preview

Now, let’s see how to call some Graph API endpoints which are still in preview i.e. in beta.

Change the API version to “Beta” in the version lookup,

Office Development

Copy and paste https://graph.microsoft.com/beta/me/insights/trending in the API endpoint address bar and press “Run Query” button,

Office Development

You will see the names of some documents are returned with their “weight”. These are the “trending” documents around the user and you need to write some code to convert the “weight” of each document to some meaningful representation to end user.

But the purpose of making this call is to make you understand how to fire a beta API call in Microsoft Graph Explorer.

Now change the API version to V1.0, keep the API endpoint URL same and fire the call,

Office Development

You will see it returns an error, because this endpoint is only in beta version and not yet in V1.0.

I hope you will play with Microsoft Graph Explorer and fire some more GET calls until I write the next article and we continue the journey of learning with the new Microsoft Graph Explorer.

Note: This article was first published by me on C# Corner website here.

Header image courtesy: Microsoft

A First Look At The New Microsoft Graph Explorer – Part Two

Note: All my blogs on Microsoft Graph API can be found here.

Part-1 of the my series “A first look at the new Microsoft Graph Explorer” can be accessed here. If you have not read it yet, I suggest you read it first to maintain continuity of your reading.

I will continue from where I left off in the last article. We will see the remaining sections of the Microsoft Graph Explorer in some detail.

The objective of this article is to cover the following topics, among others:

  • History section
  • Request & Response sections
  • Share Query section

For a quick note; you can see Microsoft Graph Explorer here.

The “History” section

Office Development

Scroll down on the left section to see the History section.

You can collapse “Sample Queries” section if it has some sample queries in it, to see the History section quickly.

Office Development

If the “History” section is already collapsed, expand it.

Office Development

Upon expanding, or if it is already expanded, you will see it like below.

Office Development

If you haven’t executed any Graph API at all, then the section will be empty.

Office Development

The “History” section maintains the history of the Graph API calls you executed and by clicking on the links in this section, you can easily re-play those calls. A fresh request will be made to the Graph API when you click on a link from history.

Note that the “History” section maintains only the history of the request, and not the response. This means, the request will be fired again and you will always see the latest response from Graph API. There is no way to see what the response was originally when you fired that query  the first time.

As you make the Graph API calls, the browser URL does not change, so to get back to any of your previous calls, you can use this “History” section.

Let’s see now what’s there for each row in the “History” section.

Office Development

  • “GET” and “PATCH” indicates the request type
  • The “/v1.0/me/” indicates the API endpoint. It is equivalent of the full endpoint https://graph.microsoft.com/v1.0/me/, but for brevity it is displayed like this.
  • “200”, “204”, “400” are the HTTP response codes of the API call indicating what happened at that time
  • “3 minutes ago” displays the time at which that call was made
  • “146 ms” is the time taken by the Graph Explorer to execute the request.

The “History” section data is stored in cookies in your local machine and it is browser specific.

If you were working on Internet Explorer and if you open Firefox or vice versa, then you will not see the same history. This is true even if you are logged in using your Microsoft account.

Do you want to see more history? Click on the “show more” link at the bottom right of the history section.

Office Development

Office Development

Once you click on the “show more” link, Graph Explorer will open “History” popup.

Office Development

The contents of the popup are self-explanatory. You can either remove individual entry by taking the mouse over to a row and clicking “x” button at the end of the row, or remove all entries by clicking “Remove All” button.

If you click on any row, then the popup will close and the API call will be fired again.

“Request Header” and “Request Body” section

Along with the API endpoint and passing parameters in query string, sometimes you will also need to pass more data to the Graph API.

It is possible to pass additional data to MS Graph API thru the “Request Headers” and “Request Body” sections which can be found just below the API address bar,

Office Development

“Request Header” section

The HTTP request headers can be specified in the “Request Headers” area in form of key-value pairs. If you see by default there will be one textbox for the “Key” entry, on value side there is no textbox,

Office Development

The textbox on the “Value” side will appear once you start typing something in the “Key” textbox.

Let’s write “Accept” in the “Key” textbox,

Office Development

Immediately you will see there will be a textbox beneath the “Value” header, and a new row for “Key” textbox will be added as well.

Note that you must “type” something in the “Key” textbox for the “Value” textbox to be visible. If you copy and paste something inside the textbox, then the “Value” textbox will not appear.

How to pass some value in request header, how to execute the call and how to interpret the result will be covered later.

“Request Body” section

Let’s now see the “Request Body” section.

Click on the “Request Body” link just besides “Request Header” link.

Office Development

You will see a text area in which you can enter free-form text,

Office Development

“GET” requests will not have a request body, but to show you a demo I have copied one JSON result body and pasted it in the request body text area,

Office Development

You see it has little bit of “intellisense” too! It identifies the matching starting “{“ bracket when your cursor moves to the ending “}” bracket.

You can fire any “GET” call with anything in the request body, Graph API will just ignore it,

Office Development

How to pass some value in request body, how to execute the call, and how to interpret the result will be covered later.

“Response” sections

The response section is just below the requests section and it shows you the response you get back from the Microsoft Graph API call.

There are three sections here: “Response Message”, “Response Preview” and “Response Headers”,

Office Development

“Response Message” section is visible only after you fire an API call.

“Response Preview” and “Response Headers” both are read-only text areas because you are not supposed to write anything inside it.

For the demo, just click on “my profile” link in the “Getting Started” section inside “Sample Queries” on left side,

Office Development

Immediately you will see the API call result in the results section,

Office Development

“Response Message” section

The “Response Message” section is highlighted above.

It indicates,

Office Development

  • Success: the API call executed without any errors
  • Status Code 200: HTTP response code
    • For the understanding of HTTP status codes, click here.
  • 139ms: request execution time taken by Graph Explorer

In case of some failure, it will be like,

Office Development

“Response Preview” section

Office Development

It shows the Graph API call’s result body in JSON format.

“Response Headers” section

Click on the “Response Headers” section to see the HTTP response headers values,

Office Development

You will see here values for content-Type, request-id, duration, etc. among others. The response header values prove very handy sometimes in debugging API call errors.

Which API versions are supported in Microsoft Graph Explorer?

As of now, Microsoft Graph APIs are only in two versions: V1.0 for general availability, and “beta” for preview. Microsoft Graph Explorer supports both these versions.

You can see the supported API versions in Microsoft Graph Explorer when you expand the “API Version” selection as shown below,

Office Development

When to change the version and how to execute the API calls is covered later.

Which HTTP request types/verbs/actions are supported in Microsoft Graph Explorer?

Microsoft Graph Explorer supports the following HTTP actions/HTTP verbs as shown below. Remember you must be logged in for the dropdown to be enabled,

Office Development

“PUT” has been added now which did not exist in earlier version of MS Graph Explorer.

When to change the request type and how to execute the API calls is covered later.

“Run Query” button

Office Development

This one is obvious, but I thought my article would not be complete without mentioning each part of the MS Graph Explorer!

You press it to execute the call to the Graph API. If the API endpoint is not specified or some garbage value is entered, then it will simply ignore and will not execute anything. Cool!

“Share Query” link

Office Development

It’s the little link on the right side on top of response text area.

Office Development

Using this link, you can share your queries with others. It will allow others to execute the same query as you did in the MS Graph Explorer.

For the demo, click on the “my mail” link on left side,

Office Development

The API endpoint will be changed to https://graph.microsoft.com/v1.0/me/messages and the result will be shown to you.

Now click on the “Share Query” link,

Office Development

You will see the following pop-up,

Office Development

The textbox has following link inside it:

https://developer.microsoft.com/en-us/graph/graph-explorer?request=me/messages&method=GET&version=v1.0

It is formatted such that the link can be fired from any browser and the API call will be setup.

To test it, copy the link and click on “Close” to close the dialog.

Open another browser and paste the link in its address bar and press Enter,

Office Development

You will see that the API endpoint, HTTP request type and API version are set. You must press the “Run Query” button to execute the call.

What’s next

I will cover execution of some queries with sample account and Office 365 developer account in the next article.

Moreover, after reading this introduction to Microsoft Graph Explorer, I think you might be interested to know more about Microsoft Graph API.

Wait for my next article in this series, until it is published you can:

  • Read my article on Office365 developer program here.
  • Create an Office365 developer account here.
  • Learn more about Microsoft Graph API here.
  • Try Microsoft Graph Explorer here.
  • Learn more about Office 365 development here.

Note: This article was originally published by me on C# Corner website here.

Header image courtesy: Microsoft

A First Look At The New Microsoft Graph Explorer – Part One

Note: All my blogs on Microsoft Graph API can be found here.

Recently, Microsoft has launched the new and updated version of Microsoft Graph Explorer. The concept behind the Microsoft Graph API and the Microsoft Graph Explorer remain the same, but this launch is an effort by the Microsoft Graph team to make developer experience more engaging and to add more functionality to Microsoft Graph Explorer.

I have already written an article on the previous version of Microsoft Graph Explorer here while it was in effect. But with the launch of a new version with new UI, things have changed in Microsoft Graph Explorer. So, I wanted to write an article on it which will guide you through the new version. This article is part 1 of the multipart series I plan to write on the new Microsoft Graph Explorer.

Please note that this article is written in a way that it can be read as an independent article without the need to look at my earlier article.

Remember, there is no way to access the old version of Microsoft Graph Explorer. It has been totally replaced by the current version. My first impression is that you are going to like it much more than the old version.

Before we start with what’s new in Microsoft Graph Explorer, let’s first get a quick introduction of Microsoft Graph.

Microsoft Graph

The official Microsoft documentation defines Microsoft Graph as,

“Microsoft Graph exposes multiple APIs from Office 365 and other Microsoft cloud services through a single endpoint: https://graph.microsoft.com. Microsoft Graph simplifies queries that would otherwise be more complex.”

So, in a nutshell, Microsoft Graph gives you a single REST API endpoint which you can call to interact with “almost anything” in Office365. It delegates calls to different Office 365 cloud services via one single endpoint.

Now, let’s learn about Microsoft Graph Explorer.

Microsoft Graph Explorer

Microsoft Graph Explorer is a fantastic tool if you want to work with Microsoft Graph APIs or if you are learning to develop with Graph APIs. Consider it as a developer sandbox or a playground where a developer can have first-hand experience of Microsoft Graph APIs.

Where can you access Microsoft Graph Explorer?

It can be accessed here – https://developer.microsoft.com/en-us/graph/graph-explorer

Microsoft Graph Explorer

What do you need in order to work with Microsoft Graph Explorer?

Microsoft Graph Explorer provides you default login – a sample account with which you can fire some GET calls using Microsoft Graph APIs.

But if you want to explore more and also want to fire POST, PATCH and DELETE calls to Microsoft Graph API, then you will need to login with Microsoft credentials. I will suggest you get an Office 365 developer account.

Warning

A word of caution here; never play with your live Office 365 data or work account here with Microsoft Graph APIs. You may accidentally update or delete some important information. It is advisable to use a test/demo account.

If you join the Microsoft Office 365 developer program here, Microsoft will give you one year free Office 365 developer subscription for non-commercial use with 5 users. You can read more on it in my related article “Office 365 developer program” here.

What can you do with Microsoft Graph Explorer?

A lot!

Microsoft Graph Explorer gives you a test client to access whatever you can access with Microsoft Graph REST APIs.

Using Microsoft Graph Explorer, you can:

  • Access/Modify data from Office 365 and other cloud services like SharePoint online, OneDrive, etc.
  • Navigate different Office 365 entities and traverse the relationships amongst them
  • Get intelligence and insights from the Microsoft cloud (limited to commercial users only)

In short, with Microsoft Graph Explorer is a one stop shop for everything you want to play with in Graph APIs.

Why should you use Microsoft Graph Explorer?

Microsoft Graph Explorer is a great tool to test how Microsoft Graph APIs work. A developer can use Microsoft Graph Explorer to:

  • Test Graph API calling logic beforehand dealing with any endpoint
  • See what data Graph API gives you back
  • See how the POST, PATCH and DELETE calls work
  • See how an entity in Office 365 can be accessed, using which relationship path

A first look at the new Microsoft Graph Explorer

Microsoft Graph Explorer

The screen shot of the new Microsoft Graph Explorer with some annotations above is mostly self-explanatory.

Some sections are covered in more detail below. I will also cover sections on left side in black background which were not mentioned in above screen shot due to space crunch:

The “Authentication” section

Microsoft Graph Explorer

By default, it launches API calls with the in-built sample account which you can use it to get some data without login in. You can sign-in to your account using the sign in button,

Microsoft Graph Explorer

Please note one thing here. If you go to the “Request Type” drop-down, you will see,

Microsoft Graph Explorer

You are not allowed to change the request type if you are not logged in with your Microsoft account. This is because someone can fire update/delete calls to Microsoft Graph API and change the data in Microsoft sample account. So, for the sanity anything except a “GET” is disabled till your login.

Once your login with your Microsoft credentials is done, then you can fire more queries apart from “GET” request type.

There is one more use of this sample account I have found. It has bulk data for messages and other items. Your newly created Office 365 developer account may not have that much data until you do the laborious task of creating it into your account. So when you want to test paging, delta queries, etc. this sample account comes into help.

The “Sample Queries” section

Microsoft Graph Explorer

In the left side section, just below authentication you will see the “Sample Queries” section,

Microsoft Graph Explorer

Here you will find some frequently used API calls labelled under “Getting Started”.

The purpose of the sample queries section is to provide developers a ready-made API call which can be immediately executed in the Microsoft Graph Explorer without the need for the developer to go and find the API URL and input parameters in documentation.

You can directly click on any link in the “Sample Queries” section and that call will be fired immediately against the Graph API and result will be shown to you.

For example, let’s click on “my photo” link in the Sample Queries” section, you will see on the right-side section, the API call for getting user’s photo is executed and you are shown the result:

Microsoft Graph Explorer

The Graph Explorer automatically changes the API endpoint to https://graph.microsoft.com/v1.0/me/photo/$value, fires the query and shows you user’s photo.

Note the 3 different columns in the “Sample Queries” section for each row

  • Request Type
  • Brief name of API call
  • Link to documentation

Microsoft Graph Explorer

The first column
indicates the type of API call, which is “GET” here.

The second column indicates a brief name for the API call.

e.g. if you move the cursor over the “my profile” text you will see the tooltip,

Microsoft Graph Explorer

The tooltip/hint here indicates the actual API endpoint “https://graph.microsoft.com/v1.0/me“ which will be used in the call and which will be seen later in the API address bar once the call is fired,

Microsoft Graph Explorer

The third column is the link to the relevant Graph API documentation section. If you move mouse over to it, you will see tooltip for documentation,

Microsoft Graph Explorer

If you click on that link, the documentation will load in the new tab,

Microsoft Graph Explorer

Do you want to see some more sample queries?

Click on the “show more samples” link at the bottom of “Sample Queries” section,

Microsoft Graph Explorer

Microsoft Graph Explorer

A “Sample Categories” popup will open with some category/group names and options for each to make the selection ON or OFF,

Microsoft Graph Explorer

Notice that you were already seeing the “Getting Started” section, and here the section’s selection is “On”,

Microsoft Graph Explorer

The (6) at the end of “Getting Started” indicates there are 6 queries/endpoints in this section. This can be verified if you close the pop-up and once again go back to “Sample Queries” section,

Microsoft Graph Explorer

Now back to the “Sample Categories” popup. Let’s now select some more categories and see what happens. I have selected three more categories – Users, Outlook mail and OneDrive,

Microsoft Graph Explorer

Click on the “X” button on top right section to close the pop-up. See the “Sample Categories” section, you will have the selected categories in it,

Microsoft Graph Explorer

You can click on any call to get it fired and see result in Microsoft Graph Explorer.

Notice one thing here that if you are not yet logged in and using the sample account, then you cannot fire the “POST” calls,

Microsoft Graph Explorer

Once again click the “show more samples” link, and make all categories selection “off” and close the pop-up,

Microsoft Graph Explorer

You will see now there are no more  sample queries,

Microsoft Graph Explorer

This flow is just to show you how you can make category selection “on” or “off”. I will suggest you to check all the categories and all its queries once at least.

That’s it for part 1. I will cover more in part 2 of this series.

See you in the next article. Until then – Happy Learning!

Note: This article was first published by me on C# Corner website on May 09 2017 here.

Header image courtesy: Microsoft

Register your application to work with Office 365 – Part 2

Learn how to register your application to work with Office 365

In this article, I will continue from where we left in part-1 to register an application to work with Office 365 using the Microsoft App Registration Portal.

This is part-2 of the two-part series, I suggest to read the part-1 here first before continuing.

The objectives of this article are:

  • Alternate way to register your application
  • How to run sample code
  • Access your registered application from MS Azure Portal
  • Application flow

Alternate Way to register:

You can also register application from the “Quick Start” page which is shown immediately after your login to App Registration Portal https://apps.dev.microsoft.com/portal/quickstart:

Quick Start.png

Click on the “Web” link, you will be shown following:

“Web” link.png

Enter the application name and your contact email, then click on “Create”. I entered “CSCorner” in the application name:

Create.png

You will be shown a success message and asked for redirect URL:

redirect URL3.png

For a quick demo, enter the same URL we entered above http://localhost:57329/AfterLoginPage and click “Save”.

How to run sample code:

After clicking “Save” button in above section, you will be shown a sample code section:

sample code section.png

You can see that your application’s ID and redirect URL are already there. This is a simple HTML and JavaScript code which you can quickly integrate into your application to redirect users to Microsoft for login.

Copy the script to any HTML page header section or create a new page in sample ASP.Net web application we created above.

Scroll down on the portal registration page, you will see code for HTML button:

HTML button.png

Copy this code to body section of new HTML page you created. Save and run the page in browser.

If you create a new ASP.Net web form, then mark to page as startup page and run your web application.

In both the cases, it is necessary that the http://localhost:57329 site is running so that Microsoft can redirect your application to that page.

Both the before login page and after login page of sample web application are attached with this article. You need to add them to your sample application to test demo. Don’t forget to change “clientId” and “redirectUri” values in your page:

sample application.png

Run the application or browse the HTML page you created:

Run the application.png

Click on the Sign in button. You will be shown a login page from Microsoft:

login page from Microsoft.png

Enter your Microsoft login and password, click on “Sign in”.

You may be shown a page like shown below asking for your permission to give grant to application if you are logging in for the first time. Please note this is not the actual screen shot of my application, I have taken it as reference from Microsoft site:

permission.png

Image source: Microsoft

You will be redirected to the page mentioned in “Redirect URL” setting:

redirect.png

Congratulations! You have implemented the authentication with MS Identity stack. Remember you must write code for fetching data from MS Graph API or any other Office 365 APIs. This article covers only registering your application with MS App Registration Portal and demo of logging in using Microsoft credentials.

Access your registered apps from MS Azure Portal:

The applications you registered here are also accessible from MS Azure Portal.

To do so, login to MS Azure portal https://portal.azure.com with the same login you used to register your app on MS App Registration Portal.

Once you are logged in, find and click on the link “Azure Active Directory” Azure Active Directory in left pane:

Azure Active Directory2.png

One more menu will open, find and click on the link “App registrations”App registrations:

App registrations2.png

Alternatively, without clicking on that link, Azure portal will show you the registered apps on the dashboard:

dashboard.png

Either click on the “App Registrations” menu on left or click on the “App Registrations” web part in dashboard.

You will be shown following screen:

App Registrations3.png

You will not see your registered app directly here, Click on the “Microsoft Application Console” link.

Azure portal will redirect you to a login page, once your login is successful, you will be redirected to “My Applications” page of MS Application Registration Portal:

Microsoft Application Console.png

Application flow:

If you really want to develop an application and fetch some data from Office 365, you will need to do much more than just register an application in the portal.

Here is the complete application flow for your reference, you can follow it step by step to develop an application which will access data from MS Graph API or Office 365 APIs:

  • Register the application on Microsoft App Registration Portal: https://apps.dev.microsoft.com
  • Configure the project with ID & key or copy and paste the sample code from portal quick start
  • Authenticate the user and get an access token
  • Call Microsoft Graph API / Office 365 API(s) / Other MS Cloud API
  • Parse the result, show the result to application user

I will cover these steps in detail in a future article, until then – Happy learning!

 

Header Image Credit: C# Corner

Register your application to work with Office 365 – Part 1

Register your application to work with Office 365 using the Microsoft Application Registration Portal.

In this article, I will explain how you can register your application to work with Office 365 using the Microsoft App Registration Portal.

This is part-1 of the two-part series, you can continue to read another part here.

These are the objectives of the article:

  • What is Microsoft Application Registration portal?
  • Why you should know about it?
  • Overview of components in Microsoft Application Registration portal

 Background:

If you are developing an application which is going to work with Microsoft Office 365, like fetching data using MS Graph API or any other Office 365 API, then you will need to register your application with Microsoft first.

Your application users need to be authenticated in Microsoft identity stack first before your application can fetch data using the MS Graph API or any other Office 365 API on their behalf.

 What is Microsoft Application Registration portal?

MS Application Registration Portal is the website where you can go and register your application so that it can work with MS Identity stack and you can get access token to get data from Microsoft APIs.

Here you can:

  • Register new applications
  • Modify existing application for – access permissions, redirection URL, etc.
  • Generate keys
  • Set up application profile

 Why you should know about Microsoft Application Registration portal?

Apart from the purpose stated above, if you want to eliminate managing user name and passwords in your application on your own and let users log in with Microsoft work or school or personal account, then you can delegate the work of authentication to Microsoft. Users can login to your application using Microsoft Identity stack.

By supporting sign in with Microsoft identity stack, your application can have single sign on with Windows and Microsoft cloud applications, can protect your users with the same technology and investments used to protect Microsoft’s users, and can programmatically access information and insights about users via the Microsoft Graph API or other Office 365 APIs.

Any application which wants to use the capabilities of MS Identity stack must first be registered in MS App Registration portal. Here you will be able to get an App ID and redirect URL along with secret code which is necessary to make your app work with Office 365.

Important:

At the Application Registration portal, you will generate an App Secret which will be shown to you only once. Please retain that App Secret, as you will need it to run your app. If you forget it, you will need to restart the registration flow again. There is no way to get the App Secret again.

Cross-platform support:

It supports registering application for iOS, Android, web, and more:

cross

Access data from Microsoft APIs

Access user data inside the enterprise — get an Office 365 user’s calendar, mail, and contacts. The registration in MS App Registration Portal satisfies the basic authentication requirement, you must write code specific to the Office 365 or any other Microsoft API.

Wide use

The Microsoft identity stack has been battle tested by some of the biggest companies in the world.

Using MS Identity stack, you can offer one-click sign in to:

  • Around 85% of the Fortune 500 companies’ users
  • Around 85M monthly active users on Office 365 commercial
  • Around 400M Outlook.com monthly active users

What you will need to register?

You can register using your Microsoft work or school or personal account. You can use your MS Office 365 developer account or windows live account to register your app.

If you are developing for Office 365 and you want to create a developer trial account, read my article here in which I have explained in detail how you can get a free Office 365 account for 1 year.

Where you can register your application?

You can visit the MS App Registration portal here, and then click “Register your app >

reg.png

If you are not already logged in and you click on “Register your app >” link, then portal will first redirect you to login page:

log.png

If you enter your Office 365 developer account, then you will be shown a screen like below to enter password:

pw.png

Let’s see different components in MS App Registration Component

Once you have entered your correct password and successfully logged in, you will be shown the following screen:

f1.png

You can see here the options to register an application for iOS, Android or Web.

If you click on the “My Applications” link on top right, then it will show you any existing application registration in current login id:

my apps.png

Application name and its GUID app id are masked in above screen shot by me for security purpose. You can also see “Add an app” button on top right in this screen. Click on that button and you will see a popup to register new application:

register new application.png

Enter the name of your application and click “Create application”. I entered “CSharpCorner” and clicked on the button:

Create application.png

Portal will create an application named “CSharpCorner” for you. I have highlighted the application name. I have also hidden my email id and application id which is unique id for your application. Have a look at different options available in this page. One by one I will cover those below.

Also, note the message displayed below application name header “CsharpCorner Registration”:

CsharpCorner Registration.png

It says that the application “CSharpCorner” will be registered in the MS Azure active directory instance which manages the login account with which you have logged in. What it means is covered later in this article.

For the scope of this article, “Azure Active Directory” is not covered in any more detail but I suggest you read about it on Microsoft Docs here.

On the same page, note that a section for assigning Microsoft Graph permissions:

Microsoft Graph permissions.png

Further down the page, you will see some other profile settings:

profile settings.png

You can add logo for your application, and URLs for your application’s home page, ToS, Privacy, etc.

Still further down the page, there are some other advanced options, along with save and cancel buttons:

advanced options.png

“Application Secrets” section:

Scroll to the “Application Secrets” section.

Application Secrets.png

Click on the “Generate New Password” button to create a password for our application. Portal will generate new password for your application and show in a popup:

Generate New Password.png

Note that the password will be shown to you only once now and there is no way to see this password again. So, it is necessary to store this password somewhere safe so that you can use it in your code later.

You will use this password along with the “application id” of this application to make your users authenticated by Microsoft.

Click “Ok” button and you will see that Portal shows you masked password:

masked password.png

Mostly in programming you will use the application id and password combination to redirect your users to authenticate on Microsoft site. But if you want to create a private key/certificate it can be done here too.

Click on the “Generate New Key Pair” link:

Generate New Key Pair.png

Enter the password and click “Ok”. Remember the password used to create the key, store it somewhere safely. Also, within seconds when the private key is ready, Portal will show you message to save it:

download the file.png

Click on “Save File” and then click “Ok” to download the file.

Once the file is downloaded, you can go to the download location and see the file:

download location.png

Double click on it to import; a certificate import wizard will be shown to you:

certificate import wizard.png

For the scope of this article, the certificate import wizard is not covered. You can explore it on your own.

“Platforms” section:

Now go back to the App Registration Portal, scroll to the “Platforms” section and click on “Add Platform” button:

Platforms

You will see the “Add Platform” popup:

Add Platform.png

 

Web application, Native application and Web API platforms can be added here. Click on “Web”. The following section will be added to the page:

Web application.png

The most important setting here is the “Redirect URL”:

Redirect URL.png

It’s the URL to which the user’s browser will be redirected after Microsoft authenticates the user. It should be a URL of a page in your web application which you want to show once user completes authentication with Microsoft, like a landing page.

For showing you a demo, I have created a sample ASP.Net application on my PC and taken its local URL which I will enter in the “Redirect URL” textbox:

http://localhost:57329/AfterLoginPage

Redirect URL 2.png

Similarly, you can also click on “Add Platform” again and select “Native Application” this time:

Native Application.png

You will see the “Native Application” section will be added to the page:

Native Application2.png

Once again click on “Add Platform” and select “Web API”:

Web API.png

The “Web API” section will be added to page:

Web API2.png

I will not go into details of “Native Application” and “Web API” sections.

You can delete these two platforms if you added for testing, because for demo I will show you only “Web” platform.

“Microsoft Graph Permissions” section:

In this section, the permission to your application when it communicates with MS Graph API is decided.

To understand better, read the following extract from Microsoft Docs:

By defining these types of permissions, the resource has fine-grained control over its data and how the data is exposed. A third-party app can request these permissions from an app user. The app user must approve the permissions before the app can act on the user’s behalf. By chunking the resource’s functionality into smaller permission sets, third-party apps can be built to request only the specific permissions that they need to perform their function. App users can know exactly how an app will use their data, and they can be more confident that the app is not behaving with malicious intent.

By default, there is only one “User.Read” permission which is the simple most read-only permission:

User.Read.png

Click on the “Add” button besides “Delegated Permissions”. You will be shown the “Select Permission” popup:

Select Permission.png

It’s up to you which permission you want to give to your application based on the type of work you are doing in it. Never give unnecessary or all permissions to application as it may result in some user data loss inadvertently. Select only those permissions which you actually need in your application. Let’s say your application will send and receive emails, then select the Mail.Read and Mail.Send permissions.

Click “Ok” and see the permissions are there on the page:

permissions.png

Scroll down to the bottom of the page and click on “Save” to save the changes.

There is also another way to register your application which I will cover in part-2 of the series.

To read how to register application in alternate way, how to see registered applications in MS Azure Portal and for a quick demo, check my part-2 article here.

 

Header Image Credit: C# Corner