API Web che chiama le API Web: Configurazione del codice

Si applica a: Tenant della forza lavoro (altre informazioni)

Questo articolo descrive come configurare il codice per un'app per le API Web usando il flusso del codice di autorizzazione OAuth 2.0.

Microsoft consiglia di usare il pacchetto NuGet Microsoft.Identity.Web durante lo sviluppo di un'API protetta ASP.NET Core che chiama le API Web downstream. Vedere API Web protetta: Configurazione del codice | Microsoft.Identity.Web per una rapida presentazione di tale libreria nel contesto di un'API Web.

Prerequisiti

• Un account Azure con una sottoscrizione attiva. Creare un account gratuito. Questo account deve disporre delle autorizzazioni per gestire le applicazioni. Usare uno dei ruoli seguenti necessari per registrare l'applicazione:
  • Amministratore di applicazioni
  • Sviluppatore di applicazioni
• Registrare una nuova app nell'interfaccia di amministrazione di Microsoft Entra, configurata solo per gli account in questa directory organizzativa. Per altri dettagli, vedere Registrare un'applicazione . Registrare i valori seguenti dalla pagina Panoramica dell'applicazione per usarli in un secondo momento:
  • ID applicazione (cliente)
  • ID della directory (cliente)
• Aggiungere un certificato client alla registrazione dell'app. Per altre informazioni, vedere Aggiungere e gestire le credenziali dell'applicazione in Microsoft Entra ID.

Configurare l'app

Scegliere una lingua per l'API Web.

ASP.NET Core

Segreti del client o certificati del client

Dato che la tua app Web ora chiama un'API Web downstream, fornisci un segreto client o un certificato client nel file appsettings.json. È anche possibile aggiungere una sezione che specifica:

• URL dell'API Web downstream
• Ambiti necessari per chiamare l'API

Nell'esempio seguente la GraphBeta sezione specifica queste impostazioni.

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

Nota

È possibile proporre una raccolta di credenziali client, inclusa una soluzione senza credenziali, ad esempio la federazione delle identità del carico di lavoro per Azure Kubernetes. Le versioni precedenti di Microsoft.Identity.Web hanno espresso il segreto client in una singola proprietà "ClientSecret" anziché "ClientCredentials". Questa opzione è ancora supportata per la compatibilità con le versioni precedenti, ma non è possibile usare sia la proprietà "ClientSecret" che l'insieme "ClientCredentials".

Anziché un segreto client, è possibile fornire un certificato client. Il frammento di codice seguente illustra l'uso di un certificato archiviato in 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"]
  }
}

Avviso

Se ci si dimentica di modificare Scopes in una matrice, quando si tenta di usare gli IDownstreamApi i scope risulteranno nulli e IDownstreamApi tenterà una chiamata anonima (non autenticata) all'API downstream, che genererà un 401/unauthenticated.

Microsoft.Identity.Web offre diversi modi per descrivere i certificati, sia per configurazione che per codice. Per informazioni dettagliate, vedere Microsoft.Identity.Web - Uso dei certificati in GitHub.

Program.cs

using Microsoft.Identity.Web;

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

Un'API Web deve acquisire un token per l'API downstream. Specificarlo aggiungendo la .EnableTokenAcquisitionToCallDownstreamApi() riga dopo .AddMicrosoftIdentityWebApi(Configuration). Questa riga espone il ITokenAcquisition servizio che può essere usato nelle azioni del controller/delle pagine.

Tuttavia, un metodo alternativo consiste nell'implementare una cache dei token. Ad esempio, aggiungere .AddInMemoryTokenCaches(), a Program.cs consente di memorizzare nella cache il token.

using Microsoft.Identity.Web;

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

Microsoft.Identity.Web offre due meccanismi per chiamare un'API Web downstream da un'altra API. L'opzione scelta dipende dal fatto che si voglia chiamare Microsoft Graph o un'altra API.

Opzione 1: Chiamare Microsoft Graph

Per chiamare Microsoft Graph, Microsoft.Identity.Web consente di utilizzare direttamente il GraphServiceClient esposto da Microsoft Graph SDK nelle azioni dell'API.

Nota

Esiste un problema in corso per Microsoft Graph SDK v5+. Per altre informazioni, vedere il problema di GitHub.

Per esporre Microsoft Graph:

1. Aggiungere il pacchetto NuGet Microsoft.Identity.Web.GraphServiceClient al progetto.
2. Aggiungere .AddMicrosoftGraph() dopo .EnableTokenAcquisitionToCallDownstreamApi() in Program.cs. .AddMicrosoftGraph() ha diverse sovrascritture. Usando l'override che accetta una sezione di configurazione come parametro, il codice diventa:

using Microsoft.Identity.Web;

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

Opzione 2: Chiamare un'API Web downstream diversa da Microsoft Graph

1. Aggiungere il pacchetto NuGet Microsoft.Identity.Web.DownstreamApi al progetto.
2. Aggiungere .AddDownstreamApi() dopo .EnableTokenAcquisitionToCallDownstreamApi() in Program.cs. Il codice diventa:

using Microsoft.Identity.Web;

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

dove;

• MyApi indica il nome dell'API Web downstream che l'API Web intende chiamare
• MyApiScope è l'ambito necessario per richiedere l'API Web per interagire con l'API Web downstream

Questi valori verranno rappresentati nel codice JSON che sarà simile al frammento di codice seguente.

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

Se l'app Web deve chiamare un'altra risorsa API, ripetere il .AddDownstreamApi() metodo con l'ambito pertinente, come illustrato nel frammento di codice seguente:

using Microsoft.Identity.Web;

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

Si noti che .EnableTokenAcquisitionToCallDownstreamApi viene chiamato senza alcun parametro, il che significa che il token di accesso viene acquisito just-in-time quando il controller richiede il token specificando l'ambito.

L'ambito può anche essere passato quando si chiama .EnableTokenAcquisitionToCallDownstreamApi, che fa sì che l'applicazione web acquisti il token durante l'accesso utente iniziale. Il token verrà quindi estratto dalla cache quando il controller lo richiede.

Analogamente alle app Web, è possibile scegliere varie implementazioni della cache dei token. Per informazioni dettagliate, vedere Microsoft Identity Web - Serializzazione della cache dei token in GitHub.

L'immagine seguente mostra le possibilità di Microsoft.Identity.Web e l'impatto sulle Program.cs:

Nota

Per comprendere appieno gli esempi di codice, acquisire familiarità con i concetti fondamentali di base di ASP.NET e in particolare con l'inserimento delle dipendenze e le opzioni.

ASP.NET

Segreti del client o certificati del client

Dato che la tua app Web ora chiama un'API Web downstream, fornisci un segreto client o un certificato client nel file appsettings.json. È anche possibile aggiungere una sezione che specifica:

• URL dell'API Web downstream
• Ambiti necessari per chiamare l'API

Nell'esempio seguente la GraphBeta sezione specifica queste impostazioni.

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

Nota

È possibile proporre una raccolta di credenziali client, inclusa una soluzione senza credenziali, ad esempio la federazione delle identità del carico di lavoro per Azure Kubernetes. Le versioni precedenti di Microsoft.Identity.Web hanno espresso il segreto client in una singola proprietà "ClientSecret" anziché "ClientCredentials". Questa opzione è ancora supportata per la compatibilità con le versioni precedenti, ma non è possibile usare sia la proprietà "ClientSecret" che l'insieme "ClientCredentials".

Anziché un segreto client, è possibile fornire un certificato client. Il frammento di codice seguente illustra l'uso di un certificato archiviato in 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"]
  }
}

Avviso

Se ci si dimentica di modificare Scopes in una matrice, quando si tenta di usare gli IDownstreamApi i scope risulteranno nulli e IDownstreamApi tenterà una chiamata anonima (non autenticata) all'API downstream, che genererà un 401/unauthenticated.

Microsoft.Identity.Web offre diversi modi per descrivere i certificati, sia per configurazione che per codice. Per informazioni dettagliate, vedere Microsoft.Identity.Web - Uso dei certificati in GitHub.

Modificare Startup.Auth.cs

L'app Web deve acquisire un token per l'API downstream, Microsoft.Identity.Web offre due meccanismi per chiamare un'API downstream da un'API Web. L'opzione scelta dipende dal fatto che si voglia chiamare Microsoft Graph o un'altra API.

Opzione 1: Chiamare Microsoft Graph

Se si vuole chiamare Microsoft Graph, Microsoft.Identity.Web consente di usare direttamente GraphServiceClient (esposto da Microsoft Graph SDK) nelle azioni API. Per esporre Microsoft Graph:

1. Aggiungere il pacchetto NuGet Microsoft.Identity.Web.GraphServiceClient al progetto.

2. Aggiungere .AddMicrosoftGraph() alla raccolta di servizi nel file Startup.Auth.cs . .AddMicrosoftGraph() ha diverse sovrascritture. Usando l'override che accetta una sezione di configurazione come parametro, il codice diventa:

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

Opzione 2: Chiamare un'API Web downstream diversa da Microsoft Graph

Se si vuole chiamare un'API diversa da Microsoft Graph, Microsoft.Identity.Web consente di usare l'interfaccia nelle azioni dell'API IDownstreamApi . Per usare questa interfaccia:

1. Aggiungere il pacchetto NuGet Microsoft.Identity.Web.DownstreamApi al progetto.
2. Aggiungere .AddDownstreamApi() dopo .EnableTokenAcquisitionToCallDownstreamApi() nel file Startup.cs . .AddDownstreamApi() ha due argomenti:
   • Nome di un servizio (API): questo nome viene usato nelle azioni del controller per fare riferimento alla configurazione corrispondente
   • sezione di configurazione che rappresenta i parametri usati per chiamare l'API Web downstream.

Ecco il codice:

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

Giava

Uso del flusso OBO (On-behalf-of)

Il flusso on-behalf-of (OBO) viene utilizzato per ottenere un token da utilizzare per chiamare l'API web a valle. In questo flusso, l'API Web riceve un token di connessione con autorizzazioni delegate dall'utente dall'applicazione client e quindi scambia questo token per un altro token di accesso per chiamare l'API Web downstream.

Il codice seguente utilizza il framework di Spring Security nell'API web per ottenere il token bearer convalidato. Usa quindi la libreria Java MSAL per ottenere un token per l'API downstream usando la acquireToken chiamata con OnBehalfOfParameters. MSAL memorizza nella cache il token in modo che le chiamate successive all'API possano usare acquireTokenSilently per ottenere il token memorizzato nella cache.

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

Pitone

Uso del flusso OBO (On-behalf-of)

Il flusso on-behalf-of (OBO) viene utilizzato per ottenere un token da utilizzare per chiamare l'API web a valle. In questo flusso, l'API Web riceve un token di connessione con autorizzazioni delegate dall'utente dall'applicazione client e quindi scambia questo token per un altro token di accesso per chiamare l'API Web downstream.

Un'API Web Python deve usare un middleware per convalidare il token di connessione ricevuto dal client. L'API Web può quindi ottenere il token di accesso per l'API downstream usando la libreria Python MSAL chiamando il acquire_token_on_behalf_of metodo . Per un esempio di uso di questa API, vedere il codice di test per microsoft-authentication-library-for-python in GitHub. Vedere anche la discussione del problema 53 nello stesso repository per un approccio che ignora la necessità di un'applicazione di livello intermedio.

È anche possibile vedere un esempio dell'implementazione del flusso OBO nell'esempio ms-identity-python-on-behalf-of .

È anche possibile vedere un esempio di implementazione del flusso OBO in Node.js e Funzioni di Azure.

Protocollo

Per ulteriori informazioni sul protocollo OBO, vedere la piattaforma di identità Microsoft e il flusso OAuth 2.0 On-Behalf-Of.

Passaggio successivo

Acquisire un token per l'app.