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

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

ご利用の 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"]
    }
}

クライアント シークレットの代わりに、クライアント証明書を指定することができます。 次のコード スニペットは、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"]
  }
}

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 を公開するには、次の手順を実行します。

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 への影響を示しています。

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

ご利用の 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"]
    }
}

クライアント シークレットの代わりに、クライアント証明書を指定することができます。 次のコード スニペットは、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"]
  }
}

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

On-Behalf-Of (OBO) フローを使用する

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

On-Behalf-Of (OBO) フローを使用する

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 フローの実装の例を参照することもできます。