Web API'lerini çağıran bir web API'si: Kod yapılandırması

Şunlar için geçerlidir: İş gücü kiracıları (daha fazla bilgi edinin)

Bu makalede, OAuth 2.0 yetkilendirme kodu akışını kullanarak bir Web API'sinin kodunun nasıl yapılandırıldığı açıklanmaktadır.

Microsoft, aşağı akış web API'lerini çağıran bir ASP.NET Core korumalı API geliştirirken Microsoft.Identity.Web NuGet paketini kullanmanızı önerir. Bkz . Korumalı web API'si: Kod yapılandırması | Bir web API'si bağlamında bu kitaplığın hızlı bir sunusu için Microsoft.Identity.Web.

Önkoşullar

• Aktif bir aboneliğe sahip bir Azure hesabı. Ücretsiz bir hesap oluşturun. Bu hesabın uygulamaları yönetme izinleri olmalıdır. Uygulamayı kaydetmek için aşağıdaki rollerden birini kullanın:
  • Uygulama Yöneticisi
  • Uygulama Geliştirici
• Microsoft Entra yönetim merkezine, yalnızca bu kuruluş dizinindeki Hesaplar için yapılandırılmış yeni bir uygulama kaydedin. Daha fazla bilgi için Bir uygulamayı kaydetme bölümüne bakın. Daha sonra kullanmak üzere uygulamaya Genel Bakış sayfasından aşağıdaki değerleri kaydedin:
  • Uygulama (istemci) kimliği
  • Dizin (kullanıcı) kimliği
• Uygulama kaydına bir istemci sertifikası ekleyin. Daha fazla bilgi için bkz. Microsoft Entra Id'de uygulama kimlik bilgilerini ekleme ve yönetme.

Uygulamayı yapılandırma

Web API'niz için bir dil seçin.

ASP.NET Core

İstemci gizli dizileri veya istemci sertifikaları

Web uygulamanızın artık aşağı akış web API'sini çağırdığını göz önünde bulundurarak, appsettings.json dosyasında bir istemci gizli dizisi veya istemci sertifikası sağlayın. Şunları belirten bir bölüm de ekleyebilirsiniz:

• Aşağı akış web API'sinin URL'si
• API'yi çağırmak için gereken kapsamlar

Aşağıdaki örnekte, GraphBeta bölümü bu ayarları belirtir.

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

Not

Azure Kubernetes için iş yükü kimlik federasyonu gibi kimlik bilgisi olmayan bir çözüm de dahil olmak üzere bir istemci kimlik bilgileri koleksiyonu önerebilirsiniz. Microsoft.Identity.Web'in önceki sürümleri, istemci gizli dizisini "ClientCredentials" yerine tek bir "ClientSecret" özelliğinde ifade etti. Bu, geriye dönük uyumluluk için hala desteklenir, ancak hem "ClientSecret" özelliğini hem de "ClientCredentials" koleksiyonunu kullanamazsınız.

İstemci gizli dizisi yerine bir istemci sertifikası sağlayabilirsiniz. Aşağıdaki kod parçacığı, Azure Key Vault'ta depolanan bir sertifikanın kullanılmasını gösterir.

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

Uyarı

değerini bir dizi olarak değiştirmeyi Scopes unutursanız, kullanmayı IDownstreamApi denediğinizde kapsamlar null görünür ve aşağı akış API'sine anonim (kimliği doğrulanmamış) bir çağrı dener ve IDownstreamApi bu da ile 401/unauthenticatedsonuçlanır.

Microsoft.Identity.Web , sertifikaları hem yapılandırmaya hem de koda göre açıklamanın çeşitli yollarını sağlar. Ayrıntılar için bkz . Microsoft.Identity.Web - GitHub'da sertifikaları kullanma.

Program.cs

using Microsoft.Identity.Web;

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

Web API'sinin aşağı akış API'sine yönelik bir belirteç alması gerekir. satırının arkasına .EnableTokenAcquisitionToCallDownstreamApi()ekleyerek .AddMicrosoftIdentityWebApi(Configuration) belirtin. Bu satır, ITokenAcquisition denetleyici/sayfa eylemlerinde kullanılabilecek hizmeti kullanıma sunar.

Ancak alternatif bir yöntem, belirteç önbelleği uygulamaktır. Örneğin, .AddInMemoryTokenCaches()Program.cs eklemek belirtecin bellekte önbelleğe alınmasını sağlar.

using Microsoft.Identity.Web;

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

Microsoft.Identity.Web , başka bir API'den aşağı akış web API'sini çağırmak için iki mekanizma sağlar. Seçtiğiniz seçenek, Microsoft Graph'ı mı yoksa başka bir API'yi mi çağırmak istediğinize bağlıdır.

1. Seçenek: Microsoft Graph'ı çağırma

Microsoft Graph'ı çağırmak için Microsoft.Identity.Web, API eylemlerinde (Microsoft Graph SDK tarafından kullanıma sunulan) doğrudan kullanmanızı GraphServiceClient sağlar.

Not

Microsoft Graph SDK v5+ için devam eden bir sorun vardır. Daha fazla bilgi için GitHub sorununa bakın.

Microsoft Graph'ı kullanıma açmak için:

1. Microsoft.Identity.Web.GraphServiceClient NuGet paketini projeye ekleyin.
2. .AddMicrosoftGraph() Program.cs.EnableTokenAcquisitionToCallDownstreamApi()ekleyin. .AddMicrosoftGraph() birkaç geçersiz kılmaya sahiptir. Yapılandırma bölümünü parametre olarak alan geçersiz kılma kullanıldığında kod şu hale gelir:

using Microsoft.Identity.Web;

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

Seçenek 2: Microsoft Graph dışında bir aşağı akış web API'sini çağırma

1. Microsoft.Identity.Web.DownstreamApi NuGet paketini projeye ekleyin.
2. .AddDownstreamApi() Program.cs.EnableTokenAcquisitionToCallDownstreamApi()ekleyin. Kod şöyle olur:

using Microsoft.Identity.Web;

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

nerede;

• MyApi web API'nizin çağırmak istediği aşağı akış web API'sinin adını belirtir
• MyApiScope , web API'nizin aşağı akış web API'siyle etkileşim kurmak için istemesi için gereken kapsamdır

Bu değerler JSON'unuzda aşağıdaki kod parçacığına benzer şekilde gösterilir.

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

Web uygulamasının başka bir API kaynağını çağırması gerekiyorsa, aşağıdaki kod parçacığında gösterildiği gibi yöntemini ilgili kapsamla yineleyin .AddDownstreamApi() :

using Microsoft.Identity.Web;

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

Herhangi bir parametre olmadan çağrıldığını .EnableTokenAcquisitionToCallDownstreamApi unutmayın, yani denetleyici kapsamı belirterek belirteci istediğinde erişim belirteci tam zamanında alınır.

Kapsam çağrılırken .EnableTokenAcquisitionToCallDownstreamApide geçirilebilir ve bu da web uygulamasının ilk kullanıcı oturum açma işlemi sırasında belirteci almasını sağlar. Ardından denetleyici istediğinde belirteç önbellekten çekilir.

Web uygulamalarına benzer şekilde, çeşitli belirteç önbelleği uygulamaları seçilebilir. Ayrıntılar için bkz . Microsoft identity web - GitHub'da belirteç önbelleği serileştirme .

Aşağıdaki görüntüde Microsoft.Identity.Web'in olasılıkları ve Program.cs üzerindeki etkisi gösterilmektedir:

Not

Buradaki kod örneklerini tam olarak anlamak için ASP.NET Core temelleri ve özellikle bağımlılık ekleme ve seçenekleri hakkında bilgi sahibi olun.

ASP.NET

İstemci gizli dizileri veya istemci sertifikaları

Web uygulamanızın artık aşağı akış web API'sini çağırdığını göz önünde bulundurarak, appsettings.json dosyasında bir istemci gizli dizisi veya istemci sertifikası sağlayın. Şunları belirten bir bölüm de ekleyebilirsiniz:

• Aşağı akış web API'sinin URL'si
• API'yi çağırmak için gereken kapsamlar

Aşağıdaki örnekte, GraphBeta bölümü bu ayarları belirtir.

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

Not

Azure Kubernetes için iş yükü kimlik federasyonu gibi kimlik bilgisi olmayan bir çözüm de dahil olmak üzere bir istemci kimlik bilgileri koleksiyonu önerebilirsiniz. Microsoft.Identity.Web'in önceki sürümleri, istemci gizli dizisini "ClientCredentials" yerine tek bir "ClientSecret" özelliğinde ifade etti. Bu, geriye dönük uyumluluk için hala desteklenir, ancak hem "ClientSecret" özelliğini hem de "ClientCredentials" koleksiyonunu kullanamazsınız.

İstemci gizli dizisi yerine bir istemci sertifikası sağlayabilirsiniz. Aşağıdaki kod parçacığı, Azure Key Vault'ta depolanan bir sertifikanın kullanılmasını gösterir.

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

Uyarı

değerini bir dizi olarak değiştirmeyi Scopes unutursanız, kullanmayı IDownstreamApi denediğinizde kapsamlar null görünür ve aşağı akış API'sine anonim (kimliği doğrulanmamış) bir çağrı dener ve IDownstreamApi bu da ile 401/unauthenticatedsonuçlanır.

Microsoft.Identity.Web , sertifikaları hem yapılandırmaya hem de koda göre açıklamanın çeşitli yollarını sağlar. Ayrıntılar için bkz . Microsoft.Identity.Web - GitHub'da sertifikaları kullanma.

Startup.Auth.cs değiştir

Web uygulamanızın aşağı akış API'sine yönelik bir belirteç alması gerekir. Microsoft.Identity.Web, bir web API'sinden aşağı akış API'sini çağırmak için iki mekanizma sağlar. Seçtiğiniz seçenek, Microsoft Graph'ı mı yoksa başka bir API'yi mi çağırmak istediğinize bağlıdır.

1. Seçenek: Microsoft Graph'ı çağırma

Microsoft Graph'ı çağırmak istiyorsanız, Microsoft.Identity.Web API eylemlerinizde (Microsoft Graph SDK'sı tarafından kullanıma sunulan) doğrudan kullanmanızı GraphServiceClient sağlar. Microsoft Graph'ı kullanıma açmak için:

1. Projenize Microsoft.Identity.Web.GraphServiceClient NuGet paketini ekleyin.

2. Startup.Auth.cs.AddMicrosoftGraph()ekleyin. .AddMicrosoftGraph() birkaç geçersiz kılmaya sahiptir. Yapılandırma bölümünü parametre olarak alan geçersiz kılma kullanıldığında kod şu hale gelir:

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

Seçenek 2: Microsoft Graph dışında bir aşağı akış web API'sini çağırma

Microsoft Graph dışında bir API çağırmak istiyorsanız, Microsoft.Identity.Web API eylemlerinizde arabirimi kullanmanıza IDownstreamApi olanak tanır. Bu arabirimi kullanmak için:

1. Projenize Microsoft.Identity.Web.DownstreamApi NuGet paketini ekleyin.
2. Startup.cs.AddDownstreamApi().EnableTokenAcquisitionToCallDownstreamApi() ekleyin. .AddDownstreamApi() iki bağımsız değişkeni vardır:
   • Hizmetin adı (API): bu adı ilgili yapılandırmaya başvurmak için denetleyici eylemlerinizde kullanırsınız
   • aşağı akış web API'sini çağırmak için kullanılan parametreleri temsil eden bir yapılandırma bölümü.

Kod şu şekildedir:

  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

Adına (OBO) akışı kullanma

Adına (OBO) akışı, aşağı akış web API'sini çağırmak üzere bir belirteç almak için kullanılır. Bu akışta, web API'niz istemci uygulamasından kullanıcı tarafından atanan izinlere sahip bir taşıyıcı belirteci alır ve ardından aşağı akış web API'sini çağırmak için bu belirteci başka bir erişim belirteci ile değiştirir.

Aşağıdaki kod, doğrulanmış taşıyıcı belirtecini almak için web API'sindeki Spring Security çerçevelerini SecurityContextHolder kullanır. Ardından ile acquireTokençağrısını kullanarak aşağı akış API'sine yönelik bir belirteç almak için MSAL Java kitaplığını OnBehalfOfParameters kullanır. MSAL, sonraki API çağrılarının önbelleğe alınmış belirteci almak için kullanabilmesi acquireTokenSilently için belirteci önbelleğe alır.

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

Piton

Adına (OBO) akışı kullanma

Adına (OBO) akışı, aşağı akış web API'sini çağırmak üzere bir belirteç almak için kullanılır. Bu akışta, web API'niz istemci uygulamasından kullanıcı tarafından atanan izinlere sahip bir taşıyıcı belirteci alır ve ardından aşağı akış web API'sini çağırmak için bu belirteci başka bir erişim belirteci ile değiştirir.

Python web API'sinin istemciden alınan taşıyıcı belirtecini doğrulamak için ara yazılım kullanması gerekir. Web API'si daha sonra yöntemini çağırarak MSAL Python kitaplığını kullanarak aşağı akış API'sinin erişim belirtecini acquire_token_on_behalf_of alabilir. Bu API'yi kullanma örneği için GitHub'da microsoft-authentication-library-for-python için test koduna bakın. Orta katman uygulama gereksinimini atlayan bir yaklaşım için aynı depoda 53 . sorunun tartışmalarına da bakın.

Ayrıca ms-identity-python-on-half-of örneğinde OBO akışı uygulamasının bir örneğini de görebilirsiniz.

Node.js ve Azure İşlevleri'de OBO akış uygulaması örneğini de görebilirsiniz.

Protokol

OBO protokolü hakkında daha fazla bilgi için Microsoft kimlik platformu ve OAuth 2.0 On-Behalf-Of akışına bakın.

Sonraki adım

Uygulama için bir belirteç alın.