API web yang memanggil API web: Konfigurasi kode

Setelah mendaftarkan API web, Anda dapat mengonfigurasi kode untuk aplikasi tersebut.

Kode ini Anda gunakan untuk mengonfigurasi API web sehingga ini memanggil API web hilir yang dibangun di atas kode yang digunakan untuk melindungi API web. Untuk informasi selengkapnya, lihat API web terlindungi: Konfigurasi aplikasi.

Inti ASP.NET

Microsoft.Identity.Web

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.

Rahasia klien atau sertifikat klien

Mengingat bahwa API 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": "[Client_id-of-web-api-eg-2ec40e65-ba09-4853-bcde-bcb60029e596]",
    "TenantId": "common",
    
    // To call an API
    "ClientSecret": "[Copy the client secret added to the app from the Azure portal]",
    "ClientCertificates": []
  },
  "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": "user.read"
  }
}

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": "[Client_id-of-web-api-eg-2ec40e65-ba09-4853-bcde-bcb60029e596]",
    "TenantId": "common",
    
    // To call an API
    "ClientCertificates": [
      {
        "SourceType": "KeyVault",
        "KeyVaultUrl": "https://msidentitywebsamples.vault.azure.net",
        "KeyVaultCertificateName": "MicrosoftIdentitySamplesCert"
      }
    ]
  },
  "GraphBeta": {
    "BaseUrl": "https://graph.microsoft.com/beta",
    "Scopes": "user.read"
  }
}

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

Startup.cs

API web Anda harus mendapatkan token untuk API hilir. Anda menentukannya dengan menambahkan baris .EnableTokenAcquisitionToCallDownstreamApi() setelah .AddMicrosoftIdentityWebApi(Configuration). Baris ini mengekspose layanan ITokenAcquisition yang dapat Anda gunakan di pengontrol/tindakan halaman Anda. Namun, seperti yang akan Anda lihat dalam dua poin berikutnya, Anda dapat melakukan dengan lebih sederhana. Anda juga harus memilih penerapan cache token, misalnya .AddInMemoryTokenCaches(), di Startup.cs:

using Microsoft.Identity.Web;

public class Startup
{
    // ...
    public void ConfigureServices(IServiceCollection services)
    {
        // ...
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(Configuration, Configuration.GetSection("AzureAd"))
                .EnableTokenAcquisitionToCallDownstreamApi()
                .AddInMemoryTokenCaches();
        // ...
    }
    // ...
}

Jika Anda tidak ingin memperoleh token sendiri, Microsoft.Identity.Web menyediakan dua mekanisme untuk memanggil API web hilir dari API lainnya. 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.MicrosoftGraph ke proyek Anda.
2. Tambahkan .AddMicrosoftGraph() setelah .EnableTokenAcquisitionToCallDownstreamApi() dalam Startup.cs. .AddMicrosoftGraph() memiliki beberapa pengambilalihan. Menggunakan ambil alih yang mengambil bagian konfigurasi sebagai parameter, kodenya menjadi:

using Microsoft.Identity.Web;

public class Startup
{
    // ...
    public void ConfigureServices(IServiceCollection services)
    {
        // ...
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(Configuration, Configuration.GetSection("AzureAd"))
                .EnableTokenAcquisitionToCallDownstreamApi()
                .AddMicrosoftGraph(Configuration.GetSection("GraphBeta"))
                .AddInMemoryTokenCaches();
        // ...
    }
    // ...
}

Opsi 2: Memanggil API web hilir selain Microsoft Graph

Untuk memanggil API hilir web selain Microsoft Graph, Microsoft.Identity.Web menyediakan .AddDownstreamWebApi() yang meminta token dan memanggil API web hilir.

using Microsoft.Identity.Web;

public class Startup
{
    // ...
    public void ConfigureServices(IServiceCollection services)
    {
        // ...
        services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApi(Configuration, "AzureAd")
                .EnableTokenAcquisitionToCallDownstreamApi()
                .AddDownstreamWebApi("MyApi", Configuration.GetSection("GraphBeta"))
                .AddInMemoryTokenCaches();
        // ...
    }
    // ...
}

Seperti halnya aplikasi web, Anda dapat memilih beragam penerapan cache token. Untuk detailnya, lihat Web identitas Microsoft - Serialisasi cache token di GitHub.

Gambar berikut menunjukkan berbagai kemungkinan Microsoft.Identity.Web dan dampaknya pada file .cs Startup:

Catatan

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

Java

Alur On-behalf-of (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

Alur On-behalf-of (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 harus 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 berikutnya

Beralih ke artikel berikutnya dalam skenario ini, Memperoleh token untuk aplikasi.