2.3. Node.js アダプター

Node.js がすでにインストールされている場合は、アプリケーションのディレクトリーを作成します。

mkdir myapp && cd myapp

npm init コマンドを使用して、アプリケーションの package.json を作成します。依存関係リストに Red Hat Single Sign-On の接続アダプターを追加するようになりました。

    "dependencies": {
        "keycloak-connect": "file:keycloak-connect-18.0.7.tgz"
    }

プロジェクトのルートディレクトリーに server.js という名前のファイルを作成し、以下のコードを追加します。

    const session = require('express-session');
    const Keycloak = require('keycloak-connect');

    const memoryStore = new session.MemoryStore();
    const keycloak = new Keycloak({ store: memoryStore });

express-session 依存関係をインストールします。

    npm install express-session

server.js スクリプトを起動するには、package.json の 'scripts' セクションに以下のコマンドを追加します。

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

これで、以下のコマンドでサーバーを実行できるようになりました。

    npm run start

デフォルトでは、これはアプリケーションの主な実行ファイルとともに keycloak.json という名前のファイルを見つけ (ここではルートフォルダー)、keycloak 固有の設定を初期化します (公開鍵、レルム名、さまざまな URL など)。

この場合、Keycloak 管理コンソールにアクセスするために Keycloak デプロイメントが必要です。

使用して Keycloak 管理コンソールをデプロイする方法については、Podman または Docker のリンクを参照してください。

これで、Red Hat Single Sign-On Admin Console clients (左サイドバー) choose your client Installation Format Option Keycloak OIDC JSON Download に移動して keycloak.json ファイルを取得できます。

ダウンロードしたファイルをプロジェクトのルートディレクトリーに貼り付けます。

この方法を使用したインスタンス化により、妥当なデフォルトがすべて使用されます。または、keycloak.json ファイルの代わりに、設定オブジェクトを指定することもできます。

    const kcConfig = {
        clientId: 'myclient',
        bearerOnly: true,
        serverUrl: 'http://localhost:8080/auth',
        realm: 'myrealm',
        realmPublicKey: 'MIIBIjANB...'
    };

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

アプリケーションは、以下を使用して、ユーザーを優先しているアイデンティティープロバイダーにリダイレクトすることもできます。

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

    const session = require('express-session');
    const memoryStore = new session.MemoryStore();

    // Configure session
    app.use(
      session({
        secret: 'mySecret',
        resave: false,
        saveUninitialized: true,
        store: memoryStore,
      })
    );

    const keycloak = new Keycloak({ store: memoryStore });

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

インスタンス化したら、ミドルウェアを接続対応のアプリケーションにインストールします。

これを行うには、まず Express をインストールする必要があります。

    npm install express

次に、以下で説明されているようにプロジェクトに Express が必要になります。

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

また、以下のコードを追加して Express で Keycloak ミドルウェアを設定します。

    app.use( keycloak.middleware() );

最後に、以下のコードを main.js に追加して、3000 ポートで HTTP 要求をリッスンするようにサーバーをセットアップしましょう。

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

SSL 接続を終了するプロキシーの背後でアプリケーション実行されている場合は、express behind proxies ガイドに従って、Express を設定する必要があります。誤ったプロキシー設定を使用すると、無効なリダイレクト URI が生成されることがあります。

設定例:

    const app = express();

    app.set( 'trust proxy', true );

    app.use( keycloak.middleware() );

リソースにアクセスする前にユーザーが認証されていることを確認するには、keycloak.checkSso() を使用します。これは、ユーザーがすでにログインしている場合にのみ認証されます。ユーザーがログインしていない場合、ブラウザーは最初のリクエストされた URL にリダイレクトされ、認証されていないままになります。

    app.get( '/check-sso', keycloak.checkSso(), checkSsoHandler );

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

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

別 のアプリケーションのアプリケーションロールでリソースを保護するには、以下を行います。

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

レルムロールでリソースをセキュアにするには、以下を実行します。

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

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

keycloak-enforcer メソッドは、response_mode 設定オプションの値に応じて 2 つのモードで動作します。

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

response_mode が token に設定されている場合は、アプリケーションに送信されたベアラートークンで表されるサブジェクトの代わりにパーミッションがサーバーから取得されます。この場合、新しいアクセストークンは、サーバーによって付与されたアクセス許可を使用して、Keycloak により発行されます。サーバーが予想されるパーミッションを持つトークンに応答しなかった場合、要求は拒否されます。このモードを使用すると、以下のようにリクエストからトークンを取得できるはずです。

    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;

        // show user profile
    });

アプリケーションがセッションを使用していて、サーバーからの以前の決定をキャッシュし、更新トークンを自動的に処理する場合は、このモードが推奨されます。このモードは、クライアントとリソースサーバーとして動作するアプリケーションに特に便利です。

response_mode が permissions (デフォルトモード) に設定されている場合、サーバーは新しいアクセストークンを発行せずに付与されたパーミッションのリストのみを返します。このメソッドは、新しいトークンを発行しないだけでなく、以下のように リクエスト を介してサーバーに付与されたパーミッションを公開します。

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

        // show user profile
    });

使用中の response_mode に関係なく、keycloak.enforcer メソッドは、アプリケーションに送信されたベアラートークン内のパーミッションを確認します。ベアラートークンで予想される権限がすでに引き継がれている場合は、サーバーと対話して意思決定を取得する必要はありません。これは、クライアントが、保護されたリソースにアクセスする前に予想されるパーミッションでサーバーからアクセストークンを取得できる場合に特に便利です。そのため、増分認可などの Keycloak Authorization Services が提供する機能を使用し、keycloak.enforcer がリソースへのアクセスを強制している場合に、サーバーへの追加のリクエストを回避できます。

デフォルトでは、ポリシーエンフォーサーはアプリケーション (例: keycloak.json) に定義された client_id を使用して、Keycloak Authorization Services をサポートする Keycloak のクライアントを参照します。この場合、クライアントは実際にはリソースサーバーであることをパブリックにすることはできません。

アプリケーションがパブリッククライアント (フロントエンド) とリソースサーバー (バックエンド) の両方として機能している場合は、次の設定を使用して、適用するポリシーで Keycloak 内の別のクライアントを参照できます。

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

フロントエンドおよびバックエンドを表すために、Keycloak で個別のクライアントを使用することが推奨されます。

保護するアプリケーションが Keycloak 認可サービスで有効になり、keycloak.json でクライアント認証情報を定義している場合は、サーバーに追加の要求をプッシュして決定のためにポリシーで利用できるようにすることができます。そのため、プッシュする要求と共に JSON を返す 関数 を想定する claims 設定オプションを定義できます。

      app.get('/protected/resource', keycloak.enforcer(['resource:view', 'resource:write'], {
          claims: function(request) {
            return {
              "http.uri": ["/protected/resource"],
              "user.agent": // get user agent  from request
            }
          }
        }), function (req, res) {
          // access granted

Keycloak を設定してアプリケーションリソースを保護する方法の詳細については、Authorization Services Guide を参照してください。

    function protectBySection(token, request) {
      return token.hasRole( request.params.section );
    }

    app.get( '/:section/:page', keycloak.protect( protectBySection ), sectionHandler );

高度なログイン設定:

デフォルトでは、クライアントがベアラーのみでない限り、認可されていないすべてのリクエストは Red Hat Single Sign-On のログインページにリダイレクトされます。ただし、機密またはパブリッククライアントは、閲覧可能なエンドポイントと API エンドポイントの両方をホストする場合があります。認証されていない API 要求でのリダイレクトを防ぎ、代わりに HTTP 401 を返すようにするには、redirectToLogin 関数をオーバーライドします。

たとえば、このオーバーライドでは URL に /api/ が含まれているかどうかを確認し、ログインリダイレクトを無効にします。

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

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

ユーザーがトリガーするログアウトが呼び出されると、クエリーパラメーター redirect_url を渡すことができます。

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

次に、このパラメーターは OIDC ログアウトエンドポイントのリダイレクト URL として使用され、ユーザーは https://example.com/logged/out にリダイレクトされます。

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

Node.js アダプターの完全な使用例は、Node.js の Keycloak クイックスタート にあります。