A web API that calls web APIs: Code configuration

Client secrets or client certificates

Given that your web app now calls a downstream web API, provide a client secret or client certificate in the appsettings.json file. You can also add a section that specifies:

• The URL of the downstream web API
• The scopes required for calling the API

In the following example, the GraphBeta section specifies these settings.

{
  "AzureAd": {
    "Instance": "https://login.partner.microsoftonline.cn/",
    "ClientId": "[Enter_the_Application_Id_Here]",
    "TenantId": "common",

   // To call an API
   "ClientCredentials": [
    {
      "SourceType": "ClientSecret",
      "ClientSecret":"[Enter_the_Client_Secret_Here]"
    }
  ]
 },
 "GraphBeta": {
    "BaseUrl": "https://microsoftgraph.chinacloudapi.cn/beta",
    "Scopes": ["https://microsoftgraph.chinacloudapi.cn/user.read"]
    }
}

Instead of a client secret, you can provide a client certificate. The following code snippet shows using a certificate stored in Azure Key Vault.

{
  "AzureAd": {
    "Instance": "https://login.partner.microsoftonline.cn/",
    "ClientId": "[Enter_the_Application_Id_Here]",
    "TenantId": "common",

   // To call an API
   "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://msidentitywebsamples.vault.azure.cn",
        "KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
      }
   ]
  },
  "GraphBeta": {
    "BaseUrl": "https://microsoftgraph.chinacloudapi.cn/beta",
    "Scopes": ["https://microsoftgraph.chinacloudapi.cn/user.read"]
  }
}

Microsoft.Identity.Web provides several ways to describe certificates, both by configuration or by code. For details, see Microsoft.Identity.Web - Using certificates on GitHub.

Program.cs

using Microsoft.Identity.Web;

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

A web API needs to acquire a token for the downstream API. Specify it by adding the .EnableTokenAcquisitionToCallDownstreamApi() line after .AddMicrosoftIdentityWebApi(Configuration). This line exposes the ITokenAcquisition service that can be used in the controller/pages actions.

However, an alternative method is to implement a token cache. For example, adding .AddInMemoryTokenCaches(), to Program.cs allows the token to be cached in memory.

using Microsoft.Identity.Web;

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

Microsoft.Identity.Web provides two mechanisms for calling a downstream web API from another API. The option you choose depends on whether you want to call Microsoft Graph or another API.

Option 1: Call Microsoft Graph

To call Microsoft Graph, Microsoft.Identity.Web enables you to directly use the GraphServiceClient (exposed by the Microsoft Graph SDK) in the API actions.

To expose Microsoft Graph:

1. Add the Microsoft.Identity.Web.GraphServiceClient NuGet package to the project.
2. Add .AddMicrosoftGraph() after .EnableTokenAcquisitionToCallDownstreamApi() in Program.cs. .AddMicrosoftGraph() has several overrides. Using the override that takes a configuration section as a parameter, the code becomes:

using Microsoft.Identity.Web;

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

Option 2: Call a downstream web API other than Microsoft Graph

1. Add the Microsoft.Identity.Web.DownstreamApi NuGet package to the project.
2. Add .AddDownstreamApi() after .EnableTokenAcquisitionToCallDownstreamApi() in Program.cs. The code becomes:

using Microsoft.Identity.Web;

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

where;

• MyApi denotes the name of the downstream web API that your web API intends to call
• MyApiScope is the scope necessary for your web API to request in order to interact with the downstream web API

These values will be represented in your JSON that will be similar to the following snippet.

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

If the web app needs to call another API resource, repeat the .AddDownstreamApi() method with the relevant scope as shown in the following snippet:

using Microsoft.Identity.Web;

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

Note that .EnableTokenAcquisitionToCallDownstreamApi is called without any parameter, which means that the access token is acquired just in time as the controller requests the token by specifying the scope.

The scope can also be passed in when calling .EnableTokenAcquisitionToCallDownstreamApi, which would make the web app acquire the token during the initial user login itself. The token will then be pulled from the cache when controller requests it.

Similar to web apps, various token cache implementations can be chosen. For details, see Microsoft identity web - Token cache serialization on GitHub.

The following image shows the possibilities of Microsoft.Identity.Web and the impact on Program.cs:

Client secrets or client certificates

Given that your web app now calls a downstream web API, provide a client secret or client certificate in the appsettings.json file. You can also add a section that specifies:

• The URL of the downstream web API
• The scopes required for calling the API

In the following example, the GraphBeta section specifies these settings.

{
  "AzureAd": {
    "Instance": "https://login.partner.microsoftonline.cn/",
    "ClientId": "[Enter_the_Application_Id_Here]",
    "TenantId": "common",

   // To call an API
   "ClientCredentials": [
    {
      "SourceType": "ClientSecret",
      "ClientSecret":"[Enter_the_Client_Secret_Here]"
    }
  ]
 },
 "GraphBeta": {
    "BaseUrl": "https://microsoftgraph.chinacloudapi.cn/beta",
    "Scopes": ["https://microsoftgraph.chinacloudapi.cn/user.read"]
    }
}

Instead of a client secret, you can provide a client certificate. The following code snippet shows using a certificate stored in Azure Key Vault.

{
  "AzureAd": {
    "Instance": "https://login.partner.microsoftonline.cn/",
    "ClientId": "[Enter_the_Application_Id_Here]",
    "TenantId": "common",

   // To call an API
   "ClientCredentials": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://msidentitywebsamples.vault.azure.cn",
        "KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
      }
   ]
  },
  "GraphBeta": {
    "BaseUrl": "https://microsoftgraph.chinacloudapi.cn/beta",
    "Scopes": ["https://microsoftgraph.chinacloudapi.cn/user.read"]
  }
}

Microsoft.Identity.Web provides several ways to describe certificates, both by configuration or by code. For details, see Microsoft.Identity.Web - Using certificates on GitHub.

Modify Startup.Auth.cs

Your web app needs to acquire a token for the downstream API, Microsoft.Identity.Web provides two mechanisms for calling a downstream API from a web API. The option you choose depends on whether you want to call Microsoft Graph or another API.

Option 1: Call Microsoft Graph

If you want to call Microsoft Graph, Microsoft.Identity.Web enables you to directly use the GraphServiceClient (exposed by the Microsoft Graph SDK) in your API actions. To expose Microsoft Graph:

1. Add the Microsoft.Identity.Web.GraphServiceClient NuGet package to your project.

2. Add .AddMicrosoftGraph() to the service collection in the Startup.Auth.cs file. .AddMicrosoftGraph() has several overrides. Using the override that takes a configuration section as a parameter, the code becomes:

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

Option 2: Call a downstream web API other than Microsoft Graph

If you want to call an API other than Microsoft Graph, Microsoft.Identity.Web enables you to use the IDownstreamApi interface in your API actions. To use this interface:

1. Add the Microsoft.Identity.Web.DownstreamApi NuGet package to your project.
2. Add .AddDownstreamApi() after .EnableTokenAcquisitionToCallDownstreamApi() in the Startup.cs file. .AddDownstreamApi() has two arguments:
   • The name of a service (API): you use this name in your controller actions to reference the corresponding configuration
   • a configuration section representing the parameters used to call the downstream web API.

Here's the code:

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

Using on-behalf-of (OBO) flow

The on-behalf-of (OBO) flow is used to obtain a token to call the downstream web API. In this flow, your web API receives a bearer token with user delegated permissions from the client application and then exchanges this token for another access token to call the downstream web API.

The code below uses Spring Security framework's SecurityContextHolder in the web API to get the validated bearer token. It then uses the MSAL Java library to obtain a token for downstream API using the acquireToken call with OnBehalfOfParameters. MSAL caches the token so that subsequent calls to the API can use acquireTokenSilently to get the cached token.

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

Using on-behalf-of (OBO) flow

The on-behalf-of (OBO) flow is used to obtain a token to call the downstream web API. In this flow, your web API receives a bearer token with user delegated permissions from the client application and then exchanges this token for another access token to call the downstream web API.

A Python web API needs to use some middleware to validate the bearer token received from the client. The web API can then obtain the access token for downstream API using MSAL Python library by calling the acquire_token_on_behalf_of method. For an example of using this API, see the test code for the microsoft-authentication-library-for-python on GitHub. Also see the discussion of issue 53 in that same repository for an approach that bypasses the need for a middle-tier application.

You can also see an example of the OBO flow implementation in the ms-identity-python-on-behalf-of sample.