Abrufen von Token zum Aufrufen einer Web-API mithilfe einer Daemonanwendung

Artikel
04/09/2024

Nachdem die vertrauliche Clientanwendung erstellt wurde, können Sie ein Token für die App abrufen, indem Sie AcquireTokenForClient aufrufen, den Bereich übergeben und ggf. die Aktualisierung des Tokens erzwingen.

Anzufordernde Bereiche

Der anzufordernde Bereich für einen Anmeldeinformationsfluss für Clients ist der Name der Ressource, gefolgt von /.default. Durch diese Notation weiß Microsoft Entra ID, dass die Berechtigungen auf Anwendungsebene verwendet werden sollen, die im Zuge der Anwendungsregistrierung statisch deklariert wurden. Außerdem müssen diese API-Berechtigungen von einem Mandantenadministrator gewährt werden.

Hier sehen Sie ein Beispiel für die Definition der Bereiche für die Web-API als Teil der Konfiguration in einer Datei vom Typ appsettings.json. Dieses Beispiel stammt aus dem Codebeispiel .NET-Konsolen-Daemon auf GitHub.

{
    "AzureAd": {
        // Same AzureAd section as before.
    },

    "MyWebApi": {
        "BaseUrl": "https://localhost:44372/",
        "RelativePath": "api/TodoList",
        "RequestAppToken": true,
        "Scopes": [ "[Enter here the scopes for your web API]" ]
    }
}

final static String GRAPH_DEFAULT_SCOPE = "https://graph.microsoft.com/.default";

const tokenRequest = {
    scopes: [process.env.GRAPH_ENDPOINT + '.default'], // e.g. 'https://graph.microsoft.com/.default'
};

In MSAL Python sieht die Konfigurationsdatei wie der folgende Codeausschnitt aus:

{
    "scope": ["https://graph.microsoft.com/.default"],
}

ResourceId = "someAppIDURI";
var scopes = new [] {  ResourceId+"/.default"};

Azure AD-Ressourcen (v1.0)

Der für die Clientanmeldeinformationen verwendete Bereich muss immer die Ressourcen-ID gefolgt von /.default sein.

Wichtig

Wenn MSAL ein Zugriffstoken für eine Ressource anfordert, die ein Zugriffstoken der Version 1.0 akzeptiert, analysiert Microsoft Entra ID die gewünschte Zielgruppe aus dem angeforderten Bereich, indem alles vor dem letzten Schrägstrich als Ressourcenbezeichner verwendet wird. Wenn also, wie bei Azure SQL Database (https://database.windows.net), die Ressource eine Zielgruppe erwartet, die mit einem Schrägstrich endet (für Azure SQL Database, https://database.windows.net/), müssen Sie einen Bereich von https://database.windows.net//.default anfordern. (Beachten Sie den doppelten Schrägstrich.) Siehe auch MSAL.NET Ausgabe #747: Resource url's trailing slash is omitted, which caused sql auth failure.

AcquireTokenForClient-API

Verwenden Sie zum Abrufen eines Tokens für die App AcquireTokenForClient oder die Entsprechung für die jeweilige Plattform.

Bei Microsoft.Identity.Web müssen Sie kein Token abrufen. Sie können APIs höherer Ebene verwenden, wie unter Daemon-App, die Web-APIs aufruft – Aufrufen einer Web-API aus der App erläutert. Wenn Sie jedoch ein SDK verwenden, das ein Token erfordert, zeigt der folgende Codeschnipsel, wie Sie dieses Token abrufen.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web;

// In the Program.cs, acquire a token for your downstream API

var tokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance();
ITokenAcquirer acquirer = tokenAcquirerFactory.GetTokenAcquirer();
AcquireTokenResult tokenResult = await acquirer.GetTokenForUserAsync(new[] { "https://graph.microsoft.com/.default" });
string accessToken = tokenResult.AccessToken;

Dies ist ein Codeauszug aus den MSAL Java-Entwicklungsbeispielen.

private static IAuthenticationResult acquireToken() throws Exception {

     // Load token cache from file and initialize token cache aspect. The token cache will have
     // dummy data, so the acquireTokenSilently call will fail.
     TokenCacheAspect tokenCacheAspect = new TokenCacheAspect("sample_cache.json");

     IClientCredential credential = ClientCredentialFactory.createFromSecret(CLIENT_SECRET);
     ConfidentialClientApplication cca =
             ConfidentialClientApplication
                     .builder(CLIENT_ID, credential)
                     .authority(AUTHORITY)
                     .setTokenCacheAccessAspect(tokenCacheAspect)
                     .build();

     IAuthenticationResult result;
     try {
         SilentParameters silentParameters =
                 SilentParameters
                         .builder(SCOPE)
                         .build();

         // try to acquire token silently. This call will fail since the token cache does not
         // have a token for the application you are requesting an access token for
         result = cca.acquireTokenSilently(silentParameters).join();
     } catch (Exception ex) {
         if (ex.getCause() instanceof MsalException) {

             ClientCredentialParameters parameters =
                     ClientCredentialParameters
                             .builder(SCOPE)
                             .build();

             // Try to acquire a token. If successful, you should see
             // the token information printed out to console
             result = cca.acquireToken(parameters).join();
         } else {
             // Handle other exceptions accordingly
             throw ex;
         }
     }
     return result;
 }

Der folgende Codeschnipsel veranschaulicht den Tokenabruf in einer vertraulichen MSAL Node-Clientanwendung:

try {
    const authResponse = await cca.acquireTokenByClientCredential(tokenRequest);
    console.log(authResponse.accessToken) // display access token
} catch (error) {
    console.log(error);
}

# The pattern to acquire a token looks like this.
result = None

# First, the code looks up a token from the cache.
# Because we're looking for a token for the current app, not for a user,
# use None for the account parameter.
result = app.acquire_token_silent(config["scope"], account=None)

if not result:
    logging.info("No suitable token exists in cache. Let's get a new one from Azure AD.")
    result = app.acquire_token_for_client(scopes=config["scope"])

if "access_token" in result:
    # Call a protected API with the access token.
    print(result["token_type"])
else:
    print(result.get("error"))
    print(result.get("error_description"))
    print(result.get("correlation_id"))  # You might need this when reporting a bug.

using Microsoft.Identity.Client;

// With client credentials flows, the scope is always of the shape "resource/.default" because the
// application permissions need to be set statically (in the portal or by PowerShell), and then granted by
// a tenant administrator.
string[] scopes = new string[] { "https://graph.microsoft.com/.default" };

AuthenticationResult result = null;
try
{
 result = await app.AcquireTokenForClient(scopes)
                  .ExecuteAsync();
}
catch (MsalUiRequiredException ex)
{
    // The application doesn't have sufficient permissions.
    // - Did you declare enough app permissions during app creation?
    // - Did the tenant admin grant permissions to the application?
}
catch (MsalServiceException ex) when (ex.Message.Contains("AADSTS70011"))
{
    // Invalid scope. The scope has to be in the form "https://resourceurl/.default"
    // Mitigation: Change the scope to be as expected.
}

AcquireTokenForClient verwendet den Anwendungstokencache.

In MSAL.NET verwendet AcquireTokenForClient den Anwendungstokencache. (Alle anderen AcquireTokenXX-Methoden verwenden den Benutzertokencache.) Rufen Sie AcquireTokenSilent nicht vor AcquireTokenForClient auf, da AcquireTokenSilent den Benutzertokencache verwendet. AcquireTokenForClient überprüft den Anwendungstokencache selbst und aktualisiert diesen.

Protocol

Wenn Sie noch nicht über eine Bibliothek für die Programmiersprache Ihrer Wahl verfügen, können Sie das Protokoll auch direkt verwenden:

Erster Fall: Zugreifen auf die Tokenanforderung mit einem freigegebenen Geheimnis

POST /{tenant}/oauth2/v2.0/token HTTP/1.1           //Line breaks for clarity.
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=00001111-aaaa-2222-bbbb-3333cccc4444
&scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_secret=A1b-C2d_E3f.H4i,J5k?L6m!N7o-P8q_R9s.T0u
&grant_type=client_credentials

Zweiter Fall: Zugreifen auf die Tokenanforderung mit einem Zertifikat

POST /{tenant}/oauth2/v2.0/token HTTP/1.1               // Line breaks for clarity.
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

scope=https%3A%2F%2Fgraph.microsoft.com%2F.default
&client_id=11112222-bbbb-3333-cccc-4444dddd5555
&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer
&client_assertion=aaaaaaaa-0b0b-...
&grant_type=client_credentials

Weitere Informationen finden Sie in der Protokolldokumentation: Microsoft Identity Platform und der Fluss von OAuth 2.0-Clientanmeldeinformationen.

Problembehandlung

Haben Sie den Bereich „resource/.default“ verwendet?

Wenn Ihnen eine Fehlermeldung angezeigt wird, nach der Sie einen ungültigen Bereich verwendet haben, haben Sie wahrscheinlich nicht den Bereich resource/.default verwendet.

Wenn Ihnen beim Aufruf der API die Fehlermeldung Nicht genügend Berechtigungen zum Abschließen des Vorgangs angezeigt wird, muss der Mandantenadministrator der Anwendung Berechtigungen gewähren.

Wenn Sie Ihrer Anwendung keine Administratoreinwilligung erteilen, tritt der folgende Fehler auf:

Failed to call the web API: Forbidden
Content: {
  "error": {
    "code": "Authorization_RequestDenied",
    "message": "Insufficient privileges to complete the operation.",
    "innerError": {
      "request-id": "<guid>",
      "date": "<date>"
    }
  }
}

Wählen Sie je nach Rolle eine der folgenden Optionen aus.

Globaler Mandantenadministrator

Navigieren Sie als globaler Mandantenadministrator im Microsoft Entra Admin Center zu Unternehmensanwendungen. Wählen Sie die App-Registrierung und dann im linken Bereich im Abschnitt Sicherheit die Option Berechtigungen aus. Wählen Sie anschließend die große Schaltfläche mit der Bezeichnung Administratoreinwilligung für {Mandantenname} erteilen aus. (Dabei ist {Mandantenname} der Name des Verzeichnisses.)

Standardbenutzer

Wenn Sie ein Standardbenutzerkonto auf Ihrem Mandanten haben, müssen Sie einen Globalen Admin um die Erteilung der Administratoreinwilligung für die Anwendung bitten. Übermitteln Sie hierzu die folgende URL an den Administrator:

https://login.microsoftonline.com/Enter_the_Tenant_Id_Here/adminconsent?client_id=Enter_the_Application_Id_Here

In der URL gilt Folgendes:

Ersetzen Sie Enter_the_Tenant_Id_Here durch die Mandanten-ID oder den Mandanten Namen (z. B.contoso.microsoft.com).
Enter_the_Application_Id_Here ist die Anwendungs-ID (Client-ID) für die registrierte Anwendung.

Möglicherweise wird der Fehler AADSTS50011: No reply address is registered for the application angezeigt, nachdem Sie der App mithilfe der vorherigen URL Ihre Zustimmung erteilt haben. Dieser Fehler tritt auf, weil die Anwendung und die URL keinen Umleitungs-URI haben. Sie können diese Warnmeldung ignorieren.

Rufen Sie Ihre eigene API auf?

Wenn Ihre Daemon-App eine eigene Web-API aufruft und Sie keine App-Berechtigung zur App-Registrierung des Daemons hinzufügen konnten, müssen Sie App-Rollen zur App-Registrierung der Web-API hinzufügen.

Nächste Schritte

Fahren Sie mit dem nächsten Artikel in diesem Szenario fort: Aufrufen einer Web-API.