API web que llama a API web: Configuración del código

Una vez completado el registro de una API web, se puede configurar el código de la aplicación. La configuración de una API web para llamar a una API web de nivel inferior se basa en el código que se usa para proteger una API web. Para más información, consulte API web protegida: configuración de la aplicación.

Microsoft.Identity.Web

Microsoft recomienda usar el paquete NuGet Microsoft.Identity.Web al desarrollar API web de nivel inferior de llamada API protegidas por ASP.NET Core. Consulte API web protegida: Configuración de código | Microsoft.Identity.Web para ver una presentación rápida de la biblioteca en el contexto de una API web.

ASP.NET Core

Secretos de cliente o certificados de cliente

Dado que la aplicación web ahora llama a una API web de nivel inferior, proporcione un secreto de cliente o un certificado de cliente en el archivo appsettings.json. También puede agregar una sección que especifique:

• La dirección URL de la API web de nivel inferior.
• Los ámbitos necesarios para llamar a la API.

En el ejemplo siguiente, la sección GraphBeta especifica esta configuración.

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

Puede proponer una colección de credenciales de cliente, incluida una solución sin credenciales, como la federación de identidades de carga de trabajo para Azure Kubernetes. Las versiones anteriores de Microsoft.Identity.Web expresaron el secreto de cliente en una sola propiedad "ClientSecret" en lugar de "ClientCredentials". Esto sigue siendo compatible con versiones anteriores, pero no puede usar la propiedad "ClientSecret" y la colección "ClientCredentials".

En lugar de un secreto de cliente, puede proporcionar un certificado de cliente. En el fragmento de código siguiente se muestra el uso de un certificado almacenado en 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"]
  }
}

Advertencia

Si olvida cambiar Scopes a una matriz, cuando intente usar IDownstreamApi los ámbitos aparecerán como nulos, y IDownstreamApi intentará una llamada anónima (sin autenticar) a la API descendente, lo cual resultará en un 401/unauthenticated.

Microsoft.Identity.Web proporciona varias maneras de describir certificados, tanto mediante configuración como mediante código. Para más información, consulte Microsoft.Identity.Web: uso de certificados en GitHub.

Program.cs

using Microsoft.Identity.Web;

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

Una aplicación web tiene que adquirir un token para la API de nivel inferior. Para especificarlo, agregue la línea .EnableTokenAcquisitionToCallDownstreamApi() después de .AddMicrosoftIdentityWebApi(Configuration). Esta línea expone el servicio ITokenAcquisition, que se puede usar en las acciones de controlador o páginas.

Sin embargo, un método alternativo es implementar una caché de tokens. Por ejemplo, agregar .AddInMemoryTokenCaches() a Program.cs permite que el token se almacene en caché en memoria.

using Microsoft.Identity.Web;

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

Microsoft.Identity.Web proporciona dos mecanismos para llamar a una API web de nivel inferior desde otra API. La opción que elija dependerá de si desea llamar a Microsoft Graph o a otra API.

Opción 1: Llamada a Microsoft Graph

Para llamar a Microsoft Graph, Microsoft.Identity.Web le permite usar directamente GraphServiceClient (expuesto por el SDK de Microsoft Graph) en las acciones de la API.

Nota

Hay un problema en curso para el SDK de Microsoft Graph v5+. Para más información, consulte el problema de GitHub.

Para exponer Microsoft Graph:

1. Agregue el paquete NuGet Microsoft.Identity.Web.GraphServiceClient al proyecto.
2. Agregue .AddMicrosoftGraph() después de .EnableTokenAcquisitionToCallDownstreamApi() en Program.cs. .AddMicrosoftGraph() tiene varias invalidaciones. Cuando se utiliza la invalidación que toma una sección de la configuración como parámetro, el código se convierte en:

using Microsoft.Identity.Web;

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

Opción 2: Llamada a una API web de nivel inferior que no sea Microsoft Graph

1. Agregue el paquete NuGet Microsoft.Identity.Web.DownstreamApi al proyecto.
2. Agregue .AddDownstreamApi() después de .EnableTokenAcquisitionToCallDownstreamApi() en Program.cs. El código se convierte en:

using Microsoft.Identity.Web;

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

donde:

• MyApi indica el nombre de la API web de bajada a la que pretende llamar la API web.
• MyApiScope es el ámbito necesario para que la API web solicite para interactuar con la API web de bajada.

Estos valores se representarán en el JSON que será similar al fragmento de código siguiente.

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

Si la aplicación web necesita llamar a otro recurso de API, repita el método de la .AddDownstreamApi() con el ámbito pertinente, como se muestra en el siguiente fragmento de código:

using Microsoft.Identity.Web;

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

Tenga en cuenta que .EnableTokenAcquisitionToCallDownstreamApi se llama sin ningún parámetro, lo que significa que el token de acceso se adquirirá justo a tiempo, ya que el controlador solicita el token especificando el ámbito.

El ámbito también se puede pasar al llamar a la .EnableTokenAcquisitionToCallDownstreamApi, lo que haría que la aplicación web adquiriera el token durante el inicio de sesión del usuario. A continuación, el token se extraerá de la memoria caché cuando el controlador lo solicite.

De forma similar a las aplicaciones web, se pueden elegir varias implementaciones de caché de tokens. Para obtener más información, consulte Microsoft.Identity.Web: Serialización de la caché de tokens en GitHub.

En la imagen siguiente se muestran las posibilidades de Microsoft.Identity.Web y su impacto en Program.cs:

Nota:

Para comprender por completo los ejemplos de código que se indican a continuación, familiarícese con los aspectos básicos de ASP.NET Core y, en particular, con la inserción de dependencias y las opciones.

ASP.NET

Secretos de cliente o certificados de cliente

Dado que la aplicación web ahora llama a una API web de nivel inferior, proporcione un secreto de cliente o un certificado de cliente en el archivo appsettings.json. También puede agregar una sección que especifique:

• La dirección URL de la API web de nivel inferior.
• Los ámbitos necesarios para llamar a la API.

En el ejemplo siguiente, la sección GraphBeta especifica esta configuración.

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

Puede proponer una colección de credenciales de cliente, incluida una solución sin credenciales, como la federación de identidades de carga de trabajo para Azure Kubernetes. Las versiones anteriores de Microsoft.Identity.Web expresaron el secreto de cliente en una sola propiedad "ClientSecret" en lugar de "ClientCredentials". Esto sigue siendo compatible con versiones anteriores, pero no puede usar la propiedad "ClientSecret" y la colección "ClientCredentials".

En lugar de un secreto de cliente, puede proporcionar un certificado de cliente. En el fragmento de código siguiente se muestra el uso de un certificado almacenado en 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"]
  }
}

Advertencia

Si olvida cambiar Scopes a una matriz, cuando intente usar IDownstreamApi los ámbitos aparecerán como nulos, y IDownstreamApi intentará una llamada anónima (sin autenticar) a la API descendente, lo cual resultará en un 401/unauthenticated.

Microsoft.Identity.Web proporciona varias maneras de describir certificados, tanto mediante configuración como mediante código. Para más información, consulte Microsoft.Identity.Web: uso de certificados en GitHub.

Modificar Startup.Auth.cs

La aplicación web debe adquirir un token para la API de bajada. Microsoft.Identity.Web proporciona dos mecanismos para llamar a una API de bajada desde una API web. La opción que elija dependerá de si desea llamar a Microsoft Graph o a otra API.

Opción 1: Llamada a Microsoft Graph

Si desea llamar a Microsoft Graph, Microsoft.Identity.Web le permite usar directamente GraphServiceClient (expuesto por el SDK de Microsoft Graph) en las acciones de la API. Para exponer Microsoft Graph:

1. Agregue el paquete NuGet Microsoft.Identity.Web.GraphServiceClient a su proyecto.

2. Agregue .AddMicrosoftGraph() a la colección de servicios en el archivo Startup.Auth.cs. .AddMicrosoftGraph() tiene varias invalidaciones. Cuando se utiliza la invalidación que toma una sección de la configuración como parámetro, el código se convierte en:

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

Opción 2: Llamada a una API web de nivel inferior que no sea Microsoft Graph

Si desea llamar a una API distinta de Microsoft Graph, Microsoft.Identity.Web le permite usar la interfaz IDownstreamApi en sus acciones de API. Para usar esta interfaz:

1. Agregue el paquete NuGet Microsoft.Identity.Web.DownstreamApi al proyecto.
2. Agregue .AddDownstreamApi() después de .EnableTokenAcquisitionToCallDownstreamApi() en el archivo Startup.cs. .AddDownstreamApi() tiene dos argumentos:
   • El nombre de un servicio (API): se usa este nombre en las acciones del controlador para hacer referencia a la configuración correspondiente
   • una sección de configuración que representa los parámetros usados para llamar a la API web de bajada.

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

Java

El flujo "en nombre de" (OBO) se usa para obtener un token para llamar a la API web de nivel inferior. En este flujo, la API web recibe un token de portador con permisos delegados de usuario de la aplicación cliente y, a continuación, intercambia este token por otro token de acceso para llamar a la API web de nivel inferior.

En el código siguiente se usa el valor SecurityContextHolder de Spring Security Framework en la API web para obtener el token de portador validado. A continuación, se usa la biblioteca de MSAL Java para obtener un token para la API de nivel inferior mediante la llamada a acquireToken con OnBehalfOfParameters. MSAL almacena en caché el token para que las siguientes llamadas a la API puedan usar acquireTokenSilently para obtener el token almacenado en caché.

@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

El flujo "en nombre de" (OBO) se usa para obtener un token para llamar a la API web de nivel inferior. En este flujo, la API web recibe un token de portador con permisos delegados de usuario de la aplicación cliente y, a continuación, intercambia este token por otro token de acceso para llamar a la API web de nivel inferior.

Una API web de Python debe usar algún middleware para validar el token de portador recibido del cliente. A continuación, la API web podrá obtener el token de acceso para la API de nivel inferior mediante la biblioteca de MSAL para Python al llamar al método acquire_token_on_behalf_of. Para obtener un ejemplo del uso de esta API, consulte Código de prueba para la biblioteca de autenticación de Microsoft para Python en GitHub. Consulte también la explicación del problema 53 en ese mismo repositorio para obtener un enfoque que omita la necesidad de una aplicación de nivel intermedio.

También puede ver un ejemplo de la implementación del flujo con derechos delegados en el ejemplo ms-identity-python-on-behalf-of.

También puede ver un ejemplo de implementación del flujo con derechos delegados en Node.js y Azure Functions.

Protocolo

Para más información acerca del protocolo OBO, consulte Flujo con derechos delegados de OAuth 2.0 y Plataforma de identidad de Microsoft.

Pasos siguientes

Avance al siguiente artículo de este escenario, Obtención de un token para la aplicación.