Use MSAL in a national cloud environment

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.

• To sign in users and acquire tokens, follow this tutorial: Build an ASP.NET Core Web app signing-in users in sovereign clouds with the Microsoft identity platform.
• To call the Microsoft Graph API, follow this tutorial: Using the Microsoft identity platform to call the Microsoft Graph API from an ASP.NET Core 2.x web app, on behalf of a user signing-in using their work and school account in Microsoft National Cloud.

To enable your MSAL.js application for sovereign clouds:

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 you have access to multiple tenants, use the Directory + subscription filter in the top menu to select the tenant in which you want to register an application.

3. Search for and select Azure Active Directory.

4. Under Manage, select App registrations > New registration.

5. Enter a Name for your application. Users of your app might see this name, and you can change it later.

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

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

8. Select Register.

9. On the Overview page, note down the Application (client) ID value for later use. This tutorial requires you to enable the implicit grant flow.

10. Under Manage, select Authentication.

11. Under Implicit grant, select ID tokens and Access tokens. ID tokens and access tokens are required because this app needs to sign in users and call an API.

12. Select Save.

Step 2: Set up your web server or project

• Download the project files for a local web server, such as Node.

  or

• Download the Visual Studio 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.

To enable your MSAL Python application for sovereign clouds:

• Register your application in a specific portal, depending on the cloud. For more information on how to choose the portal refer App registration endpoints

• Use any of the samples from the repo with a few changes to the configuration, depending on the cloud, which is mentioned next.

• Use a specific authority, depending on the cloud you registered the application in. For more information on authorities for different clouds, refer Azure AD Authentication endpoints.

  Here's an example authority:

  "authority": "https://login.microsoftonline.us/Enter_the_Tenant_Info_Here"
  

• Calling the Microsoft Graph API requires an endpoint URL specific to the cloud you are using. To find Microsoft Graph endpoints for all the national clouds, refer to Microsoft Graph and Graph Explorer service root endpoints.

  Here's an example of a Microsoft Graph endpoint, with scope:

  "endpoint" : "https://graph.microsoft.us/v1.0/me"
  "scope": "User.Read"
  

To enable your MSAL for Java application for sovereign clouds:

• Register your application in a specific portal, depending on the cloud. For more information on how to choose the portal refer App registration endpoints
• Use any of the samples from the repo with a few changes to the configuration, depending on the cloud, which are mentioned next.
• Use a specific authority, depending on the cloud you registered the application in. For more information on authorities for different clouds, refer Azure AD Authentication endpoints.

Here's an example authority:

"authority": "https://login.microsoftonline.us/Enter_the_Tenant_Info_Here"

• Calling the Microsoft Graph API requires an endpoint URL specific to the cloud you are using. To find Microsoft Graph endpoints for all the national clouds, refer to Microsoft Graph and Graph Explorer service root endpoints.

Here's an example of a graph endpoint, with scope:

"endpoint" : "https://graph.microsoft.us/v1.0/me"
"scope": "User.Read"

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:

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];

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:

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 */}