Веб-API, который вызывает другие веб-API. Конфигурация кода

В этой статье описывается настройка кода для веб-ПРИЛОЖЕНИЯ API с помощью потока кода авторизации OAuth 2.0.

Корпорация Майкрософт рекомендует использовать пакет NuGet Microsoft.Identity.Web при разработке защищенных API для ASP.NET Core, которые вызывают нижестоящие веб-API. В статье Защищенный веб-API: конфигурация кода | Microsoft.Identity.Web есть краткое описание этой библиотеки в контексте веб-API.

Необходимые компоненты

• Регистрация веб-API, который вызывает веб-API

Настройка приложения

Выберите язык для веб-API.

ASP.NET Core

Секреты клиента или сертификаты клиента

Учитывая, что веб-приложение теперь вызывает нижестоящий веб-API, укажите секрет клиента или сертификат клиента в файле appsettings.json. Можно также добавить раздел, который указывает:

• URL-адрес нижестоящего веб-API;
• необходимые области для вызова API.

В следующем примере эти параметры задаются в разделе GraphBeta.

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

Примечание.

Вы можете предложить коллекцию учетных данных клиента, включая решение без учетных данных, например федерацию удостоверений рабочей нагрузки для Azure Kubernetes. Предыдущие версии Microsoft.Identity.Web выразили секрет клиента в одном свойстве ClientSecret вместо ClientCredentials. Это по-прежнему поддерживается для обратной совместимости, но нельзя использовать свойство ClientSecret и коллекцию ClientCredentials.

Вместо секрета клиента можно предоставить сертификат клиента. В приведенном ниже фрагменте кода показано использование сертификата, хранящегося в 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"]
  }
}

Предупреждение

Если вы забыли изменить Scopes массив, при попытке использовать IDownstreamApi области будут отображаться null, и IDownstreamApi будет предпринята попытка анонимного (неуверенного) вызова нижестоящего API, что приведет к 401/unauthenticatedвозникновению ошибки.

Microsoft.Identity.Web позволяет описывать сертификаты несколькими способами, как по конфигурации, так и по коду. Дополнительные сведения см. в статье на GitHub об использовании Microsoft.Identity.Web с сертификатами.

Program.cs

using Microsoft.Identity.Web;

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

Веб-API должен получить маркер для нижестоящего API. Укажите его, добавив .EnableTokenAcquisitionToCallDownstreamApi() строку после .AddMicrosoftIdentityWebApi(Configuration). Эта строка предоставляет ITokenAcquisition службу, которую можно использовать в действиях контроллера или страниц.

Однако альтернативным способом является реализация кэша маркеров. Например, добавление .AddInMemoryTokenCaches()к Program.cs позволяет кэшировать маркер в памяти.

using Microsoft.Identity.Web;

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

Microsoft.Identity.Web предоставляет два механизма вызова нижестоящего веб-API из другого API. Выбор зависит от того, что необходимо вызывать: Microsoft Graph или другой API.

Вариант 1. Вызов Microsoft Graph

Чтобы вызвать Microsoft Graph, Microsoft.Identity.Web позволяет напрямую использовать GraphServiceClient (предоставляемый пакетом SDK Microsoft Graph) в действиях API.

Примечание.

Существует постоянная проблема с пакетом SDK Microsoft Graph версии 5+. Дополнительные сведения см. в статье о проблеме GitHub.

Чтобы предоставить Microsoft Graph, выполните указанные ниже действия.

1. Добавьте в проект пакет NuGet Microsoft.Identity.Web.GraphServiceClient.
2. Добавьте .AddMicrosoftGraph() после .EnableTokenAcquisitionToCallDownstreamApi() Program.cs. .AddMicrosoftGraph() имеет несколько переопределений. При использовании переопределения, которое принимает в качестве параметра раздел конфигурации, код принимает следующий вид:

using Microsoft.Identity.Web;

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

Вариант 2. Вызов нижестоящего веб-API, отличного от Microsoft Graph

1. Добавьте в проект пакет NuGet Microsoft.Identity.Web.DownstreamApi.
2. Добавьте .AddDownstreamApi() после .EnableTokenAcquisitionToCallDownstreamApi() Program.cs. Код становится следующим:

using Microsoft.Identity.Web;

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

где;

• MyApi обозначает имя нижестоящего веб-API, который веб-API намерен вызывать.
• MyApiScope — это область, необходимая для запроса веб-API для взаимодействия с нижестоящим веб-API.

Эти значения будут представлены в формате JSON, который будет похож на следующий фрагмент кода.

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

Если веб-приложение должно вызвать другой ресурс API, повторите .AddDownstreamApi() метод с соответствующей областью, как показано в следующем фрагменте кода:

using Microsoft.Identity.Web;

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

Обратите внимание, что .EnableTokenAcquisitionToCallDownstreamApi вызывается без каких-либо параметров, что означает, что маркер доступа приобретается только вовремя, так как контроллер запрашивает маркер, указав область.

Область также может быть передана при вызове .EnableTokenAcquisitionToCallDownstreamApi, что позволит веб-приложению получить маркер во время самого входа пользователя. Затем маркер будет извлечен из кэша при запросе контроллера.

Как и в веб-приложениях, можно выбрать различные реализации кэша маркеров. Дополнительные сведения см. в статье на GitHub Microsoft identity web - Token cache serialization (Microsoft.Identity.Web: сериализация кэша маркеров).

На следующем рисунке показаны возможности Microsoft.Identity.Web и влияние на Program.cs:

Примечание.

Чтобы полностью разобраться в приведенных здесь примерах кода, ознакомьтесь с базовыми понятиями ASP.NET, в частности с внедрением зависимостей и параметрами.

ASP.NET

Секреты клиента или сертификаты клиента

Учитывая, что веб-приложение теперь вызывает нижестоящий веб-API, укажите секрет клиента или сертификат клиента в файле appsettings.json. Можно также добавить раздел, который указывает:

• URL-адрес нижестоящего веб-API;
• необходимые области для вызова API.

В следующем примере эти параметры задаются в разделе GraphBeta.

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

Примечание.

Вы можете предложить коллекцию учетных данных клиента, включая решение без учетных данных, например федерацию удостоверений рабочей нагрузки для Azure Kubernetes. Предыдущие версии Microsoft.Identity.Web выразили секрет клиента в одном свойстве ClientSecret вместо ClientCredentials. Это по-прежнему поддерживается для обратной совместимости, но нельзя использовать свойство ClientSecret и коллекцию ClientCredentials.

Вместо секрета клиента можно предоставить сертификат клиента. В приведенном ниже фрагменте кода показано использование сертификата, хранящегося в 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"]
  }
}

Предупреждение

Если вы забыли изменить Scopes массив, при попытке использовать IDownstreamApi области будут отображаться null, и IDownstreamApi будет предпринята попытка анонимного (неуверенного) вызова нижестоящего API, что приведет к 401/unauthenticatedвозникновению ошибки.

Microsoft.Identity.Web позволяет описывать сертификаты несколькими способами, как по конфигурации, так и по коду. Дополнительные сведения см. в статье на GitHub об использовании Microsoft.Identity.Web с сертификатами.

Изменение Startup.Auth.cs

Веб-приложение должно получить маркер для нижестоящего API, Microsoft.Identity.Web предоставляет два механизма вызова нижестоящего API из веб-API. Выбор зависит от того, что необходимо вызывать: Microsoft Graph или другой API.

Вариант 1. Вызов Microsoft Graph

Если необходимо вызвать Microsoft Graph, Microsoft.Identity.Web позволяет напрямую использовать GraphServiceClient (предоставляется пакетом SDK Microsoft Graph) в действиях API. Чтобы предоставить Microsoft Graph, выполните указанные ниже действия.

1. Добавьте в проект пакет NuGet Microsoft.Identity.Web.GraphServiceClient.

2. Добавьте .AddMicrosoftGraph() в коллекцию служб в файле Startup.Auth.cs . .AddMicrosoftGraph() имеет несколько переопределений. При использовании переопределения, которое принимает в качестве параметра раздел конфигурации, код принимает следующий вид:

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

Вариант 2. Вызов нижестоящего веб-API, отличного от Microsoft Graph

Если вы хотите вызвать API, отличный от Microsoft Graph, Microsoft.Identity.Web позволяет использовать IDownstreamApi интерфейс в действиях API. Чтобы использовать этот интерфейс, выполните указанные ниже действия.

1. Добавьте в проект пакет NuGet Microsoft.Identity.Web.DownstreamApi.
2. Добавьте .AddDownstreamApi() после .EnableTokenAcquisitionToCallDownstreamApi() в файл Startup.cs. .AddDownstreamApi() имеет два аргумента:
   • Имя службы (API): это имя используется в действиях контроллера для ссылки на соответствующую конфигурацию.
   • раздел конфигурации, представляющий параметры, используемые для вызова нижестоящего веб-API.

Вот этот код:

  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

Использование потока от имени (OBO)

Поток от имени (OBO) используется для получения маркера для вызова нижестоящего веб-API. В этом потоке веб-API получает маркер носителя с разрешениями, делегированными от пользователя в клиентском приложении, а затем обменивает этот маркер на другой маркер доступа для вызова нижестоящего веб-API.

Приведенный ниже код использует в веб-API SecurityContextHolder платформы Spring Security, чтобы получить проверенный маркер носителя. Затем он применяет библиотеку MSAL для Java, чтобы получить маркер для нижестоящего API с помощью вызова acquireToken с параметрами OnBehalfOfParameters. MSAL кэширует маркер, чтобы последующие вызовы этого API могли получить кэшированный маркер с помощью вызова acquireTokenSilently.

@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

Использование потока от имени (OBO)

Поток от имени (OBO) используется для получения маркера для вызова нижестоящего веб-API. В этом потоке веб-API получает маркер носителя с разрешениями, делегированными от пользователя в клиентском приложении, а затем обменивает этот маркер на другой маркер доступа для вызова нижестоящего веб-API.

Веб-API Python должен использовать некоторое ПО промежуточного слоя для проверки маркера носителя, полученного от клиента. Затем веб-API может получить маркер доступа для нижестоящего API с помощью метода acquire_token_on_behalf_of из библиотеки MSAL Python. Пример использования этого API представлен в тестовом коде для microsoft-authentication-library-for-python на сайте GitHub. См. также описание проблемы 53 в том же репозитории, где описан подход, позволяющий обойтись без ПО промежуточного слоя.

Вы также можете увидеть пример реализации потока OBO в примере ms-identity-python-on-behalf-of.

Вы также можете увидеть пример реализации потока OBO в Node.js и Функциях Azure.

Протокол

Дополнительные сведения о протоколе OBO см. в статье Поток On-Behalf-Of в OAuth 2.0 и платформа удостоверений Майкрософт.

Следующий шаг

Получение маркера для приложения.