Mengonfigurasi opsi autentikasi dalam aplikasi satu halaman dengan menggunakan Azure AD B2C

  • Artikel

Artikel ini menggunakan contoh aplikasi satu halaman (SPA) JavaScript untuk mengilustrasikan cara menambahkan autentikasi Azure Active Directory B2C (Azure AD B2C) ke aplikasi SPA Anda.

Gambaran Umum

OpenID Connect (OIDC) adalah protokol autentikasi yang dibuat di OAuth 2.0. Anda dapat menggunakan OpenID Connect untuk memasukkan pengguna ke dalam aplikasi dengan aman. Contoh SPA ini menggunakan MSAL.js dan alur OIDC PKCE. MSAL.js adalah pustaka yang disediakan Microsoft yang memudahkan penambahan dukungan autentikasi dan otorisasi ke aplikasi SPA.

Alur masuk

Alur rincian masuk melibatkan langkah berikut:

  1. Pengguna membuka aplikasi web dan memilih Masuk.
  2. Aplikasi memulai permintaan autentikasi dan mengarahkan pengguna ke Azure AD B2C.
  3. Pengguna mendaftar atau masuk dan mengatur ulang sandi. Atau, mereka dapat masuk dengan akun sosial.
  4. Setelah pengguna masuk, Azure AD B2C mengembalikan kode otorisasi ke aplikasi.
  5. Aplikasi satu halaman memvalidasi token ID, membaca klaim, dan kemudian mengizinkan pengguna memanggil sumber daya dan API terlindungi.

Ringkasan pendaftaran aplikasi

Untuk memungkinkan aplikasi masuk menggunakan Azure AD B2C dan memproses API web, Anda harus mendaftarkan dua aplikasi dalam direktori Azure AD B2C.

  • Pendaftaran aplikasi web memungkinkan aplikasi Anda untuk masuk menggunakan Azure AD B2C. Selama pendaftaran, Anda menentukan URI pengalihan. URI pengalihan adalah titik akhir di mana pengguna diarahkan oleh Azure AD B2C setelah autentikasi mereka dengan Azure AD B2C selesai. Proses pendaftaran aplikasi menghasilkan ID aplikasi, juga disebut ID klien, yang menjadi ID aplikasi Anda.

  • Pendaftaran API web memungkinkan aplikasi Anda memproses API web dengan aman. Pendaftaran mencakup cakupanAPI web. Cakupan menyediakan cara untuk mengelola izin ke sumber daya yang dilindungi seperti API web Anda. Anda memberikan izin aplikasi web ke cakupan API web. Ketika token akses diminta, aplikasi menentukan izin yang diinginkan dalam parameter cakupan permintaan.

Arsitektur dan pendaftaran aplikasi diilustrasikan dalam diagram berikut:

Diagram of a web app with web API call registrations and tokens.

Memanggil API web

Setelah autentikasi selesai, pengguna berinteraksi dengan aplikasi, yang memanggil API web yang dilindungi. API web menggunakan autentikasi token pembawa. Token pembawa adalah token akses yang diperoleh aplikasi dari Azure AD B2C. Aplikasi melewati token di header otorisasi permintaan HTTPS.

Authorization: Bearer <access token>

Jika cakupan token akses tidak cocok dengan cakupan API web, pustaka autentikasi memperoleh token akses baru dengan cakupan yang benar.

Alur keluar

Alur proses keluar meliputi langkah-langkah berikut:

  1. Dari aplikasi, pengguna keluar.
  2. Aplikasi menghapus objek sesinya, dan pustaka autentikasi menghapus cache tokennya.
  3. Aplikasi mengalihkan pengguna ke titik akhir keluar Azure Active Directory B2C untuk mengakhiri sesi Azure Active Directory B2C.
  4. Pengguna dialihkan kembali ke aplikasi.

Prasyarat

Komputer yang menjalankan:

Langkah 1: Mengonfigurasi alur pengguna

Saat pengguna mencoba masuk ke aplikasi Anda, aplikasi memulai permintaan autentikasi ke titik akhir otorisasi melalui alur pengguna. Alur pengguna mendefinisikan dan mengontrol pengalaman pengguna. Setelah pengguna menyelesaikan alur pengguna, Azure Active Directory B2C membuat token dan kemudian mengarahkan pengguna kembali ke aplikasi Anda.

Jika Anda belum melakukannya, buat alur pengguna atau kebijakan kustom. Ulangi langkah-langkah tersebut untuk membuat tiga alur pengguna terpisah sebagai berikut:

  • Gabungan alur pengguna daftar dan masuk, seperti susi. Alur pengguna ini juga mendukung pengalaman Lupa kata sandi Anda.
  • Alur pengguna Pengeditan profil, seperti edit_profile.
  • Alur pengguna Pengaturan ulang kata sandi, seperti reset_password.

Azure AD B2C menambahkan B2C_1_ ke nama alur pengguna. Misalnya, susi menjadi B2C_1_susi.

Langkah 2: Mendaftarkan SPA dan API Anda

Dalam langkah ini, Anda membuat SPA dan pendaftaran aplikasi API web, serta menentukan cakupan API web Anda.

Langkah 2.1: Mendaftarkan aplikasi API web

Untuk membuat pendaftaran aplikasi API web (ID Aplikasi: 2), ikuti langkah-langkah berikut:

  1. Masuk ke portal Azure.

  2. Pastikan Anda menggunakan direktori yang berisi penyewa AAD B2C Anda. Pilih ikon Direktori + langganan di bilah alat portal.

  3. Pada Setelan portal | Direktori + langganan, temukan direktori Azure AD B2C Anda di daftar Nama direktori, lalu pilih Beralih.

  4. Di portal Microsoft Azure, cari dan pilih AAD B2C.

  5. Pilih Pendaftaran aplikasi, lalu pilih Pendaftaran baru.

  6. Untuk Nama, masukkan nama untuk aplikasi (misalnya, my-api1). Biarkan nilai default untuk URI Pengalihan dan Jenis akun yang didukung.

  7. Pilih Daftarkan.

  8. Setelah pendaftaran aplikasi selesai, pilih Ringkasan.

  9. Catat nilai ID Aplikasi (klien) untuk digunakan nanti, saat Anda mengonfigurasi aplikasi web.

    Screenshot that demonstrates how to get a web A P I application I D.

Langkah 2.2: Mengonfigurasi cakupan

  1. Pilih aplikasi my-api1 yang Anda buat (ID Aplikasi: 2) untuk membuka halaman Ringkasannya.

  2. Di bagian Kelola, pilih Ekspos API.

  3. Di samping URI ID Aplikasi, pilih tautan Set. Ganti nilai default (GUID) dengan nama yang unik (misalnya, tasks-api ), kemudian pilih Simpan .

    Ketika aplikasi web Anda meminta token akses untuk API, ia harus menambahkan URI ini sebagai awalan bagi setiap cakupan yang Anda tentukan untuk API.

  4. Di bagian Cakupan yang ditentukan oleh API ini, pilih Tambahkan cakupan.

  5. Untuk membuat cakupan yang menentukan akses baca ke API:

    1. Untuk Nama cakupan, masukkan tasks.read.
    2. Untuk Nama tampilan perizinan admin, masukkan Akses baca ke API tugas.
    3. Untuk Deskripsi perizinan admin, masukkan Izinkan akses baca ke API tugas.

  6. Pilih Tambahkan cakupan.

  7. Pilih Tambahkan cakupan, lalu tambahkan cakupan yang menentukan akses tulis ke API:

    1. Untuk Nama cakupan, masukkan tasks.write.
    2. Untuk Nama tampilan perizinan admin, masukkan Akses tulis ke API tugas.
    3. Untuk Deskripsi perizinan admin, masukkan Izinkan akses tulis ke API tugas.

  8. Pilih Tambahkan cakupan.

Langkah 2.3: Mendaftarkan SPA

Untuk membuat pendaftaran SPA, gunakan langkah-langkah berikut:

  1. Masuk ke portal Azure.
  2. Jika Anda memiliki akses ke beberapa penyewa, pilih ikon Pengaturan di menu atas untuk beralih ke penyewa Azure AD B2C Anda dari menu Direktori + langganan.
  3. Cari dan pilih Azure AD B2C.
  4. Pilih Pendaftaran aplikasi, lalu pilih Pendaftaran baru.
  5. Masukkan Nama untuk aplikasi Anda (misalnya, MyApp).
  6. Di bagian Tipe akun yang didukung, pilih Akun di penyedia identitas atau direktori organisasi apa pun (untuk mengautentikasi pengguna dengan alur pengguna).
  7. Di bagian URI Pengalihan, pilih Aplikasi satu halaman (SPA), lalu masukkan http://localhost:6420 di kotak URL.
  8. Di bagian Izin, pilih kotak centang Berikan persetujuan admin untuk openid dan izin akses offline.
  9. Pilih Daftarkan.

Rekam ID Aplikasi (klien) untuk digunakan di lain waktu saat mengonfigurasi aplikasi web.

Screenshot of the web app Overview page for recording your web application ID.

Langkah 2.4: Mengaktifkan aliran pemberian implisit

Di lingkungan Anda sendiri, jika aplikasi SPA Anda menggunakan MSAL.js 1.3 atau yang lebih lama dan alur hibah implisit atau Anda mengonfigurasi aplikasi https://jwt.ms/ untuk menguji alur pengguna atau kebijakan kustom, Anda harus mengaktifkan alur hibah implisit dalam pendaftaran aplikasi:

  1. Di menu sebelah kiri, di bagian Kelola, pilih Autentikasi.

  2. Di bawah Hibah dan alur hibrid implisit, centang kotak Token akses (digunakan untuk alur implisit) dan token ID (digunakan untuk alur implisit dan hibrid).

  3. Pilih Simpan.

Jika aplikasi Anda menggunakan MSAL.js 2.0 atau yang lebih baru, jangan aktifkan hibah alur implisit karena MSAL.js 2.0+ mendukung alur kode otorisasi dengan PKCE. Aplikasi SPA dalam artikel ini menggunakan alur PKCE, sehingga Anda tidak perlu mengaktifkan alur hibah implisit.

Langkah 2.5: Memberikan izin

Untuk memberi izin kepada aplikasi Anda (ID Aplikasi: 1), ikuti langkah-langkah berikut:

  1. Pilih Pendaftaran aplikasi, lalu pilih aplikasi yang Anda buat (ID Aplikasi: 1).

  2. Di bagian Kelola, pilih Izin API.

  3. Di Izin yang dikonfigurasi, pilih Tambahkan izin.

  4. Pilih tab API Saya.

  5. Pilih API (ID Aplikasi: 2) yang aplikasi webnya akan diberi akses. Contohnya, masukkan my-api1.

  6. Di bagian Izin, luaskan tugas, lalu pilih cakupan yang Anda tentukan sebelumnya (misalnya, tasks.read dan tasks.write).

  7. Pilih Tambahkan izin.

  8. Pilih Beri persetujuan admin untuk <nama penyewa Anda>.

  9. Pilih Ya.

  10. Pilih Refresh, lalu pastikan bahwa Diberikan untuk ... muncul di bawah Status untuk kedua cakupan.

  11. Dari daftar Izin akses yang dikonfigurasi, pilih cakupan Anda, lalu salin nama lengkap cakupan.

    Screenshot of the configured permissions pane, showing that read access permissions are granted.

Langkah 3: Mendapatkan kode sampel SPA

Contoh ini menunjukkan cara aplikasi satu halaman dapat menggunakan Azure Active Directory B2C untuk pendaftaran dan masuk pengguna. Kemudian aplikasi memperoleh token akses dan memanggil API web yang dilindungi.

Untuk mendapatkan kode sampel SPA, Anda dapat melakukan salah satu hal berikut:

  • Unduh file zip.

  • Klon sampel dari GitHub dengan menjalankan perintah berikut:

    git clone https://github.com/Azure-Samples/ms-identity-b2c-javascript-spa.git

Langkah 3.1: Memperbarui sampel SPA

Setelah Anda mendapatkan sampel SPA, perbarui kode dengan nilai Azure AD B2C dan web API Anda. Di folder sampel, di folder App, buka file JavaScript yang tercantum dalam tabel berikut, lalu perbarui dengan nilai yang sesuai.

File Tombol Nilai
authConfig.js clientId ID SPA dari langkah 2.3.
policies.js nama Alur pengguna, atau kebijakan kustom yang Anda buat di langkah 1.
policies.js otoritas Alur pengguna Azure AD B2C Anda atau otoritas kebijakan kustom seperti https://<your-tenant-name>.b2clogin.com/<your-tenant-name>.onmicrosoft.com/<your-sign-in-sign-up-policy>. Ganti your-sign-in-sign-up-policy dengan alur pengguna atau kebijakan kustom yang Anda buat di langkah 1
policies.js authorityDomain Domain otoritas Azure AD B2C Anda seperti <your-tenant-name>.b2clogin.com.
apiConfig.js b2cScopes Cakupan API web yang Anda buat pada langkah 2.2 (misalnya, b2cScopes: ["https://<your-tenant-name>.onmicrosoft.com/tasks-api/tasks.read"]).
apiConfig.js webApi URL dari API web, http://localhost:5000/hello.

Kode yang Anda hasilkan akan terlihat seperti sampel berikut:

authConfig.js:

const msalConfig = {
    auth: {
      clientId: "<your-MyApp-application-ID>", // This is the ONLY mandatory field; everything else is optional.
      authority: b2cPolicies.authorities.signUpSignIn.authority, // Choose sign-up/sign-in user-flow as your default.
      knownAuthorities: [b2cPolicies.authorityDomain], // You must identify your tenant's domain as a known authority.
      redirectUri: "http://localhost:6420", // You must register this URI on Azure Portal/App Registration. Defaults to "window.location.href".
    },
    cache: {
      cacheLocation: "sessionStorage",  
      storeAuthStateInCookie: false, 
    },
    system: {
      loggerOptions: {
        loggerCallback: (level, message, containsPii) => {
          if (containsPii) {
            return;
          }
          switch (level) {
            case msal.LogLevel.Error:
              console.error(message);
              return;
            case msal.LogLevel.Info:
              console.info(message);
              return;
            case msal.LogLevel.Verbose:
              console.debug(message);
              return;
            case msal.LogLevel.Warning:
              console.warn(message);
              return;
          }
        }
      }
    }
  };
};

const loginRequest = {
  scopes: ["openid", ...apiConfig.b2cScopes],
};

const tokenRequest = {
  scopes: [...apiConfig.b2cScopes],  // e.g. ["https://fabrikamb2c.onmicrosoft.com/helloapi/demo.read"]
  forceRefresh: false // Set this to "true" to skip a cached token and go to the server to get a new token
};

policies.js:

const b2cPolicies = {
    names: {
        signUpSignIn: "b2c_1_susi",
        forgotPassword: "b2c_1_reset",
        editProfile: "b2c_1_edit_profile"
    },
    authorities: {
        signUpSignIn: {
            authority: "https://your-tenant-name.b2clogin.com/your-tenant-name.onmicrosoft.com/b2c_1_susi",
        },
        forgotPassword: {
            authority: "https://your-tenant-name.b2clogin.com/your-tenant-name.onmicrosoft.com/b2c_1_reset",
        },
        editProfile: {
            authority: "https://your-tenant-name.b2clogin.com/your-tenant-name.onmicrosoft.com/b2c_1_edit_profile"
        }
    },
    authorityDomain: "your-tenant-name.b2clogin.com"
}

apiConfig.js:

const apiConfig = {
  b2cScopes: ["https://your-tenant-name.onmicrosoft.com/tasks-api/tasks.read"],
  webApi: "http://localhost:5000/hello"
};

Langkah 4: Dapatkan kode sampel API web

Sekarang setelah API web terdaftar dan Anda telah menentukan cakupan, konfigurasikan API web agar berfungsi dengan penyewa Azure AD B2C Anda.

Untuk mendapatkan kode sampel API web, lakukan salah satu tindakan berikut:

Langkah 4.1: Memperbarui API web

  1. Buka file config.json di editor kode Anda.

  2. Ubah nilai variabel dengan pendaftaran aplikasi yang Anda buat sebelumnya. Selain itu, perbarui juga policyName dengan alur pengguna yang Anda buat sebagai bagian dari prasyarat (misalnya, b2c_1_susi).

    "credentials": {
    "tenantName": "<your-tenant-name>",
    "clientID": "<your-webapi-application-ID>"
},
"policies": {
    "policyName": "b2c_1_susi"
},
"resource": {
    "scope": ["tasks.read"] 
},

Langkah 4.2: Mengaktifkan CORS

Agar aplikasi satu halaman Anda dapat memanggil API web Node.js, Anda perlu mengaktifkan berbagi sumber daya lintas-asal (CORS) di API web. Dalam aplikasi produksi, Anda harus berhati-hati pada domain mana yang membuat permintaan. Dalam contoh ini, izinkan permintaan dari domain apa pun.

Untuk mengaktifkan CORS, gunakan middleware berikut. Dalam sampel kode API web Node.js yang telah diunduh, ini sudah ditambahkan ke file index.js.

app.use((req, res, next) => {
    res.header("Access-Control-Allow-Origin", "*");
    res.header("Access-Control-Allow-Headers", "Authorization, Origin, X-Requested-With, Content-Type, Accept");
    next();
});

Langkah 5: Jalankan SPA dan API web

Anda sekarang siap untuk menguji akses cakupan aplikasi satu halaman ke API. Jalankan API web Node.js dan aplikasi halaman tunggal JavaScript sampel di komputer lokal Anda. Kemudian, masuk ke aplikasi satu halaman dan pilih tombol Panggil API untuk memulai permintaan ke API yang dilindungi.

Jalankan API web Node.js

  1. Buka jendela konsol dan ubah ke direktori yang berisi sampel API web Node.js. Contohnya:

    cd active-directory-b2c-javascript-nodejs-webapi

  2. Jalankan perintah berikut:

    npm install && npm update
node index.js

    Jendela konsol menampilkan nomor port tempat aplikasi dihosting.

    Listening on port 5000...

Menjalankan aplikasi satu halaman

  1. Buka jendela konsol lain dan ubah ke direktori yang berisi sampel JavaScript SPA. Contohnya:

    cd ms-identity-b2c-javascript-spa

  2. Jalankan perintah berikut:

    npm install && npm update
npm start

    Jendela konsol menampilkan nomor port tempat aplikasi dihosting.

    Listening on port 6420...

  3. Buka http://localhost:6420 di browser Anda untuk melihat aplikasi.

    Screenshot of the SPA sample app displayed in the browser window.

  4. Selesaikan proses pendaftaran atau masuk. Setelah berhasil masuk, Anda akan melihat pesan "Pengguna <nama pengguna Anda> telah masuk".

  5. Pilih tombol ​​Call API. SPA mengirimkan token akses dalam permintaan ke API web yang dilindungi, yang menampilkan nama tampilan pengguna yang masuk:

    Screenshot of the SPA in a browser window, showing the username JSON result that's returned by the API.

Menyebarkan aplikasi Anda

Dalam aplikasi produksi, URI pengalihan pendaftaran aplikasi biasanya berupa titik akhir yang dapat diakses secara publik tempat aplikasi Anda berjalan, seperti https://contoso.com/signin-oidc.

Anda dapat menambahkan dan mengubah URI pengalihan di aplikasi Anda yang telah terdaftar kapan saja. Pembatasan berikut berlaku untuk mengalihkan URI:

  • URL balasan harus dimulai dengan skema https.
  • URL balasan peka huruf besar/kecil. Ukuran huruf harus sesuai dengan ukuran huruf pada jalur URL pada aplikasi berjalan.

Langkah berikutnya

Untuk informasi selengkapnya tentang konsep yang dibahas dalam artikel ini: