Register Your Application To Work With Office 365 – Part One

In this article, I will explain how you can register your application to work with Office 365 using Microsoft App Registration Portal. This is first part of the two-part series; you can continue to read the other 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's users need to be authenticated in Microsoft Identity Stack first, before your application can fetch the data using 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 register your application so that it can work with MS Identity Stack and you can get an access token to get data from Microsoft APIs.

Here you can:

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

Why should you know about Microsoft Application Registration portal?

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

By supporting sign in with Microsoft identity stack, your application can have a 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 a 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 regain the App Secret.

Cross-platform support

It supports registering applications for iOS, Android, web, and more.

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 will you 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 on C# Corner here, in which I have explained 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 on “Register your app >”.

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

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

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.

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, it will show you any existing application registration in current login id.

Application name and its GUID app id are masked in the above screenshot by me for security purposes. You can also see “Add an app” button at the top right of this screen. Click on that button and you will see a pop-up to register new application.

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

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 that the message displayed in the below application's name header  is “CsharpCorner Registration”:

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.

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

You can add a logo for your application and URLs of your application homepage, ToS, Privacy, etc.

Still further down the page, there are some other advanced options, along with Save and Cancel buttons.

“Application Secrets” section

Scroll to the “Application Secrets” section.

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 pop-up.

Note - 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 the portal shows you the masked password.

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.

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, the Portal will show you the message to save it.

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.

Double click on it to import; a "Certificate Import Wizard" will be shown to you.

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.

You will see the “Add Platform” popup.

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

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

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

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

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

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

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

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

You can delete these two platforms if you have added for testing; because of this 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.

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

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.

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 applications in an alternate way, how to see registered applications in MS Azure Portal, and for a quick demo, check part 2 of this article here.