Une API web qui appelle des API web : Configuration de code

Article
10/25/2023

Une fois l’inscription d’une API web terminée, le code de l’application peut être configuré. La configuration d’une API web pour appeler une API web en aval repose sur le code utilisé pour protéger une API web. Pour plus d’informations, consultez la section API web protégée : Configuration d’application.

Microsoft.Identity.Web

Microsoft vous recommande d’utiliser le package NuGet Microsoft.Identity.Web lors du développement d’une API protégée ASP.NET Core appelant des API web en aval. Voir API web protégée : Configuration du code | Microsoft.Identity.Web pour une présentation rapide de cette bibliothèque dans le contexte d’une API web.

Secrets clients ou certificats clients

Dans la mesure où votre application web appelle désormais une API web en aval, fournissez un secret client ou un certificat client dans le fichier appsettings.json. Vous pouvez également ajouter une section spécifiant ce qui suit :

URL de l’API web en aval ;
étendues requises pour appeler l’API.

Dans l’exemple suivant, la section GraphBeta spécifie ces paramètres.

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

Remarque

Vous pouvez proposer une collection d’informations d’identification client, y compris une solution sans informations d’identification comme la fédération des identités de charge de travail pour Azure Kubernetes. Les versions antérieures de Microsoft.Identity.Web exprimaient la clé secrète client dans une propriété unique « ClientSecret » au lieu de « ClientCredentials ». Ce principe est toujours pris en charge à des fins de compatibilité descendante, mais vous ne pouvez pas utiliser à la fois la propriété « ClientSecret » et la collection « ClientCredentials ».

À la place d’un secret client, vous pouvez fournir un certificat client. L’extrait de code suivant montre l’utilisation d’un certificat stocké dans 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"]
  }
}

Avertissement

Si vous oubliez de remplacer Scopes par un groupe, lorsque vous essayez d’utiliser IDownstreamApi les étendues apparaîtront nulles et IDownstreamApi tentera un appel anonyme (non authentifié) à l’API en aval, ce qui entraînera 401/unauthenticated.

Microsoft.Identity.Web offre plusieurs façons de décrire les certificats, que ce soit en définissant une configuration ou en écrivant du code. Pour plus d’informations, consultez Microsoft.Identity.Web - Using certificates sur GitHub.

Program.cs

using Microsoft.Identity.Web;

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

Une API web doit acquérir un jeton pour l’API en aval. Spécifiez-le en ajoutant la .EnableTokenAcquisitionToCallDownstreamApi()ligne après.AddMicrosoftIdentityWebApi(Configuration). Cette ligne expose le service ITokenAcquisition que vous pouvez utiliser dans vos actions de contrôleur et de pages.

Toutefois, une autre méthode consiste à implémenter un cache de jetons. Par exemple, l’ajout de .AddInMemoryTokenCaches() à Program.cs permet au jeton d’être mis en cache en mémoire.

using Microsoft.Identity.Web;

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

Microsoft.Identity.Web fournit deux mécanismes pour appeler une API web en aval à partir d’une autre API. L’option que vous choisissez varie selon que vous souhaitez appeler Microsoft Graph ou une autre API.

Option 1 : Appeler Microsoft Graph

Pour appeler Microsoft Graph, Microsoft.Identity.Web vous permet d’utiliser directement le GraphServiceClient (exposé par le Kit de développement logiciel (SDK) Microsoft Graph) dans vos actions d’API.

Notes

Il existe actuellement un problème concernant le Kit de développement logiciel (SDK) Microsoft Graph v5+. Pour plus d’informations, consultez la page problème GitHub.

Pour exposer Microsoft Graph :

Ajoutez le package NuGet Microsoft.Identity.Web.GraphServiceClient au projet.
Ajoutez .AddMicrosoftGraph() après .EnableTokenAcquisitionToCallDownstreamApi() dans Program.cs. .AddMicrosoftGraph() a plusieurs remplacements. En utilisant le remplacement qui prend une section de configuration en tant que paramètre, le code devient :

using Microsoft.Identity.Web;

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

Option n°2 : Appeler une API web en aval autre que Microsoft Graph

Ajoutez le package NuGet Microsoft.Identity.Web.DownstreamApi au projet.
Ajoutez .AddDownstreamApi() après .EnableTokenAcquisitionToCallDownstreamApi() dans Program.cs. Le code devient :

using Microsoft.Identity.Web;

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

où -

MyApi indique le nom de l’API web en aval que votre API web a l’intention d’appeler
MyApiScope est l’étendue nécessaire que votre API web doit demander afin d’interagir avec l’API web en aval

Ces valeurs vont être représentées dans votre code JSON qui va ressembler à l’extrait de code suivant.

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

Si l’application web doit appeler une autre ressource d’API, répétez la méthode .AddDownstreamApi() avec l’étendue appropriée, comme indiqué dans l’extrait suivant :

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 est appelé sans aucun paramètre, ce qui signifie que le jeton d’accès est acquis juste à temps quand le contrôleur demande le jeton en spécifiant l’étendue.

L’étendue peut également être passée lors de l’appel de .EnableTokenAcquisitionToCallDownstreamApi , ce qui permettra à l’application web d’acquérir le jeton lors de la connexion utilisateur initiale. Le jeton est ensuite extrait du cache lorsque le contrôleur le demande.

À l’instar des applications web, différentes implémentations de cache de jetons peuvent être choisies. Pour plus d’informations, consultez Microsoft identity web - Token cache serialization sur GitHub.

L’image suivante montre les possibilités pour Microsoft.Identity.Web et l’impact sur Program.cs :

Block diagram showing service configuration options in startup dot C S for calling a web API and specifying a token cache implementation

Remarque

Pour bien comprendre les exemples de code présentés ici, vous devez maîtriser les notions de base d'ASP.NET Core, en particulier l'injection de dépendances et le modèle options.

Secrets clients ou certificats clients

URL de l’API web en aval ;
étendues requises pour appeler l’API.

Dans l’exemple suivant, la section GraphBeta spécifie ces paramètres.

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

Remarque

À la place d’un secret client, vous pouvez fournir un certificat client. L’extrait de code suivant montre l’utilisation d’un certificat stocké dans 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"]
  }
}

Avertissement

Modifier Startup.Auth.cs

Votre application web doit acquérir un jeton pour l’API en aval. Microsoft.Identity.Web propose deux mécanismes pour appeler une API en aval à partir d’une API web. L’option que vous choisissez varie selon que vous souhaitez appeler Microsoft Graph ou une autre API.

Option 1 : Appeler Microsoft Graph

Si vous souhaitez appeler Microsoft Graph, Microsoft.Identity.Web vous permet d’utiliser directement le GraphServiceClient (exposé par le Kit de développement logiciel (SDK) Microsoft Graph) dans vos actions d’API. Pour exposer Microsoft Graph :

Ajoutez le package NuGet Microsoft.Identity.Web.GraphServiceClient à votre projet.

Ajoutez .AddMicrosoftGraph() à la collection de services dans le fichier Startup.Auth.cs. .AddMicrosoftGraph() a plusieurs remplacements. En utilisant le remplacement qui prend une section de configuration en tant que paramètre, le code devient :

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 n°2 : Appeler une API web en aval autre que Microsoft Graph

Si vous souhaitez appeler une autre API que Microsoft Graph, Microsoft.Identity.Web vous permet d’utiliser directement l’interface IDownstreamApi dans vos actions d’API. Pour utiliser cette interface :

Ajoutez le package NuGet Microsoft.Identity.Web.DownstreamApi au projet.
Ajoutez .AddDownstreamApi() après .EnableTokenAcquisitionToCallDownstreamApi() dans le fichier Startup.cs. .AddDownstreamApi() possède deux arguments :
- Le nom d’un service (api), que vous utilisez dans vos actions de contrôleur pour référencer la configuration correspondante
- Une section de configuration représentant les paramètres utilisés pour appeler l’API web en aval.

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

Le flux On-behalf-of (OBO) permet d’obtenir un jeton pour appeler l’API web en aval. Dans ce flux, votre API web reçoit de l’application cliente un jeton du porteur avec des permissions déléguées par l’utilisateur, puis échange ce jeton contre un autre jeton d’accès pour appeler l’API web en aval.

Le code ci-dessous utilise le SecurityContextHolder de l’infrastructure de sécurité Spring dans l’API web pour récupérer le jeton du porteur validé. Il utilise ensuite la bibliothèque Java MSAL pour obtenir un jeton pour l’API en aval à l’aide de l’appel acquireToken avec OnBehalfOfParameters. MSAL met en cache le jeton afin que les appels subséquents à l’API puissent utiliser acquireTokenSilently pour récupérer ce jeton.

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

Une API web Python doit utiliser un intergiciel pour valider le jeton du porteur reçu du client. L'API web peut ensuite obtenir le jeton d'accès de l'API située en aval à l'aide de la bibliothèque MSAL Python en appelant la méthode acquire_token_on_behalf_of. Pour obtenir un exemple d’utilisation de cette API, consultez le code de test pour microsoft-authentication-library-for-python sur GitHub. Consultez également la présentation du problème 53 dans ce même dépôt pour une approche qui contourne la nécessité d’une application de niveau intermédiaire.

Vous pouvez également voir un exemple de l’implémentation du flux OBO dans l’exemple ms-identity-python-on-behalf-of.

Vous pouvez également voir un exemple d’implémentation de flux OBO dans NodeJS et Azure Functions.

Protocol

Pour plus d’informations sur le protocole OBO, consultez la section Plateforme d’identités Microsoft et flux On-Behalf-Of OAuth 2.0.

Étapes suivantes

Passez à l’article suivant de ce scénario, Acquérir un jeton pour l’application.

Une API web qui appelle des API web : Configuration de code

Microsoft.Identity.Web

Secrets clients ou certificats clients

Program.cs

Option 1 : Appeler Microsoft Graph

Option n°2 : Appeler une API web en aval autre que Microsoft Graph

Protocol

Étapes suivantes

Ressources supplémentaires