Skip to content
This repository has been archived by the owner on Jan 23, 2020. It is now read-only.

Latest commit

 

History

History
211 lines (136 loc) · 15.6 KB

README-National-Cloud.md

File metadata and controls

211 lines (136 loc) · 15.6 KB
Raw
services platforms author level client service endpoint
active-directory
dotnet
negoe
200
.NET Web App (MVC)
Microsoft Graph
AAD v1.0

Build a multi-tenant SaaS web application using Microsoft identity platform & OpenID Connect

Build status

About this sample

This sample shows how to build an ASP.NET MVC web application that uses OpenID Connect to sign in users from any Azure Active Directory tenant in any national cloud using the ASP.Net OpenID Connect OWIN middleware and the Active Directory Authentication Library (ADAL) for .NET.

It also introduces developers to the concept of

  • Microsoft National cloud environments
  • Multi-tenant Azure Active Directory application

[!Note] If you want to run this sample in Microsoft worldwide Cloud, navigate to the README.md.

Microsoft National cloud environments

National clouds (aka Sovereign clouds) are physically isolated instances of Azure. These regions of Azure are designed to make sure that data residency, sovereignty, and compliance requirements are honored within geographical boundaries.

In addition to the public cloud​, Azure Active Directory is deployed in the following National clouds:  

  • Azure US Government
  • Azure China 21Vianet
  • Azure Germany

Multi-tenant Azure Active Directory application

When it comes to developing apps, developers can choose to configure their app to be either single-tenant or multi-tenant during app registration in the Azure portal.

  • Single-tenant is for building line of business apps for users within your organization. These apps are only available to users that are in the same tenant as the app registration.

  • Multi-tenant Multi-tenant is for apps built by independent software vendors for any organization within a specific national cloud. These apps are available to users in any tenant where the app is provisioned by an administrator or consented by a user.

For more information about apps and tenancy, see Tenancy in Azure Active Directory

For more information about how the protocols work in this scenario and other scenarios, see the Authentication Scenarios for Azure AD document.

Overview

Scenario

This sample demonstrates a multi-tenant .NET Web App (MVC) application signing in users from multiple Azure AD tenants within a National cloud calling Microsoft Graph.

  1. The web app allows the tenant admins to sign up (and provision this app in their tenant) by signing them in using the ASP.Net OpenID Connect OWIN middleware.
  2. Once an admin consents to the application's requested permissions, the users of these tenants can then sign in themselves and create a Todo list for themselves.
  3. The application also uses the Active Directory Authentication Library (ADAL) for .NET library to obtain a JWT access token from Azure Active Directory (Azure AD) for Microsoft Graph.
  4. The access token is used as a bearer token to authenticate the user when calling Microsoft Graph to fetch the signed-in user's details.

[!Note] Azure Government applications can use Azure AD Government identities, but can also use Azure AD Public identities to authenticate to an application hosted in Azure Government. A multi-tenant application will not be accessible using Azure AD Public identities. To know more about choosing identity authority go to choose identity authority in Azure Government.

How to run this sample

To run this sample, you'll need:

Step 1: Clone or download this repository

From your shell or command line:

git clone https://github.com/Azure-Samples/active-directory-dotnet-webapp-multitenant-openidconnect.git`

or download and extract the repository .zip file.

Given that the name of the sample is pretty long, and so are the name of the referenced NuGet packages, you might want to clone it in a folder close to the root of your hard drive, to avoid file size limitations on Windows.

If you are using the automation provided via Powershell to create your app, you need to change the Configure.ps1 and Cleanup.ps1 as instructed below to append the -AzureEnvironmentName parameter. The details on this parameter and its possible values are listed in Connect-AzureAD.

Connect-AzureAD -TenantId $tenantId -AzureEnvironmentName AzureUSGovernment

Step 2: Register the sample application with your Azure Active Directory tenant

  1. Sign in to the US Government Azure portal page select New registration.

    For registering your app in other National Clouds go to App Registration endpoints of the National Cloud of your choice, using either a work or school account.

    Note: Azure Germany doesn't support App registrations (Preview) experience.

  2. When the Register an application page appears, enter your application's registration information:

    • In the Name section, enter a meaningful application name that will be displayed to users of the app, for example TodoListWebApp_MT.
    • In the Supported account types section, select Accounts in any organizational directory.
    • In the Redirect URI section, select Web in the combo-box and enter the following redirect URIs.
      • https://localhost:44302/
      • https://localhost:44302/Onboarding/ProcessCode

  3. Select Register to create the application.

  4. On the app Overview page, find the Application (client) ID value and record it for later. You'll need it to configure the Visual Studio configuration file for this project.

  5. In the list of pages for the app, select Authentication.

    • In the Advanced settings section set Logout URL to https://localhost:44302/Account/EndSession
    • In the Advanced settings | Implicit grant section, check ID tokens as this sample requires the Implicit grant flow to be enabled to sign-in the user, and call an API.

  6. Select Save.

  7. The new customer onboarding process implemented by the sample requires the application to perform an OAuth2 request, which in turn requires to associate a key to the app in your tenant. From the Certificates & secrets page, in the Client secrets section, choose New client secret:

    • Type a key description (of instance app secret),
    • Select a key duration of either In 1 year, In 2 years, or Never Expires.
    • When you press the Add button, the key value will be displayed, copy, and save the value in a safe location.
    • You'll need this key later to configure the project in Visual Studio. This key value will not be displayed again, nor retrievable by any other means, so record it as soon as it is visible from the Azure portal.

  8. In the list of pages for the app, select API permissions

    • Click the Add a permission button and then,
    • Ensure that the Microsoft APIs tab is selected
    • In the Commonly used Microsoft APIs section, click on Microsoft Graph
    • In the Delegated permissions section, ensure that the right permissions are checked: User.Read, User.Read.All. Use the search box if necessary.
    • Select the Add permissions button

Step 3: Configure the sample to use your Azure AD tenant

In the steps below, "ClientID" is the same as "Application ID" or "AppId".

Open the solution dotnet-webapp-multitenant-oidc.sln in Visual Studio to configure the project (no s).

Configure the service project

  1. Open the TodoListWebApp\Web.Config file
  2. Find the app key ida:ClientId and replace the existing value with the application ID (clientId) of the TodoListWebApp_MT application copied from the Azure portal.
  3. Find the app key ida:ClientSecret and replace the existing value with the key you saved during the creation of the TodoListWebApp_MT app, in the Azure portal.
  4. Find the app key ida:RedirectUri and replace the existing value with the base address of the TodoListWebApp_MT project (by default https://localhost:44302/).
  5. Find the app key ida:AADInstance and replace the existing value with the corresponding Azure AD endpoint for the national cloud you want to target.
  6. Find the app key ida:GraphAPIEndpoint and replace the existing value with the corresponding Microsoft Graph endpoint for the national cloud you want to target.

Step 5: Run the sample

Clean the solution, rebuild the solution, and run it. The sample implements two distinct tasks: the onboarding of a new customer and regular sign in & use of the application.

Sign up

  • When running the app for the first time, you'd need to sign-in as an administrator first. Click the Sign Up link on the top bar.

Sign Up link

  • You will be presented with a form that simulates an onboarding process. Check the checkbox and Click the SignUp button.

Sign Up form

  • Now you are going through the admin consent flow. In this flow, the app gets provisioned for all the users in one organization. You'll be transferred to the Azure AD portal. Sign in as the administrator and you'd be presented with the following screen to consent on behalf of all users.

Admin Consent

  • Click Accept to provision a service principal of this app in the tenant. You will be transported back to the app, where your registration will be finalized.

  • If the app is not provisioned in your tenant by the tenant administrator using the steps laid out above, the sign-up process will result in the following error.

Need admin approval

Sign in

  • Once you signed up, you can either click on the Todo tab or the sign in link to gain access to the application.

  • If you are selecting **sign in the same session in which you signed up, you will automatically sign in with the same account you used for signing up.

  • If you are signing in during a new session, you will be presented with Azure AD's credentials prompt: sign in using an account compatible with the sign-up option you chose earlier (the exact same account if you used user consent, any user form the same tenant if you used admin consent).

  • If you try to sign-in before the tenant administrator has provisioned the app in the tenant using the Sign up link above, you will see the following error.

AADSTS700016, App not found

To learn more about the code, go to About the code

Community Help and Support

Use Stack Overflow to get support from the community. Ask your questions on Stack Overflow first and browse existing issues to see if someone has asked your question before. Make sure that your questions or comments are tagged with [adal msal dotnet].

If you find a bug in the sample, raise the issue on GitHub Issues.

To provide a recommendation, visit the following User Voice page.

Contributing

If you'd like to contribute to this sample, see CONTRIBUTING.MD.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

More information

For more information, see the following links:

For more information about how OAuth 2.0 protocols work in this scenario and other scenarios, see Authentication Scenarios for Azure AD.