Usar o MSAL em um ambiente de nuvem nacional

Artigo
10/25/2023

Nuvens nacionais, também conhecidas como nuvens soberanas, são instâncias do Azure isoladas fisicamente. Essas regiões do Azure ajudam a garantir que os requisitos de residência, soberania e conformidade de dados sejam respeitados dentro de limites geográficos.

Além da nuvem mundial da Microsoft, a MSAL (Biblioteca de Autenticação da Microsoft) permite que os desenvolvedores de aplicativos em nuvens nacionais adquiram tokens para autenticar e chamar APIs Web seguras. Essas APIs Web podem ser o Microsoft Graph ou outras APIs da Microsoft.

Incluindo a nuvem global do Azure, o Microsoft Entra ID é implantado nas seguintes nuvens nacionais:

Azure Governamental
Microsoft Azure operado pela 21Vianet
Azure Alemanha (fechamento em 29 de outubro de 2021)

Este guia demonstra como entrar em contas corporativas e de estudante, obter um token de acesso e chamar a API do Microsoft Graph no ambiente de nuvem do Azure Governamental.

Azure Alemanha (Microsoft Cloud Deutschland)

Aviso

O Azure Alemanha (Microsoft Cloud Deutschland) será fechado em 29 de outubro de 2021. Os serviços e aplicativos que você optar por não migrar para uma região do Azure global antes dessa data ficarão inacessíveis.

Se você não migrou seu aplicativo do Azure Alemanha, siga as informações do Microsoft Entra para a migração do Azure Alemanha para começar.

Pré-requisitos

Antes de começar, atenda a estes pré-requisitos.

Escolha as identidades apropriadas

Os aplicativos do Azure Governamental podem usar identidades do Microsoft Entra Governamental e identidades do Microsoft Entra Público para autenticar usuários. Como você pode usar qualquer uma dessas identidades, decida qual ponto de extremidade de autoridade você deve escolher para seu cenário:

Microsoft Entra Público: normalmente utilizado se sua organização já tiver um locatário do Microsoft Entra Público para dar suporte ao Microsoft 365 (Público ou GCC) ou a outro aplicativo.
Microsoft Entra Governamental: normalmente utilizado se sua organização já tiver um locatário do Microsoft Entra Governamental para dar suporte ao Office 365 (GCC High ou DoD) ou estiver criando um locatário novo no Microsoft Entra Governamental.

Depois de decidir, uma consideração especial é onde você realiza o registro do aplicativo. Se você escolher identidades do Microsoft Entra Público para o aplicativo do Azure Governamental, deverá registrar o aplicativo no locatário do Microsoft Entra Público.

Obter uma assinatura do Azure Governamental

Para obter uma assinatura do Azure Governamental, veja Gerenciamento e conexão à sua assinatura no Azure Governamental.

Caso você não tenha uma assinatura do Azure Governamental, crie uma conta gratuita antes de começar.

Para obter detalhes sobre como usar uma nuvem nacional com uma linguagem de programação específica, escolha a guia correspondente ao seu idioma:

Você pode usar o MSAL.NET para conectar usuários, adquirir tokens e chamar a API do Microsoft Graph em nuvens nacionais.

Os tutoriais a seguir demonstram como criar um aplicativo Web do ASP.NET Core. O aplicativo usa o OpenID Connect para conectar usuários com uma conta corporativa e de estudante em uma organização que pertence a uma nuvem nacional.

Para conectar usuários e adquirir tokens, siga este tutorial: Criar um aplicativo Web do ASP.NET Core que conecte usuários em nuvens soberanas com a plataforma de identidade da Microsoft.
Para chamar a API do Microsoft Graph, siga este tutorial: Uso da plataforma de identidade da Microsoft para chamar a API do Microsoft Graph a partir de um aplicativo Web do ASP.NET Core, em nome de um usuário que entra usando a conta corporativa e de estudante na nuvem nacional da Microsoft.

Para habilitar o aplicativo MSAL.js para nuvens soberanas:

Registre o aplicativo em um portal específico, dependendo da nuvem. Para obter mais informações sobre como escolher o portal, veja Pontos de extremidade de registro do aplicativo
Use qualquer um dos exemplos do repositório com algumas alterações na configuração, dependendo da nuvem, que é mencionada a seguir.
Use uma autoridade específica, dependendo da nuvem em que você registrou o aplicativo. Para saber mais sobre autoridades para nuvens diferentes, confira Pontos de extremidade da Autenticação do Microsoft Entra.
Chamar a API do Microsoft Graph requer um URL de ponto de extremidade específico para a nuvem que você está usando. Para localizar pontos de extremidade do Microsoft Graph para todas as nuvens nacionais, veja Pontos de extremidade raiz do serviço do Explorador do Graph e do Microsoft Graph.

Veja aqui um exemplo de autoridade:

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

Veja aqui um exemplo de um ponto de extremidade do Microsoft Graph, com escopo:

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

Este é o código mínimo para autenticar um usuário com uma nuvem soberana e chamar o Microsoft Graph:

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

// Initialize MSAL
const msalObj = new PublicClientApplication(msalConfig);

// Get token using popup experience
try {
    const graphToken = await msalObj.acquireTokenPopup({
        scopes: ["User.Read"]
    });
} catch(error) {
    console.log(error)
}

// Call the Graph API
const headers = new Headers();
const bearer = `Bearer ${graphToken}`;

headers.append("Authorization", bearer);

fetch("https://graph.microsoft.us/v1.0/me", {
    method: "GET",
    headers: headers
})

Para habilitar o aplicativo Python da MSAL para nuvens soberanas:

Registre o aplicativo em um portal específico, dependendo da nuvem. Para obter mais informações sobre como escolher o portal, veja Pontos de extremidade de registro do aplicativo
Use qualquer um dos exemplos do repositório com algumas alterações na configuração, dependendo da nuvem, que é mencionada a seguir.
Use uma autoridade específica, dependendo da nuvem em que você registrou o aplicativo. Para saber mais sobre autoridades para nuvens diferentes, confira Pontos de extremidade da Autenticação do Microsoft Entra.

Veja aqui um exemplo de autoridade:
```
"authority": "https://login.microsoftonline.us/Enter_the_Tenant_Info_Here"
```
Chamar a API do Microsoft Graph requer um URL de ponto de extremidade específico para a nuvem que você está usando. Para localizar pontos de extremidade do Microsoft Graph para todas as nuvens nacionais, veja Pontos de extremidade raiz do serviço do Explorador do Graph e do Microsoft Graph.

Veja aqui um exemplo de um ponto de extremidade do Microsoft Graph, com escopo:
```
"endpoint" : "https://graph.microsoft.us/v1.0/me"
"scope": "User.Read"
```

Para habilitar o aplicativo MSAL para Java para nuvens soberanas:

Registre o aplicativo em um portal específico, dependendo da nuvem. Para obter mais informações sobre como escolher o portal, veja Pontos de extremidade de registro do aplicativo
Use qualquer uma das amostras do repositório com algumas alterações na configuração, dependendo da nuvem, que são mencionadas a seguir.
Use uma autoridade específica, dependendo da nuvem em que você registrou o aplicativo. Para saber mais sobre autoridades para nuvens diferentes, confira Pontos de extremidade da Autenticação do Microsoft Entra.

Veja aqui um exemplo de autoridade:

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

Chamar a API do Microsoft Graph requer um URL de ponto de extremidade específico para a nuvem que você está usando. Para localizar pontos de extremidade do Microsoft Graph para todas as nuvens nacionais, veja Pontos de extremidade raiz do serviço do Explorador do Graph e do Microsoft Graph.

Veja aqui um exemplo de um ponto de extremidade do Graph, com escopo:

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

O MSAL para iOS e macOS pode ser utilizado para adquirir tokens em nuvens nacionais, mas exige configuração adicional ao criar MSALPublicClientApplication.

Por exemplo, se você quiser que o aplicativo seja multilocatário em uma nuvem nacional (aqui, Governo dos EUA), poderá escrever:

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

O MSAL para iOS e macOS pode ser utilizado para adquirir tokens em nuvens nacionais, mas exige configuração adicional ao criar MSALPublicClientApplication.

Por exemplo, se você quiser que o aplicativo seja multilocatário em uma nuvem nacional (aqui, Governo dos EUA), poderá escrever:

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

Próximas etapas

Veja Pontos de extremidade de autenticação de nuvem nacional para obter uma lista de URLs do portal do Azure e de pontos de extremidade de token para cada nuvem.

Documentação da nuvem nacional: