Webové rozhraní API pro volání jiných rozhraní API: Konfigurace kódu

Platí pro: Tenanti pracovních sil (další informace)

Tento článek popisuje, jak nakonfigurovat kód pro aplikaci webového rozhraní API pomocí toku autorizačního kódu OAuth 2.0.

Microsoft doporučuje použít balíček NuGet Microsoft.Identity.Web při vývoji chráněného rozhraní API v ASP.NET Core, které volá podřízené webové rozhraní API. Viz Chráněné webové rozhraní API: Konfigurace kódu | Microsoft.Identity.Web pro rychlou prezentaci této knihovny v kontextu webového rozhraní API.

Požadavky

• Účet Azure s aktivním předplatným. Vytvořte si bezplatný účet. Tento účet musí mít oprávnění ke správě aplikací. K registraci aplikace použijte některou z následujících rolí:
  • Správce aplikace
  • Vývojář aplikací
• Zaregistrujte novou aplikaci v Centru pro správu Microsoft Entra, která je nakonfigurovaná jenom pro účty v tomto organizačním adresáři. Další podrobnosti najdete v tématu Registrace aplikace . Na stránce Přehled aplikace si poznamenejte následující hodnoty pro pozdější použití:
  • ID aplikace (klienta)
  • ID adresáře (klienta)
• Přidejte klientský certifikát do registrace aplikace. Další informace naleznete v tématu Přidání a správa přihlašovacích údajů aplikace v Microsoft Entra ID.

Konfigurace aplikace

Zvolte jazyk webového rozhraní API.

ASP.NET Core

Tajné klíče klienta nebo klientské certifikáty

Vzhledem k tomu, že vaše webová aplikace teď volá podřízené webové rozhraní API, zadejte tajný klíč klienta nebo klientský certifikát do souboru appsettings.json . Můžete také přidat oddíl, který určuje:

• Adresa URL podřízeného webového rozhraní API
• Obory vyžadované pro volání rozhraní API

V následujícím příkladu GraphBeta část určuje tato nastavení.

{
  "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"]
    }
}

Poznámka:

Můžete navrhnout kolekci přihlašovacích údajů klienta, včetně řešení bez přihlašovacích údajů, jako je federace identit úloh pro Azure Kubernetes. Předchozí verze Microsoft.Identity.Web vyjádřily tajný klíč klienta v jedné vlastnosti ClientSecret místo ClientCredentials. Tato funkce je stále podporovaná pro zpětnou kompatibilitu, ale nemůžete použít vlastnost ClientSecret i kolekci ClientCredentials.

Místo tajného klíče klienta můžete zadat klientský certifikát. Následující fragment kódu ukazuje použití certifikátu uloženého ve službě Azure Key Vault.

{
  "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"]
  }
}

Varování

Pokud zapomenete změnit Scopes na pole, při pokusu použít IDownstreamApi, se obory zobrazí jako null, a IDownstreamApi se pokusí o anonymní (neověřené) volání směrem k podřízenému rozhraní API, což bude mít za následek 401/unauthenticated.

Microsoft.Identity.Web nabízí několik způsobů, jak popsat certifikáty podle konfigurace nebo kódu. Podrobnosti najdete v tématu Microsoft.Identity.Web – Použití certifikátů na GitHubu.

Program.cs

using Microsoft.Identity.Web;

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

Webové rozhraní API potřebuje získat token pro podřízené rozhraní API. Zadejte ji přidáním .EnableTokenAcquisitionToCallDownstreamApi() řádku za .AddMicrosoftIdentityWebApi(Configuration). Tento řádek zveřejňuje ITokenAcquisition službu, kterou lze použít v akcích kontroleru nebo stránek.

Alternativní metodou je však implementace mezipaměti tokenů. Například přidání .AddInMemoryTokenCaches(), do Program.cs umožňuje, aby token byl uložen do mezipaměti v paměti.

using Microsoft.Identity.Web;

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

Microsoft.Identity.Web poskytuje dva mechanismy pro volání podřízeného webového rozhraní API z jiného rozhraní API. Možnost, kterou zvolíte, závisí na tom, jestli chcete volat Microsoft Graph nebo jiné rozhraní API.

Možnost 1: Volání Microsoft Graphu

Pokud chcete volat Microsoft Graph, Microsoft.Identity.Web umožňuje přímo používat GraphServiceClient (které poskytuje sada Microsoft Graph SDK) v akcích API.

Poznámka:

Stále dochází k problému se sadou Microsoft Graph SDK verze 5 nebo novější. Další informace najdete v problému s GitHubem.

Zpřístupnit Microsoft Graph:

1. Přidejte do projektu balíček NuGet Microsoft.Identity.Web.GraphServiceClient .
2. Přidejte .AddMicrosoftGraph() za .EnableTokenAcquisitionToCallDownstreamApi() do Program.cs. .AddMicrosoftGraph() má několik přetížení. Při použití přepsání, které jako parametr přijímá sekci konfigurace, se kód změní:

using Microsoft.Identity.Web;

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

Možnost 2: Volání podřízeného webového rozhraní API jiného než Microsoft Graphu

1. Přidejte do projektu balíček NuGet Microsoft.Identity.Web.DownstreamApi .
2. Přidejte .AddDownstreamApi() za .EnableTokenAcquisitionToCallDownstreamApi() do Program.cs. Kód se změní na:

using Microsoft.Identity.Web;

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

kde;

• MyApi označuje název podřízeného webového rozhraní API, které vaše webové rozhraní API hodlá volat.
• MyApiScope je rozsah potřebný k tomu, aby vaše webové rozhraní API požadovalo interakci s podřízeným webovým rozhraním API.

Tyto hodnoty budou reprezentovány ve formátu JSON, které budou podobné následujícímu fragmentu kódu.

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

Pokud webová aplikace potřebuje volat jiný prostředek rozhraní API, opakujte .AddDownstreamApi() metodu s příslušným oborem, jak je znázorněno v následujícím fragmentu kódu:

using Microsoft.Identity.Web;

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

Všimněte si, že .EnableTokenAcquisitionToCallDownstreamApi se volá bez jakéhokoli parametru, což znamená, že přístupový token se získá včas, protože kontroler požaduje token zadáním oboru.

Rozsah se dá předat také při volání .EnableTokenAcquisitionToCallDownstreamApi, což způsobí, že webová aplikace získá token během počátečního přihlášení uživatele. Token bude poté vytažen z mezipaměti, na vyžádání řadiče.

Podobně jako u webových aplikací je možné zvolit různé implementace mezipaměti tokenů. Podrobnosti najdete na webu Microsoft Identity – Serializace mezipaměti tokenů na GitHubu.

Následující obrázek ukazuje možnosti Microsoft.Identity.Web a dopad na Program.cs:

Poznámka:

Abyste plně porozuměli příkladům kódu, seznamte se se základy ASP.NET Core a zejména injektážem závislostí a možnostmi.

ASP.NET

Tajné klíče klienta nebo klientské certifikáty

Vzhledem k tomu, že vaše webová aplikace teď volá podřízené webové rozhraní API, zadejte tajný klíč klienta nebo klientský certifikát do souboru appsettings.json . Můžete také přidat oddíl, který určuje:

• Adresa URL podřízeného webového rozhraní API
• Obory vyžadované pro volání rozhraní API

V následujícím příkladu GraphBeta část určuje tato nastavení.

{
  "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"]
    }
}

Poznámka:

Můžete navrhnout kolekci přihlašovacích údajů klienta, včetně řešení bez přihlašovacích údajů, jako je federace identit úloh pro Azure Kubernetes. Předchozí verze Microsoft.Identity.Web vyjádřily tajný klíč klienta v jedné vlastnosti ClientSecret místo ClientCredentials. Tato funkce je stále podporovaná pro zpětnou kompatibilitu, ale nemůžete použít vlastnost ClientSecret i kolekci ClientCredentials.

Místo tajného klíče klienta můžete zadat klientský certifikát. Následující fragment kódu ukazuje použití certifikátu uloženého ve službě Azure Key Vault.

{
  "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"]
  }
}

Varování

Pokud zapomenete změnit Scopes na pole, při pokusu použít IDownstreamApi, se obory zobrazí jako null, a IDownstreamApi se pokusí o anonymní (neověřené) volání směrem k podřízenému rozhraní API, což bude mít za následek 401/unauthenticated.

Microsoft.Identity.Web nabízí několik způsobů, jak popsat certifikáty podle konfigurace nebo kódu. Podrobnosti najdete v tématu Microsoft.Identity.Web – Použití certifikátů na GitHubu.

Úprava Startup.Auth.cs

Vaše webová aplikace potřebuje získat token pro podřízené rozhraní API, Microsoft.Identity.Web poskytuje dva mechanismy pro volání podřízeného rozhraní API z webového rozhraní API. Možnost, kterou zvolíte, závisí na tom, jestli chcete volat Microsoft Graph nebo jiné rozhraní API.

Možnost 1: Volání Microsoft Graphu

Pokud chcete volat Microsoft Graph, Microsoft.Identity.Web umožňuje přímo používat GraphServiceClient (vystavené sadou Microsoft Graph SDK) v akcích rozhraní API. Zpřístupnit Microsoft Graph:

1. Přidejte do projektu balíček NuGet Microsoft.Identity.Web.GraphServiceClient .

2. Přidejte .AddMicrosoftGraph() do kolekce služeb v souboru Startup.Auth.cs . .AddMicrosoftGraph() má několik přetížení. Při použití přepsání, které jako parametr přijímá sekci konfigurace, se kód změní:

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

Možnost 2: Volání podřízeného webového rozhraní API jiného než Microsoft Graphu

Pokud chcete volat jiné rozhraní než Microsoft Graph, Microsoft.Identity.Web umožňuje používat IDownstreamApi rozhraní v akcích rozhraní API. Chcete-li použít toto rozhraní:

1. Přidejte do projektu balíček NuGet Microsoft.Identity.Web.DownstreamApi .
2. Přidejte .AddDownstreamApi() za .EnableTokenAcquisitionToCallDownstreamApi() v souboru Startup.cs. .AddDownstreamApi() má dva argumenty:
   • Název služby (API): Tento název použijete v akcích kontroleru k odkazování na odpovídající konfiguraci.
   • oddíl konfigurace představující parametry používané k volání podřízeného webového rozhraní API.

Tady je kód:

  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

Použití toku on-behalf-of (OBO)

Tok procesu on-behalf-of (OBO) se používá k získání tokenu pro volání podřízeného webového API. V tomto toku vaše webové rozhraní API obdrží nosný token s uživatelskými delegovanými oprávněními z klientské aplikace a pak tento token vymění za jiný přístupový token pro volání podřízeného webového rozhraní API.

Následující kód používá SecurityContextHolder rámce Spring Security ve webovém API, aby získal ověřený nosný token. Pak použije knihovnu MSAL Java k získání tokenu pro následné rozhraní API prostřednictvím volání acquireToken s OnBehalfOfParameters. MSAL token ukládá do mezipaměti, aby následné volání rozhraní API bylo možné použít acquireTokenSilently k získání tokenu uloženého v mezipaměti.

@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

Použití toku on-behalf-of (OBO)

Tok procesu on-behalf-of (OBO) se používá k získání tokenu pro volání podřízeného webového API. V tomto toku vaše webové rozhraní API obdrží nosný token s uživatelskými delegovanými oprávněními z klientské aplikace a pak tento token vymění za jiný přístupový token pro volání podřízeného webového rozhraní API.

Webové rozhraní API Pythonu musí k ověření nosné tokeny přijatého z klienta použít nějaký middleware. Webové rozhraní API pak může získat přístupový token pro podřízené rozhraní API pomocí knihovny MSAL Python voláním acquire_token_on_behalf_of metody. Příklad použití tohoto rozhraní API najdete v testovacím kódu pro microsoft-authentication-library-for-python na GitHubu. Projděte si také diskuzi o problému 53 ve stejném úložišti pro přístup, který obchází potřebu aplikace střední vrstvy.

Také si můžete prohlédnout příklad implementace toku OBO v ukázce ms-identity-python-on-behalf-of.

Můžete si také prohlédnout příklad implementace toku OBO v Node.js a Azure Functions.

Protokol

Další informace o protokolu OBO naleznete ve flow Microsoft Identity Platform a OAuth 2.0 On-Behalf-Of.

Další krok

Získejte token pro aplikaci.