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
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.
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.
It supports registering application 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.
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 >”
If you are not already logged in and you click on “Register your app >” link, then portal will first redirect you to login page:
If you enter your Office 365 developer account, then you will be shown a screen like below to enter 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, then it will show you any existing application registration in current login id:
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:
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 the message displayed below application name header “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 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:
“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 popup:
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:
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, Portal will show you 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.
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:
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 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:
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 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