Internetowy interfejs API, który wywołuje internetowe interfejsy API: konfiguracja kodu

W tym artykule opisano sposób konfigurowania kodu dla aplikacji internetowego interfejsu API przy użyciu przepływu kodu autoryzacji OAuth 2.0.

Firma Microsoft zaleca użycie pakietu NuGet Microsoft.Identity.Web podczas tworzenia chronionego interfejsu API ASP.NET Core wywołującego podrzędne internetowe interfejsy API. Zobacz Chroniony internetowy interfejs API: konfiguracja kodu | Microsoft.Identity.Web umożliwia szybką prezentację tej biblioteki w kontekście internetowego interfejsu API.

Wymagania wstępne

• Rejestrowanie internetowego interfejsu API wywołującego internetowe interfejsy API

Konfigurowanie aplikacji

Wybierz język internetowego interfejsu API.

ASP.NET Core

Wpisy tajne klienta lub certyfikaty klienta

Biorąc pod uwagę, że aplikacja internetowa wywołuje teraz podrzędny internetowy interfejs API, podaj klucz tajny klienta lub certyfikat klienta w pliku appsettings.json . Możesz również dodać sekcję, która określa:

• Adres URL podrzędnego internetowego interfejsu API
• Zakresy wymagane do wywoływania interfejsu API

W poniższym przykładzie GraphBeta sekcja określa te ustawienia.

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

Uwaga

Możesz zaproponować kolekcję poświadczeń klienta, w tym rozwiązanie bez poświadczeń, takie jak federacja tożsamości obciążenia dla usługi Azure Kubernetes. Poprzednie wersje pliku Microsoft.Identity.Web wyraziły wpis tajny klienta w pojedynczej właściwości "ClientSecret" zamiast "ClientCredentials". Jest to nadal obsługiwane w przypadku zgodności z poprzednimi wersjami, ale nie można użyć zarówno właściwości "ClientSecret", jak i kolekcji "ClientCredentials".

Zamiast klucza tajnego klienta można podać certyfikat klienta. Poniższy fragment kodu przedstawia użycie certyfikatu przechowywanego w usłudze 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"]
  }
}

Ostrzeżenie

Jeśli zapomnisz zmienić Scopes obiekt na tablicę, próba użycia IDownstreamApi zakresów będzie mieć wartość null i IDownstreamApi podejmie próbę wywołania anonimowego (nieuwierzytelnionego) do podrzędnego interfejsu API, co spowoduje 401/unauthenticatedwystąpienie .

Microsoft.Identity.Web udostępnia kilka sposobów opisywania certyfikatów, zarówno przez konfigurację, jak i kod. Aby uzyskać szczegółowe informacje, zobacz Microsoft.Identity.Web — używanie certyfikatów w witrynie GitHub.

Program.cs

using Microsoft.Identity.Web;

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

Internetowy interfejs API musi uzyskać token dla podrzędnego interfejsu API. Określ go, dodając .EnableTokenAcquisitionToCallDownstreamApi() wiersz po .AddMicrosoftIdentityWebApi(Configuration). Ten wiersz uwidacznia usługę ITokenAcquisition , która może być używana w akcjach kontrolera/stron.

Alternatywną metodą jest jednak zaimplementowanie pamięci podręcznej tokenów. Na przykład dodanie .AddInMemoryTokenCaches()elementu do Program.cs umożliwia buforowanie tokenu w pamięci.

using Microsoft.Identity.Web;

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

Microsoft.Identity.Web udostępnia dwa mechanizmy wywoływania podrzędnego internetowego interfejsu API z innego interfejsu API. Wybrana opcja zależy od tego, czy chcesz wywołać program Microsoft Graph, czy inny interfejs API.

Opcja 1. Wywoływanie programu Microsoft Graph

Aby wywołać program Microsoft Graph, microsoft.Identity.Web umożliwia bezpośrednie używanie GraphServiceClient (uwidocznionych przez zestaw SDK programu Microsoft Graph) w akcjach interfejsu API.

Uwaga

Istnieje ciągły problem dotyczący zestawu Microsoft Graph SDK w wersji 5 lub nowszej. Aby uzyskać więcej informacji, zapoznaj się z problemem z usługą GitHub.

Aby uwidocznić program Microsoft Graph:

1. Dodaj pakiet NuGet Microsoft.Identity.Web.GraphServiceClient do projektu.
2. Dodaj .AddMicrosoftGraph() po .EnableTokenAcquisitionToCallDownstreamApi() w Program.cs. .AddMicrosoftGraph() ma kilka przesłonięć. Za pomocą przesłonięcia, które przyjmuje sekcję konfiguracji jako parametr, kod staje się następujący:

using Microsoft.Identity.Web;

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

Opcja 2. Wywoływanie podrzędnego internetowego interfejsu API innego niż Microsoft Graph

1. Dodaj pakiet NuGet Microsoft.Identity.Web.DownstreamApi do projektu.
2. Dodaj .AddDownstreamApi() po .EnableTokenAcquisitionToCallDownstreamApi() w Program.cs. Kod staje się:

using Microsoft.Identity.Web;

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

gdzie;

• MyApi określa nazwę podrzędnego internetowego interfejsu API, który ma być wywoływany przez internetowy interfejs API
• MyApiScope to zakres niezbędny do zażądania internetowego interfejsu API w celu interakcji z podrzędnym internetowym interfejsem API

Te wartości będą reprezentowane w kodzie JSON, który będzie podobny do poniższego fragmentu kodu.

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

Jeśli aplikacja internetowa musi wywołać inny zasób interfejsu API, powtórz metodę .AddDownstreamApi() z odpowiednim zakresem, jak pokazano w poniższym fragmencie kodu:

using Microsoft.Identity.Web;

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

Należy pamiętać, że .EnableTokenAcquisitionToCallDownstreamApi jest wywoływany bez żadnego parametru, co oznacza, że token dostępu jest uzyskiwany w odpowiednim czasie, ponieważ kontroler żąda tokenu, określając zakres.

Zakres można również przekazać podczas wywoływania metody .EnableTokenAcquisitionToCallDownstreamApi, co spowoduje, że aplikacja internetowa uzyska token podczas początkowego logowania użytkownika. Token zostanie następnie ściągnięty z pamięci podręcznej, gdy kontroler zażąda go.

Podobnie jak w przypadku aplikacji internetowych, można wybrać różne implementacje pamięci podręcznej tokenów. Aby uzyskać szczegółowe informacje, zobacz Microsoft identity web — token cache serialization on GitHub (Sieć Web tożsamości firmy Microsoft — serializacja pamięci podręcznej tokenów w witrynie GitHub).

Na poniższej ilustracji przedstawiono możliwości microsoft.Identity.Web oraz wpływ na Program.cs:

Uwaga

Aby w pełni zrozumieć przykłady kodu, zapoznaj się z podstawami ASP.NET Core, a w szczególności z iniekcją zależności i opcjami.

ASP.NET

Wpisy tajne klienta lub certyfikaty klienta

Biorąc pod uwagę, że aplikacja internetowa wywołuje teraz podrzędny internetowy interfejs API, podaj klucz tajny klienta lub certyfikat klienta w pliku appsettings.json . Możesz również dodać sekcję, która określa:

• Adres URL podrzędnego internetowego interfejsu API
• Zakresy wymagane do wywoływania interfejsu API

W poniższym przykładzie GraphBeta sekcja określa te ustawienia.

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

Uwaga

Możesz zaproponować kolekcję poświadczeń klienta, w tym rozwiązanie bez poświadczeń, takie jak federacja tożsamości obciążenia dla usługi Azure Kubernetes. Poprzednie wersje pliku Microsoft.Identity.Web wyraziły wpis tajny klienta w pojedynczej właściwości "ClientSecret" zamiast "ClientCredentials". Jest to nadal obsługiwane w przypadku zgodności z poprzednimi wersjami, ale nie można użyć zarówno właściwości "ClientSecret", jak i kolekcji "ClientCredentials".

Zamiast klucza tajnego klienta można podać certyfikat klienta. Poniższy fragment kodu przedstawia użycie certyfikatu przechowywanego w usłudze 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"]
  }
}

Ostrzeżenie

Jeśli zapomnisz zmienić Scopes obiekt na tablicę, próba użycia IDownstreamApi zakresów będzie mieć wartość null i IDownstreamApi podejmie próbę wywołania anonimowego (nieuwierzytelnionego) do podrzędnego interfejsu API, co spowoduje 401/unauthenticatedwystąpienie .

Microsoft.Identity.Web udostępnia kilka sposobów opisywania certyfikatów, zarówno przez konfigurację, jak i kod. Aby uzyskać szczegółowe informacje, zobacz Microsoft.Identity.Web — używanie certyfikatów w witrynie GitHub.

Modyfikowanie Startup.Auth.cs

Aplikacja internetowa musi uzyskać token dla podrzędnego interfejsu API. Microsoft.Identity.Web udostępnia dwa mechanizmy wywoływania podrzędnego interfejsu API z internetowego interfejsu API. Wybrana opcja zależy od tego, czy chcesz wywołać program Microsoft Graph, czy inny interfejs API.

Opcja 1. Wywoływanie programu Microsoft Graph

Jeśli chcesz wywołać program Microsoft Graph, microsoft.Identity.Web umożliwia bezpośrednie używanie GraphServiceClient (uwidocznionych przez zestaw SDK programu Microsoft Graph) w akcjach interfejsu API. Aby uwidocznić program Microsoft Graph:

1. Dodaj pakiet NuGet Microsoft.Identity.Web.GraphServiceClient do projektu.

2. Dodaj .AddMicrosoftGraph() do kolekcji usług w pliku Startup.Auth.cs . .AddMicrosoftGraph() ma kilka przesłonięć. Za pomocą przesłonięcia, które przyjmuje sekcję konfiguracji jako parametr, kod staje się następujący:

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

Opcja 2. Wywoływanie podrzędnego internetowego interfejsu API innego niż Microsoft Graph

Jeśli chcesz wywołać interfejs API inny niż Microsoft Graph, microsoft.Identity.Web umożliwia korzystanie z interfejsu w akcjach interfejsu IDownstreamApi API. Aby użyć tego interfejsu:

1. Dodaj pakiet NuGet Microsoft.Identity.Web.DownstreamApi do projektu.
2. Dodaj .AddDownstreamApi() po .EnableTokenAcquisitionToCallDownstreamApi() w pliku Startup.cs . .AddDownstreamApi() ma dwa argumenty:
   • Nazwa usługi (API): ta nazwa jest używana w akcjach kontrolera w celu odwoływania się do odpowiedniej konfiguracji
   • sekcja konfiguracji reprezentująca parametry używane do wywoływania podrzędnego internetowego interfejsu API.

Oto kod:

  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

Korzystanie z przepływu on-behalf-of (OBO)

Przepływ on-behalf-of (OBO) służy do uzyskiwania tokenu w celu wywołania podrzędnego internetowego interfejsu API. W tym przepływie internetowy interfejs API otrzymuje token elementu nośnego z delegowanymi uprawnieniami użytkownika z aplikacji klienckiej, a następnie wymienia ten token dla innego tokenu dostępu w celu wywołania podrzędnego internetowego interfejsu API.

Poniższy kod używa platformy SecurityContextHolder Spring Security w internetowym interfejsie API, aby uzyskać zweryfikowany token elementu nośnego. Następnie używa biblioteki MSAL Java do uzyskania tokenu dla interfejsu API podrzędnego przy użyciu wywołania acquireToken z OnBehalfOfParameters. Biblioteka MSAL buforuje token, dzięki czemu kolejne wywołania interfejsu API mogą używać acquireTokenSilently do pobierania tokenu buforowanego.

@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

Korzystanie z przepływu on-behalf-of (OBO)

Przepływ on-behalf-of (OBO) służy do uzyskiwania tokenu w celu wywołania podrzędnego internetowego interfejsu API. W tym przepływie internetowy interfejs API otrzymuje token elementu nośnego z delegowanymi uprawnieniami użytkownika z aplikacji klienckiej, a następnie wymienia ten token dla innego tokenu dostępu w celu wywołania podrzędnego internetowego interfejsu API.

Internetowy interfejs API języka Python musi używać oprogramowania pośredniczącego do weryfikowania tokenu elementu nośnego otrzymanego od klienta. Internetowy interfejs API może następnie uzyskać token dostępu dla podrzędnego interfejsu API przy użyciu biblioteki MSAL języka Python, wywołując metodę acquire_token_on_behalf_of . Przykład użycia tego interfejsu API można znaleźć w kodzie testowym biblioteki microsoft-authentication-for-python w witrynie GitHub. Zapoznaj się również z omówieniem problemu 53 w tym samym repozytorium, aby zapoznać się z podejściem, które pomija potrzebę zastosowania aplikacji warstwy środkowej.

Przykład implementacji przepływu OBO można również zobaczyć w przykładzie ms-identity-python-on-behalf-of .

Możesz również zapoznać się z przykładem implementacji przepływu OBO w usługach Node.js i Azure Functions.

Protokół

Aby uzyskać więcej informacji na temat protokołu OBO, zobacz przepływ Platforma tożsamości Microsoft i OAuth 2.0 On-Behalf-Of.

Następny krok

Uzyskaj token dla aplikacji.