Use MSAL in a national cloud environment

  • 4 minutes to read

National clouds are physically isolated instances of Azure. These regions of Azure help make sure that data residency, sovereignty, and compliance requirements are honored within geographical boundaries.

In addition to the Microsoft worldwide cloud, the Microsoft Authentication Library (MSAL) enables application developers in national clouds to acquire tokens in order to authenticate and call secured web APIs. These web APIs can be Microsoft Graph or other Microsoft APIs.

Including the global cloud, Azure Active Directory (Azure AD) is deployed in the following national clouds:  

  • Azure Government
  • Azure China 21Vianet
  • Azure Germany

This guide demonstrates how to sign in to work and school accounts, get an access token, and call the Microsoft Graph API in the Azure Government cloud environment.

Prerequisites

Before you start, make sure that you meet these prerequisites.

Choose the appropriate identities

Azure Government applications can use Azure AD Government identities and Azure AD Public identities to authenticate users. Because you can use any of these identities, you need to decide which authority endpoint you should choose for your scenario:

  • Azure AD Public: Commonly used if your organization already has an Azure AD Public tenant to support Office 365 (Public or GCC) or another application.
  • Azure AD Government: Commonly used if your organization already has an Azure AD Government tenant to support Office 365 (GCC High or DoD) or is creating a new tenant in Azure AD Government.

After you decide, a special consideration is where you perform your app registration. If you choose Azure AD Public identities for your Azure Government application, you must register the application in your Azure AD Public tenant.

Get an Azure Government subscription

To get an Azure Government subscription, see Managing and connecting to your subscription in Azure Government.

If you don't have an Azure Government subscription, create a free account before you begin.

JavaScript

Step 1: Register your application

  1. Sign in to the Azure portal.

    To find Azure portal endpoints for other national clouds, see App registration endpoints.

  2. If your account gives you access to more than one tenant, select your account in the upper-right corner, and set your portal session to the desired Azure AD tenant.

  3. Go to the App registrations page on the Microsoft identity platform for developers.

  4. When the Register an application page appears, enter a name for your application.

  5. Under Supported account types, select Accounts in any organizational directory.

  6. In the Redirect URI section, select the Web platform and set the value to the application's URL based on your web server. See the next sections for instructions on how to set and obtain the redirect URL in Visual Studio and Node.

  7. Select Register.

  8. On the app Overview page, note down the Application (client) ID value.

  9. This tutorial requires you to enable the implicit grant flow. In the left pane of the registered application, select Authentication.

  10. In Advanced settings, under Implicit grant, select the ID tokens and Access tokens check boxes. ID tokens and access tokens are required because this app needs to sign in users and call an API.

  11. Select Save.

Step 2: Set up your web server or project

Then skip to Configure your JavaScript SPA to configure the code sample before running it.

Step 3: Use the Microsoft Authentication Library to sign in the user

Follow steps in the JavaScript tutorial to create your project and integrate with MSAL to sign in the user.

Step 4: Configure your JavaScript SPA

In the index.html file created during project setup, add the application registration information. Add the following code at the top within the <script></script> tags in the body of your index.html file:

const msalConfig = {
    auth:{
        clientId: "Enter_the_Application_Id_here",
        authority: "https://login.microsoftonline.us/Enter_the_Tenant_Info_Here",
        }
}

const graphConfig = {
        graphEndpoint: "https://graph.microsoft.us",
        graphScopes: ["user.read"],
}

// create UserAgentApplication instance
const myMSALObj = new UserAgentApplication(msalConfig);

In that code:

  • Enter_the_Application_Id_here is the Application (client) ID value for the application that you registered.

  • Enter_the_Tenant_Info_Here is set to one of the following options:

    • If your application supports Accounts in this organizational directory, replace this value with the tenant ID or tenant name (for example, contoso.microsoft.com).
    • If your application supports Accounts in any organizational directory, replace this value with organizations.

    To find authentication endpoints for all the national clouds, see Azure AD authentication endpoints.

    Note

    Personal Microsoft accounts are not supported in national clouds.

  • graphEndpoint is the Microsoft Graph endpoint for the Microsoft cloud for US government.

    To find Microsoft Graph endpoints for all the national clouds, see Microsoft Graph endpoints in national clouds.

.NET

You can use MSAL.NET to sign in users, acquire tokens, and call the Microsoft Graph API in national clouds.

The following tutorials demonstrate how to build a .NET Core 2.2 MVC Web app. The app uses OpenID Connect to sign in users with a work and school account in an organization that belongs to a national cloud.

MSAL for iOS and macOS

MSAL for iOS and macOS can be used to acquire tokens in national clouds, but it requires additional configuration when creating MSALPublicClientApplication.

For instance, if you want your application to be a multi-tenant application in a national cloud (here US Government), you could write:

Objective-C:

MSALAADAuthority *aadAuthority =
                [[MSALAADAuthority alloc] initWithCloudInstance:MSALAzureUsGovernmentCloudInstance
                                                   audienceType:MSALAzureADMultipleOrgsAudience
                                                      rawTenant:nil
                                                          error:nil];
                                                          
MSALPublicClientApplicationConfig *config =
                [[MSALPublicClientApplicationConfig alloc] initWithClientId:@"<your-client-id-here>"
                                                                redirectUri:@"<your-redirect-uri-here>"
                                                                  authority:aadAuthority];
                                                                  
NSError *applicationError = nil;
MSALPublicClientApplication *application =
                [[MSALPublicClientApplication alloc] initWithConfiguration:config error:&applicationError];

Swift:

let authority = try? MSALAADAuthority(cloudInstance: .usGovernmentCloudInstance, audienceType: .azureADMultipleOrgsAudience, rawTenant: nil)
        
let config = MSALPublicClientApplicationConfig(clientId: "<your-client-id-here>", redirectUri: "<your-redirect-uri-here>", authority: authority)
if let application = try? MSALPublicClientApplication(configuration: config) { /* Use application */}

Next steps

Learn more about: