Aktifkan opsi autentikasi API web Node.js menggunakan Azure Active Directory B2C

  • Artikel
  • 5 menit untuk membaca

Artikel ini menjelaskan cara mengaktifkan, menyesuaikan, dan meningkatkan pengalaman autentikasi Azure Active Directory B2C (Azure AD B2C) untuk API web Node.js Anda.

Sebelum Anda mulai, penting untuk membiasakan diri dengan artikel berikut:

Menggunakan domain kustom

Dengan menggunakan domain kustom, Anda dapat sepenuhnya menandai URL autentikasi. Dari perspektif pengguna, pengguna tetap berada di domain Anda selama proses autentikasi, bukan dialihkan ke nama domain b2clogin.com Azure Active Directory B2C.

Untuk menghapus semua referensi “b2c” pada URL, Anda dapat mengganti nama penyewa B2C Anda, contoso.onmicrosoft.com, pada URL permintaan autentikasi dengan pengidentifikasi unik ID penyewa Anda. Misalnya, Anda dapat mengubah https://fabrikamb2c.b2clogin.com/contoso.onmicrosoft.com/ menjadi https://account.contosobank.co.uk/<tenant ID GUID>/.

Untuk menggunakan domain kustom dan ID penyewa Anda di URL autentikasi, ikuti panduan di Mengaktifkan domain kustom. Di bagian folder akar proyek, buka file .env. File ini memuat informasi tentang penyedia identitas Azure AD B2C Anda.

Dalam .env file aplikasi web Anda, lakukan hal berikut:

  • Ganti semua instans tenant-name.b2clogin.com dengan domain kustom Anda. Misalnya, ganti tenant-name.b2clogin.com, ke login.contoso.com.
  • Ganti semua instans tenant-name.onmicrosoft.com dengan ID penyewa Anda. Untuk informasi selengkapnya, lihat Gunakan ID penyewa.

Konfigurasi berikut menunjukkan pengaturan aplikasi sebelum perubahan:

#B2C sign up and sign in user flow/policy authority
SIGN_UP_SIGN_IN_POLICY_AUTHORITY=https://contoso.b2clogin.com/contoso.onmicrosoft.com/B2C_1_susi
#B2C authority domain
AUTHORITY_DOMAIN=https://contoso.b2clogin.com
#client redirect url
APP_REDIRECT_URI=http://localhost:3000/redirect
#Logout endpoint 
LOGOUT_ENDPOINT=https://contoso.b2clogin.com/contoso.onmicrosoft.com/B2C_1_susi/oauth2/v2.0/logout?post_logout_redirect_uri=http://localhost:3000

Konfigurasi berikut menunjukkan pengaturan aplikasi setelah perubahan:

#B2C sign up and sign in user flow/policy authority
SIGN_UP_SIGN_IN_POLICY_AUTHORITY=https://login.contoso.com/12345678-0000-0000-0000-000000000000/B2C_1_susi
#B2C authority domain
AUTHORITY_DOMAIN=https://login.contoso.com
#client redirect url
APP_REDIRECT_URI=http://localhost:3000/redirect
#Logout endpoint 
LOGOUT_ENDPOINT=https://login.contoso.com/12345678-0000-0000-0000-000000000000/B2C_1_susi/oauth2/v2.0/logout?post_logout_redirect_uri=http://localhost:3000

Dalam index.js file API web Anda, lakukan hal berikut:

  • Ganti semua instans tenant-name.b2clogin.com dengan domain kustom Anda. Misalnya, ganti tenant-name.b2clogin.com, ke login.contoso.com.

  • Ganti semua instans tenant-name.onmicrosoft.com dengan ID penyewa Anda. Untuk informasi selengkapnya, lihat Gunakan ID penyewa.

Konfigurasi berikut menunjukkan pengaturan aplikasi sebelum perubahan:

const options = {
    identityMetadata: `https://${config.credentials.tenantName}.b2clogin.com/${config.credentials.tenantName}.onmicrosoft.com/${config.policies.policyName}/${config.metadata.version}/${config.metadata.discovery}`,
    clientID: config.credentials.clientID,
    ......
}

Konfigurasi berikut menunjukkan pengaturan aplikasi setelah perubahan:

const options = {
    identityMetadata: `https://login.contoso.com/12345678-0000-0000-0000-000000000000/${config.policies.policyName}/${config.metadata.version}/${config.metadata.discovery}`,
    clientID: config.credentials.clientID,
    ......
}

Prepopulasi nama rincian masuk

Selama perjalanan pengguna masuk, aplikasi Anda mungkin menargetkan pengguna tertentu. Saat aplikasi menargetkan pengguna, aplikasi dapat menentukan permintaan otorisasi login_hint parameter kueri dengan nama rincian masuk pengguna. Azure Active Directory B2C secara otomatis mengisi nama rincian masuk, dan pengguna hanya perlu memberikan kata sandi.

Untuk mengisi nama rincian masuk terlebih dahulu, lakukan hal berikut:

  1. Jika Anda menggunakan kebijakan kustom, tambahkan klaim input yang diperlukan, seperti yang dijelaskan dalam Menyiapkan masuk langsung.
  2. Temukan authCodeRequest objek, dan atur loginHint atribut dengan petunjuk masuk.

Cuplikan kode berikut menunjukkan cara meneruskan parameter petunjuk masuk. Ini digunakan bob@contoso.com sebagai nilai atribut.

authCodeRequest.loginHint = "bob@contoso.com"

return confidentialClientApplication.getAuthCodeUrl(authCodeRequest)
        .then((response) => {

Memilih sebelumnya penyedia identitas

Jika Anda mengonfigurasi perjalanan rincian masuk untuk aplikasi Anda untuk menyertakan akun sosial, seperti Facebook, LinkedIn, atau Google, Anda dapat menentukan parameter domain_hint. Parameter kueri ini memberikan petunjuk untuk Azure AD B2C tentang IdP sosial yang harus digunakan untuk rincian masuk. Misalnya, jika aplikasi menentukan domain_hint=facebook.com, alur masuk langsung menuju ke halaman masuk Facebook.

Untuk mengalihkan pengguna ke penyedia identitas eksternal, lakukan tindakan berikut:

  1. Periksa nama domain penyedia identitas eksternal Anda. Untuk informasi selengkapnya, lihat Mengalihkan rincian masuk ke penyedia sosial.
  2. Temukan authCodeRequest objek, dan atur domainHint atribut dengan petunjuk domain yang sesuai.

Cuplikan kode berikut menunjukkan cara melewati parameter petunjuk domain. Ini menggunakan facebook.com sebagai nilai atribut.

authCodeRequest.domainHint = "facebook.com"

return confidentialClientApplication.getAuthCodeUrl(authCodeRequest)
        .then((response) => {

Tentukan bahasa UI

Kustomisasi bahasa pemrogram di Microsoft Azure AD B2C memungkinkan alur pengguna Anda untuk mengakomodasi berbagai bahasa yang sesuai dengan kebutuhan pelanggan Anda. Untuk informasi selengkapnya, lihat Kustomisasi bahasa.

Untuk mengatur bahasa pilihan, lakukan hal berikut:

  1. Mengonfigurasi penyesuaian bahasa.
  2. Temukan authCodeRequest objek, dan atur extraQueryParameters atribut dengan ui_locales parameter tambahan yang sesuai.

Cuplikan kode berikut menunjukkan cara melewati ui_locales parameter. Ini digunakan es-es sebagai nilai atribut.

authCodeRequest.extraQueryParameters = {"ui_locales" : "es-es"}

return confidentialClientApplication.getAuthCodeUrl(authCodeRequest)
        .then((response) => {

Meneruskan parameter string kueri kustom

Dengan kebijakan kustom, Anda dapat meneruskan parameter string kueri kustom. Contoh kasus penggunaan yang tepat adalah saat Anda ingin mengubah konten halaman secara dinamis.

Untuk meneruskan parameter string kueri kustom, lakukan tindakan berikut:

  1. Konfigurasi elemen ContentDefinitionParameters.
  2. Temukan authCodeRequest objek, dan atur extraQueryParameters atribut dengan parameter tambahan yang sesuai.

Cuplikan kode berikut menunjukkan cara melewati campaignId parameter string kueri kustom. Ini digunakan germany-promotion sebagai nilai atribut.

authCodeRequest.extraQueryParameters = {"campaignId" : "germany-promotion"}

return confidentialClientApplication.getAuthCodeUrl(authCodeRequest)
        .then((response) => {

Meneruskan petunjuk token ID

Aplikasi pihak yang mengandalkan dapat mengirim JSON Web Token (JWT) masuk sebagai bagian dari permintaan otorisasi OAuth2. Token masuk adalah petunjuk tentang pengguna atau permintaan otorisasi. Azure AD B2C memvalidasi token, lalu mengekstrak klaim.

Untuk memasukkan petunjuk token ID dalam permintaan autentikasi, lakukan tindakan berikut:

  1. Dalam kebijakan kustom Anda, tetapkan profil teknis petunjuk token ID.
  2. Temukan authCodeRequest objek, dan atur extraQueryParameters atribut dengan id_token_hint parameter tambahan yang sesuai.

Cuplikan kode berikut menunjukkan cara menentukan petunjuk token ID:

authCodeRequest.extraQueryParameters = {"id_token_hint": idToken}

return confidentialClientApplication.getAuthCodeUrl(authCodeRequest)

Mengonfigurasi pengelogan

Pustaka MSAL menghasilkan pesan log yang dapat membantu mendiagnosis masalah. Aplikasi ini dapat mengonfigurasi pengelogan. Aplikasi juga dapat memberikan Anda kontrol khusus atas tingkat detail serta apakah data pribadi dan organisasi dicatat atau tidak.

Kami menyarankan Anda membuat panggilan balik pengelogan MSAL dan menyediakan cara bagi pengguna untuk mengirimkan log ketika mereka memiliki masalah autentikasi. MSAL menyediakan beberapa tingkat detail pengelogan:

  • Kesalahan: Menunjukkan ada sesuatu yang salah, dan kesalahan dibuat. Tingkat ini digunakan untuk penelusuran kesalahan dan mengidentifikasi masalah.
  • Peringatan: Belum tentu ada kesalahan atau kegagalan, tetapi ditujukan untuk diagnostik dan menentukan masalah.
  • Info: MSAL akan mencatat peristiwa yang ditujukan untuk tujuan informasi yang tidak selalu dimaksudkan untuk penelusuran kesalahan.
  • Verbose: Ini adalah tingkat default. MSAL mencatat detail lengkap perilaku pustaka.

Secara default, pencatat MSAL tidak menangkap data pribadi atau organisasi apa pun. Pustaka memberi Anda opsi untuk mengaktifkan pengelogan data pribadi dan organisasi jika Anda memutuskan untuk melakukannya.

Untuk mengonfigurasi pengelogan, di index.js, konfigurasikan kunci berikut:

  • logLevel memungkinkan Anda menentukan tingkat pencatatan. Kemungkinan nilai: Error, Warning, Info, dan Verbose.
  • piiLoggingEnabled memungkinkan input data pribadi. Nilai yang mungkin: true atau false.

Cuplikan kode berikut menunjukkan cara mengonfigurasi pengelogan MSAL:

 const confidentialClientConfig = {
    ...
    system: {
        loggerOptions: {
            loggerCallback(loglevel, message, containsPii) {
                console.log(message);
            },
            piiLoggingEnabled: false,
            logLevel: msal.LogLevel.Verbose,
        }
    }
};

Langkah berikutnya

Pelajari lebih lanjut: opsi konfigurasi MSAL.js.