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

S’applique à : Locataires de main-d’œuvre (en savoir plus)

Cet article explique comment configurer du code pour une application API Web à l’aide du flux du code d’autorisation OAuth 2.0.

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.

Prerequisites

• Un compte Azure avec un abonnement actif. Créez un compte gratuitement. Ce compte doit disposer des autorisations nécessaires pour gérer les applications. Utilisez l’un des rôles suivants nécessaires pour inscrire l’application :
  • Administrateur d’application
  • Développeur d’applications
• Inscrivez une nouvelle application dans le Centre d’administration Microsoft Entra, configurée pour les comptes dans cet annuaire organisationnel uniquement. Pour plus d’informations, reportez-vous à l'enregistrement d'une application. Enregistrez les valeurs suivantes à partir de la page Vue d’ensemble de l’application pour une utilisation ultérieure :
  • ID d’application (client)
  • ID de l’annuaire (locataire)
• Ajoutez un certificat client à l’inscription de l’application. Pour plus d’informations, consultez Ajouter et gérer les informations d’identification d’application dans l’ID Microsoft Entra.

Configurer l’application

Choisissez une langue pour votre API Web.

ASP.NET Core

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

Note

Vous pouvez proposer un ensemble d’informations d’identification client, y compris une solution sans informations d’identification telle que la fédération d’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 ». Cette fonctionnalité est toujours prise en charge à des fins de compatibilité ascendante, 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"]
  }
}

Warning

Si vous oubliez de remplacer Scopes par un tableau, lorsque vous essayez d’utiliser la IDownstreamApi, les champs d’application apparaîtront comme nuls et IDownstreamApi tentera un appel anonyme (non authentifié) vers l’API en aval, ce qui entraînera une erreur 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();
// ...

L’API web doit acquérir un jeton pour l’API en aval. Spécifiez-le en ajoutant la ligne .EnableTokenAcquisitionToCallDownstreamApi() 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.

Note

Il existe un problème persistant pour Microsoft Graph SDK v5+. Pour en savoir plus, consultez la page Problème GitHub.

Pour exposer Microsoft Graph :

1. Ajoutez le package NuGet Microsoft.Identity.Web.GraphServiceClient au projet.
2. 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

1. Ajoutez le package NuGet Microsoft.Identity.Web.DownstreamApi au projet.
2. 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 désigne le nom de l’API Web en aval que votre API Web a l’intention d’appeler ;
• MyApiScope correspond à la portée nécessaire à votre API Web pour interagir avec l’API Web en aval.

Ces valeurs seront représentées dans votre JSON, qui ressemblera à l’extrait 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();
// ...

Notez que .EnableTokenAcquisitionToCallDownstreamApi est appelé sans aucun paramètre, ce qui signifie que le jeton d’accès est acquis juste à temps lorsque 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 :

Note

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.

ASP.NET

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

Note

Vous pouvez proposer un ensemble d’informations d’identification client, y compris une solution sans informations d’identification telle que la fédération d’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 ». Cette fonctionnalité est toujours prise en charge à des fins de compatibilité ascendante, 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"]
  }
}

Warning

Si vous oubliez de remplacer Scopes par un tableau, lorsque vous essayez d’utiliser la IDownstreamApi, les champs d’application apparaîtront comme nuls et IDownstreamApi tentera un appel anonyme (non authentifié) vers l’API en aval, ce qui entraînera une erreur 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.

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 :

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

2. 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 :

1. Ajoutez le package NuGet Microsoft.Identity.Web.DownstreamApi à votre projet.
2. 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 contenant 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();
          }
      }
  }

Java

Utilisation du flux on-behalf-of (OBO)

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

Python

Utilisation du flux on-behalf-of (OBO)

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.

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 Node.js et Azure Functions.

Protocole

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

Étape suivante

Acquérir un jeton pour l’application.