Ett webb-API som anropar webb-API:er: Kodkonfiguration

Den här artikeln beskriver hur du konfigurerar kod för en webb-API-app med hjälp av OAuth 2.0-auktoriseringskodflödet.

Microsoft rekommenderar att du använder NuGet-paketet Microsoft.Identity.Web när du utvecklar ett ASP.NET Core-skyddat API som anropar underordnade webb-API:er. Se Skyddat webb-API: Kodkonfiguration | Microsoft.Identity.Web för en snabb presentation av biblioteket i kontexten för ett webb-API.

Förutsättningar

• Registrera ett webb-API som anropar webb-API:er

Konfigurera appen

Välj ett språk för webb-API:et.

ASP.NET Core

Klienthemligheter eller klientcertifikat

Eftersom webbappen nu anropar ett underordnat webb-API anger du en klienthemlighet eller ett klientcertifikat i appsettings.json-filen. Du kan också lägga till ett avsnitt som anger:

• URL:en för det underordnade webb-API:et
• De omfång som krävs för att anropa API:et

I följande exempel anger avsnittet GraphBeta dessa inställningar.

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

Kommentar

Du kan föreslå en samling klientautentiseringsuppgifter, inklusive en lösning utan autentiseringsuppgifter som arbetsbelastningsidentitetsfederation för Azure Kubernetes. Tidigare versioner av Microsoft.Identity.Web uttryckte klienthemligheten i en enda egenskap "ClientSecret" i stället för "ClientCredentials". Detta stöds fortfarande för bakåtkompatibilitet, men du kan inte använda både egenskapen "ClientSecret" och samlingen "ClientCredentials".

I stället för en klienthemlighet kan du ange ett klientcertifikat. Följande kodfragment visar hur du använder ett certifikat som lagras i 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"]
  }
}

Varning

Om du glömmer att ändra Scopes till en matris visas null när du försöker använda omfången IDownstreamApi och IDownstreamApi ett anonymt (oautentiserat) anrop till det underordnade API:et, vilket resulterar i ett 401/unauthenticated.

Microsoft.Identity.Web innehåller flera sätt att beskriva certifikat, både efter konfiguration eller kod. Mer information finns i Microsoft.Identity.Web – Använda certifikat på GitHub.

Program.cs

using Microsoft.Identity.Web;

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

Ett webb-API måste hämta en token för det underordnade API:et. Ange den genom att lägga till .EnableTokenAcquisitionToCallDownstreamApi() raden efter .AddMicrosoftIdentityWebApi(Configuration). Den här raden exponerar tjänsten ITokenAcquisition som kan användas i åtgärder för kontrollant/sidor.

En alternativ metod är dock att implementera en tokencache. Om du till exempel lägger till .AddInMemoryTokenCaches(), i Program.cs kan token cachelagras i minnet.

using Microsoft.Identity.Web;

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

Microsoft.Identity.Web innehåller två mekanismer för att anropa ett underordnat webb-API från ett annat API. Vilket alternativ du väljer beror på om du vill anropa Microsoft Graph eller något annat API.

Alternativ 1: Anropa Microsoft Graph

Om du vill anropa Microsoft Graph gör Microsoft.Identity.Web att du kan använda GraphServiceClient (exponerad av Microsoft Graph SDK) direkt i API-åtgärderna.

Kommentar

Det finns ett pågående problem för Microsoft Graph SDK v5+. Mer information finns i GitHub-problemet.

Så här exponerar du Microsoft Graph:

1. Lägg till NuGet-paketet Microsoft.Identity.Web.GraphServiceClient i projektet.
2. Lägg till .AddMicrosoftGraph() efter .EnableTokenAcquisitionToCallDownstreamApi() i Program.cs. .AddMicrosoftGraph() har flera åsidosättningar. Med hjälp av åsidosättningen som tar ett konfigurationsavsnitt som en parameter blir koden:

using Microsoft.Identity.Web;

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

Alternativ 2: Anropa ett annat underordnat webb-API än Microsoft Graph

1. Lägg till NuGet-paketet Microsoft.Identity.Web.DownstreamApi i projektet.
2. Lägg till .AddDownstreamApi() efter .EnableTokenAcquisitionToCallDownstreamApi() i Program.cs. Koden blir:

using Microsoft.Identity.Web;

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

var;

• MyApi anger namnet på det underordnade webb-API:et som ditt webb-API avser att anropa
• MyApiScope är det omfång som krävs för att webb-API:et ska kunna begäras för att interagera med det underordnade webb-API:et

Dessa värden representeras i din JSON som liknar följande kodfragment.

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

Om webbappen behöver anropa en annan API-resurs upprepar du .AddDownstreamApi() metoden med relevant omfång enligt följande kodfragment:

using Microsoft.Identity.Web;

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

Observera att .EnableTokenAcquisitionToCallDownstreamApi anropas utan någon parameter, vilket innebär att åtkomsttoken hämtas precis i tid när kontrollanten begär token genom att ange omfånget.

Omfånget kan också skickas när du anropar .EnableTokenAcquisitionToCallDownstreamApi, vilket gör att webbappen hämtar token under den första användarinloggningen. Token hämtas sedan från cacheminnet när kontrollanten begär den.

På samma sätt som med webbappar kan du välja olika implementeringar av tokencache. Mer information finns i Microsoft identity web – Token cache serialization on GitHub (Microsoft identity web – Token cache serialization on GitHub).

Följande bild visar möjligheterna med Microsoft.Identity.Web och påverkan på Program.cs:

Kommentar

Om du vill förstå kodexemplen fullt ut här bör du känna till grunderna för ASP.NET Core, särskilt beroendeinmatning och alternativ.

ASP.NET

Klienthemligheter eller klientcertifikat

Eftersom webbappen nu anropar ett underordnat webb-API anger du en klienthemlighet eller ett klientcertifikat i appsettings.json-filen. Du kan också lägga till ett avsnitt som anger:

• URL:en för det underordnade webb-API:et
• De omfång som krävs för att anropa API:et

I följande exempel anger avsnittet GraphBeta dessa inställningar.

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

Kommentar

Du kan föreslå en samling klientautentiseringsuppgifter, inklusive en lösning utan autentiseringsuppgifter som arbetsbelastningsidentitetsfederation för Azure Kubernetes. Tidigare versioner av Microsoft.Identity.Web uttryckte klienthemligheten i en enda egenskap "ClientSecret" i stället för "ClientCredentials". Detta stöds fortfarande för bakåtkompatibilitet, men du kan inte använda både egenskapen "ClientSecret" och samlingen "ClientCredentials".

I stället för en klienthemlighet kan du ange ett klientcertifikat. Följande kodfragment visar hur du använder ett certifikat som lagras i 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"]
  }
}

Varning

Om du glömmer att ändra Scopes till en matris visas null när du försöker använda omfången IDownstreamApi och IDownstreamApi ett anonymt (oautentiserat) anrop till det underordnade API:et, vilket resulterar i ett 401/unauthenticated.

Microsoft.Identity.Web innehåller flera sätt att beskriva certifikat, både efter konfiguration eller kod. Mer information finns i Microsoft.Identity.Web – Använda certifikat på GitHub.

Ändra Startup.Auth.cs

Webbappen måste hämta en token för det underordnade API:et. Microsoft.Identity.Web tillhandahåller två mekanismer för att anropa ett underordnat API från ett webb-API. Vilket alternativ du väljer beror på om du vill anropa Microsoft Graph eller något annat API.

Alternativ 1: Anropa Microsoft Graph

Om du vill anropa Microsoft Graph gör Microsoft.Identity.Web att du kan använda GraphServiceClient (exponeras av Microsoft Graph SDK) direkt i dina API-åtgärder. Så här exponerar du Microsoft Graph:

1. Lägg till NuGet-paketet Microsoft.Identity.Web.GraphServiceClient i projektet.

2. Lägg till .AddMicrosoftGraph() i tjänstsamlingen i Startup.Auth.cs-filen. .AddMicrosoftGraph() har flera åsidosättningar. Med hjälp av åsidosättningen som tar ett konfigurationsavsnitt som en parameter blir koden:

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

Alternativ 2: Anropa ett annat underordnat webb-API än Microsoft Graph

Om du vill anropa ett annat API än Microsoft Graph gör Microsoft.Identity.Web att du kan använda IDownstreamApi gränssnittet i dina API-åtgärder. Så här använder du det här gränssnittet:

1. Lägg till NuGet-paketet Microsoft.Identity.Web.DownstreamApi i projektet.
2. Lägg till .AddDownstreamApi() efter .EnableTokenAcquisitionToCallDownstreamApi() i filen Startup.cs . .AddDownstreamApi() har två argument:
   • Namnet på en tjänst (API): du använder det här namnet i dina kontrollantåtgärder för att referera till motsvarande konfiguration
   • ett konfigurationsavsnitt som representerar de parametrar som används för att anropa det underordnade webb-API:et.

Här är koden:

  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

Använda OBO-flödet (on-behalf-of)

OBO-flödet (on-behalf-of) används för att hämta en token för att anropa det underordnade webb-API:et. I det här flödet tar webb-API:et emot en ägartoken med användardelegeringsbehörigheter från klientprogrammet och utbyter sedan denna token mot en annan åtkomsttoken för att anropa det underordnade webb-API:et.

Koden nedan använder Spring Security Framework i SecurityContextHolder webb-API:et för att hämta den verifierade ägartoken. Den använder sedan MSAL Java-biblioteket för att hämta en token för nedströms-API:et med hjälp av anropet acquireToken med OnBehalfOfParameters. MSAL cachelagrar token så att efterföljande anrop till API:et kan använda acquireTokenSilently för att hämta den cachelagrade token.

@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

Använda OBO-flödet (on-behalf-of)

OBO-flödet (on-behalf-of) används för att hämta en token för att anropa det underordnade webb-API:et. I det här flödet tar webb-API:et emot en ägartoken med användardelegeringsbehörigheter från klientprogrammet och utbyter sedan denna token mot en annan åtkomsttoken för att anropa det underordnade webb-API:et.

Ett Python-webb-API måste använda vissa mellanprogram för att verifiera den ägartoken som tas emot från klienten. Webb-API:et kan sedan hämta åtkomsttoken för nedströms-API:et med hjälp av MSAL Python-biblioteket genom att anropa acquire_token_on_behalf_of metoden. Ett exempel på hur du använder det här API:et finns i testkoden för microsoft-authentication-library-for-python på GitHub. Se även diskussionen om problem 53 på samma lagringsplats för en metod som kringgår behovet av ett mellannivåprogram.

Du kan också se ett exempel på OBO-flödesimplementeringen i exemplet ms-identity-python-on-behalf-of .

Du kan också se ett exempel på implementering av OBO-flöde i Node.js och Azure Functions.

Protokoll

Mer information om OBO-protokollet finns i flödet Microsofts identitetsplattform och OAuth 2.0 On-Behalf-Of.

Gå vidare

Hämta en token för appen.