Mengaktifkan autentikasi di API web milik Anda menggunakan Azure AD B2C

Untuk mengotorisasi akses ke API web, Anda hanya dapat melayani permintaan yang menyertakan token akses valid yang menjadi masalah Azure Active Directory B2C (Azure AD B2C). Artikel ini menunjukkan 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 diizinkan untuk menghubungi titik akhir API web Anda.

Prasyarat

Sebelum Anda mulai, 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 contoh API web dengan API web Anda sendiri.

• Mengonfigurasi autentikasi dalam aplikasi ASP.NET Core sampel
• Mengonfigurasi autentikasi dalam aplikasi halaman tunggal (single-page application (SPA)) sampel

Gambaran Umum

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

Aplikasi menyelesaikan langkah-langkah berikut:

1. Aplikasi mengautentikasi pengguna dengan Azure AD B2C.

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

3. Aplikasi meneruskan token akses sebagai token pembawa di header autentikasi permintaan HTTP menggunakan format ini:

   Authorization: Bearer <access token>
   

API web menyelesaikan langkah-langkah berikut:

1. API web membaca token pembawa dari header otorisasi dalam permintaan HTTP.

2. API web memvalidasi token.

3. API web memvalidasi izin (cakupan) dalam token.

4. API web membaca klaim yang dikodekan dalam token (opsional).

5. API web 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 menggunakan Azure AD B2C. Proses pendaftaran aplikasi menghasilkan ID Aplikasi, juga dikenal sebagai ID klien, yang mengidentifikasi aplikasi Anda secara unik (misalnya, ID Aplikasi: 1).

• Pendaftaran API web memungkinkan aplikasi Anda untuk 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 ApIikasi: 2). Berikan izin kepada aplikasi Anda (ID Aplikasi: 1) ke cakupan API web (ID Aplikasi: 2).

Pendaftaran aplikasi dan arsitektur aplikasi dijelaskan dalam diagram berikut:

Mempersiapkan 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:

Inti ASP.NET

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

Node.js

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

Langkah 1: Membuat API web yang dilindungi

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

Inti ASP.NET

Gunakan perntah 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 . 

Ketika 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 dengan nama app.js.
3. Dalam command shell, 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 Express.

Langkah 2: Memasang dependensi

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

Inti ASP.NET

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.

Inti ASP.NET

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

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

Temukan fungsi ConfigureServices(IServiceCollection services). Kemudian, sebelum baris services.AddControllers(); 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 baris app.UseRouting(); kode, tambahkan cuplikan kode berikut:

app.UseAuthentication();

Setelah perubahan, kode Anda akan terlihat seperti cuplikan kode 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: Menambahkan titik akhir

Tambahkan dua titik akhir ke API web Anda:

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

Untuk menambahkan titik akhir anonim:

Inti ASP.NET

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:

Inti ASP.NET

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});
        }
    }
}

Pengontrol HelloController controller didekorasi dengan AuthorizeAttribute, yang membatasi akses hanya ke pengguna yang diautentikasi.

Pengontrol juga didekorasi dengan [RequiredScope("tasks.read")]. RequiredScopeAttribute memverifikasi bahwa API web dipanggil dengan cakupan yang benar, 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']});
    }
);

Titik akhir /hello terlebih dahulu 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 berlokasi di dalam file konfigurasi.

Langkah 5: Mengonfigurasikan server web Anda

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

Inti ASP.NET

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: Mengonfigurasikan API web

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

Inti ASP.NET

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:

Bagian	Tombol	Nilai
AzureAdB2C	Instans	Bagian pertama dari nama penyewa Azure AD B2C Anda (misalnya, https://contoso.b2clogin.com).
AzureAdB2C	Domain	Nama penyewa lengkap penyewa Azure AD B2C Anda (misalnya, contoso.onmicrosoft.com).
AzureAdB2C	ClientId	ID aplikasi API web. Pada diagram di atas, ini adalah aplikasi dengan ID Aplikasi: 2. Untuk mempelajari cara mendapatkan ID pendaftaran aplikasi API web Anda, lihat Prasyarat.
AzureAdB2C	SignUpSignInPolicyId	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:

Bagian	Tombol	Nilai
informasi masuk	tenantName	Nama penyewa/nama domain Azure AD B2C (misalnya, contoso.onmicrosoft.com).
informasi masuk	clientId	ID aplikasi API web. Pada diagram di atas, ini adalah aplikasi dengan ID Aplikasi: 2. Untuk mempelajari cara mendapatkan ID pendaftaran aplikasi API web Anda, lihat Prasyarat.
informasi masuk	penerbit	Nilai klaim iss penerbit 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	policyName	Alur pengguna, atau kebijakan kustom. Untuk mempelajari cara mendapatkan alur atau kebijakan pengguna Anda, lihat Prasyarat.
sumber daya	cakupan	Cakupan pendaftaran aplikasi API web Anda. Untuk mempelajari cara mendapatkan cakupan API web Anda, lihat Prasyarat.

Langkah 7: Menjalankan dan menguji API web

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

Inti ASP.NET

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

 dotnet run

Anda akan melihat output berikut, yang berarti bahwa aplikasi Anda sudah beroperasi dan siap untuk menerima permintaan.

Now listening on: http://localhost:6000

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

Tip

Alternatifnya, untuk menjalankan perintah dotnet run, Anda dapat menggunakan debugger Visual Studio Code. Debugger bawaan Visual Studio Code membantu mempercepat loop edit, 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 command shell, mulai aplikasi web dengan menjalankan perintah berikut:

node app.js

Anda akan melihat output berikut, yang berarti bahwa aplikasi Anda sudah beroperasi dan siap untuk menerima permintaan.

Example app listening on port 6000!

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

Tip

Atau, untuk menjalankan perintah node app.js, Anda dapat menggunakan debugger Visual Studio Code. Debugger bawaan Visual Studio Code membantu mempercepat loop edit, 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: Menghubungi 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 akan mengembalikan pesan kesalahan HTTP yang tidak sah, yang mengonfirmasikan bahwa API web dilindungi dengan token pembawa.

Terus konfigurasikan aplikasi Anda untuk memanggil API web. Untuk panduan, lihat bagian Prasyarat.

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

Langkah berikutnya

Dapatkan contoh lengkap di GitHub:

Inti ASP.NET

• Dapatkan API web menggunakan pustaka identitas Microsoft.

Node.js

• Dapatkan API web menggunakan pustaka Passport.js.