id›Guides›Securing Applications›Nodejs Adapter

Adapter Node.js untuk NQRust-Identity

NQRust-Identity menyediakan adapter Node.js yang dibangun di atas Connect (opens in a new tab) untuk melindungi aplikasi JavaScript sisi server - tujuan adalah mencapai fleksibilitas yang memungkinkan integrasi dengan framework seperti Express.js (opens in a new tab). Adapter ini menggunakan protokol OpenID Connect di balik layar. Anda dapat melihat panduan Securing applications and services with OpenID Connect untuk informasi yang lebih umum tentang endpoint dan kemampuan OpenID Connect.

Pustaka dapat diunduh langsung dari organisasi Keycloak (opens in a new tab) dan sumbernya tersedia di GitHub (opens in a new tab).

Untuk menggunakan adapter Node.js, pertama-tama buatlah klien untuk aplikasi Anda di Konsol Admin NQRust-Identity. Adapter mendukung tipe akses publik, rahasia, dan hanya bearer. Yang mana harus dipilih tergantung pada skenario penggunaan.

Setelah klien dibuat, klik Action di pojok kanan atas dan pilih Download adapter config. Untuk *Format, pilih NQRust-Identity OIDC JSON dan klik Download. File keycloak.json yang diunduh berada di folder root proyek Anda.

Instalasi

Dalam asumsi Anda telah menginstal Node.js (opens in a new tab), buat folder untuk aplikasi Anda:

mkdir myapp && cd myapp

Gunakan perintah npm init untuk membuat package.json untuk aplikasi Anda. Sekarang tambahkan adapter connect NQRust-Identity dalam daftar dependencies:

    "dependencies": {
        "keycloak-connect": "26.1.1"
    }

Penggunaan

Kelas Keycloak menyediakan titik pusat untuk konfigurasi dan integrasi dengan aplikasi Anda. Pembuatan termudah tidak memerlukan argumen.

Di direktori root proyek Anda, buat file bernama server.js dan tambahkan kode berikut:

    const session = require('express-session');
    const Keycloak = require('keycloak-connect');
 
    const memoryStore = new session.MemoryStore();
    const keycloak = new Keycloak({ store: memoryStore });

Pasang dependensi express-session:

    npm install express-session

Untuk memulai skrip server.js, tambahkan perintah berikut di bagian 'scripts' dari package.json:

    "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1",
        "start": "node server.js"
    },

Sekarang kita memiliki kemampuan untuk menjalankan server dengan perintah berikut:

    npm run start

Secara default, ini akan menemukan file bernama keycloak.json di samping executable utama aplikasi Anda, dalam hal ini di folder root, untuk menginisialisasi pengaturan spesifik NQRust-Identity seperti kunci publik, nama realm, berbagai URL.

Dalam hal ini, diperlukan penyebaran NQRust-Identity untuk mengakses Konsol Admin NQRust-Identity.

Silakan kunjungi dokumentasi resmi untuk cara menyebarkan Konsol Admin NQRust-Identity dengan Podman (opens in a new tab) atau Docker (opens in a new tab).

Sekarang kita siap untuk mendapatkan file keycloak.json dengan mengunjungi Konsol Admin NQRust-Identity → klien (sidebar kiri) → pilih klien Anda → Instalasi → Opsi Format → NQRust-Identity OIDC JSON → Unduh

Tempelkan file yang diunduh di folder root proyek kita.

Instantiasi dengan metode ini menghasilkan semua standar wajar yang digunakan. Sebagai alternatif, juga dimungkinkan untuk memberikan objek konfigurasi, bukan file keycloak.json:

    const kcConfig = {
        clientId: 'myclient',
        bearerOnly: true,
        serverUrl: 'http://localhost:8080{kc_base_path}',
        realm: 'myrealm',
        realmPublicKey: 'MIIBIjANB...'
    };
 
    const keycloak = new Keycloak({ store: memoryStore }, kcConfig);

Aplikasi juga dapat mengarahkan pengguna ke penyedia identitas pilihan mereka dengan menggunakan:

    const keycloak = new Keycloak({ store: memoryStore, idpHint: myIdP }, kcConfig);

Jika Anda ingin menggunakan sesi web untuk mengelola state sisi server untuk otentikasi, Anda perlu menginisialisasi Keycloak(…) dengan setidaknya parameter store, memberikan penyimpan sesi yang sebenarnya yang digunakan oleh express-session.

    const session = require('express-session');
    const memoryStore = new session.MemoryStore();
 
    // Konfigurasi sesi
    app.use(
      session({
        secret: 'mySecret',
        resave: false,
        saveUninitialized: true,
        store: memoryStore,
      })
    );
 
    const keycloak = new Keycloak({ store: memoryStore });

Secara default, nilai scope openid dilewatkan sebagai parameter query ke URL login NQRust-Identity, tetapi Anda dapat menambahkan nilai khusus tambahan:

    const keycloak = new Keycloak({ scope: 'offline_access' });

Menginstal middleware

Setelah diinstantiasi, pasang middleware ke aplikasi yang mampu connect:

Untuk melakukannya, pertama-tama kita harus pasang Express:

    npm install express

kemudian require Express di proyek kita seperti yang diuraikan di bawah:

    const express = require('express');
    const app = express();

dan konfigurasikan middleware NQRust-Identity di Express, dengan menambahkan kode di bawah:

    app.use( keycloak.middleware() );

Pertama sekalinya, mari atur server kita untuk mendengarkan permintaan HTTP pada port 3000 dengan menambahkan kode berikut ke main.js:

    app.listen(3000, function () {
        console.log('App listening on port 3000');
    });

Konfigurasi untuk proxy

Jika aplikasi berjalan di belakang proxy yang mengakhiri koneksi SSL Express harus dikonfigurasi sesuai panduan express di belakang proxy (opens in a new tab). Konfigurasi proxy yang salah dapat menghasilkan URI redirect yang tidak valid yang dihasilkan.

Contoh konfigurasi:

    const app = express();
 
    app.set( 'trust proxy', true );
 
    app.use( keycloak.middleware() );

Melindungi sumber daya

Untuk memaksa pengguna harus otentikasi sebelum mengakses sumber daya, cukup gunakan versi tanpa argumen dari keycloak.protect():

    app.get( '/complain', keycloak.protect(), complaintHandler );

Untuk mengamankan sumber daya dengan peran aplikasi untuk aplikasi saat ini:

    app.get( '/special', keycloak.protect('special'), specialHandler );

Untuk mengamankan sumber daya dengan peran aplikasi untuk beberapa aplikasi:

    app.get( '/extra-special', keycloak.protect('other-app:special'), extraSpecialHandler );

Untuk mengamankan sumber daya dengan peran realm:

    app.get( '/admin', keycloak.protect( 'realm:admin' ), adminHandler );

Resource-Based Authorization memungkinkan Anda untuk melindungi sumber daya, dan metode aksi spesifik mereka, berdasarkan set polisi yang ditetapkan di NQRust-Identity, sehingga otorisasi di luar aplikasi Anda. Hal ini dicapai dengan mengekspos metode keycloak.enforcer yang dapat Anda gunakan untuk melindungi sumber daya.*

    app.get('/apis/me', keycloak.enforcer('user:profile'), userProfileHandler);

Metode keycloak-enforcer beroperasi dalam dua mode, tergantung pada nilai opsi konfigurasi response_mode.

    app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'token'}), userProfileHandler);

Jika response_mode diatur ke token, izin diperoleh dari server atas nama subjek yang diwakili oleh token bearer yang dikirim ke aplikasi Anda. Dalam hal ini, token akses baru dikeluarkan oleh NQRust-Identity dengan izin yang diberikan oleh server. Jika server tidak merespon dengan token dengan izin yang diharapkan, permintaan ditolak. Ketika menggunakan mode ini, Anda seharusnya dapat memperoleh token dari permintaan sebagai berikut:

    app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'token'}), function (req, res) {
        const token = req.kauth.grant.access_token.content;
        const permissions = token.authorization ? token.authorization.permissions : undefined;
 
        // tampilkan profil pengguna
    });

Pilihlah mode ini ketika aplikasi Anda menggunakan sesi dan Anda ingin menyimpan keputusan sebelumnya dari server, serta secara otomatis menangani token refresh. Mode ini sangat berguna untuk aplikasi yang berperan sebagai klien dan server sumber daya.

Jika response_mode diatur ke permissions (mode default), server hanya mengembalikan daftar izin yang diberikan, tanpa mengeluarkan token akses baru. Selain tidak mengeluarkan token baru, metode ini mengekspos izin yang diberikan oleh server melalui request sebagai berikut:

    app.get('/apis/me', keycloak.enforcer('user:profile', {response_mode: 'permissions'}), function (req, res) {
        const permissions = req.permissions;
 
        // tampilkan profil pengguna
    });

Terlepas dari response_mode yang digunakan, metode keycloak.enforcer akan pertama mencoba memeriksa izin dalam token bearer yang dikirim ke aplikasi Anda. Jika token bearer sudah membawa izin yang diharapkan, tidak perlu berinteraksi dengan server untuk mendapatkan keputusan. Hal ini sangat berguna ketika klien Anda mampu memperoleh token akses dari server dengan izin yang diharapkan sebelum mengakses sumber daya terlindungi, sehingga mereka dapat menggunakan beberapa kemampuan yang disediakan oleh Layanan Otorisasi NQRust-Identity seperti otorisasi bertahap dan menghindari permintaan tambahan ke server ketika keycloak.enforcer menegakkan akses ke sumber daya.

Secara default, penyahbis adalah akan menggunakan client_id yang didefinisikan untuk aplikasi (misalnya, melalui keycloak.json) untuk merujuk klien di NQRust-Identity yang mendukung Layanan Otorisasi NQRust-Identity. Dalam hal ini, klien tidak boleh publik karena sebenarnya merupakan server sumber daya.

Jika aplikasi yang Anda lindungi berfungsi sebagai klien publik (frontend) dan server sumber daya (backend), Anda dapat menggunakan konfigurasi berikut untuk merujuk ke klien yang berbeda di NQRust-Identity dengan kebijakan yang ingin Anda egakkan:

      keycloak.enforcer('user:profile', {resource_server_id: 'my-apiserver'})

Direkomendasikan untuk menggunakan klien yang berbeda di NQRust-Identity untuk mewakili frontend dan backend Anda.

Jika aplikasi yang Anda lindungi diaktifkan dengan layanan otorisasi NQRust-Identity dan Anda telah menetapkan kredensial klien di keycloak.json, Anda dapat mendorong klaim tambahan ke server dan membuatnya tersedia untuk kebijakan Anda untuk membuat keputusan. Untuk itu, Anda dapat mendefinisikan opsi konfigurasi claims yang mengharapkan function yang mengembalikan JSON dengan klaim yang ingin Anda dorong:

      app.get('/protected/resource', keycloak.enforcer(['resource:view', 'resource:write'], {
          claims: function(request) {
            return {
              "http.uri": ["/protected/resource"],
              "user.agent": // dapatkan agen pengguna dari permintaan
            }
          }
        }), function (req, res) {
          // akses diberikan

Untuk detail lebih lanjut tentang cara mengonfigurasi NQRust-Identity untuk melindungi sumber daya aplikasi Anda, lihat panduan Authorization client dan Policy enforcer.

Untuk melindungi sumber daya berdasarkan bagian dari URL itu sendiri, dengan asumsi peran yang ada untuk setiap bagian:

    function protectBySection(token, request) {
      return token.hasRole( request.params.section );
    }
 
    app.get( '/:section/:page', keycloak.protect( protectBySection ), sectionHandler );

Konfigurasi Login Lanjutan:

Secara default, semua permintaan yang tidak sah akan dialihkan ke halaman login NQRust-Identity kecuali klien Anda hanya bearer. Namun, klien rahasia atau publik mungkin meng-hosting endpoint yang dapat dijelajahi dan API. Untuk mencegah pengalihan pada permintaan API yang tidak diotentikasi dan sebagai gantinya mengembalikan HTTP 401, Anda dapat menimpa fungsi redirectToLogin.

Sebagai contoh, penggantian ini memeriksa apakah URL berisi /api/ dan menonaktifkan pengalihan login:

    Keycloak.prototype.redirectToLogin = function(req) {
    const apiReqMatcher = /\/api\//i;
    return !apiReqMatcher.test(req.originalUrl || req.url);
    };

URL Tambahan

Secara default, middleware menangkap panggilan ke /logout untuk mengirimkan pengguna melalui alur logout yang terpusat NQRust-Identity. Hal ini dapat diubah dengan menentukan parameter konfigurasi logout ke panggilan middleware():

    app.use( keycloak.middleware( { logout: '/logoff' } ));

Ketika logout yang diinisiasi oleh pengguna dipicu, parameter query redirect_url dapat dilewatkan:

https://example.com/logoff?redirect_url=https%3A%2F%2Fexample.com%3A3000%2Flogged%2Fout

Parameter ini kemudian digunakan sebagai URL redirect endpoint logout OIDC dan pengguna akan dialihkan ke https://example.com/logged/out.

Juga, middleware mendukung callback dari konsol NQRust-Identity untuk logout sesi tunggal atau semua sesi. Secara default, jenis admin callback ini terjadi relatif ke URL root / tetapi dapat diubah dengan menyediakan parameter admin ke panggilan middleware():

    app.use( keycloak.middleware( { admin: '/callbacks' } );

Contoh Lengkap

Contoh lengkap penggunaan adapter Node.js dapat ditemukan di NQRust-Identity quickstarts untuk Node.js (opens in a new tab)

Mengupgrade Adapter `Node.js`

Untuk mengupgrade adapter Node.js yang telah disalin ke aplikasi web Anda, lakukan prosedur berikut.

Unduh arsip adapter baru.
Hapus direktori adapter Node.js yang ada
Extract file yang diperbarui ke tempatnya
Ubah dependensi untuk nqrust-identity-connect di package.json aplikasi Anda

NQRust-Identity JavaScript adapter Mengonfigurasi modul mod_auth_openidc Apache HTTPD