Desktop-app die web-API's aanroept: Een token verkrijgen met behulp van geïntegreerde Windows-verificatie

Als u zich wilt aanmelden bij een domeingebruiker op een domein of computer die is toegevoegd aan Microsoft Entra, gebruikt u geïntegreerde Windows-verificatie (IWA).

Beperkingen

• Geïntegreerde Windows-verificatie is alleen beschikbaar voor federatieve+ gebruikers, dat wil gezegd: gebruikers die zijn gemaakt in Active Directory en worden ondersteund door Microsoft Entra-id. Gebruikers die rechtstreeks in Microsoft Entra ID zijn gemaakt zonder Active Directory-backing, ook wel beheerde gebruikers genoemd, kunnen deze verificatiestroom niet gebruiken. Deze beperking heeft geen invloed op de gebruikersnaam- en wachtwoordstroom.

• IWA omzeilt meervoudige verificatie (MFA) niet. Als MFA is geconfigureerd, kan IWA mislukken als er een MFA-uitdaging is vereist, omdat MFA gebruikersinteractie vereist.

  IWA is niet-interactief, maar MFA vereist interactiviteit van gebruikers. Wanneer de id-provider aanvraagt dat MFA wordt uitgevoerd, wordt niet door u bepaald, maar door de tenantbeheerder. Van wat we hebben gezien, is MFA vereist wanneer u zich aanmeldt vanuit een ander(e) land/regio, wanneer u niet via VPN bent verbonden met een bedrijfsnetwerk, en soms zelfs wanneer u wel via VPN bent verbonden. Verwacht geen deterministische set regels. Microsoft Entra ID maakt gebruik van AI om continu te leren of MFA vereist is. Val terug op een gebruikersprompt zoals interactieve verificatie of een apparaatcodestroom als IWA mislukt.

• De instantie die is doorgegeven bij PublicClientApplicationBuilder, moet het volgende zijn:

  • Met tenant in de vorm https://login.microsoftonline.com/{tenant}/, waarbij tenant de GUID is die de tenant-id vertegenwoordigt of een domein is dat aan de tenant is gekoppeld.
  • Voor werk- en schoolaccounts: https://login.microsoftonline.com/organizations/.
  • Persoonlijke Microsoft-accounts worden niet ondersteund. U kunt geen /common- of /consumers-tenants gebruiken.

• Omdat geïntegreerde Windows-verificatie een stroom op de achtergrond is:

  • Moet de gebruiker van uw toepassing eerder toestemming hebben gegeven om de toepassing te kunnen gebruiken.
  • Of moet de tenantbeheerder eerder toestemming hebben gegeven voor alle gebruikers in de tenant om de toepassing te kunnen gebruiken.
  • Met andere woorden:
    • Ofwel u als ontwikkelaar hebt de knop Verlenen in de Azure-portal voor uzelf geselecteerd.
    • Ofwel een tenantbeheerder heeft de knop Beheerderstoestemming verlenen/intrekken voor {tenantdomein} geselecteerd op het tabblad API-machtigingen van de registratie voor de toepassing. Zie Machtigingen toevoegen voor toegang tot uw web-API voor meer informatie.
    • Of u hebt een manier opgegeven voor gebruikers om toestemming te geven voor de toepassing. Zie Individuele gebruikerstoestemming aanvragen voor meer informatie.
    • Of u hebt een manier opgegeven voor de tenantbeheerder om toestemming te geven voor de toepassing. Zie Beheerderstoestemming voor meer informatie.

• Deze stroom is ingeschakeld voor .NET-desktop-, .NET- en UWP-apps.

Zie Machtigingen en toestemming op het Microsoft-identiteitsplatform voor meer informatie over toestemming.

Meer informatie over het gebruik ervan

.NET

Gebruik in MSAL.NET:

AcquireTokenByIntegratedWindowsAuth(IEnumerable<string> scopes)

Normaal gesproken hebt u slechts één parameter (scopes) nodig. Afhankelijk van de manier waarop uw Windows-beheerder de beleidsregels instelt, mogen toepassingen op uw Windows-computer de aangemelde gebruiker mogelijk niet opzoeken. In dat geval gebruikt u een tweede methode, .WithUsername(), en geeft u de gebruikersnaam van de aangemelde gebruiker in UPN-indeling door, bijvoorbeeld joe@contoso.com.

Het volgende voorbeeld toont de meest recente case, met uitleg over het soort uitzonderingen dat u kunt krijgen en de bijbehorende beperkingen.

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);
}

Zie AcquireTokenByIntegratedWindowsAuthParameterBuilder voor de lijst met mogelijke modifiers op AcquireTokenByIntegratedWindowsAuthentication.

Java

Dit extract is afkomstig uit de MSAL Java-codevoorbeelden.

   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

Deze stroom is niet van toepassing op macOS.

Node.js

Deze stroom wordt nog niet ondersteund in MSAL Node.

Python

Deze stroom wordt nog niet ondersteund in MSAL Python.

Volgende stappen

Ga verder met het volgende artikel in dit scenario, Een web-API aanroepen vanuit de desktop-app.