End-to-end walkthrough: How to Multi-tenant Application, register it with Azure AD, onboard tenants, go through the admin consent workflow, work with incremental [just-in-time] consent. All the code we write will be in C# and the application is an ASP.NET MVC application.
What is our application going to do?
We will enable two primary things:
- Read and write certain Azure resources and;
- Read and write user and group related information in Azure AD.
This is Step 1 of the series. To navigate to other articles in this series, look at the end of any article in the series for the list.
- A “Microsoft Account”. This is typically your Hotmail (Live, Outlook.com, etc) or Xbox account. If you don’t know, try logging into this website. If it works, then you are okay to continue.
- A valid Azure Subscription. If you don’t have one at this point, you should go here and get one. Even a free trial one is alright.
Note: If you have more than one Microsoft Account (we shall call it “MSA” in short from now on), you should pick one of them and use the same account for your Azure subscription and to perform all the steps below.
- Log on to the Azure Portal.
- On the top search bar, type in “active directory” and select “Azure Active Directory” from the results shown.
- Once the blade has loaded, look on the left-hand side list for “App registrations” and click that.
- Click “+ New registration” on the top menu bar.
- You can change the selections/entries you make on this screen later. But let us not set ourselves for confusion. So, enter the following information.
- Click on the Register button below.
- It will take a couple of seconds for the application to be registered and you will be taken to the Overview screen of your new app.
- Pick up the highlighted values from this screen and paste them into Notepad. Save this file as “multitenant app credentials” on your desktop.
- On the left side, do you see an “Integration assistant (preview)” ?Clicking on that is going to provide you with an evaluation of everything you need to set up in a TODO list. But since this is a Preview, it is going to change and I am not going to go that way for this walkthrough. If you do want to try it out, you should select “Web App” and “Web API”. Also turn on the “Is this application calling APIs?”. You should see the following result:
To make the changes according to the Integration Assistant’s recommendation, click on the “…” next to the recommendation and select “Go to page”:
- To continue with our walkthrough, you should now go to the “Certificates and secrets” page and click on the “+ New client secret” button.
- A popup will appear asking you to type in a Description and select an expiry time. Make whatever selections you want and click Add.
- As soon as the secret is generated, it will be displayed on the screen. IMMEDIATELY copy this into that same Notepad file, call this one “client secret”.
- Let’s switch to the “Token configuration” tab. Later in our walkthrough, we will require to know what User Groups in the Azure AD the logged on user is a member of. To know this, there are several painful ways. The easiest is to ask Azure AD to include it in the list of claims returned. On the Token configuration page, click the “+ Add groups claim” button. A flyout will appear. Make the selections as follows:
- Click the “Add” button at the bottom of the flyout.
- Now head into the “API permissions” page. Here is where things begin to get interesting…
Remember we said at the top of the article that the application would read/write information from the Azure AD and also talk to Azure itself?
- Click the “+ Add a permission” [each time you click this, you can any number of permissions, but target only a single API].
- Click on “Microsoft Graph”
- The list under “Delegated permissions” will be required. We don’t much care for the “Application permissions” at this point — those become relevant only if we want to run our app in the background, which we are not. Click on “Delegated permissions”.
- You MUST select the first four (email, offline_access, openid and profile). Without this set, when the user tries to login, you and the user attempting to log on will see a lot of errors.
- Scroll down to “Directory”, click on it to see a list. Select “Directory.AccessAsUser.All” and “Directory.Read.All”. We will need this in our onboarding workflow.
- Scroll down to Group and select both (“Group.Read.All” and “Group.ReadWrite.All”). We will be creating and managing User Groups in our sample application and need these two to be able to do that.
- Scroll right to the bottom and find “User”. Select everything including and below “User.Read” — “User.Read”, “User.Read.All”, “User.ReadBasic.All”, “User.ReadWrite” and “User.ReadWrite.All”.
- Click “Add permissions” button at the bottom.
Some of these permissions may look as if they overlap and you only need to select the highest permissions. But, we need different permissions [and combinations] at different points in our app. Also, some of those permissions will be used when the Azure AD Administrator is logged in, others when a “lesser” user is logged in.You should never use or demand more permissions than are required for an operation!
- Click “+ Add a permission” again. This time, from the flyout, select “Azure Service Management” — this is to be able to talk to Azure itself via Azure’s APIs.
- This API has exactly one permission (“user_impersonation”). Select it and click “Add permissions”
- At this point, your “API permissions” screen should have the following list of permissions. If you missed one, simply click on the “Add a permission” and make changes. It is alright if you added more permissions than I listed above, but do ensure that you have at least the list that I have.
You may go into the “Branding” page and edit the values there. Make sure that you DO NOT upload a logo, and leave the “Publisher domain” value as default — do not attempt to map it to a verified domain at this point.
Your Notepad file should look as follows:
This step is now complete. You now have a valid registered Azure AD multi-tenant application. The next step will begin with creating the accompanying ASP.NET MVC application.