Webové rozhraní API, které volá webová rozhraní API: Konfigurace kódu

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 rozhraní API chráněného 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

• Registrace webového rozhraní API, které volá webová rozhraní API

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

Upozorňující

Pokud zapomenete změnit Scopes pole, při pokusu o použití IDownstreamApi oborů se zobrazí hodnota null a IDownstreamApi pokusíte se anonymní (neověřené) volání do podřízeného rozhraní API, což bude mít za 401/unauthenticatednásledek .

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 (vystavené sadou Microsoft Graph SDK) v akcích rozhraní 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.

Zveřejnění Microsoft Graphu:

1. Přidejte do projektu balíček NuGet Microsoft.Identity.Web.GraphServiceClient .
2. Přidejte .AddMicrosoftGraph() za .EnableTokenAcquisitionToCallDownstreamApi() Program.cs. .AddMicrosoftGraph() má několik přepsání. Pomocí přepsání, které jako parametr přebírá oddíl konfigurace, se kód stane:

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() Program.cs. Kód se stane:

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.

Obor 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 sám. Token se pak natáhne z mezipaměti, když ho kontroler požádá.

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

Upozorňující

Pokud zapomenete změnit Scopes pole, při pokusu o použití IDownstreamApi oborů se zobrazí hodnota null a IDownstreamApi pokusíte se anonymní (neověřené) volání do podřízeného rozhraní API, což bude mít za 401/unauthenticatednásledek .

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. Zveřejnění Microsoft Graphu:

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řepsání. Pomocí přepsání, které jako parametr přebírá oddíl konfigurace, se kód stane:

   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() soubor 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 on-behalf-of (OBO) slouží k získání tokenu pro volání podřízeného webového rozhraní 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á rozhraní Spring Security SecurityContextHolder ve webovém rozhraní API k získání ověřeného nosné tokenu. Pak pomocí knihovny MSAL Java získá token pro podřízené rozhraní API pomocí acquireToken volání 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 on-behalf-of (OBO) slouží k získání tokenu pro volání podřízeného webového rozhraní 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.

Můžete si také 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 najdete v toku Microsoft Identity Platform a OAuth 2.0 On-Behalf-Of.

Další krok

Získejte token pro aplikaci.