Web-API, die Web-APIs aufruft: Codekonfiguration

Sobald die Registrierung für eine Web-API abgeschlossen ist, kann der Anwendungscode konfiguriert werden. Das Konfigurieren einer Web-API zum Aufrufen einer nachgeschalteten Web-API basiert auf dem Code, der zum Schutz einer Web-API verwendet wird. Weitere Informationen finden Sie unter Geschützte Web-API: App-Konfiguration.

Microsoft.Identity.Web

Microsoft empfiehlt die Verwendung des NuGet-Pakets Microsoft.Identity.Web beim Entwickeln einer geschützten ASP.NET Core-API, die Downstream-Web-APIs aufruft. Weitere Informationen finden Sie unter Geschützte Web-API: Codekonfiguration | Microsoft.Identity.Web finden Sie eine kurze Präsentation dieser Bibliothek im Kontext einer Web-API.

ASP.NET Core

Geheime Clientschlüssel oder Clientzertifikate

Wenn Ihre Web-App jetzt eine Downstream-Web-API aufruft, geben Sie in der Datei appsettings.json einen geheimen Clientschlüssel oder ein Clientzertifikat an. Sie können auch einen Abschnitt hinzufügen, in dem Folgendes angegeben wird:

• Die URL der Downstream-Web-API
• Die zum Aufrufen der API erforderlichen Bereiche

Im folgenden Beispiel sind diese Einstellungen im Abschnitt GraphBeta angegeben.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Enter_the_Application_Id_Here]",
    "TenantId": "common",

   // To call an API
   "ClientCredentials": [
    {
      "SourceType": "ClientSecret",
      "ClientSecret":"[Enter_the_Client_Secret_Here]"
    }
  ]
 },
 "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": ["user.read"]
    }
}

Hinweis

Sie können eine Sammlung von Clientanmeldeinformationen vorschlagen, einschließlich einer Lösung ohne Anmeldeinformationen wie Workloadidentitätsverbund für Azure Kubernetes. In früheren Versionen von Microsoft.Identity.Web wurde der geheime Clientschlüssel in einer einzelnen Eigenschaft namens „ClientSecret“ anstelle von „ClientCredentials“ ausgedrückt. Dies wird aus Gründen der Abwärtskompatibilität weiterhin unterstützt, Sie können aber nicht sowohl die Eigenschaft „ClientSecret“ als auch die Sammlung „ClientCredentials“ verwenden.

Statt eines geheimen Clientschlüssels können Sie ein Clientzertifikat angeben. Im folgenden Codeausschnitt ist die Verwendung eines in Azure Key Vault gespeicherten Zertifikats dargestellt.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Enter_the_Application_Id_Here]",
    "TenantId": "common",

   // To call an API
   "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
        "KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
      }
   ]
  },
  "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": ["user.read"]
  }
}

Warnung

Wenn Sie vergessen, die Scopes in ein Array zu ändern, erscheinen die Scopes bei der Verwendung der IDownstreamApi als Null und die IDownstreamApi versucht einen anonymen (unauthentifizierten) Aufruf der Downstream API, was zu 401/unauthenticated führt.

Microsoft.Identity.Web bietet verschiedene Möglichkeiten, Zertifikate zu beschreiben, sowohl durch Konfiguration als auch durch Code. Weitere Informationen finden Sie unter Microsoft.Identity.Web: Verwenden von Zertifikaten auf GitHub.

Program.cs

using Microsoft.Identity.Web;

// ...
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(Configuration, Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();
// ...

Eine Web-API muss ein Token für die Downstream-API abrufen. Die Angabe erfolgt durch Hinzufügen der Zeile .EnableTokenAcquisitionToCallDownstreamApi() nach .AddMicrosoftIdentityWebApi(Configuration). Diese Zeile macht den ITokenAcquisition-Dienst verfügbar, der in Controller-/Seitenaktionen verwendet werden kann.

Als alternative Methode kann jedoch auch ein Tokencache implementiert werden. Durch das Hinzufügen von .AddInMemoryTokenCaches() zu Program.cs kann das Token beispielsweise im Arbeitsspeicher zwischengespeichert werden.

using Microsoft.Identity.Web;

// ...
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(Configuration, Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddInMemoryTokenCaches();
// ...

Microsoft.Identity.Web stellt zwei Mechanismen zum Aufrufen einer nachgeschalteten Web-API über eine andere API bereit. Welche Option Sie auswählen, hängt davon ab, ob Sie Microsoft Graph oder eine andere API aufrufen möchten.

Option 1: Aufrufen von Microsoft Graph

Zum Aufrufen von Microsoft Graph bietet Microsoft.Identity.Web die Möglichkeit, den (über das Microsoft Graph SDK verfügbar gemachten) GraphServiceClient in den API-Aktionen direkt zu verwenden.

Hinweis

Es gibt ein anhaltendes Problem mit Microsoft Graph SDK v5 und höher. Weitere Informationen finden Sie unter GitHub-Problem.

Gehen Sie wie folgt vor, um Microsoft Graph verfügbar zu machen:

1. Fügen Sie dem Projekt das NuGet-Paket Microsoft.Identity.Web.GraphServiceClient hinzu.
2. Fügen Sie .AddMicrosoftGraph() nach .EnableTokenAcquisitionToCallDownstreamApi() in Program.cs hinzu. .AddMicrosoftGraph() verfügt über mehrere Überschreibungen. Wenn Sie die Überschreibung verwenden, die einen Konfigurationsabschnitt als Parameter annimmt, sieht der Code wie folgt aus:

using Microsoft.Identity.Web;

// ...
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(Configuration, Configuration.GetSection("AzureAd"))
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddMicrosoftGraph(Configuration.GetSection("GraphBeta"))
    .AddInMemoryTokenCaches();
// ...

Option 2: Aufrufen einer anderen Downstream-Web-API als Microsoft Graph

1. Fügen Sie dem Projekt das NuGet-Paket Microsoft.Identity.Web.DownstreamApi hinzu.
2. Fügen Sie .AddDownstreamApi() nach .EnableTokenAcquisitionToCallDownstreamApi() in Program.cs hinzu. Der Code ändert sich wie folgt:

using Microsoft.Identity.Web;

// ...
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(Configuration, "AzureAd")
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("MyApi", Configuration.GetSection("MyApiScope"))
    .AddInMemoryTokenCaches();
// ...

Dabei gilt:

• MyApi gibt den Namen der nachgeschalteten Web-API an, die Ihre Web-API aufrufen möchte
• MyApiScope ist der Bereich, der für Ihre Web-API erforderlich ist, um mit der nachgeschalteten Web-API zu interagieren.

Diese Werte werden in Ihrem JSON-Code dargestellt, der dem folgenden Codeschnipsel ähnelt.

"DownstreamAPI": {
      "BaseUrl": "https://downstreamapi.contoso.com/",
      "Scopes": "user.read"
    },

Wenn die Web-App eine andere API-Ressource aufrufen muss, wiederholen Sie die .AddDownstreamApi() Methode mit dem relevanten Bereich, wie im folgenden Ausschnitt gezeigt:

using Microsoft.Identity.Web;

// ...
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(Configuration, "AzureAd")
    .EnableTokenAcquisitionToCallDownstreamApi()
    .AddDownstreamApi("MyApi", Configuration.GetSection("MyApiScope"))
    .AddDownstreamApi("MyApi2", Configuration.GetSection("MyApi2Scope"))
    .AddInMemoryTokenCaches();
// ...

Beachten Sie, dass .EnableTokenAcquisitionToCallDownstreamApi ohne Parameter aufgerufen wird. Dies bedeutet, dass das Zugriffstoken just in time abgerufen wird, während der Controller das Token durch Angabe des Bereichs anfordert.

Der Bereich kann auch beim Aufrufen von .EnableTokenAcquisitionToCallDownstreamApi übergeben werden, wodurch die Web-App das Token während der ersten Benutzeranmeldung selbst abruft. Das Token wird dann aus dem Cache abgerufen, wenn der Controller es anfordert.

Ähnlich wie bei Web-Apps stehen verschiedene Tokencacheimplementierungen zur Auswahl. Weitere Informationen finden Sie unter Microsoft.Identity.Web: Tokencacheserialisierung auf GitHub.

In der folgenden Abbildung sind die Möglichkeiten von Microsoft.Identity.Web und die Auswirkungen auf Program.cs dargestellt:

Hinweis

Um die hier aufgeführten Codebeispiele in vollem Umfang zu verstehen, müssen Sie mit den ASP.NET Core-Grundlagen und insbesondere mit der Abhängigkeitsinjektion und den Optionen vertraut sein.

ASP.NET

Geheime Clientschlüssel oder Clientzertifikate

Wenn Ihre Web-App jetzt eine Downstream-Web-API aufruft, geben Sie in der Datei appsettings.json einen geheimen Clientschlüssel oder ein Clientzertifikat an. Sie können auch einen Abschnitt hinzufügen, in dem Folgendes angegeben wird:

• Die URL der Downstream-Web-API
• Die zum Aufrufen der API erforderlichen Bereiche

Im folgenden Beispiel sind diese Einstellungen im Abschnitt GraphBeta angegeben.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Enter_the_Application_Id_Here]",
    "TenantId": "common",

   // To call an API
   "ClientCredentials": [
    {
      "SourceType": "ClientSecret",
      "ClientSecret":"[Enter_the_Client_Secret_Here]"
    }
  ]
 },
 "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": ["user.read"]
    }
}

Hinweis

Sie können eine Sammlung von Clientanmeldeinformationen vorschlagen, einschließlich einer Lösung ohne Anmeldeinformationen wie Workloadidentitätsverbund für Azure Kubernetes. In früheren Versionen von Microsoft.Identity.Web wurde der geheime Clientschlüssel in einer einzelnen Eigenschaft namens „ClientSecret“ anstelle von „ClientCredentials“ ausgedrückt. Dies wird aus Gründen der Abwärtskompatibilität weiterhin unterstützt, Sie können aber nicht sowohl die Eigenschaft „ClientSecret“ als auch die Sammlung „ClientCredentials“ verwenden.

Statt eines geheimen Clientschlüssels können Sie ein Clientzertifikat angeben. Im folgenden Codeausschnitt ist die Verwendung eines in Azure Key Vault gespeicherten Zertifikats dargestellt.

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "[Enter_the_Application_Id_Here]",
    "TenantId": "common",

   // To call an API
   "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
        "KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
      }
   ]
  },
  "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": ["user.read"]
  }
}

Warnung

Wenn Sie vergessen, die Scopes in ein Array zu ändern, erscheinen die Scopes bei der Verwendung der IDownstreamApi als Null und die IDownstreamApi versucht einen anonymen (unauthentifizierten) Aufruf der Downstream API, was zu 401/unauthenticated führt.

Microsoft.Identity.Web bietet verschiedene Möglichkeiten, Zertifikate zu beschreiben, sowohl durch Konfiguration als auch durch Code. Weitere Informationen finden Sie unter Microsoft.Identity.Web: Verwenden von Zertifikaten auf GitHub.

Ändern von Startup.Auth.cs

Ihre Web-App muss ein Token für die Downstream-API abrufen. Microsoft.Identity.Web bietet zwei Mechanismen zum Aufrufen einer Downstream-API über eine Web-API. Welche Option Sie auswählen, hängt davon ab, ob Sie Microsoft Graph oder eine andere API aufrufen möchten.

Option 1: Aufrufen von Microsoft Graph

Wenn Sie Microsoft Graph aufrufen möchten, bietet Microsoft.Identity.Web die Möglichkeit, den (über das Microsoft Graph SDK verfügbar gemachten) GraphServiceClient in Ihren API-Aktionen direkt zu verwenden. Gehen Sie wie folgt vor, um Microsoft Graph verfügbar zu machen:

1. Fügen Sie Ihrem Projekt das NuGet-Paket Microsoft.Identity.Web.GraphServiceClient hinzu.

2. Fügen Sie .AddMicrosoftGraph() der Dienstsammlung in der Datei Startup.Auth.cs hinzu. .AddMicrosoftGraph() verfügt über mehrere Überschreibungen. Wenn Sie die Überschreibung verwenden, die einen Konfigurationsabschnitt als Parameter annimmt, sieht der Code wie folgt aus:

   using Microsoft.Extensions.DependencyInjection;
   using Microsoft.Identity.Client;
   using Microsoft.Identity.Web;
   using Microsoft.Identity.Web.OWIN;
   using Microsoft.Identity.Web.TokenCacheProviders.InMemory;
   using Microsoft.IdentityModel.Validators;
   using Microsoft.Owin.Security;
   using Microsoft.Owin.Security.Cookies;
   using Owin;
   
   namespace WebApp
   {
      public partial class Startup
      {
          public void ConfigureAuth(IAppBuilder app)
          {
              app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);
   
              app.UseCookieAuthentication(new CookieAuthenticationOptions());
   
              // Get an TokenAcquirerFactory specialized for OWIN
              OwinTokenAcquirerFactory owinTokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();
   
              // Configure the web app.
              app.AddMicrosoftIdentityWebApi(owinTokenAcquirerFactory);
   
              // Add the services you need.
              owinTokenAcquirerFactory.Services
                  .AddMicrosoftGraph()
                  .AddInMemoryTokenCaches();
              owinTokenAcquirerFactory.Build();
          }
      }
   }
   

Option 2: Aufrufen einer anderen Downstream-Web-API als Microsoft Graph

Wenn Sie eine andere API als Microsoft Graph aufrufen möchten, bietet Microsoft.Identity.Web die Möglichkeit, die IDownstreamApi-Schnittstelle in Ihren API-Aktionen zu verwenden. So verwenden Sie diese Schnittstelle

1. Fügen Sie Ihrem Projekt das NuGet-Paket Microsoft.Identity.Web.DownstreamApi hinzu.
2. Fügen Sie in der Datei Startup.cs nach .EnableTokenAcquisitionToCallDownstreamApi() den Eintrag .AddDownstreamApi() hinzu. .AddDownstreamApi() hat zwei Argumente:
   • Name eines Diensts (API): Sie verwenden diesen Namen in Ihren Controlleraktionen, um auf die entsprechende Konfiguration zu verweisen.
   • Konfigurationsabschnitt, der die Parameter darstellt, die zum Aufrufen der Downstream-Web-API verwendet werden

Der Code lautet wie folgt:

  using Microsoft.Extensions.DependencyInjection;
  using Microsoft.Identity.Client;
  using Microsoft.Identity.Web;
  using Microsoft.Identity.Web.OWIN;
  using Microsoft.Identity.Web.TokenCacheProviders.InMemory;
  using Microsoft.IdentityModel.Validators;
  using Microsoft.Owin.Security;
  using Microsoft.Owin.Security.Cookies;
  using Owin;

  namespace WebApp
  {
      public partial class Startup
      {
          public void ConfigureAuth(IAppBuilder app)
          {
              app.SetDefaultSignInAsAuthenticationType(CookieAuthenticationDefaults.AuthenticationType);

              app.UseCookieAuthentication(new CookieAuthenticationOptions());

              // Get a TokenAcquirerFactory specialized for OWIN.
              OwinTokenAcquirerFactory owinTokenAcquirerFactory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();

              // Configure the web app.
              app.AddMicrosoftIdentityWebApi(owinTokenAcquirerFactory);

              // Add the services you need.
              owinTokenAcquirerFactory.Services
                  .AddDownstreamApi("Graph", owinTokenAcquirerFactory.Configuration.GetSection("GraphBeta"))
                  .AddInMemoryTokenCaches();
              owinTokenAcquirerFactory.Build();
          }
      }
  }

Java

Der On-Behalf-Of-Fluss (OBO) wird verwendet, um ein Token zum Aufrufen der Downstream-Web-API abzurufen. In diesem Flow empfängt Ihre Web-API ein Bearertoken mit den vom Benutzer delegierten Berechtigungen von der Clientanwendung und tauscht dieses Token dann mit einem anderen Zugriffstoken aus, um die Downstream-Web-API aufzurufen.

Der folgende Code verwendet den SecurityContextHolder des Spring Security-Frameworks in der Web-API, um das überprüfte Bearertoken abzurufen. Anschließend wird mithilfe der MSAL-Java-Bibliothek ein Token für die Downstream-API über einen acquireToken-Aufruf mit OnBehalfOfParameters abgerufen. MSAL speichert das Token zwischen, damit für nachfolgende Aufrufe der API acquireTokenSilently verwendet werden kann, um das zwischengespeicherte Token abzurufen.

@Component
class MsalAuthHelper {

    @Value("${security.oauth2.client.authority}")
    private String authority;

    @Value("${security.oauth2.client.client-id}")
    private String clientId;

    @Value("${security.oauth2.client.client-secret}")
    private String secret;

    @Autowired
    CacheManager cacheManager;

    private String getAuthToken(){
        String res = null;
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();

        if(authentication != null){
            res = ((OAuth2AuthenticationDetails) authentication.getDetails()).getTokenValue();
        }
        return res;
    }

    String getOboToken(String scope) throws MalformedURLException {
        String authToken = getAuthToken();

        ConfidentialClientApplication application =
                ConfidentialClientApplication.builder(clientId, ClientCredentialFactory.create(secret))
                        .authority(authority).build();

        String cacheKey = Hashing.sha256()
                .hashString(authToken, StandardCharsets.UTF_8).toString();

        String cachedTokens = cacheManager.getCache("tokens").get(cacheKey, String.class);
        if(cachedTokens != null){
            application.tokenCache().deserialize(cachedTokens);
        }

        IAuthenticationResult auth;
        SilentParameters silentParameters =
                SilentParameters.builder(Collections.singleton(scope))
                        .build();
        auth = application.acquireTokenSilently(silentParameters).join();

        if (auth == null){
            OnBehalfOfParameters parameters =
                    OnBehalfOfParameters.builder(Collections.singleton(scope),
                            new UserAssertion(authToken))
                            .build();

            auth = application.acquireToken(parameters).join();
        }

        cacheManager.getCache("tokens").put(cacheKey, application.tokenCache().serialize());

        return auth.accessToken();
    }
}

Python

Der On-Behalf-Of-Fluss (OBO) wird verwendet, um ein Token zum Aufrufen der Downstream-Web-API abzurufen. In diesem Flow empfängt Ihre Web-API ein Bearertoken mit den vom Benutzer delegierten Berechtigungen von der Clientanwendung und tauscht dieses Token dann mit einem anderen Zugriffstoken aus, um die Downstream-Web-API aufzurufen.

Eine Python-Web-API muss eine Middleware verwenden, um das vom Client empfangene Bearertoken zu überprüfen. Die Web-API kann dann das Zugriffstoken für die Downstream-API mithilfe der MSAL-Python-Bibliothek über einen Aufruf der acquire_token_on_behalf_of-Methode abrufen. Ein Beispiel zur Verwendung dieser API finden Sie im Testcode für microsoft-authentication-library-for-python in GitHub. Siehe auch die Erörterung von Issue 53 im selben Repository zum Ansatz, der die Notwendigkeit einer Anwendung auf mittlerer Ebene umgeht.

Ein Beispiel für die Implementierung des OBO-Flusses finden Sie auch im Beispiel ms-identity-python-on-behalf-of.

Ein Beispiel für die Implementierung des OBO-Flusses finden Sie auch unter Node.js und Azure Functions.

Protocol

Weitere Informationen zum OBO-Protokoll finden Sie unter Microsoft Identity Platform und der On-Behalf-Of-Flow von OAuth 2.0.

Nächste Schritte

Fahren Sie mit dem nächsten Artikel in diesem Szenario fort: Abrufen eines Tokens für die App.