Menjalankan pengujian integrasi otomatis

Sebagai pengembang, Anda ingin menjalankan tes integrasi otomatis pada aplikasi yang Anda kembangkan. Memanggil API Anda yang dilindungi oleh platform identitas Microsoft (atau API lain yang dilindungi seperti Microsoft Graph) dalam pengujian integrasi otomatis adalah sebuah tantangan. ID Microsoft Entra sering memerlukan perintah masuk pengguna interaktif, yang sulit diotomatiskan. Artikel ini menjelaskan bagaimana Anda dapat menggunakan alur non-interaktif, yang disebut Pemberian Info Masuk Kata Sandi Pemilik Sumber Daya (ROPC), untuk memasukkan pengguna secara otomatis untuk pengujian.

Untuk mempersiapkan pengujian integrasi otomatis Anda, buat beberapa pengguna uji, buat dan konfigurasikan pendaftaran aplikasi, dan kemungkinan buat beberapa perubahan konfigurasi pada penyewa Anda. Beberapa langkah ini memerlukan hak istimewa admin. Selain itu, Microsoft menyarankan agar Anda tidak menggunakan alur ROPC di lingkungan produksi. Buat penyewa uji terpisah di mana Anda adalah administratornya sehingga Anda dapat menjalankan pengujian integrasi otomatis dengan aman dan efektif.

Peringatan

Microsoft menyarankan Anda untuk tidak menggunakan alur ROPC di lingkungan produksi. Dalam sebagian besar skenario produksi, alternatif yang lebih aman tersedia dan direkomendasikan. Alur ROPC membutuhkan tingkat kepercayaan yang sangat tinggi pada aplikasi, dan membawa risiko yang tidak ada dalam alur autentikasi lainnya. Anda hanya boleh menggunakan alur ini untuk tujuan pengujian di penyewa uji terpisah, dan hanya dengan pengguna uji.

Penting

• platform identitas Microsoft hanya mendukung ROPC dalam penyewa Microsoft Entra, bukan akun pribadi. Ini berarti Anda harus menggunakan titik akhir khusus penyewa (https://login.microsoftonline.com/{TenantId_or_Name}) atau titik akhir organizations.
• Akun pribadi yang diundang ke penyewa Microsoft Entra tidak dapat menggunakan ROPC.
• Akun yang tidak memiliki kata sandi tidak dapat masuk dengan ROPC, yang berarti fitur seperti masuk dengan SMS, FIDO, dan aplikasi Authenticator tidak akan berfungsi dengan aliran itu.
• Jika pengguna perlu menggunakan autentikasi multifaktor (MFA) untuk masuk ke aplikasi, mereka akan diblokir.
• ROPC tidak didukung dalam skenario federasi identitas hibrid (misalnya, MICROSOFT Entra ID dan Active Directory Federation Services (AD FS) yang digunakan untuk mengautentikasi akun lokal). Jika pengguna halaman penuh dialihkan ke penyedia identitas lokal, Microsoft Entra ID tidak dapat menguji nama pengguna dan kata sandi terhadap penyedia identitas tersebut. Namun, autentikasi pass-through didukung dengan ROPC.
• Pengecualian untuk skenario gabungan identitas hibrida adalah sebagai berikut: Kebijakan Home Realm Discovery dengan AllowCloudPasswordValidation yang diatur ke TRUE akan memungkinkan alur ROPC berfungsi untuk pengguna gabungan saat kata sandi lokal disinkronkan ke cloud. Untuk informasi lebih lanjut, lihat Mengaktifkan autentikasi ROPC langsung dari pengguna gabungan untuk aplikasi warisan.

Membuat penyewa uji terpisah

Menggunakan alur autentikasi ROPC berisiko di lingkungan produksi, jadi buat penyewa terpisah untuk menguji aplikasi Anda. Anda dapat menggunakan penyewa uji yang ada, tetapi Anda harus menjadi admin penyewa karena beberapa langkah berikut memerlukan hak istimewa admin.

Membuat dan mengonfigurasi brankas kunci

Kami menyarankan Anda menyimpan nama pengguna dan sandi pengujian dengan aman sebagai rahasia di Azure Key Vault. Ketika Anda menjalankan tes nanti, tes berjalan dalam konteks prinsip keamanan. Perwakilan keamanan adalah pengguna Microsoft Entra jika Anda menjalankan pengujian secara lokal (misalnya, di Visual Studio atau Visual Studio Code), atau perwakilan layanan atau identitas terkelola jika Anda menjalankan pengujian di Azure Pipelines atau sumber daya Azure lainnya. Prinsip keamanan harus memiliki izin rahasia Baca dan Daftar sehingga penguji bisa mendapatkan nama pengguna dan kata sandi uji dari brankas kunci Anda. Untuk informasi selengkapnya, baca Autentikasi di Azure Key Vault.

1. Buat brankas kunci baru jika Anda belum memilikinya.
2. Catat nilai properti Vault URI (mirip dengan https://<your-unique-keyvault-name>.vault.azure.net/) yang digunakan dalam pengujian contoh nanti di artikel ini.
3. Tetapkan kebijakan akses untuk prinsip keamanan yang menjalankan pengujian. Berikan izin rahasia kepada pengguna, perwakilan layanan, atau identitas terkelola Dapatkan dan Daftar di brankas kunci.

Membuat uji pengguna

Tip

Langkah-langkah dalam artikel ini mungkin sedikit berbeda berdasarkan portal tempat Anda memulai.

Buat beberapa pengguna uji di penyewa Anda untuk pengujian. Karena pengguna pengujian bukanlah manusia yang sebenarnya, sebaiknya Anda menetapkan sandi yang rumit dan menyimpan sandi ini dengan aman sebagai rahasia di Azure Key Vault.

1. Masuk ke pusat admin Microsoft Entra sebagai setidaknya Administrator Aplikasi Cloud.
2. Telusuri ke Pengguna>Identitas>Semua pengguna.
3. Pilih Pengguna baru dan buat satu atau beberapa akun pengguna uji di direktori Anda.
4. Contoh pengujian nanti dalam artikel ini menggunakan pengguna uji tunggal. Tambahkan nama pengguna dan sandi uji sebagai rahasia di brankas kunci yang Anda buat sebelumnya. Tambahkan nama pengguna sebagai rahasia bernama "TestUserName" dan kata sandi sebagai rahasia bernama "TestPassword".

Membuat dan mengonfigurasi pendaftaran aplikasi

Daftarkan aplikasi yang bertindak sebagai aplikasi klien Anda saat memanggil API selama pengujian. Ini seharusnya bukan aplikasi yang sama yang mungkin sudah Anda miliki dalam produksi. Anda harus memiliki aplikasi terpisah untuk digunakan hanya untuk tujuan pengujian.

Daftarkan aplikasi

Membuat pendaftaran aplikasi. Anda dapat mengikuti langkah-langkah di panduan memulai pendaftaran aplikasi. Anda tidak perlu menambahkan URI pengalihan atau menambahkan info masuk, sehingga Anda dapat melewati bagian tersebut.

Catat ID Aplikasi (klien), yang digunakan dalam contoh pengujian nanti di artikel ini.

Aktifkan aplikasi Anda untuk alur klien publik

ROPC adalah alur klien publik, jadi Anda perlu mengaktifkan aplikasi untuk alur klien publik. Dari pendaftaran aplikasi Anda di pusat admin Microsoft Entra, buka Autentikasi>Pengaturan>tingkat lanjut Izinkan alur klien publik. Atur tombol beralih ke Ya.

Menyetujui izin yang ingin Anda gunakan saat pengujian

Karena ROPC bukan alur interaktif, Anda tidak akan diminta dengan layar persetujuan untuk menyetujui ini saat runtime. Pra-persetujuan izin untuk menghindari kesalahan saat memperoleh token.

Tambahkan izin ke aplikasi Anda. Jangan tambahkan izin sensitif atau hak istimewa tinggi ke aplikasi, sebaiknya lingkup skenario pengujian Anda ke skenario integrasi dasar seputar integrasi dengan ID Microsoft Entra.

Dari pendaftaran aplikasi Anda di pusat admin Microsoft Entra, buka Izin>API Tambahkan izin. Tambahkan izin yang Anda butuhkan untuk memanggil API yang akan Anda gunakan. Contoh pengujian lebih lanjut dalam artikel ini menggunakan izin https://graph.microsoft.com/User.Read dan https://graph.microsoft.com/User.ReadBasic.All.

Setelah izin ditambahkan, Anda harus menyetujuinya. Cara Anda menyetujui izin bergantung pada apakah aplikasi pengujian Anda berada di penyewa yang sama dengan pendaftaran aplikasi dan apakah Anda seorang admin di penyewa.

Pendaftaran aplikasi dan aplikasi berada di penyewa yang sama dan Anda adalah seorang admin

Jika Anda berencana menguji aplikasi di penyewa yang sama dengan tempat Anda mendaftarkannya dan Anda adalah administrator di penyewa tersebut, Anda dapat menyetujui izin dari pusat admin Microsoft Entra. Dalam pendaftaran aplikasi Anda di portal Azure, buka Izin API dan pilih tombol Berikan izin admin untuk <nama_penyewa Anda> di samping tombol Tambahkan izin, lalu Ya untuk mengonfirmasi.

Pendaftaran aplikasi dan aplikasi berada di penyewa yang berbeda, atau Anda bukan admin

Jika Anda tidak berencana menguji aplikasi di penyewa yang sama dengan tempat Anda mendaftarkannya, atau Anda bukan administrator di penyewa, Anda tidak dapat menyetujui izin dari pusat admin Microsoft Entra. Namun, Anda masih dapat menyetujui beberapa izin dengan memicu perintah masuk di browser web.

Di pendaftaran aplikasi Anda di pusat admin Microsoft Entra, buka Konfigurasi>Platform Autentikasi>Tambahkan Web platform.> Tambahkan URI pengalihan "https://localhost" dan pilih Konfigurasi.

Tidak ada cara bagi pengguna non-admin untuk melakukan pra-persetujuan melalui portal Azure, jadi kirim permintaan berikut di browser. Saat Anda diminta dengan layar masuk, masuk dengan akun uji yang Anda buat di langkah sebelumnya. Menyetujui izin yang diminta. Anda mungkin perlu mengulangi langkah ini untuk setiap API yang ingin Anda panggil dan menguji pengguna yang ingin Anda gunakan.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id={your_client_ID}
&response_type=code
&redirect_uri=https://localhost
&response_mode=query
&scope={resource_you_want_to_call}/.default
&state=12345

Ganti {penyewa} dengan ID penyewa Anda, {your_client_ID} dengan ID klien aplikasi Anda, dan {resource_you_want_to_call} dengan pengidentifikasi URI (misalnya, "https://graph.microsoft.com") atau ID aplikasi dari API yang Anda coba akses.

Kecualikan aplikasi dan pengguna pengujian dari kebijakan MFA Anda

Penyewa Anda kemungkinan memiliki kebijakan Akses Bersyarat yang memerlukan autentikasi multifaktor (MFA) untuk semua pengguna, seperti yang direkomendasikan oleh Microsoft. MFA tidak akan bekerja dengan ROPC, jadi Anda harus mengecualikan aplikasi pengujian dan pengguna pengujian dari persyaratan ini.

Untuk mengecualikan akun pengguna:

1. Masuk ke pusat admin Microsoft Entra sebagai setidaknya Administrator Aplikasi Cloud.
2. Telusuri ke Identity>Security Center di panel navigasi kiri lalu pilih Akses Bersyar.
3. Di Kebijakan, pilih kebijakan Akses Bersyarat yang memerlukan MFA.
4. Pilih Pengguna atau identitas beban kerja.
5. Pilih tab Kecualikan, lalu centang kotak Pengguna dan grup.
6. Pilih akun pengguna yang akan dikecualikan di Pilih pengguna yang dikecualikan.
7. Pilih tombol Pilih lalu Simpan.

Untuk mengecualikan aplikasi uji:

1. Di Kebijakan, pilih kebijakan Akses Bersyarat yang memerlukan MFA.
2. Pilih Aplikasi atau tindakan cloud.
3. Pilih tab Kecualikan lalu Pilih aplikasi cloud yang dikecualikan.
4. Pilih aplikasi yang ingin Anda kecualikan di Pilih aplikasi cloud yang dikecualikan.
5. Pilih tombol Pilih lalu Simpan.

Tulis pengujian aplikasi Anda

Sekarang setelah Anda siap, Anda dapat menulis pengujian otomatis Anda. Berikut ini adalah pengujian untuk:

1. Kode contoh .NET menggunakan Microsoft Authentication Library (MSAL) dan xUnit, kerangka kerja pengujian umum.
2. Kode contoh JavaScript menggunakan Microsoft Authentication Library (MSAL) dan Playwright, kerangka kerja pengujian umum.

.NET

Menyiapkan file appsettings.json Anda

Tambahkan ID klien dari aplikasi pengujian yang Anda buat sebelumnya, cakupan yang diperlukan, dan URI brankas kunci ke file appsettings.json proyek pengujian Anda.

{
  "Authentication": {
    "AzureCloudInstance": "AzurePublic", //Will be different for different Azure clouds, like US Gov
    "AadAuthorityAudience": "AzureAdMultipleOrgs",
    "ClientId": <your_client_ID>
  },

  "WebAPI": {
    "Scopes": [
      //For this Microsoft Graph example.  Your value(s) will be different depending on the API you're calling
      "https://graph.microsoft.com/User.Read",
      //For this Microsoft Graph example.  Your value(s) will be different depending on the API you're calling
      "https://graph.microsoft.com/User.ReadBasic.All"
    ]
  },

  "KeyVault": {
    "KeyVaultUri": "https://<your-unique-keyvault-name>.vault.azure.net//"
  }
}

Siapkan klien Anda untuk digunakan di semua kelas pengujian Anda

Gunakan SecretClient() untuk mendapatkan rahasia nama pengguna dan kata sandi pengujian dari Azure Key Vault. Kode menggunakan back-off eksponensial untuk percobaan ulang jika Key Vault sedang dibatasi.

DefaultAzureCredential() mengautentikasi dengan Azure Key Vault dengan mendapatkan token akses dari perwakilan layanan yang dikonfigurasi oleh variabel lingkungan atau identitas terkelola (jika kode berjalan pada sumber daya Azure dengan identitas terkelola). Jika kode berjalan secara lokal, DefaultAzureCredential menggunakan info masuk pengguna lokal. Baca selengkapnya di konten pustaka klien Identitas Azure.

Gunakan Microsoft Authentication Library (MSAL) untuk mengautentikasi menggunakan alur ROPC dan mendapatkan token akses. Token akses diteruskan sebagai token pembawa dalam permintaan HTTP.

using Xunit;
using System.Threading.Tasks;
using Microsoft.Identity.Client;
using System.Security;
using System.Net;
using System.Net.Http;
using System.Net.Http.Headers;
using Microsoft.Extensions.Configuration;
using Azure.Identity;
using Azure.Security.KeyVault.Secrets;
using Azure.Core;
using System;

public class ClientFixture : IAsyncLifetime
{
    public HttpClient httpClient;

    public async Task InitializeAsync()
    {
        var builder = new ConfigurationBuilder().AddJsonFile("<path-to-json-file>");

        IConfigurationRoot Configuration = builder.Build();

        var PublicClientApplicationOptions = new PublicClientApplicationOptions();
        Configuration.Bind("Authentication", PublicClientApplicationOptions);
        var app = PublicClientApplicationBuilder.CreateWithApplicationOptions(PublicClientApplicationOptions)
            .Build();

        SecretClientOptions options = new SecretClientOptions()
        {
            Retry =
                {
                    Delay= TimeSpan.FromSeconds(2),
                    MaxDelay = TimeSpan.FromSeconds(16),
                    MaxRetries = 5,
                    Mode = RetryMode.Exponential
                 }
        };

        string keyVaultUri = Configuration.GetValue<string>("KeyVault:KeyVaultUri");
        var client = new SecretClient(new Uri(keyVaultUri), new DefaultAzureCredential(), options);

        KeyVaultSecret userNameSecret = client.GetSecret("TestUserName");
        KeyVaultSecret passwordSecret = client.GetSecret("TestPassword");

        string password = passwordSecret.Value;
        string username = userNameSecret.Value;
        string[] scopes = Configuration.GetSection("WebAPI:Scopes").Get<string[]>();
        SecureString securePassword = new NetworkCredential("", password).SecurePassword;

        AuthenticationResult result = null;
        httpClient = new HttpClient();

        try
        {
            result = await app.AcquireTokenByUsernamePassword(scopes, username, securePassword)
                .ExecuteAsync();
        }
        catch (MsalException) { }

        string accessToken = result.AccessToken;
        httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("bearer", accessToken);
    }

    public Task DisposeAsync() => Task.CompletedTask;
}

Gunakan di kelas pengujian Anda

Contoh berikut adalah tes yang memanggil Microsoft Graph. Ganti tes ini dengan apa pun yang ingin Anda uji pada aplikasi atau API Anda sendiri.

public class ApiTests : IClassFixture<ClientFixture>
{
    ClientFixture clientFixture;

    public ApiTests(ClientFixture clientFixture)
    {
        this.clientFixture = clientFixture;
    }

    [Fact]
    public async Task GetRequestTest()
    {
        var testClient = clientFixture.httpClient;
        HttpResponseMessage response = await testClient.GetAsync("https://graph.microsoft.com/v1.0/me");
        var responseCode = response.StatusCode.ToString();
        Assert.Equal("OK", responseCode);
    }
}

JavaScript

Menyiapkan file authConfig.json Anda

Tambahkan ID klien dan ID penyewa aplikasi pengujian yang sebelumnya Anda buat, URI brankas kunci, dan nama rahasia ke file authConfig.js dari proyek pengujian Anda.

export const msalConfig = {
    auth: {
        clientId: 'Enter_the_Application_Id_Here',
        authority: 'https://login.microsoftonline.com/Enter_the_Tenant_Id_Here',
    },
};

export const keyVaultConfig = {
    keyVaultUri: 'https://<your-unique-keyvault-name>.vault.azure.net',
    secretName: 'Enter_the_Secret_Name',
};

Menginisialisasi MSAL.js dan mengambil kredensial pengguna dari Key Vault

Inisialisasi konteks autentikasi MSAL.js dengan membuat instans PublicClientApplication dengan objek Konfigurasi. Properti konfigurasi minimum yang clientID diperlukan adalah aplikasi.

Gunakan SecretClient() untuk mendapatkan rahasia nama pengguna dan kata sandi pengujian dari Azure Key Vault.

DefaultAzureCredential() mengautentikasi dengan Azure Key Vault dengan mendapatkan token akses dari perwakilan layanan yang dikonfigurasi oleh variabel lingkungan atau identitas terkelola (jika kode berjalan pada sumber daya Azure dengan identitas terkelola). Jika kode berjalan secara lokal, DefaultAzureCredential menggunakan info masuk pengguna lokal. Baca selengkapnya di konten pustaka klien Identitas Azure.

Gunakan Microsoft Authentication Library (MSAL) untuk mengautentikasi menggunakan alur ROPC dan mendapatkan token akses. Token akses diteruskan sebagai token pembawa dalam permintaan HTTP.

import { test, expect } from '@playwright/test';
import { DefaultAzureCredential } from '@azure/identity';
import { SecretClient } from '@azure/keyvault-secrets';
import { PublicClientApplication, CacheKVStore } from '@azure/msal-node';
import { msalConfig, keyVaultConfig } from '../authConfig';

let tokenCache;
const KVUri = keyVaultConfig.keyVaultUri;
const secretName = keyVaultConfig.secretName;

async function getCredentials() {
    try {
        const credential = new DefaultAzureCredential();
        const secretClient = new SecretClient(KVUri, credential);
        const secret = await secretClient.getSecret(keyVaultConfig.secretName);
        const password = secret.value;
        return [secretName, password];
    } catch (error) {
        console.log(error);
    }
}

test.beforeAll(async () => {
    const pca = new PublicClientApplication(msalConfig);
    const [username, password] = await getCredentials();
    const usernamePasswordRequest = {
        scopes: ['user.read', 'User.ReadBasic.All'],
        username: username,
        password: password,
    };
    await pca.acquireTokenByUsernamePassword(usernamePasswordRequest);
    tokenCache = pca.getTokenCache().getKVStore();
});

Menjalankan rangkaian pengujian

Dalam file yang sama, tambahkan pengujian seperti yang ditunjukkan di bawah ini:

/**
 * Stores the token in the session storage and reloads the page
 */
async function setSessionStorage(page, tokens) {
    const cacheKeys = Object.keys(tokens);
    for (let key of cacheKeys) {
        const value = JSON.stringify(tokenCache[key]);
        await page.context().addInitScript(
            (arr) => {
                window.sessionStorage.setItem(arr[0], arr[1]);
            },
            [key, value]
        );
    }
    await page.reload();
}

test.describe('Testing Authentication with MSAL.js ', () => {
    test('Test user has signed in successfully', async ({ page }) => {
        await page.goto('http://localhost:<port>/');
        let signInButton = page.getByRole('button', { name: /Sign In/i });
        let signOutButton = page.getByRole('button', { name: /Sign Out/i });
        let welcomeDev = page.getByTestId('WelcomeMessage');
        expect(await signInButton.count()).toBeGreaterThan(0);
        expect(await signOutButton.count()).toBeLessThanOrEqual(0);
        expect(await welcomeDev.innerHTML()).toEqual('Please sign-in to see your profile and read your mails');
        await setSessionStorage(page, tokenCache);
        expect(await signInButton.count()).toBeLessThanOrEqual(0);
        expect(await signOutButton.count()).toBeGreaterThan(0);
        expect(await welcomeDev.innerHTML()).toContain(`Welcome`);
    });
});

Untuk informasi selengkapnya, silakan periksa contoh kode berikut Contoh Pengujian MSAL.js.