Mengaktifkan autentikasi di API web Anda sendiri dengan menggunakan Azure AD B2C

Penting

Berlaku mulai 1 Mei 2025, Azure AD B2C tidak akan lagi tersedia untuk dibeli untuk pelanggan baru. Pelajari lebih lanjut di FAQ kami.

Untuk mengotorisasi akses ke API web, Anda hanya dapat melayani permintaan yang menyertakan token akses valid yang dikeluarkan oleh Azure Active Directory B2C (Azure AD B2C). Artikel ini memperlihatkan kepada Anda cara mengaktifkan otorisasi Azure AD B2C ke API web Anda. Setelah Anda menyelesaikan langkah-langkah dalam artikel ini, hanya pengguna yang mendapatkan token akses yang valid yang akan diotorisasi untuk memanggil titik akhir API web Anda.

Prasyarat

Sebelum memulai, baca salah satu artikel berikut, yang membahas cara mengonfigurasi autentikasi untuk aplikasi yang memanggil API web. Kemudian, ikuti langkah-langkah dalam artikel ini untuk mengganti api web sampel dengan API web Anda sendiri.

• Mengonfigurasi autentikasi dalam sampel aplikasi ASP.NET Core
• Mengonfigurasi autentikasi dalam sampel aplikasi halaman tunggal (SPA)

Gambaran Umum

Autentikasi berbasis token memastikan bahwa permintaan ke API web menyertakan token akses yang valid.

Aplikasi menyelesaikan langkah-langkah berikut:

1. Ini mengautentikasi pengguna dengan Azure AD B2C.

2. Ini memperoleh token akses dengan izin (cakupan) yang diperlukan untuk titik akhir API web.

3. Ini mengirimkan token akses sebagai token pembawa di header autentikasi permintaan HTTP dengan menggunakan format ini:

   Authorization: Bearer <access token>
   

API web menyelesaikan langkah-langkah berikut:

1. Ini membaca token pembawa dari header otorisasi dalam permintaan HTTP.

2. Ini memvalidasi token.

3. Ini melakukan validasi izin (cakupan) dalam token.

4. Ini membaca klaim yang dikodekan dalam token (opsional).

5. Ini menanggapi permintaan HTTP.

Ringkasan pendaftaran aplikasi

Untuk mengaktifkan aplikasi Anda untuk masuk dengan Azure AD B2C dan memanggil API web, Anda perlu mendaftarkan dua aplikasi di direktori Azure AD B2C.

• Pendaftaran aplikasi web, seluler, atau SPA memungkinkan aplikasi Anda untuk masuk dengan Azure AD B2C. Proses pendaftaran aplikasi menghasilkan ID Aplikasi, juga dikenal sebagai ID klien, yang secara unik mengidentifikasi aplikasi Anda (misalnya, ID Aplikasi: 1).

• Pendaftaran API web memungkinkan aplikasi Anda memanggil API web yang dilindungi. Pendaftaran mengekspos izin API web (cakupan). Proses pendaftaran aplikasi menghasilkan ID Aplikasi, yang secara unik mengidentifikasi API web Anda (misalnya, ID Aplikasi: 2). Berikan izin aplikasi Anda (ID Aplikasi: 1) ke cakupan API web (ID Aplikasi: 2).

Pendaftaran aplikasi dan arsitektur aplikasi dijelaskan dalam diagram berikut:

Menyiapkan lingkungan pengembangan Anda

Di bagian berikutnya, Anda membuat proyek API web baru. Pilih bahasa pemrograman Anda, ASP.NET Core, atau Node.js. Pastikan Anda memiliki komputer yang menjalankan salah satu perangkat lunak berikut:

ASP.NET Core

• Visual Studio Code
• C# untuk Visual Studio Code (versi terbaru)
• .NET 5.0 SDK

Node.js

• Visual Studio Code, atau editor kode lain
• Runtime Node.js

Langkah 1: Membuat API web yang dilindungi

Buat proyek API web baru. Pertama, pilih bahasa pemrograman yang ingin Anda gunakan, ASP.NET Core atau Node.js.

ASP.NET Core

Gunakan perintah dotnet new. Perintah dotnet new membuat folder baru bernama TodoList dengan aset proyek API web. Buka direktori, lalu buka Visual Studio Code.

dotnet new webapi -o TodoList
cd TodoList
code . 

Saat Anda diminta untuk "menambahkan aset yang diperlukan ke proyek," pilih Ya.

Node.js

Gunakan Express untuk Node.js untuk membangun API web. Untuk membuat API web, lakukan hal berikut:

1. Buat folder baru bernama TodoList.
2. Di bawah folder TodoList , buat file bernama app.js.
3. Pada jendela perintah, jalankan npm init -y. Perintah ini membuat file package.json default untuk proyek Node.js Anda.
4. Dalam command shell, jalankan npm install express. Perintah ini menginstal kerangka kerja Ekspres.

Langkah 2: Instal dependensi

Tambahkan pustaka autentikasi ke proyek API web Anda. Pustaka autentikasi mengurai header autentikasi HTTP, memvalidasi token, dan mengekstrak klaim. Untuk informasi selengkapnya, tinjau dokumentasi untuk pustaka.

ASP.NET Core

Untuk menambahkan pustaka autentikasi, instal paket dengan menjalankan perintah berikut:

dotnet add package Microsoft.Identity.Web

Node.js

Untuk menambahkan pustaka autentikasi, instal paket dengan menjalankan perintah berikut:

npm install passport
npm install passport-azure-ad
npm install morgan

Paket Morgan adalah middleware pencatat permintaan HTTP untuk Node.js.

Langkah 3: Memulai pustaka autentikasi

Tambahkan kode yang diperlukan untuk memulai pustaka autentikasi.

ASP.NET Core

Buka Startup.cs lalu, di awal kelas, tambahkan deklarasi berikut using :

using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.Identity.Web;

Temukan fungsi ConfigureServices(IServiceCollection services). Kemudian, sebelum services.AddControllers(); baris kode, tambahkan cuplikan kode berikut:

public void ConfigureServices(IServiceCollection services)
{
    // Adds Microsoft Identity platform (Azure AD B2C) support to protect this Api
    services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
            .AddMicrosoftIdentityWebApi(options =>
    {
        Configuration.Bind("AzureAdB2C", options);

        options.TokenValidationParameters.NameClaimType = "name";
    },
    options => { Configuration.Bind("AzureAdB2C", options); });
    // End of the Microsoft Identity platform block    

    services.AddControllers();
}

Temukan fungsi Configure. Kemudian, segera setelah app.UseRouting(); baris kode, tambahkan cuplikan kode berikut:

app.UseAuthentication();

Setelah perubahan, kode Anda akan terlihat seperti cuplikan berikut:

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
    }

    app.UseHttpsRedirection();

    app.UseRouting();
    
    // Add the following line 
    app.UseAuthentication();
    // End of the block you add
    
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

Node.js

Tambahkan kode JavaScript berikut ke file app.js Anda.

// Import the required libraries
const express = require('express');
const morgan = require('morgan');
const passport = require('passport');
const config = require('./config.json');

// Import the passport Azure AD library
const BearerStrategy = require('passport-azure-ad').BearerStrategy;

// Set the Azure AD B2C options
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,
    audience: config.credentials.clientID,
    issuer: config.credentials.issuer,
    policyName: config.policies.policyName,
    isB2C: config.settings.isB2C,
    scope: config.resource.scope,
    validateIssuer: config.settings.validateIssuer,
    loggingLevel: config.settings.loggingLevel,
    passReqToCallback: config.settings.passReqToCallback
}

// Instantiate the passport Azure AD library with the Azure AD B2C options
const bearerStrategy = new BearerStrategy(options, (token, done) => {
        // Send user info using the second argument
        done(null, { }, token);
    }
);

// Use the required libraries
const app = express();

app.use(morgan('dev'));

app.use(passport.initialize());

passport.use(bearerStrategy);

//enable CORS (for testing only -remove in production/deployment)
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 4: Tambahkan titik akhir

Tambahkan dua titik akhir ke API web Anda:

• Titik akhir anonim /public . Titik akhir ini mengembalikan tanggal dan waktu saat ini. Gunakan untuk men-debug API web Anda dengan panggilan anonim.
• Titik akhir yang dilindungi /hello . Titik akhir ini mengembalikan nilai name klaim dalam token akses.

Untuk menambahkan titik akhir anonim:

ASP.NET Core

Di bawah folder /Controllers , tambahkan file PublicController.cs , lalu tambahkan ke cuplikan kode berikut:

using System;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;

namespace TodoList.Controllers
{
    [ApiController]
    [Route("[controller]")]
    public class PublicController : ControllerBase
    {
        private readonly ILogger<PublicController> _logger;

        public PublicController(ILogger<PublicController> logger)
        {
            _logger = logger;
        }

        [HttpGet]
        public ActionResult Get()
        {
            return Ok( new {date = DateTime.UtcNow.ToString()});
        }
    }
}

Node.js

Dalam file app.js , tambahkan kode JavaScript berikut:

// API anonymous endpoint
app.get('/public', (req, res) => res.send( {'date': new Date() } ));

Untuk menambahkan titik akhir yang dilindungi:

ASP.NET Core

Di bawah folder /Controllers , tambahkan file HelloController.cs , lalu tambahkan ke kode berikut:

using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Extensions.Logging;
using Microsoft.Identity.Web.Resource;

namespace TodoList.Controllers
{
    [Authorize]
    [RequiredScope("tasks.read")]
    [ApiController]
    [Route("[controller]")]
    public class HelloController : ControllerBase
    {

        private readonly ILogger<HelloController> _logger;
        private readonly IHttpContextAccessor _contextAccessor;

        public HelloController(ILogger<HelloController> logger, IHttpContextAccessor contextAccessor)
        {
            _logger = logger;
            _contextAccessor = contextAccessor;
        }

        [HttpGet]
        public ActionResult Get()
        {
            return Ok( new { name = User.Identity.Name});
        }
    }
}

HelloController Pengontrol dihiasi dengan AuthorizeAttribute, yang membatasi akses hanya untuk pengguna yang diautentikasi.

Pengontrol juga dihiasi dengan [RequiredScope("tasks.read")]. RequiredScopeAttribute memverifikasi bahwa API web dipanggil dengan cakupan yang tepat, tasks.read.

Node.js

Dalam file app.js , tambahkan kode JavaScript berikut:

// API protected endpoint
app.get('/hello',
    passport.authenticate('oauth-bearer', {session: false}),
    (req, res) => {
        console.log('Validated claims: ', req.authInfo);
        
        // Service relies on the name claim.  
        res.status(200).json({'name': req.authInfo['name']});
    }
);

Endpoint /hello pertama kali memanggil fungsi passport.authenticate(). Fungsi autentikasi hanya membatasi akses ke pengguna yang diautentikasi.

Fungsi autentikasi juga memverifikasi bahwa API web dipanggil dengan cakupan yang tepat. Cakupan yang diizinkan terletak di file konfigurasi.

Langkah 5: Mengonfigurasi server web

Di lingkungan pengembangan, atur API web untuk mendengarkan nomor port permintaan HTTP atau HTTPS masuk. Dalam contoh ini, gunakan port HTTP 6000 dan port HTTPS 6001. URI dasar API web akan untuk http://localhost:6000 HTTP dan https://localhost:6001 untuk HTTPS.

ASP.NET Core

Tambahkan cuplikan JSON berikut ke file appsettings.json .

"Kestrel": {
    "EndPoints": {
      "Http": {
        "Url": "http://localhost:6000"
      },
      "Https": {
         "Url": "https://localhost:6001"   
        }
    }
  }

Node.js

Tambahkan kode JavaScript berikut ke file app.js . Dimungkinkan untuk menyiapkan titik akhir HTTP dan HTTPS untuk aplikasi Node.

// Starts listening on port 6000
const port = process.env.PORT || 6000;

app.listen(port, () => {
    console.log('Listening on port ' + port);
});

Langkah 6: Mengonfigurasi API web

Tambahkan konfigurasi ke file konfigurasi. File berisi informasi tentang penyedia identitas Azure AD B2C Anda. Aplikasi API web menggunakan informasi ini untuk memvalidasi token akses yang diteruskan aplikasi web sebagai token pembawa.

ASP.NET Core

Di bawah folder akar proyek, buka file appsettings.json , lalu tambahkan pengaturan berikut:

{
  "AzureAdB2C": {
    "Instance": "https://contoso.b2clogin.com",
    "Domain": "contoso.onmicrosoft.com",
    "ClientId": "<web-api-app-application-id>",
    "SignedOutCallbackPath": "/signout/<your-sign-up-in-policy>",
    "SignUpSignInPolicyId": "<your-sign-up-in-policy>"
  },
  // More settings here
}

Dalam file appsettings.json , perbarui properti berikut ini:

Bagian	Kunci	Nilai
AzureAdB2C	Kasus	Bagian pertama dari nama penyewa Azure AD B2C Anda (misalnya, https://contoso.b2clogin.com).
AzureAdB2C	Ruang Lingkup	Nama lengkap penyewa Azure AD B2C Anda (misalnya, ).
AzureAdB2C	ClientId	ID aplikasi API web. Dalam diagram sebelumnya, ini adalah aplikasi dengan ID Aplikasi: 2. Untuk mempelajari cara mendapatkan ID pendaftaran aplikasi API web Anda, lihat Prasyarat.
AzureAdB2C	IDKebijakanDaftarMasukMasuk	Alur pengguna, atau kebijakan kustom. Untuk mempelajari cara mendapatkan alur atau kebijakan pengguna Anda, lihat Prasyarat.

Node.js

Di bawah folder akar proyek, buat file config.json , lalu tambahkan ke cuplikan JSON berikut:

{
    "credentials": {
        "tenantName": "<your-tenant-name>.onmicrosoft.com",
        "clientID": "<your-webapi-application-ID>",
        "issuer": "https://<your-tenant-name>.b2clogin.com/<your-tenant-ID>/v2.0/"
    },
    "policies": {
        "policyName": "b2c_1_susi"
    },
    "resource": {
        "scope": ["tasks.read"]
    },
    "metadata": {
        "discovery": ".well-known/openid-configuration",
        "version": "v2.0"
    },
    "settings": {
        "isB2C": true,
        "validateIssuer": true,
        "passReqToCallback": false,
        "loggingLevel": "info"
    }
}

Dalam file config.json , perbarui properti berikut ini:

Bagian	Kunci	Nilai
Bukti identitas	namaPenyewa	Nama penyewa/nama domain Azure AD B2C Anda (misalnya, contoso.onmicrosoft.com).
Bukti identitas	ID klien	ID aplikasi API web. Dalam diagram sebelumnya, ini adalah aplikasi dengan ID Aplikasi: 2. Untuk mempelajari cara mendapatkan ID pendaftaran aplikasi API web Anda, lihat Prasyarat.
Bukti identitas	penerbit	Nilai klaim penerbit iss token. Secara default, Azure AD B2C mengembalikan token dalam format berikut: https://<your-tenant-name>.b2clogin.com/<your-tenant-ID>/v2.0/. Ganti <your-tenant-name> dengan bagian pertama dari nama penyewa Azure AD B2C Anda. Ganti <your-tenant-ID> dengan ID penyewa Azure AD B2C Anda.
Kebijakan	Nama Kebijakan	Alur pengguna, atau kebijakan kustom. Untuk mempelajari cara mendapatkan alur atau kebijakan pengguna Anda, lihat Prasyarat.
Sumber daya	ruang lingkup	Cakupan pendaftaran aplikasi API web Anda. Untuk mempelajari cara mendapatkan cakupan API web Anda, lihat Prasyarat.

Langkah 7: Jalankan dan uji API web

Terakhir, jalankan API web dengan pengaturan lingkungan Azure AD B2C Anda.

ASP.NET Core

Di shell perintah, mulai aplikasi web dengan menjalankan perintah berikut:

 dotnet run

Anda akan melihat output berikut, yang berarti aplikasi Anda aktif dan berjalan dan siap menerima permintaan.

Now listening on: http://localhost:6000

Untuk menghentikan program, di shell perintah, pilih Ctrl+C. Anda dapat menjalankan ulang aplikasi dengan menggunakan node app.js perintah .

Petunjuk / Saran

Atau, untuk menjalankan dotnet run perintah, Anda dapat menggunakan debugger Visual Studio Code. Debugger bawaan Visual Studio Code membantu mempercepat perulangan pengeditan, kompilasi, dan debug Anda.

Buka browser dan kunjungi http://localhost:6000/public. Di jendela browser, Anda akan melihat teks berikut ditampilkan, bersama dengan tanggal dan waktu saat ini.

Node.js

Di shell perintah, mulai aplikasi web dengan menjalankan perintah berikut:

node app.js

Anda akan melihat output berikut, yang berarti aplikasi Anda aktif dan berjalan dan siap menerima permintaan.

Example app listening on port 6000!

Untuk menghentikan program, di shell perintah, pilih Ctrl+C. Anda dapat menjalankan ulang aplikasi dengan menggunakan node app.js perintah .

Petunjuk / Saran

Atau, untuk menjalankan node app.js perintah, gunakan debugger Visual Studio Code. Debugger bawaan Visual Studio Code membantu mempercepat perulangan pengeditan, kompilasi, dan debug Anda.

Buka browser dan kunjungi http://localhost:6000/public. Di jendela browser, Anda akan melihat teks berikut ditampilkan, bersama dengan tanggal dan waktu saat ini.

Langkah 8: Panggil API web dari aplikasi Anda

Cobalah untuk memanggil titik akhir API web yang dilindungi tanpa token akses. Buka browser dan kunjungi http://localhost:6000/hello. API mengembalikan pesan kesalahan HTTP yang tidak sah, mengonfirmasi bahwa API web dilindungi dengan token pembawa.

Lanjutkan mengonfigurasi aplikasi Anda untuk memanggil API web. Untuk panduan, lihat bagian Prasyarat .

Tonton video ini untuk mempelajari beberapa praktik terbaik saat Anda mengintegrasikan Azure AD B2C dengan API.

Konten terkait

Dapatkan contoh lengkap di GitHub:

ASP.NET Core

• Dapatkan API web dengan menggunakan pustaka identitas Microsoft.

Node.js

• Dapatkan API web dengan menggunakan pustakaPassport.js.