Aplicativo de área de trabalho que chama APIs Web: adquirir um token usando a Autenticação Integrada do Windows

Para conectar um usuário de domínio em um domínio ou em um computador ingressado no Microsoft Entra, use a IWA (Autenticação Integrada do Windows).

Restrições

• A Autenticação Integrada do Windows está disponível apenas para usuários federados+, ou seja, usuários criados no Active Directory e apoiados pelo Microsoft Entra ID. Os usuários criados diretamente no Microsoft Entra ID, sem apoio do Active Directory usuários, conhecidos como usuários gerenciados, não podem usar esse fluxo de autenticação. Essa limitação não afeta o fluxo de nome de usuário e senha.

• A IWA não ignora a autenticação multifator (MFA). Caso a MFA esteja configurada, a IWA poderá falhar caso um desafio de MFA seja necessário, pois esta exige a interação do usuário.

  A IWA é não interativa, mas a MFA requer a interatividade do usuário. Você não controla o momento em que o provedor de identidade solicita que a MFA seja executada; o administrador do locatário é quem faz isso. De acordo com nossas observações, a MFA será solicitada quando você for entrar estando em um país/região diferente, quando não estiver conectado via VPN a uma rede corporativa e, às vezes, até mesmo estando conectado via VPN. Não espere que haja um conjunto determinístico de regras. O Microsoft Entra ID usa a IA (inteligência artificial) para aprender continuamente se a MFA é necessária. Faça o fallback para um prompt de usuário como uma autenticação interativa ou um fluxo de código de dispositivo caso a IWA falhe.

• A autoridade passada em PublicClientApplicationBuilder precisa ser:

  • Com locatários do formulário https://login.microsoftonline.com/{tenant}/, em que tenant é o GUID que representa a ID do locatário ou um domínio associado ao locatário.
  • Para contas corporativas ou de estudante: https://login.microsoftonline.com/organizations/.
  • Não há suporte para contas pessoais da Microsoft. Você não pode usar locatários /common ou /consumers.

• Como a Autenticação Integrada do Windows é um fluxo silencioso:

  • O usuário do seu aplicativo deve ter consentido o uso do aplicativo anteriormente.
  • Ou, o administrador de locatários deve ter consentido o uso do aplicativo anteriormente para todos os usuários no locatário.
  • Em outras palavras:
    • Ou você, como desenvolvedor, selecionou o botão Concessão no portal do Azure por conta própria.
    • Ou, um administrador de locatários selecionou o botão Conceder/revogar consentimento do administrador para {domínio de locatário} na guia Permissões de API do registro do aplicativo. Para obter mais informações, confira Adicionar permissões para acessar sua API Web.
    • Ou, você forneceu uma forma de os usuários consentirem com o aplicativo. Para obter mais informações, consulte Solicitar consentimento de usuário individual.
    • Ou, você forneceu uma forma de o administrador do locatário consentir com o aplicativo. Para obter mais informações, consulte Consentimento do administrador.

• Esse fluxo está habilitado para aplicativos de área de trabalho .NET, .NET e UWP.

Para obter mais informações sobre consentimento, confira Permissões e consentimento da plataforma de identidade da Microsoft.

Saiba como usá-lo

.NET

No MSAL.NET, use:

AcquireTokenByIntegratedWindowsAuth(IEnumerable<string> scopes)

Geralmente, você precisa de apenas um parâmetro (scopes). Dependendo de como o administrador do Windows configurou as políticas, os aplicativos em seu computador Windows podem não ter permissão para pesquisar o usuário conectado. Nesse caso, use um segundo método, .WithUsername(), e passe o nome de usuário conectado em um formato UPN, por exemplo, joe@contoso.com.

O exemplo a seguir apresenta o caso mais atual, com explicações dos tipos de exceções que você pode obter e suas atenuações.

static async Task GetATokenForGraph()
{
 string authority = "https://login.microsoftonline.com/contoso.com";
 string[] scopes = new string[] { "user.read" };
 IPublicClientApplication app = PublicClientApplicationBuilder
      .Create(clientId)
      .WithAuthority(authority)
      .Build();

 var accounts = await app.GetAccountsAsync();

 AuthenticationResult result = null;
 if (accounts.Any())
 {
  result = await app.AcquireTokenSilent(scopes, accounts.FirstOrDefault())
      .ExecuteAsync();
 }
 else
 {
  try
  {
   result = await app.AcquireTokenByIntegratedWindowsAuth(scopes)
      .ExecuteAsync(CancellationToken.None);
  }
  catch (MsalUiRequiredException ex)
  {
   // MsalUiRequiredException: AADSTS65001: The user or administrator has not consented to use the application
   // with ID '{appId}' named '{appName}'.Send an interactive authorization request for this user and resource.

   // you need to get user consent first. This can be done, if you are not using .NET (which does not have any Web UI)
   // by doing (once only) an AcquireToken interactive.

   // If you are using .NET or don't want to do an AcquireTokenInteractive, you might want to suggest the user to navigate
   // to a URL to consent: https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id={clientId}&response_type=code&scope=user.read

   // AADSTS50079: The user is required to use multi-factor authentication.
   // There is no mitigation - if MFA is configured for your tenant and AAD decides to enforce it,
   // you need to fallback to an interactive flows such as AcquireTokenInteractive or AcquireTokenByDeviceCode
   }
   catch (MsalServiceException ex)
   {
    // Kind of errors you could have (in ex.Message)

    // MsalServiceException: AADSTS90010: The grant type is not supported over the /common or /consumers endpoints. Please use the /organizations or tenant-specific endpoint.
    // you used common.
    // Mitigation: as explained in the message from Azure AD, the authority needs to be tenanted or otherwise organizations

    // MsalServiceException: AADSTS70002: The request body must contain the following parameter: 'client_secret or client_assertion'.
    // Explanation: this can happen if your application was not registered as a public client application in Azure AD
    // Mitigation: in the Azure portal, edit the manifest for your application and set the `allowPublicClient` to `true`
   }
   catch (MsalClientException ex)
   {
      // Error Code: unknown_user Message: Could not identify logged in user
      // Explanation: the library was unable to query the current Windows logged-in user or this user is not AD or AAD
      // joined (work-place joined users are not supported).

      // Mitigation 1: on UWP, check that the application has the following capabilities: Enterprise Authentication,
      // Private Networks (Client and Server), User Account Information

      // Mitigation 2: Implement your own logic to fetch the username (e.g. john@contoso.com) and use the
      // AcquireTokenByIntegratedWindowsAuth form that takes in the username

      // Error Code: integrated_windows_auth_not_supported_managed_user
      // Explanation: This method relies on a protocol exposed by Active Directory (AD). If a user was created in Azure
      // Active Directory without AD backing ("managed" user), this method will fail. Users created in AD and backed by
      // AAD ("federated" users) can benefit from this non-interactive method of authentication.
      // Mitigation: Use interactive authentication
   }
 }

 Console.WriteLine(result.Account.Username);
}

Para obter a lista de possíveis modificadores de AcquireTokenByIntegratedWindowsAuthentication, consulte AcquireTokenByIntegratedWindowsAuthParameterBuilder.

Java

Este extrato é dos Exemplos de código MSAL Java.

   PublicClientApplication pca = PublicClientApplication.builder(clientId)
                .authority(authority)
                .build();

        Set<IAccount> accountsInCache = pca.getAccounts().join();
        IAccount account = getAccountByUsername(accountsInCache, username);

        //Attempt to acquire token when user's account is not in the application's token cache
        IAuthenticationResult result = acquireTokenIntegratedWindowsAuth(pca, scope, account, username);
        System.out.println("Account username: " + result.account().username());
        System.out.println("Access token:     " + result.accessToken());
        System.out.println("Id token:         " + result.idToken());
        System.out.println();

        //Get list of accounts from the application's token cache, and search them for the configured username
        //getAccounts() will be empty on this first call, as accounts are added to the cache when acquiring a token
        accountsInCache = pca.getAccounts().join();
        account = getAccountByUsername(accountsInCache, username);

        //Attempt to acquire token again, now that the user's account and a token are in the application's token cache
        result = acquireTokenIntegratedWindowsAuth(pca, scope, account, username);
        System.out.println("Account username: " + result.account().username());
        System.out.println("Access token:     " + result.accessToken());
        System.out.println("Id token:         " + result.idToken());
    }

    private static IAuthenticationResult acquireTokenIntegratedWindowsAuth( PublicClientApplication pca,
                                                                            Set<String> scope,
                                                                            IAccount account,
                                                                            String username) throws Exception {

        IAuthenticationResult result;
        try {
            SilentParameters silentParameters =
                    SilentParameters
                            .builder(scope)
                            .account(account)
                            .build();
            // Try to acquire token silently. This will fail on the first acquireTokenIntegratedWindowsAuth() call
            // because the token cache does not have any data for the user you are trying to acquire a token for
            result = pca.acquireTokenSilently(silentParameters).join();
            System.out.println("==acquireTokenSilently call succeeded");
        } catch (Exception ex) {
            if (ex.getCause() instanceof MsalException) {
                System.out.println("==acquireTokenSilently call failed: " + ex.getCause());
                IntegratedWindowsAuthenticationParameters parameters =
                        IntegratedWindowsAuthenticationParameters
                                .builder(scope, username)
                                .build();

                // Try to acquire a token using Integrated Windows Authentication (IWA). You will need to generate a Kerberos ticket.
                // If successful, you should see the token and account information printed out to console
                result = pca.acquireToken(parameters).join();
                System.out.println("==Integrated Windows Authentication flow succeeded");
            } else {
                // Handle other exceptions accordingly
                throw ex;
            }
        }
        return result;
    }

macOS

Esse fluxo não se aplica ao macOS.

Node.js

Ainda não há suporte para esse fluxo no nó MSAL.

Python

Ainda não há suporte para esse fluxo na MSAL Python.

Próximas etapas

Vá para o próximo artigo desse cenário, Chamar uma API Web a partir do aplicativo da área de trabalho.