Uma API da Web que chama APIs da Web: Configuração de código

2025-04-10

Aplica-se a: Círculo verde com um símbolo de marca de verificação branco. Locatários de trabalho Círculo branco com um símbolo X cinzento. Locatários externos (saiba mais)

Este artigo descreve como configurar o código para uma aplicação de API web usando o fluxo de autorização por código OAuth 2.0.

A Microsoft recomenda que você use o pacote NuGet Microsoft.Identity.Web ao desenvolver uma API protegida do ASP.NET Core chamando APIs da Web downstream. Consulte API da Web protegida: Configuração de código | Microsoft.Identity.Web para uma apresentação rápida dessa biblioteca no contexto de uma API da Web.

Pré-requisitos

Registrar uma API da Web que chama APIs da Web

Configurar o aplicativo

Escolha um idioma para sua API da Web.

Segredos do cliente ou certificados do cliente

Como a sua aplicação web agora chama uma API web downstream, forneça um client secret ou um certificado de cliente no ficheiro appsettings.json. Você também pode adicionar uma seção que especifique:

A URL da API Web a jusante
Os escopos necessários para chamar a API

No exemplo a seguir, a GraphBeta seção especifica essas configurações.

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

Nota

Você pode propor uma coleção de credenciais de cliente, incluindo uma solução sem credenciais, como federação de identidade de carga de trabalho para Kubernetes do Azure. Versões anteriores do Microsoft.Identity.Web expressavam o segredo do cliente em uma única propriedade "ClientSecret" em vez de "ClientCredentials". Ainda é suportado para compatibilidade retroativa, mas não é possível usar a propriedade "ClientSecret" e a coleção "ClientCredentials" simultaneamente.

Em vez de um segredo do cliente, você pode fornecer um certificado de cliente. O trecho de código a seguir mostra o uso de um certificado armazenado no Cofre de Chaves do Azure.

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

Aviso

Se te esqueceres de alterar o Scopes para uma matriz, quando tentares usar os IDownstreamApi escopos aparecerão nulos e IDownstreamApi tentará uma chamada anónima (não autenticada) para a API descendente, o que resultará num 401/unauthenticated.

Microsoft.Identity.Web fornece várias maneiras de descrever certificados, tanto por configuração quanto por código. Para obter detalhes, consulte Microsoft.Identity.Web - Usando certificados no GitHub.

Program.cs

using Microsoft.Identity.Web;

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

Uma API da Web precisa adquirir um token para a API downstream. Especifique-o adicionando a .EnableTokenAcquisitionToCallDownstreamApi() linha após .AddMicrosoftIdentityWebApi(Configuration). Esta linha expõe o serviço ITokenAcquisition que pode ser utilizado nas ações do controlador e das páginas.

No entanto, um método alternativo é implementar um cache de token. Por exemplo, adicionar .AddInMemoryTokenCaches(), a Program.cs permite que o token seja armazenado em cache na memória.

using Microsoft.Identity.Web;

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

Microsoft.Identity.Web fornece dois mecanismos para chamar uma API da Web downstream de outra API. A opção escolhida depende se você deseja chamar o Microsoft Graph ou outra API.

Opção 1: Chamar o Microsoft Graph

Para chamar o Microsoft Graph, Microsoft.Identity.Web permite que você use diretamente o GraphServiceClient (exposto pelo SDK do Microsoft Graph) nas ações da API.

Nota

Há um problema contínuo para o Microsoft Graph SDK v5+. Para obter mais informações, consulte o problema do GitHub.

Para expor o Microsoft Graph:

Adicione o pacote NuGet Microsoft.Identity.Web.GraphServiceClient ao projeto.
Adicione .AddMicrosoftGraph() depois .EnableTokenAcquisitionToCallDownstreamApi() em Program.cs. .AddMicrosoftGraph() tem várias substituições. Usando a sobrescrição que utiliza uma seção de configuração como parâmetro, o código fica:

using Microsoft.Identity.Web;

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

Opção 2: Chamar uma API da Web downstream diferente do Microsoft Graph

Adicione o pacote NuGet Microsoft.Identity.Web.DownstreamApi ao projeto.
Adicione .AddDownstreamApi() depois .EnableTokenAcquisitionToCallDownstreamApi() em Program.cs. O código torna-se:

using Microsoft.Identity.Web;

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

onde

MyApi indica o nome da API da Web downstream que sua API da Web pretende chamar
MyApiScope é o escopo necessário para a sua API web solicitar para interagir com a API web downstream

Esses valores serão representados em seu JSON que será semelhante ao trecho a seguir.

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

Se o aplicativo Web precisar chamar outro recurso de API, repita o .AddDownstreamApi() método com o escopo relevante, conforme mostrado no seguinte trecho:

using Microsoft.Identity.Web;

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

Observe que .EnableTokenAcquisitionToCallDownstreamApi é chamado sem qualquer parâmetro, o que significa que o token de acesso é adquirido exatamente no tempo em que o controlador solicita o token especificando o escopo.

O escopo também pode ser passado ao chamar .EnableTokenAcquisitionToCallDownstreamApi, o que faria com que o aplicativo Web adquirisse o token durante o próprio login inicial do usuário. O token será então retirado do cache quando o controlador o solicitar.

Semelhante aos aplicativos Web, várias implementações de cache de token podem ser escolhidas. Para obter detalhes, consulte Microsoft identity web - Serialização do cache de token no GitHub.

A imagem a seguir mostra as possibilidades do Microsoft.Identity.Web e o impacto no Program.cs:

Diagrama de blocos que mostra opções de configuração de serviço no arquivo Startup.cs para chamar uma API da Web e especificar uma implementação de cache de token

Nota

Para entender completamente os exemplos de código aqui, esteja familiarizado com os fundamentos do ASP.NET Core e, em particular, com a injeção de dependência e as opções.

Segredos do cliente ou certificados do cliente

A URL da API Web a jusante
Os escopos necessários para chamar a API

No exemplo a seguir, a GraphBeta seção especifica essas configurações.

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

Nota

Em vez de um segredo do cliente, você pode fornecer um certificado de cliente. O trecho de código a seguir mostra o uso de um certificado armazenado no Cofre de Chaves do Azure.

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

Aviso

Modificar Startup.Auth.cs

Seu aplicativo Web precisa adquirir um token para a API downstream, Microsoft.Identity.Web fornece dois mecanismos para chamar uma API downstream de uma API da Web. A opção escolhida depende se você deseja chamar o Microsoft Graph ou outra API.

Opção 1: Chamar o Microsoft Graph

Se você quiser chamar o Microsoft Graph, Microsoft.Identity.Web permite que você use diretamente o GraphServiceClient (exposto pelo SDK do Microsoft Graph) em suas ações de API. Para expor o Microsoft Graph:

Adicione o pacote NuGet Microsoft.Identity.Web.GraphServiceClient ao seu projeto.

Adicione .AddMicrosoftGraph() à coleção de serviços no arquivo Startup.Auth.cs . .AddMicrosoftGraph() tem várias substituições. Usando a sobrescrição que utiliza uma seção de configuração como parâmetro, o código fica:

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

Opção 2: Chamar uma API da Web downstream diferente do Microsoft Graph

Se pretender chamar uma API diferente do Microsoft Graph, Microsoft.Identity.Web permite-lhe usar a interface nas suas ações de API IDownstreamApi. Para usar esta interface:

Adicione o pacote NuGet Microsoft.Identity.Web.DownstreamApi ao seu projeto.
Adicione .AddDownstreamApi() depois .EnableTokenAcquisitionToCallDownstreamApi() no arquivo Startup.cs . .AddDownstreamApi() tem dois argumentos:
- O nome de um serviço (API): você usa esse nome nas ações do controlador para fazer referência à configuração correspondente
- uma seção de configuração que representa os parâmetros usados para chamar a API da Web downstream.

Aqui está o código:

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

Usando o fluxo em nome de (OBO)

O fluxo on-behalf-of (OBO) é usado para obter um token para chamar a API da Web downstream. Nesse fluxo, sua API da Web recebe um token de portador com permissões delegadas pelo usuário do aplicativo cliente e, em seguida, troca esse token por outro token de acesso para chamar a API da Web downstream.

O código abaixo usa a estrutura do SecurityContextHolder Spring Security na API da Web para obter o token de portador validado. Em seguida, ele usa a biblioteca Java MSAL para obter um token para API downstream usando a acquireToken chamada com OnBehalfOfParameters. O MSAL armazena em cache o token para que as chamadas subsequentes para a API possam ser usadas acquireTokenSilently para obter o token armazenado em cache.

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

Usando o fluxo em nome de (OBO)

Uma API web Python precisa usar algum middleware para validar o token portador recebido do cliente. A API da Web pode então obter o token de acesso para a API downstream usando a biblioteca MSAL Python chamando o acquire_token_on_behalf_of método. Para obter um exemplo de uso dessa API, consulte o código de teste para a microsoft-authentication-library-for-python no GitHub. Veja também a discussão do problema 53 nesse mesmo repositório para uma abordagem que contorna a necessidade de um aplicativo de camada intermediária.

Você também pode ver um exemplo da implementação do fluxo OBO no exemplo ms-identity-python-on-behalf-of .

Você também pode ver um exemplo de implementação de fluxo OBO no Node.js e no Azure Functions.

Protocolo

Para obter mais informações sobre o protocolo OBO, consulte o Microsoft identity platform and OAuth 2.0 On-Behalf-Of flow.

Próximo passo

Adquira um token para o aplicativo.

Partilhar via

Uma API da Web que chama APIs da Web: Configuração de código

Pré-requisitos

Configurar o aplicativo

Segredos do cliente ou certificados do cliente

Program.cs

Opção 1: Chamar o Microsoft Graph

Opção 2: Chamar uma API da Web downstream diferente do Microsoft Graph

Protocolo

Próximo passo

Comentários

Recursos adicionais