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

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

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

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.

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 :

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

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

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

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

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.