Web API を呼び出す Web API:コード構成

Web API の登録が完了したら、アプリケーション コードを構成できます。 ダウンストリームの Web API を呼び出す Web API は、Web API の保護に使用されるコードに基づいて構成します。 詳細については、保護された Web API: アプリ構成に関するページを参照してください。

Microsoft.Identity.Web

ダウンストリーム Web API を呼び出す ASP.NET Core で保護された API を開発する場合は、Microsoft.Identity.Web NuGet パッケージを使用することをお勧めします。 「保護された Web API: Web API のコンテキストでそのライブラリをすばやく表示するには、コード構成の「Microsoft.Identity.Web」を参照してください。

ASP.NET Core

クライアント シークレットまたはクライアント証明書

ご利用の Web アプリでダウンストリーム Web API を呼び出すことができるようになったため、クライアント シークレットまたはクライアント証明書を appsettings.json ファイルに指定してください。 次を指定するセクションを追加することもできます。

• ダウンストリーム Web API の URL
• 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"]
    }
}

Note

Azure Kubernetes のワークロード ID フェデレーションのような資格情報のないソリューションなど、クライアント資格情報のコレクションを提案できます。 以前のバージョンの Microsoft.Identity.Web では、"ClientCredentials" ではなく単一のプロパティ "ClientSecret" でクライアント シークレットが表現されていました。 これは下位互換性のために引き続きサポートされていますが、"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();
// ...

Web API では、ダウンストリーム API のトークンを取得する必要があります。 これを指定するには、.AddMicrosoftIdentityWebApi(Configuration) の後に .EnableTokenAcquisitionToCallDownstreamApi() 行を追加します。 この行により、コントローラーまたはページのアクションで使用できる ITokenAcquisition サービスが公開されます。

ただし、別の方法として、トークン キャッシュを実装する方法もあります。 たとえば、.AddInMemoryTokenCaches() を Program.cs に追加すると、トークンをメモリにキャッシュできます。

using Microsoft.Identity.Web;

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

Microsoft.Identity.Web には、別の API からダウンストリーム Web API を呼び出すための 2 つのメカニズムが用意されています。 選択するオプションは、Microsoft Graph または別の API のどちらを呼び出すかによって異なります。

オプション 1: Microsoft Graph の呼び出し

Microsoft Graph を呼び出すために、Microsoft.Identity.Web では、(Microsoft Graph SDK で公開されている) GraphServiceClient を API アクションで直接使用できます。

注意

Microsoft Graph SDK v5 以降には進行中の問題があります。 詳細については、GitHub イシューを参照してください。

Microsoft Graph を公開するには、次の手順を実行します。

1. Microsoft.Identity.Web.GraphServiceClient NuGet パッケージをプロジェクトに追加します。
2. Program.cs で .EnableTokenAcquisitionToCallDownstreamApi() の後に .AddMicrosoftGraph() を追加します。 .AddMicrosoftGraph() にはいくつかのオーバーライドがあります。 構成セクションをパラメーターとして受け取るオーバーライドを使用すると、コードは次のようになります。

using Microsoft.Identity.Web;

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

オプション 2:Microsoft Graph 以外のダウンストリーム Web API を呼び出す

1. Microsoft.Identity.Web.DownstreamApi NuGet パッケージをプロジェクトに追加します。
2. Program.cs で .EnableTokenAcquisitionToCallDownstreamApi() の後に .AddDownstreamApi() を追加します。 コードは次のようになります。

using Microsoft.Identity.Web;

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

このとき

• MyApi は、Web API が呼び出す予定のダウンストリーム Web API の名前を示します
• MyApiScope は、ダウンストリーム Web API と対話するための Web API の要求で必要なスコープです

これらの値は、次のスニペットのような JSON で表されます。

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

Web アプリで別の 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 を呼び出すときに渡すこともできます。これにより、Web アプリは最初のユーザー ログイン自体の間にトークンを取得します。 その後、コントローラーが要求すると、トークンがキャッシュからプルされます。

Web アプリと同様に、さまざまなトークン キャッシュ実装を選択できます。 詳細については、GitHub の Microsoft identity web - Token cache serialization (トークン キャッシュのシリアル化) を参照してください。

次の図は、実現可能な Microsoft.Identity.Web と Program.cs への影響を示しています。

Note

これらのコード例を完全に理解するために、ASP.NET Core の基礎、特に依存関係の挿入とオプションについてよく理解してください。

ASP.NET

クライアント シークレットまたはクライアント証明書

ご利用の Web アプリでダウンストリーム Web API を呼び出すことができるようになったため、クライアント シークレットまたはクライアント証明書を appsettings.json ファイルに指定してください。 次を指定するセクションを追加することもできます。

• ダウンストリーム Web API の URL
• 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"]
    }
}

Note

Azure Kubernetes のワークロード ID フェデレーションのような資格情報のないソリューションなど、クライアント資格情報のコレクションを提案できます。 以前のバージョンの Microsoft.Identity.Web では、"ClientCredentials" ではなく単一のプロパティ "ClientSecret" でクライアント シークレットが表現されていました。 これは下位互換性のために引き続きサポートされていますが、"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 を変更する

Web アプリでダウンストリーム API のトークンを取得する必要があります。Microsoft.Identity.Web には、Web API からダウンストリーム API を呼び出すためのメカニズムが 2 つ用意されています。 選択するオプションは、Microsoft Graph または別の API のどちらを呼び出すかによって異なります。

オプション 1: Microsoft Graph の呼び出し

Microsoft Graph を呼び出す場合は、Microsoft.Identity.Web を使用すると、API アクションで GraphServiceClient (Microsoft Graph SDK によって公開されている) を直接使用することができます。 Microsoft Graph を公開するには、次の手順を実行します。

1. Microsoft.Identity.Web.GraphServiceClient NuGet パッケージをプロジェクトに追加します。

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:Microsoft Graph 以外のダウンストリーム Web API を呼び出す

Microsoft Graph ではなく API を呼び出す場合は、Microsoft.Identity.Web を使用すると、API アクションで IDownstreamApi インターフェイスを使用できます。 このインターフェイスを使用するには、以下を行います。

1. Microsoft.Identity.Web.DownstreamApi NuGet パッケージをプロジェクトに追加します。
2. Startup.cs ファイルで .EnableTokenAcquisitionToCallDownstreamApi() の後に .AddDownstreamApi() を追加します。 .AddDownstreamApi() には次の 2 つの引数があります。
   • サービスの名前 (api): コントローラー アクションでこの名前を使用して、対応する構成を参照します
   • ダウンストリーム Web 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

On-Behalf-Of (OBO) フローは、ダウンストリーム Web API を呼び出すトークンを取得するために使用されます。 このフローでは、Web API は、ユーザーが委任したアクセス許可を持つベアラー トークンをクライアント アプリケーションから受信し、このトークンを別のアクセス トークンと交換してダウンストリーム Web API を呼び出します。

次のコードでは、Web API で Spring Security フレームワークの SecurityContextHolder を使用して、検証済みのベアラー トークンを取得します。 次に、MSAL Java ライブラリを使用して、OnBehalfOfParameters を設定した acquireToken を使ってダウンストリーム API のトークンを取得します。 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

On-Behalf-Of (OBO) フローは、ダウンストリーム Web API を呼び出すトークンを取得するために使用されます。 このフローでは、Web API は、ユーザーが委任したアクセス許可を持つベアラー トークンをクライアント アプリケーションから受信し、このトークンを別のアクセス トークンと交換してダウンストリーム Web API を呼び出します。

Python Web API では、クライアントから受信したベアラー トークンを検証するために何らかのミドルウェアを使用する必要があります。 Web API は、acquire_token_on_behalf_of メソッドを呼び出すことにより、MSAL Python ライブラリを使用してダウンストリーム API のアクセス トークンを取得できます。 この API の使用例については、GitHub の microsoft-authentication-library-for-python のテスト コードを参照してください。 また、中間層アプリケーションの必要性をなくす方法については、同じリポジトリ内の問題 53 の説明も参照してください。

ms-identity-python-on-behalf-of サンプルで、OBO フローの実装の例を参照することもできます。

また、Node.js と Azure Functions への OBO フロー実装の例を確認することもできます。

Protocol

OBO プロトコルの詳細については、「Microsoft ID プラットフォームと OAuth 2.0 On-Behalf-Of フロー」を参照してください。

次のステップ

このシナリオの次の記事であるアプリのトークンの取得に関する記事に進みます。