Skip to content

Latest commit

 

History

History
 
 

1-4-Sovereign

README.md

services platforms author level client endpoint
active-directory
dotnet
negoe
100
ASP.NET Core Web App
Microsoft identity platform

Build an ASP.NET Core Web app signing-in users in sovereign clouds with the Microsoft identity platform

Build status

Scenario

This sample shows how to build a .NET Core MVC Web app that uses OpenID Connect to sign in users. Users can only sign in with their 'work and school' accounts in their organization belonging to national or sovereign clouds. This sample use US Government cloud scenario. It leverages the ASP.NET Core OpenID Connect middleware.

Sign in with Azure AD

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

Note that enabling your application for sovereign clouds requires you to:

  • register your application in a specific portal, depending on the cloud
  • use a specific authority, depending on the cloud in the config file for your application
  • in case you want to call the graph, this requires a specific Graph endpoint URL, depending on the cloud.

More details in Authentication in National Clouds

How to run this sample

To run this sample:

Pre-requisites: Install .NET Core 3.0 or later (for example for Windows) by following the instructions at .NET and C# - Get Started in 10 Minutes. In addition to developing on Windows, you can develop on [Linux](https://ww w.microsoft.com/net/core#linuxredhat), Mac, or Docker.

Step 1: Download/Clone this sample code

This sample was created from the dotnet core 3.0 dotnet new mvc template with SingleOrg authentication, and then tweaked to let it support tokens for the Microsoft identity platform endpoint.

You can clone this sample from your shell or command line:

git clone https://github.com/Azure-Samples/microsoft-identity-platform-aspnetcore-webapp-tutorial webapp
cd webapp
cd "1-WebApp-OIDC\1-4-Sovereign"

Given that the name of the sample is very 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.

Step 2: Register the sample with your Azure AD tenant

  1. Sign in to the US Government Azure portal

    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. Choose the Azure AD tenant where you want to create your applications

    • If your account is present in more than one Azure AD tenant, select profile button at the top-right corner in the menu on top of the page and select Switch Directory.
    • On Directory + Subscription switch your portal session to the desired Azure AD tenant.

  3. In the left-hand navigation pane, select the Azure Active Directory service, and then select App registrations (Preview).

  4. In App registrations (Preview) page, select New registration.

  5. 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 WebApp.
    • In the Supported account types section, select Accounts in this organizational directory only (name of your org).
    • In the Redirect URI (optional) section, select Web in the combo-box.
    • For the Redirect URI, enter the base URL for the sample. By default, this sample uses https://localhost:44321/.
    • Select Register to create the application.

  6. 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.

  7. Still in the Overview page, find the Directory (tenant) ID value and record it for later.

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

    • In the Redirect URIs, add a redirect URL of type Web and valued https://localhost:44321/signin-oidc
    • In the Advanced settings section set Logout URL to https://localhost:44321/signout-oidc
    • 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.
    • Select Save.

Note that unless the Web App calls a Web API no certificate or secret is needed.

Step 3: Configure your App

Option 1: In the appsettings.json file:

  • replace the Instance value with the relevant authority value of the US Government cloud that is https://login.microsoftonline.us
  • replace the ClientID value with the Application ID from the application you registered in Application Registration portal on Step 2.
  • replace the TenantId value with the Tenant ID where you registered your Application on Step 2.

Option 2: Create and configure sample from the command line

  1. Run the following command to create a sample from the command line using the SingleOrg template:

    dotnet new mvc --auth SingleOrg --client-id <Enter_the_Application_Id_here> --tenant-id <yourTenantId>

    Note: Replace Enter_the_Application_Id_here with the Application Id from the application Id you just registered in the Application Registration Portal and <yourTenantId> with the Directory (tenant) ID where you created your application.

  2. Open the generated project (.csproj) in Visual Studio, and save the solution.

  3. Add the Microsoft.Identity.Web.csproj project, which is located at the root of this sample repo, to your solution (Add Existing Project ...). It's used to simplify signing-in and, in the next tutorial phases, to get a token

  4. Add a reference from your newly generated project to Microsoft.Identity.Web (right click on the Dependencies node under your new project, and choose Add Reference ..., and then in the projects tab find the Microsoft.Identity.Web project)

  5. Open the Startup.cs file and:

    • at the top of the file, add the following using directive:
     using Microsoft.Identity.Web;

    • in the ConfigureServices method, replace the two following lines:

          services.AddAuthentication(AzureADDefaults.AuthenticationScheme)
            .AddAzureAD(options => Configuration.Bind("AzureAd", options));

      by this line:

             services.AddMicrosoftIdentityPlatformAuthentication(Configuration);

      This enables your application to use the Microsoft identity platform endpoint. This endpoint is capable of signing-in users both with their Work and School and Microsoft Personal accounts.

    1. Change the Properties\launchSettings.json file to ensure that you start your web app from https://localhost:44321 as registered. For this:
    • update the sslPort of the iisSettings section to be 44321
    • in the applicationUrl property of use https://localhost:44321

Step 3: Run the sample

  1. Build the solution and run it.

  2. Open your web browser and make a request to the app. Accept the IIS Express SSL certificate if needed. The app immediately attempts to authenticate you via the Microsoft identity platform endpoint. Sign in with your personal account or with work or school account.

Troubleshooting

known issue on iOS 12

ASP.NET core applications create session cookies that represent the identity of the caller. Some Safari users using iOS 12 had issues, which are described in ASP.NET Core #4467 and the Web kit bugs database Bug 188165 - iOS 12 Safari breaks ASP.NET Core 2.1 OIDC authentication.

If your web site needs to be accessed from users using iOS 12, you probably want to disable the SameSite protection, but also ensure that state changes are protected with CSRF anti-forgery mechanism. See the how to fix section of Microsoft Security Advisory: iOS12 breaks social, WSFed, and OIDC logins #4647

About The code

This sample shows how to use the OpenID Connect ASP.NET Core middleware to sign in users from a single Azure AD tenant. The middleware is initialized in the Startup.cs file by passing it the Client ID of the app, and the URL of the Azure AD tenant where the app is registered. These values are read from the appsettings.json file. The middleware takes care of:

  • Downloading the Azure AD metadata, finding the signing keys, and finding the issuer name for the tenant.
  • Processing OpenID Connect sign-in responses by validating the signature and issuer in an incoming JWT, extracting the user's claims, and putting the claims in ClaimsPrincipal.Current.
  • Integrating with the session cookie ASP.NET Core middleware to establish a session for the user.

You can trigger the middleware to send an OpenID Connect sign-in request by decorating a class or method with the [Authorize] attribute or by issuing a challenge (see the AccountController.cs file, which is part of ASP.NET Core):

The middleware in this project is created as a part of the open-source ASP.NET Core Security project.

These steps are encapsulated in the Microsoft.Identity.Web project, and in particular in the StartupHelper.cs file

Next steps

Learn more

To understand more about app registration, see: