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

Artigo
10/24/2023

Quando o registro para uma API Web estiver concluído, o código do aplicativo poderá ser configurado. A configuração de uma API da Web para chamar uma API da Web downstream baseia-se no código usado na proteção de uma API da Web. Para obter mais informações, consulte API da Web protegida: configuração do aplicativo.

Microsoft.Identity.Web

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.

Segredos do cliente ou certificados do cliente

Como seu aplicativo Web agora chama uma API da Web downstream, forneça um segredo do cliente ou um certificado de cliente no arquivo appsettings.json . Você também pode adicionar uma seção que especifique:

O URL da API Web downstream
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". Isso ainda é suportado para compatibilidade com versões anteriores, mas você não pode usar a propriedade "ClientSecret" e a coleção "ClientCredentials".

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 você esquecer de alterar o Scopes para uma matriz, quando tentar usar os IDownstreamApi escopos aparecerá nulo e IDownstreamApi tentará uma chamada anônima (não autenticada) para a API downstream, o que resultará em um 401/unauthenticatedarquivo .

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 ITokenAcquisition serviço que pode ser usado nas ações controlador/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 substituição que usa uma seção de configuração como parâmetro, o código se torna:

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();
// ...

em que;

MyApi indica o nome da API da Web downstream que sua API da Web pretende chamar
MyApiScope é o escopo necessário para sua API da Web solicitar para interagir com a API da 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 de cache de token no GitHub.

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

Block diagram showing service configuration options in startup dot C S for calling a web API and specifying a token cache implementation

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

O URL da API Web downstream
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 substituição que usa uma seção de configuração como parâmetro, o código se torna:

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 você quiser chamar uma API diferente do Microsoft Graph, Microsoft.Identity.Web permitirá que você use a interface em suas ações de IDownstreamApi API. 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();
          }
      }
  }

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

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 a plataforma de identidade da Microsoft e o fluxo OAuth 2.0 On-Behalf-Of.

Próximos passos

Passe para o próximo artigo neste cenário, Adquirir um token para o aplicativo.

Share via

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

Microsoft.Identity.Web

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

Segredos do cliente ou certificados do cliente

Modificar Startup.Auth.cs

Opção 1: Chamar o Microsoft Graph

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

Protocolo

Próximos passos

Recursos adicionais