Seamless Integration: Mastering App Registration in Microsoft Entra
When I began developing software, authentication and authorisation were a pain—creating authentication forms, managing users and credentials, and managing roles and permissions manually. It sucks, plain and simple.
Around 2006/2007 OAuth and Open ID were born, first OAuth, and then evolution to Open ID. They gave birth to a new world of authentication and authorization, leading the market to many Identity Providers (Google, Facebook, Twitter, Github, Okta, Auth0, Microsoft, etc).
Nearly two decades since its inception, OAuth2 (with OpenID) has become the gold standard in the software development industry for securing applications. However, many professionals across software development, system administration, and cloud management are still mastering the configuration, integration, and recognition of OAuth flows and benefits.
In this article, I’ll guide you through the steps to configure Microsoft Entra, enabling seamless integration with your application.
Prerequisites
Since we are configuring Microsoft Entra, we will need a Microsoft Entra instance. You might be thinking, ‘Nuno, I’m not an organization, and I don’t want to pay Microsoft just to learn it.’
I understand your concern, and I have good news for you: You can get a Microsoft Entra instance for free, and you don’t need to be an organization. As long as you follow the rules, you won’t pay a cent.
How?
By joining the “Microsoft 365 Developer Program” you gain access to a Microsoft 365 E5 developer subscription, and with this subscription, you have a sandbox and, if you would like, 25 dummy users for testing purposes.
I recommend checking out the documentation and joining the program. I’ll write another article about this program in the future.
Authorization Code Flow with PKCE
In today’s world, modern applications like Single Page Applications (SPA) calling APIs or using Swagger are becoming the norm. From my experience, the best way to secure these applications is by using the ‘Authorization Code Flow with Proof Key for Code Exchange (PKCE).’ The great news is that Microsoft Entra supports this flow out of the box, providing a secure and seamless integration for your applications. It’s a game-changer for developers looking to enhance their app’s security effortlessly.
You can learn more from the flow in this Microsoft document.
App Registration
For our application to be able to authenticate users with Microsoft accounts, we need to integrate with Microsoft Entra and to integrate with Microsoft Entra, we need to register an “application” and configure it.
Think of application registration in Microsoft Entra as giving your app a unique identity within the Microsoft ecosystem. When you register an application, you’re essentially telling Microsoft Entra, ‘Hey, this is my app, and I want it to securely interact with your services.’ This process involves setting up essential details like the app’s name, redirect URIs, and permissions. It’s like creating a passport for your app, allowing it to authenticate users and access resources securely. From my experience, this step is crucial for ensuring your app can leverage Microsoft Entra’s robust security features seamlessly.
Register a new application.
We can enter the Microsoft Entra homepage, by accessing and logging in to their URL: https://entra.microsoft.com/.
Once we are logged in, we are ready to make some magic. 🪄
On the left toolbar, we have an “Applications” option. This is our starting point. Expand the option, and the client in “App Registrations”.
Now that we are at the “App Registrations” landpage we can create a new identity for our application.
There are several approaches to application registration. From my experience, the best approach is:
From my experience, having two Microsoft Entra instances — one for production with all the organization users and another for development and testing purposes — is a smart move. By keeping these instances segregated, we can protect our production environment from misleading accesses and ensure better security compliance.
In the ‘Development Instance,’ it’s best to have one, and only one, application registration per application and environment. While this approach might add some complexity to the configuration, it significantly reduces potential security hazards and allows the application development to evolve smoothly. It’s a small price to pay for the peace of mind and security it brings.
For demo purposes, I’ll focus on configuring a demo application. I’ll cover this in detail in another article in the future.
When we are registering a new application, there are three fields to be fulfilled.
The “Name” is the identification for our application, should be unique within the tenant, and should be clear to avoid any doubt. The “Supported account types” will impact how you develop the application, especially if you are using the Microsoft Authentication Library. For now, I will choose the option “Accounts in this organizational directory only” (it will fit the needs of system admins and developers within organizations). And the last field is “Redirect URI (optional)”.
The “Redirect URI (optional)” is optional if you are creating a “Service Principal”, but required if you are using it to integrate Microsoft Entra with an application. I selected a “Single-page application (SPA)” and added the return URL for the REACT application localhost development.
Click Register and you just created your first app registration. Easy, right?!
Yeah, it is easy but it isn’t quite over yet.
App Registration Overview
When integrating Microsoft Entra with our application, most of the information needed is in the “Overview” panel, under the “Essentials” section”.
In this section we gather the “Application (client) ID”, “Directory (tenant) ID”, and the “Redirect URIs”. These are the minimum information that you need to integrate with your demo application. However, we are not building demo applications. We are building great applications. :)
Let us continue then.
Authentication Panel
This is the panel where we may change our redirect uri or even add more. If you notice, under “Grant types” you may read:
This is great, and allows us to be more creative and security demanding with our application, and also allows us to have single sign-on with other organization apps with the same login.
Every application has its domain of functionality and purpose, however, if you need more information from the logged user you will need to add more information.
So we will check these options:
The Access tokens are used to grant access to protected resources, such as APIs. When a client application receives an access token, it can use this token to authenticate API requests on behalf of the user. The ID tokens are used to authenticate users and provide information about the user, such as their identity and attributes.
The remaining options we can leave it as they are.
Certificates & secrets
Since we are using ‘Authorization Code Flow with Proof Key for Code Exchange (PKCE)’ we don’t need to create a secret, and our application doesn’t need any certificate. However, with other OAuth flows, or application purposes, you may need to configure some secrets or certificates. While creating them, read carefully the dialogs, since once set you can not read back the secrets.
Token configuration
This panel is where we can add more claims to the user token. These claims can be chosen from a list of available fields. You may add the ones that fit your purpose, however, I recommend you to keep it simple and add the claims that you need for the application.
App roles
Every application has more than one user type. We have the regular user, with limited permission, and we have an admin user, with all the permission in the app. We could manage them in the application, but it would require that we manage users also, and that is what we are presenting. The purpose of an Identity Server is to manage the identities of the users and applications.
In this section, we should create (at least) two roles: app_user, and app_admin.
For our application, we should select the more appropriate member type. For the demo purposes, I’m selecting both. This means that I may add the role to the application, and also to users and groups.
Although I gave simple names, in an organizational scope we should give more meaningful names and follow some naming conventions like “[application name]_[application_role]”, so it will become easier when adding roles to users or groups.
Expose an API
Exposing an API is used to define and manage how your web API is accessed by client applications. Here we can define the scope of the application, and how the information may be displayed.
We are going to start adding an “Application ID URI”, which will be our identifier. Just click on “Add” and accept the suggestion.
When adding scopes, we are defining the scopes of the applications that integrate our app registry. Since we add roles for applications, we may not do anything else, however, we can add some custom scopes for the application, for specific purposes. For demo purposes, we add two scopes with the same naming as the roles.
API permissions
Here is where the magic is done.😉 .
By default the Microsoft Graph “User.Read” permission is set, and allows the client application to get some information from the user, like name or email. Different Graph scopes give access to other information. You should always use the minimum information needed for the application.
We are going to add the two permissions created in the previous step.
Click on “Add a permission”, select “APIs my organization uses”, and search for your app registration name. Then click on the permissions that you like and done.
By now, we have an app registration with roles, the application has permissions and if we configure our app, everything will go fine.
But we are not finished… just yet.
Manifest
Depending on the “age” of your tenant, you may need to edit your app registration manifest. Why?
Microsoft Entra app registration in 2024 uses version 2 of the manifest. And when you have a recent tenant you are using version 2 by default. However, many organizations are still using the previous version and don’t have any plans to migrate. So if you are using the Microsoft identity framework libraries you will make the calls for version 2, while the Microsoft Entra will reply with version 1 by default. And most likely get an error message stating that your token has invalid claims.
To fix this, you need to go to your manifest, and select “AAD Graph App Manifest (Deprecating Soon)”.
In the manifest, search for the key “accessTokenAcceptedVersion” (should be on line 4) and put the number 2.
With this change, the token that you’ll receive will be valid.
Add Roles to Users/Groups
The last mile of the journey has been long but our goal is near.
Until now we made the configurations of our app, in “App Registration”, and as far as the “App Registration” our work is done. However …
However, our application has roles and if we do not do any more configurations, we are not able to take full benefit of the Microsoft Entra and our application. Let us walk this last mile together.
Another section on the Microsoft Entra admin site is “Enterprise application”, which is located in the menu on your left.
Once you enter this section, choose your application from the list.
The application roles earlier can be applied either to users or to groups (and applications, but that is beside the point). The best practice is to add roles to existing groups, or even create a new group and add roles to them.
The reason is only because it is easier to maintain, either the users that can access the application, or Microsoft Entra users and groups permissions. For demo purposes, that doesn’t make any difference, but when you are in an organization with 300 employees, soon you find ways to keep effort very low. 😉
With full disclosure, my Microsoft Entra plan doesn’t allow group assignments. I am only able to demonstrate the add roles to users, but the screens and options are the same for groups.
From the menu on the left choose “Users and groups” and from the list choose “Add user/group”.
On the next screen choose the user/group or users/groups that you want to add the role, and choose the role. Luckily we can select multiple users to give one role. On the other hand, we can only add one role at a time.
So we have to do it twice. At the end, the list should be similar to this:
That is it. We are, finally, done.
The next step is to develop our application integrate Microsoft Entra with MSAL SDK Libraries, and configure with the “Overview”, “Roles”, and “Scopes” values that we covered earlier.
Conclusion
Mastering app registration in Microsoft Entra might seem daunting at first, but with the right guidance and a bit of practice, it becomes a straightforward process. By leveraging the power of OAuth2 and OpenID, you can ensure your applications are secure and user-friendly. Remember, the key to success lies in understanding the flow and configuration details, and always keeping security at the forefront of your development process.
So, dive in, experiment, and don’t be afraid to make mistakes. Each step you take brings you closer to seamless integration and a more secure application environment. Happy coding!
