API web yang memanggil API web: Konfigurasi kode

Artikel ini menjelaskan cara mengonfigurasi kode untuk aplikasi API Web menggunakan alur kode otorisasi OAuth 2.0.

Microsoft menyarankan agar Anda menggunakan paket NuGet Microsoft.Identity.Web saat mengembangkan API terlindungi ASP.NET Core yang memanggil API web hilir. Lihat API web terlindungi: Konfigurasi kode | Microsoft.Identity.Web untuk presentasi cepat pustaka tersebut dalam konteks API web.

Prasyarat

• Mendaftarkan API web yang memanggil API web

Mengonfigurasikan aplikasi

Pilih bahasa untuk API web Anda.

Inti ASP.NET

Rahasia klien atau sertifikat klien

Mengingat bahwa aplikasi web Anda sekarang memanggil API web hilir, sediakan sertifikat rahasia klien atau klien dalam file appsettings.json. Anda juga dapat menambahkan bagian yang menentukan:

• URL API web hilir
• Cakupan yang diperlukan untuk memanggil API

Dalam contoh berikut, bagian GraphBeta menentukan pengaturan ini.

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

Catatan

Anda dapat mengusulkan kumpulan kredensial klien, termasuk solusi tanpa kredensial seperti federasi identitas beban kerja untuk Azure Kubernetes. Versi Microsoft.Identity.Web sebelumnya mengekspresikan rahasia klien dalam satu properti "ClientSecret" alih-alih "ClientCredentials". Ini masih didukung untuk kompatibilitas mundur tetapi Anda tidak dapat menggunakan properti "ClientSecret", dan koleksi "ClientCredentials".

Alih-alih rahasia klien, Anda dapat menyediakan sertifikat klien. Cuplikan kode berikut ini memperlihatkan menggunakan sertifikat yang disimpan di 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"]
  }
}

Peringatan

Jika Anda lupa mengubah Scopes ke array, ketika Anda mencoba menggunakan IDownstreamApi cakupan akan muncul null, dan IDownstreamApi akan mencoba panggilan anonim (tidak diautentikasi) ke API hilir, yang akan menghasilkan 401/unauthenticated.

Microsoft.Identity.Web menyediakan beberapa cara untuk menjelaskan sertifikat, baik berdasarkan konfigurasi maupun kode. Untuk detailnya, lihat Microsoft.Identity.Web - Menggunakan sertifikat di GitHub.

Program.cs

using Microsoft.Identity.Web;

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

API web perlu memperoleh token untuk API hilir. Tentukan dengan menambahkan .EnableTokenAcquisitionToCallDownstreamApi() baris setelah .AddMicrosoftIdentityWebApi(Configuration). Baris ini mengekspos ITokenAcquisition layanan yang dapat digunakan dalam tindakan pengontrol/halaman.

Namun, metode alternatif adalah menerapkan cache token. Misalnya, menambahkan .AddInMemoryTokenCaches(), ke Program.cs memungkinkan token di-cache dalam memori.

using Microsoft.Identity.Web;

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

Microsoft.Identity.Web menyediakan dua mekanisme untuk memanggil API web hilir dari API lain. Opsi yang Anda pilih tergantung pada apakah Anda ingin memanggil Microsoft Graph atau API lain.

Opsi 1: Memanggil Microsoft Graph

Untuk memanggil Microsoft Graph, Microsoft.Identity.Web memungkinkan Anda untuk langsung menggunakan GraphServiceClient (diekspos oleh Microsoft Graph SDK) dalam tindakan API.

Catatan

Ada masalah yang sedang berlangsung untuk Microsoft Graph SDK v5+. Untuk informasi selengkapnya, lihat masalah GitHub.

Untuk mengekspose Microsoft Graph:

1. Tambahkan paket NuGet Microsoft.Identity.Web.GraphServiceClient ke proyek.
2. Tambahkan .AddMicrosoftGraph() setelah .EnableTokenAcquisitionToCallDownstreamApi() di Program.cs. .AddMicrosoftGraph() memiliki beberapa pengambilalihan. Menggunakan ambil alih yang mengambil bagian konfigurasi sebagai parameter, kodenya menjadi:

using Microsoft.Identity.Web;

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

Opsi 2: Memanggil API web hilir selain Microsoft Graph

1. Tambahkan paket Microsoft.Identity.Web.DownstreamApi NuGet ke proyek.
2. Tambahkan .AddDownstreamApi() setelah .EnableTokenAcquisitionToCallDownstreamApi() di Program.cs. Kode menjadi:

using Microsoft.Identity.Web;

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

mana;

• MyApi menunjukkan nama API web hilir yang ingin dipanggil API web Anda
• MyApiScope adalah cakupan yang diperlukan agar API web Anda meminta untuk berinteraksi dengan API web hilir

Nilai-nilai ini akan diwakili dalam JSON Anda yang akan mirip dengan cuplikan berikut.

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

Jika aplikasi web perlu memanggil sumber daya API lain, ulangi .AddDownstreamApi() metode dengan cakupan yang relevan seperti yang ditunjukkan dalam cuplikan berikut:

using Microsoft.Identity.Web;

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

Perhatikan bahwa .EnableTokenAcquisitionToCallDownstreamApi dipanggil tanpa parameter apa pun, yang berarti bahwa token akses diperoleh tepat pada waktunya karena pengontrol meminta token dengan menentukan cakupan.

Cakupan juga dapat diteruskan saat memanggil .EnableTokenAcquisitionToCallDownstreamApi, yang akan membuat aplikasi web memperoleh token selama login pengguna awal itu sendiri. Token kemudian akan ditarik dari cache ketika pengontrol memintanya.

Mirip dengan aplikasi web, berbagai implementasi cache token dapat dipilih. Untuk detailnya, lihat Web identitas Microsoft - Serialisasi cache token di GitHub.

Gambar berikut menunjukkan kemungkinan Microsoft.Identity.Web dan dampaknya pada Program.cs:

Catatan

Untuk sepenuhnya memahami contoh kode di sini, kuasai dasar-dasar ASP.NET Core, dan khususnya dengan injeksi dependensi dan opsi.

ASP.NET

Rahasia klien atau sertifikat klien

Mengingat bahwa aplikasi web Anda sekarang memanggil API web hilir, sediakan sertifikat rahasia klien atau klien dalam file appsettings.json. Anda juga dapat menambahkan bagian yang menentukan:

• URL API web hilir
• Cakupan yang diperlukan untuk memanggil API

Dalam contoh berikut, bagian GraphBeta menentukan pengaturan ini.

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

Catatan

Anda dapat mengusulkan kumpulan kredensial klien, termasuk solusi tanpa kredensial seperti federasi identitas beban kerja untuk Azure Kubernetes. Versi Microsoft.Identity.Web sebelumnya mengekspresikan rahasia klien dalam satu properti "ClientSecret" alih-alih "ClientCredentials". Ini masih didukung untuk kompatibilitas mundur tetapi Anda tidak dapat menggunakan properti "ClientSecret", dan koleksi "ClientCredentials".

Alih-alih rahasia klien, Anda dapat menyediakan sertifikat klien. Cuplikan kode berikut ini memperlihatkan menggunakan sertifikat yang disimpan di 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"]
  }
}

Peringatan

Jika Anda lupa mengubah Scopes ke array, ketika Anda mencoba menggunakan IDownstreamApi cakupan akan muncul null, dan IDownstreamApi akan mencoba panggilan anonim (tidak diautentikasi) ke API hilir, yang akan menghasilkan 401/unauthenticated.

Microsoft.Identity.Web menyediakan beberapa cara untuk menjelaskan sertifikat, baik berdasarkan konfigurasi maupun kode. Untuk detailnya, lihat Microsoft.Identity.Web - Menggunakan sertifikat di GitHub.

Mengubah Startup.Auth.cs

Aplikasi web Anda perlu memperoleh token untuk API hilir, Microsoft.Identity.Web menyediakan dua mekanisme untuk memanggil API hilir dari API web. Opsi yang Anda pilih tergantung pada apakah Anda ingin memanggil Microsoft Graph atau API lain.

Opsi 1: Memanggil Microsoft Graph

Jika Anda ingin memanggil Microsoft Graph, Microsoft.Identity.Web memungkinkan Anda untuk langsung menggunakan GraphServiceClient (diekspos oleh Microsoft Graph SDK) dalam API tindakan Anda. Untuk mengekspose Microsoft Graph:

1. Tambahkan paket NuGet Microsoft.Identity.Web.GraphServiceClient ke proyek Anda.

2. Tambahkan .AddMicrosoftGraph() ke kumpulan layanan dalam file Startup.Auth.cs . .AddMicrosoftGraph() memiliki beberapa pengambilalihan. Menggunakan ambil alih yang mengambil bagian konfigurasi sebagai parameter, kodenya menjadi:

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

Opsi 2: Memanggil API web hilir selain Microsoft Graph

Jika Anda ingin memanggil API selain Microsoft Graph, Microsoft.Identity.Web memungkinkan Anda menggunakan IDownstreamApi antarmuka dalam tindakan API Anda. Untuk menggunakan antarmuka ini:

1. Tambahkan paket Microsoft.Identity.Web.DownstreamApi NuGet ke proyek Anda.
2. Tambahkan .AddDownstreamApi() setelah .EnableTokenAcquisitionToCallDownstreamApi() dalam Startup.cs. .AddDownstreamApi() memiliki dua argumen:
   • Nama layanan (API): Anda menggunakan nama ini dalam tindakan pengontrol Anda untuk mereferensikan konfigurasi yang sesuai
   • bagian konfigurasi yang mewakili parameter yang digunakan untuk memanggil API web hilir.

Berikut kodenya:

  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

Menggunakan alur atas nama (OBO)

Alur atas nama (OBO) digunakan untuk mendapatkan token untuk memanggil API web hilir. Dalam alur ini, API web Anda menerima token pembawa dengan izin yang didelegasikan pengguna dari aplikasi klien, lalu menukar token ini dengan token akses lain untuk memanggil API web hilir.

Kode di bawah ini menggunakan kerangka kerja Spring Security SecurityContextHolder di API web untuk mendapatkan token pembawa tervalidasi. Lalu menggunakan pustaka MSAL Java untuk memperoleh token untuk API hilir menggunakan panggilan acquireToken dengan OnBehalfOfParameters. MSAL menembolokan token sehingga panggilan API berikutnya dapat menggunakan acquireTokenSilently untuk mendapatkan token 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();
    }
}

Python

Menggunakan alur atas nama (OBO)

Alur atas nama (OBO) digunakan untuk mendapatkan token untuk memanggil API web hilir. Dalam alur ini, API web Anda menerima token pembawa dengan izin yang didelegasikan pengguna dari aplikasi klien, lalu menukar token ini dengan token akses lain untuk memanggil API web hilir.

API web Python perlu menggunakan beberapa middleware untuk memvalidasi token pembawa yang diterima dari klien. API web lalu dapat memperoleh token akses untuk API hilir menggunakan pustaka MSAL Python dengan memanggil metode acquire_token_on_behalf_of. Untuk contoh penggunaan API ini, lihat kode uji untuk microsoft-authentication-library-for-python di GitHub. Lihat juga pembahasan masalah 53 dalam repositori yang sama untuk pendekatan yang melewati kebutuhan untuk aplikasi tingkat menengah.

Anda juga dapat melihat contoh penerapan alur OBO dalam sampel ms-identity-python-on-behalf-of.

Anda juga dapat melihat contoh penerapan alur OBO di Node.js dan Azure Functions.

Protokol

Untuk informasi selengkapnya tentang protokol OBO, lihat platform identitas Microsoft dan alur On-Behalf-Of OAuth 2.0.

Langkah selanjutnya

Memperoleh token untuk aplikasi.