API Web che chiama le API Web: Configurazione del codice

Segreti client o certificati client

Dato che l'app Web chiama ora un'API Web downstream, fornire 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"]
    }
}

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

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 controller/pagine.

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

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 usare direttamente ( GraphServiceClient esposto da Microsoft Graph SDK) nelle azioni dell'API.

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 sostituzioni. 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 renderebbe l'app Web acquisire il token durante l'accesso utente iniziale stesso. 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:

Segreti client o certificati client

Dato che l'app Web chiama ora un'API Web downstream, fornire 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"]
    }
}

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

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

Uso del flusso OBO (On-behalf-of)

Il flusso on-behalf-of (OBO) viene usato per ottenere un token per chiamare l'API Web downstream. 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 usa Spring Security Framework nell'API SecurityContextHolder Web per ottenere il token di connessione 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();
    }
}

Uso del flusso OBO (On-behalf-of)

Il flusso on-behalf-of (OBO) viene usato per ottenere un token per chiamare l'API Web downstream. 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 .