Skip to content

Commit 8f0e600

Browse files
Shama-KShama-K
committed
Readme Updates
1 parent c50df9a commit 8f0e600

File tree

1 file changed

+71
-71
lines changed

1 file changed

+71
-71
lines changed

‎4-WebApp-your-API/4-3-AnyOrg/Readme.md

Lines changed: 71 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -34,30 +34,33 @@ This sample demonstrates how to develop a multi-tenant ASP.NET Core MVC web appl
3434
- [Step 1: Clone or download this repository](#step-1-clone-or-download-this-repository)
3535
- [Step 2: Register the sample application with your Azure Active Directory tenant](#step-2-register-the-sample-application-with-your-azure-active-directory-tenant)
3636
- [Step 3: Run the sample](#step-3-run-the-sample)
37+
- [Testing the Application](#testing-the-application)
3738
- [About the code](#about-the-code)
3839
- [Community Help and Support](#community-help-and-support)
3940
- [Contributing](#contributing)
4041
- [More information](#more-information)
4142

4243
### Scenario
4344

44-
In this scenario, you protect a Web API using the Microsoft Identity Platform so that only authenticated users can access it. The API will support authenticated users with Work and School accounts. Further on the API will also call a downstream API (Microsoft Graph) on-behalf of the signed-in user to provide additional value to its client apps.
45+
In this sample, we would protect an ASP.Net Core Web API using the Microsoft Identity Platform. The Web API will be protected using Azure Active Directory OAuth Bearer Authorization. The API will support authenticated users with Work and School accounts. Further on the API will also call a downstream API (Microsoft Graph) on-behalf of the signed-in user to provide additional value to its client apps.
4546

4647
### Overview
4748

4849
This sample presents a Web application that signs-in users and obtains an Access Token for protected Web API.
4950

51+
Both applications use the Microsoft Authentication Library [MSAL.NET](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet) to sign-in user and obtain a JWT access token through the [OAuth 2.0](https://docs.microsoft.com/azure/active-directory/develop/active-directory-protocols-oauth-code) protocol.
52+
5053
The Web App:
5154

52-
1. TodoListClient uses [MSAL.NET](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet) and [Microsoft.Identity.Web](https://github.com/AzureAD/microsoft-identity-web) to authenticate a user.
53-
2. Acquires an access token for the Web API.
54-
3. Calls the ASP.NET Core Web API by using the access token as a bearer token in the authentication header of the Http request.
55+
1. Signs-in users using the MSAL.NET library.
56+
1. Acquires an access token for the Web API.
57+
1. Calls the ASP.NET Core Web API by using the access token as a bearer token in the authentication header of the Http request.
5558

5659
The Web API:
5760

58-
1. TodoListService uses [MSAL.NET](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet) and [Microsoft.Identity.Web](https://github.com/AzureAD/microsoft-identity-web) to protect its endpoint and accept authorized calls.
59-
2. Acquires another access token on-behalf-of the signed-in user using the [on-behalf of flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow).
60-
3. The Web API then uses this new Access token to call Microsoft Graph
61+
1. Authorizes the caller (user) using the ASP.NET JWT Bearer Authorization middleware.
62+
1. Acquires another access token on-behalf-of the signed-in user using the [on-behalf of flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow).
63+
1. The Web API then uses this new Access token to call Microsoft Graph.
6164

6265
![Topology](./ReadmeFiles/topology.png)
6366

@@ -224,7 +227,20 @@ Open the project in your IDE (like Visual Studio) to configure the code.
224227
1. Find the app key `AdminConsentRedirectApi` and replace the existing value with the Redirect URI for WebApi-MultiTenant-v2 app. For example, `https://localhost:44351/api/Home` .
225228
### Step 3: Run the sample
226229

227-
#### Using a command line interface such as VS Code integrated terminal, follow the steps below:
230+
You can run the sample by using either Visual Studio or command line interface as shown below:
231+
232+
#### Run the sample using Visual Studio
233+
234+
Clean the solution, rebuild the solution, and run it. You might want to go into the solution properties and set both projects as startup projects, with the service project starting first.
235+
236+
When you start the Web API from Visual Studio, depending on the browser you use, you'll get:
237+
238+
- an empty web page (with Microsoft Edge)
239+
- or an error HTTP 401 (with Chrome)
240+
241+
This behavior is expected as the browser is not authenticated. The Web application will be authenticated, so it will be able to access the Web API.
242+
243+
#### Run the sample using a command line interface such as VS Code integrated terminal
228244

229245
##### Step 1. Install .NET Core dependencies
230246

@@ -252,36 +268,70 @@ Learn more about [HTTPS in .NET Core](https://docs.microsoft.com/aspnet/core/sec
252268

253269
##### Step 3. Run the applications
254270

255-
In both the windows execute the below command:
271+
In both the console windows execute the below command:
256272

257273
```console
258274
dotnet run
259275
```
260276
Open your browser and navigate to `https://localhost:44321`.
261277

262-
#### Run the sample using Visual Studio:
278+
> NOTE: Remember, the To-Do list is stored in memory in this `TodoListService` app. Each time you run the projects, your To-Do list will get emptied.
263279
264-
Clean the solution, rebuild the solution, and run it. You might want to go into the solution properties and set both projects as startup projects, with the service project starting first.
280+
### Testing the Application
265281

266-
When you start the Web API from Visual Studio, depending on the browser you use, you'll get:
282+
To properly test this application, you need *at least* **2** tenants, and on each tenant, *at least* **1** administrator and **1** non-administrator account.
267283

268-
- an empty web page (case with Microsoft Edge)
269-
- or an error HTTP 401 (case with Chrome)
284+
Before each test, you should delete your **service principal** for the tenant you are about to test, in order to remove any previously given consents and start the **provisioning process** from scratch.
270285

271-
This behavior is expected as you are not authenticated. The client application will be authenticated, so it will be able to access the Web API.
286+
> #### How to delete Service Principals
287+
>
288+
> Steps for deleting a service principal differs with respect to whether the principal is in the **home tenant** of the application or in another tenant. If it is in the **home tenant**, you will find the entry for the application under the **App Registrations** blade. If it is another tenant, you will find the entry under the **Enterprise Applications** blade. Read more about these blades in the [How and why applications are added to Azure AD](https://docs.microsoft.com/azure/active-directory/develop/active-directory-how-applications-are-added).The screenshot below shows how to access the service principal from a **home tenant**:
289+
>
290+
> ![principal1](./ReadmeFiles/Home_Tenant_SP.png)
291+
>
292+
> The rest of the process is the same for both cases. In the next screen, click on **Properties** and then the **Delete** button on the upper side.
293+
>
294+
> ![principal1](./ReadmeFiles/Home_Tenant_SP_Delete.png)
295+
>
296+
> You have now deleted the service principal of Web App for that tenant. Similarly, you can delete the service principal for Web API. Next time, admin needs to provision service principal for both the applications in the tenant from which *that* admin belongs.
272297
273-
## Explore the sample
298+
#### Ways of providing admin consent
274299

275-
Explore the sample by signing in into the TodoList client, adding items to the To Do list and assigning them to users. If you stop the application without signing out, the next time you run the application, you won't be prompted to sign in again.
300+
A service principal of your multi-tenant app is created manually or programmatically by a tenant admin using one of the following
301+
1. Using the [/adminconsent endpoint](https://docs.microsoft.com/azure/active-directory/develop/v2-admin-consent)
302+
2. [Using the PowerShell command](https://docs.microsoft.com/powershell/azure/create-azure-service-principal-azureps).
276303

277-
For Home Tenant, admin needs to sign-in first as `User.Read.All` permission requires admin consent for the organization.
304+
- **Consent using the `/adminconsent` endpoint**
278305

279-
For guest tenant, you need to provision service principal for that tenant. It can be done by clicking on `Admin Consent` link that is present on home page of Web App. The link provides consent screen that is used to create service principal by admin of the guest tenant.
306+
You can try the /adminconsent endpoint on the home page of the sample by clicking on the `Consent as Admin` link. Web API is provisioned first because the Web App is dependent on the Web API.
280307

281-
> NOTE: Remember, the To-Do list is stored in memory in this `TodoListService` app. Each time you run the projects, your To-Do list will get emptied.
308+
![admin consent endpoint](./ReadmeFiles/AdminConsentBtn.png)
309+
310+
> #### The `.default` scope
311+
>
312+
> Did you notice the scope here is set to `.default`, as opposed to `User.Read.All` for Microsoft Graph and `access_as_user` for Web API? This is a built-in scope for every application that refers to the static list of permissions configured on the application registration. Basically, it *bundles* all the permissions in one scope. The /.default scope can be used in any OAuth 2.0 flow, but is necessary when using the v2 admin consent endpoint to request application permissions. Read about `scopes` usage at [Scopes and permissions in the Microsoft Identity Platform](https://docs.microsoft.com/azure/active-directory/develop/v2-permissions-and-consent#scopes-and-permissions).
313+
314+
When redirected to the `/adminconsent` endpoint, the tenant admin will see:
315+
316+
![redirect](./ReadmeFiles/admin_redirect_api.png)
317+
318+
After you choose an admin account, it will lead to the following prompt for Web API consent screen:
319+
320+
![consent](./ReadmeFiles/admin_consent_api.png)
321+
322+
When you click `Accept`, it will redirects to `/adminconsent` endpoint for Web App:
323+
324+
![redirect](./ReadmeFiles/admin_redirect_app.png)
325+
326+
After you choose an admin account, it will lead to the Web App consent as below:
327+
328+
![consent](./ReadmeFiles/admin_consent_app.png)
329+
330+
Once it finishes, your applications service principal will be provisioned in that tenant.
282331

283332
> Did the sample not work for you as expected? Did you encounter issues trying this sample? Then please reach out to us using the [GitHub Issues](../../../../issues) page.
284333
334+
285335
## About the code
286336

287337
### Provisioning your Multi-tenant Apps in another Azure AD Tenant
@@ -438,63 +488,13 @@ services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
438488
},
439489
options => { Configuration.Bind("AzureAd", options); });
440490
```
441-
### Testing the Application
442-
443-
To properly test this application, you need *at least* **2** tenants, and on each tenant, *at least* **1** administrator and **1** non-administrator account.
444-
445-
Before each test, you should delete your **service principal** for the tenant you are about to test, in order to remove any previously given consents and start the **provisioning process** from scratch.
446-
447-
> #### How to delete Service Principals
448-
>
449-
> Steps for deleting a service principal differs with respect to whether the principal is in the **home tenant** of the application or in another tenant. If it is in the **home tenant**, you will find the entry for the application under the **App Registrations** blade. If it is another tenant, you will find the entry under the **Enterprise Applications** blade. Read more about these blades in the [How and why applications are added to Azure AD](https://docs.microsoft.com/azure/active-directory/develop/active-directory-how-applications-are-added).The screenshot below shows how to access the service principal from a **home tenant**:
450-
>
451-
> ![principal1](./ReadmeFiles/Home_Tenant_SP.png)
452-
>
453-
> The rest of the process is the same for both cases. In the next screen, click on **Properties** and then the **Delete** button on the upper side.
454-
>
455-
> ![principal1](./ReadmeFiles/Home_Tenant_SP_Delete.png)
456-
>
457-
> You have now deleted the service principal of Web App for that tenant. Similarly, you can delete the service principal for Web API. Next time, admin needs to provision service principal for both the applications in the tenant from which *that* admin belongs.
458-
459-
### Ways of providing admin consent
460-
461-
A service principal of your multi-tenant app is created manually or programmatically by a tenant admin using one of the following
462-
1. Using the [/adminconsent endpoint](https://docs.microsoft.com/azure/active-directory/develop/v2-admin-consent)
463-
2. [Using the PowerShell command](https://docs.microsoft.com/powershell/azure/create-azure-service-principal-azureps).
464-
465-
- **Consent using the `/adminconsent` endpoint**
466-
467-
You can try the /adminconsent endpoint on the home page of the sample by clicking on the `Consent as Admin` link. Web API is provisioned first because the Web App is dependent on the Web API.
468-
469-
![admin consent endpoint](./ReadmeFiles/AdminConsentBtn.png)
470-
471-
> #### The `.default` scope
472-
>
473-
> Did you notice the scope here is set to `.default`, as opposed to `User.Read.All` for Microsoft Graph and `access_as_user` for Web API? This is a built-in scope for every application that refers to the static list of permissions configured on the application registration. Basically, it *bundles* all the permissions in one scope. The /.default scope can be used in any OAuth 2.0 flow, but is necessary when using the v2 admin consent endpoint to request application permissions. Read about `scopes` usage at [Scopes and permissions in the Microsoft Identity Platform](https://docs.microsoft.com/azure/active-directory/develop/v2-permissions-and-consent#scopes-and-permissions).
474-
475-
When redirected to the `/adminconsent` endpoint, the tenant admin will see:
476-
477-
![redirect](./ReadmeFiles/admin_redirect_api.png)
478491

479-
After you choose an admin account, it will lead to the following prompt for Web API consent screen:
480-
481-
![consent](./ReadmeFiles/admin_consent_api.png)
482-
483-
When you click `Accept`, it will redirects to `/adminconsent` endpoint for Web App:
484-
485-
![redirect](./ReadmeFiles/admin_redirect_app.png)
486-
487-
After you choose an admin account, it will lead to the Web App consent as below:
488-
489-
![consent](./ReadmeFiles/admin_consent_app.png)
490-
491-
Once it finishes, your applications service principal will be provisioned in that tenant.
492492

493493
## Community Help and Support
494494

495495
Use [Stack Overflow](http://stackoverflow.com/questions/tagged/msal) to get support from the community.
496496
Ask your questions on Stack Overflow first and browse existing issues to see if someone has asked your question before.
497-
Make sure that your questions or comments are tagged with [`msal` `dotnet`].
497+
Make sure that your questions or comments are tagged with [`azure-active-directory` `msal` `dotnet`].
498498

499499
If you find a bug in the sample, please raise the issue on [GitHub Issues](../../issues).
500500

0 commit comments

Comments
 (0)