アプリケーションおよびサービスの保護ガイド

理解すべき最も重要なエンドポイントは、well-known 設定エンドポイントです。Red Hat build of Keycloak の OpenID Connect 実装に関連するエンドポイントおよびその他の設定オプションをリスト表示します。エンドポイントは次のとおりです。

/realms/{realm-name}/.well-known/openid-configuration

完全な URL を取得するには、Red Hat build of Keycloak のベース URL を追加し、{realm-name} をレルムの名前に置き換えます。以下に例を示します。

http://localhost:8080/realms/master/.well-known/openid-configuration

一部の RP ライブラリーは、このエンドポイントから必要なすべてのエンドポイントを取得しますが、その他のライブラリーでは、エンドポイントを個別にリスト表示しないといけない場合があります。

/realms/{realm-name}/protocol/openid-connect/auth

/realms/{realm-name}/protocol/openid-connect/token

/realms/{realm-name}/protocol/openid-connect/userinfo

/realms/{realm-name}/protocol/openid-connect/logout

/realms/{realm-name}/protocol/openid-connect/certs

/realms/{realm-name}/protocol/openid-connect/token/introspect

/realms/{realm-name}/clients-registrations/openid-connect

/realms/{realm-name}/protocol/openid-connect/revoke

/realms/{realm-name}/protocol/openid-connect/auth/device

/realms/{realm-name}/protocol/openid-connect/ext/ciba/auth

認可コードフローは、ユーザーエージェントを Red Hat build of Keycloak にリダイレクトします。Red Hat build of Keycloak でユーザーが正常に認証されると、認可コードが作成され、ユーザーエージェントはアプリケーションにリダイレクトされます。その後、アプリケーションは認証情報と共に認可コードを使用して、Red Hat build of Keycloak からアクセストークン、更新トークン、および ID トークンを取得します。

フローは Web アプリケーションにターゲットとして設定されていますが、ユーザーエージェントを組み込むことができるモバイルアプリケーションなど、ネイティブアプリケーションに推奨されます。

詳細は、OpenID Connect 仕様の Authorization Code Flow を参照してください。

暗黙的フローは認可コードフローと同じような機能ですが、アクセストークンおよび ID トークンが返される認可コードを返す代わりに、このフローが返されます。このアプローチにより、追加の呼び出しでアクセストークンの認可コードを交換する必要がなくなります。ただし、更新トークンは含まれません。そのため、有効期限の長いアクセストークンを許可する必要があります。しかし、これらのトークンを無効にするのは非常に難しいため、このアプローチは現実的ではありません。あるいは、最初のアクセストークンの有効期限が切れた後、新しいアクセストークンを取得するために新しいリダイレクトを要求できます。暗黙的フローは、アプリケーションがユーザーを認証し、ログアウト自体を処理する場合に便利です。

代わりに、アクセストークンと認可コードの両方が返されるハイブリッドフローを使用できます。

注意すべき点は、アクセストークンが Web サーバーのログやブラウザーの履歴から漏洩する可能性があるため、暗黙的なフローとハイブリッドフローの両方に潜在的なセキュリティーリスクがあることです。アクセストークンの有効期限を短くすることで、この問題をある程度軽減できます。

詳細は、OpenID Connect 仕様の 暗黙的フロー を参照してください。

Red Hat build of Keycloak では Direct Grant と呼ばれるリソース所有者のパスワード認証情報を使用すると、ユーザー認証情報をトークンと交換できます。必須でない限り、このフローの使用は推奨できません。このフローは、従来のアプリケーションおよびコマンドラインインターフェイスなどで役に立ちます。

このフローの使用には次のような制限があります。

クライアントでリソースオーナーパスワード認証情報の使用を許可するには、クライアントの Direct Access Grants Enabled オプションを有効にする必要があります。

このフローは OpenID Connect に含まれず、OAuth 2.0 仕様の一部です。

詳細は、OAuth 2.0 仕様の リソースオーナーパスワード認証情報の付与 の章を参照してください。

curl \
  -d "client_id=myclient" \
  -d "client_secret=40cc097b-2a57-4c17-b36a-8fdf3fc2d578" \
  -d "username=user" \
  -d "password=password" \
  -d "grant_type=password" \
  "http://localhost:8080/realms/master/protocol/openid-connect/token"

クライアント認証情報は、クライアント (アプリケーションおよびサービス) がユーザーの代わりにではなく、自身の代わりにアクセスを取得する場合に使用されます。たとえば、これらの認証情報は、特定のユーザーではなく、一般的なシステムに変更を適用するバックグラウンドサービスなどに役立ちます。

Red Hat build of Keycloak は、クライアントがシークレットまたは公開鍵/秘密鍵のいずれかを使用して認証するためのサポートを提供します。

このフローは OpenID Connect に含まれず、OAuth 2.0 仕様の一部です。

詳細は、OAuth 2.0 仕様の クライアント認証情報の付与 の章を参照してください。

デバイス認可グラントは、入力機能が制限されているか、適切なブラウザーがないインターネット接続デバイスで実行されているクライアントによって使用されます。アプリケーションは、Red Hat build of Keycloak にデバイスコードとユーザーコードを要求します。Red Hat build of Keycloak は、デバイスコードとユーザーコードを作成します。Red Hat build of Keycloak は、デバイスコードおよびユーザーコードなどの応答をアプリケーションに返します。アプリケーションはユーザーにユーザーコードと検証 URI を提供します。ユーザーは検証 URI にアクセスし、別のブラウザーを使用して認証されます。Red Hat build of Keycloak がユーザー認可を完了するまで、アプリケーションは繰り返し Red Hat build of Keycloak をポーリングします。ユーザー認証が完了すると、アプリケーションはデバイスコードを取得します。アプリケーションは認証情報と共にデバイスコードを使用して、Red Hat build of Keycloak からアクセストークン、更新トークン、および ID トークンを取得します。

詳細は、OAuth 2.0 デバイス認可グラントの仕様 参照してください。

Client Initiated Backchannel Authentication Grant は、OAuth 2.0 の認可コードグラントのように、ユーザーのブラウザーを介してリダイレクトせずに、OpenID プロバイダーと直接通信することで認可フローを開始するクライアントによって使用されます。

クライアントは、クライアントによる認証要求を識別する auth_req_id を Red Hat build of Keycloak に要求します。Red Hat build of Keycloakは auth_req_id を作成します。

クライアントは、auth_req_id を受信したてからユーザーが認証されるまで、Red Hat build of Keycloak からアクセストークン、更新トークン、および ID トークンを取得するために、auth_req_id と引き換えに Red Hat build of Keycloak を繰り返しポーリングする必要があります。

クライアントが ping モードを使用する場合は、トークンエンドポイントを繰り返しポーリングする必要はありませんが、Red Hat build of Keycloak から指定されたクライアント通知エンドポイントに送信される通知を待つことができます。クライアント通知エンドポイントは、Red Hat build of Keycloak 管理コンソールで設定できます。クライアント通知エンドポイントのコントラクトの詳細は、CIBA 仕様を参照してください。

詳細は、OpenID Connect クライアントが開始したバックチャンネル認証フローの仕様 を参照してください。

また、このガイドの バックチャンネル認証エンドポイント やサーバー管理ガイドの クライアントが開始したバックチャンネル認証グラント セクションなど、Red Hat build of Keycloak ドキュメントの別の箇所も参照してください。FAPI CIBA 準拠の詳細は、このガイドの FAPI セクション を参照してください。

Red Hat build of Keycloak には、Red Hat JBoss Enterprise Application Platform のアダプターは含まれていません。ただし、Red Hat JBoss Enterprise Application Platform にデプロイされた既存アプリケーションの代替があります。

Red Hat build of Keycloak には、Spring Boot 用のアダプターは含まれていません。ただし、Spring Boot でビルドされた既存アプリケーションの代替があります。

Spring Security は、OAuth 2 と OpenID Connect の包括的なサポートを提供します。詳細は、Spring Security のドキュメント を参照してください。

Spring Boot 2.x の場合は、Red Hat Single Sign-On 7.6 の Spring Boot アダプターを Red Hat build of Keycloak サーバーと組み合わせて使用することもできます。詳細は、Red Hat Single Sign-On のドキュメント を参照してください。

アダプターはいくつかの方法で配布されますが、NPM から keycloak-js パッケージをインストールすることが推奨されます。

npm install keycloak-js

ライブラリーは、/js/keycloak.js にある Red Hat build of Keycloak サーバーから直接取得することも可能で、さらに ZIP アーカイブとしても配布されます。ただし、Keycloak サーバーから直接アダプターを組み込む方法は非推奨化が検討されており、今後この機能は来削除される可能性があります。

クライアント側のアプリケーションの使用に関しては、クライアントの認証情報をクライアント側のアプリケーションに保存する安全な方法がないため、クライアントはパブリッククライアントでなければならない点を考慮する必要があります。これにより、クライアント用に設定したリダイレクト URI が正しく、可能な限り具体的であることを確認することが非常に重要になります。

アダプターを使用するには、Red Hat build of Keycloak 管理コンソールででアプリケーションのクライアントを作成します。Capability config ページで Client authentication を Off に切り替えて、クライアントを公開します。

また、Valid Redirect URI と Web Origins を設定する必要があります。そうしないと、セキュリティーの脆弱性が生じる可能性があるため、できるだけ具体的にしてください。

次の例は、アダプターを初期化する方法を示しています。Keycloak コンストラクターに渡されるオプションは、必ず設定したクライアントのオプションに置き換えてください。

import Keycloak from 'keycloak-js';

const keycloak = new Keycloak({
    url: 'http://keycloak-server${kc_base_path}',
    realm: 'myrealm',
    clientId: 'myapp'
});

try {
    const authenticated = await keycloak.init();
    console.log(`User is ${authenticated ? 'authenticated' : 'not authenticated'}`);
} catch (error) {
    console.error('Failed to initialize adapter:', error);
}

認証するには、login 関数を呼び出します。アダプターを自動的に認証する場合、2 つのオプションがあります。、login-required または check-sso を init() 関数に渡せます。

silent check-sso オプションを設定できます。この機能を有効にすると、ブラウザーは Red Hat build of Keycloak サーバーの完全なリダイレクトを実行せず、アプリケーションには戻りません。しかし、このこのアクションは非表示の iframe で実行されます。したがって、ブラウザーはアプリケーションの初期化時に一度だけアプリケーションリソースをロードして解析し、Red Hat build of Keycloak からアプリケーションにリダイレクトされた後にこれを再び実行することはありません。このアプローチは、SPA (Single Page Applications) の場合に特に役立ちます。

silent check-sso を有効にするには、init メソッドで silentCheckSsoRedirectUri 属性を指定します。この URI が、アプリケーション内の有効なエンドポイントであることを確認してください。Red Hat build of Keycloak 管理コンソールの有効なリダイレクトとして設定する必要があります。

keycloak.init({
    onLoad: 'check-sso',
    silentCheckSsoRedirectUri: `${location.origin}/silent-check-sso.html`
});

認証の状態が正常にチェックされ、Red Hat build of Keycloak サーバーからトークンを取得すると、サイレント check-sso リダイレクト URI のページが iframe に読み込まれます。受信したトークンをメインアプリケーションに送信する以外のタスクはなく、次のようになります。

<!doctype html>
<html>
<body>
    <script>
        parent.postMessage(location.href, location.origin);
    </script>
</body>
</html>

このページは、アダプターの 一部ではなく、silentCheckSsoRedirectUri の指定された場所にあるアプリケーションによって提供される必要がある点に注意してください。

login-required を有効にするには、onLoad を login-required に設定し、init メソッドに渡します。

keycloak.init({
    onLoad: 'login-required'
});

ユーザーが認証された後、Authorization ヘッダーにベアラートークンを含めることで、アプリケーションは Red Hat build of Keycloak で保護された RESTful サービスへのリクエストを実行できます。以下に例を示します。

async function fetchUsers() {
    const response = await fetch('/api/users', {
        headers: {
            accept: 'application/json',
            authorization: `Bearer ${keycloak.token}`
        }
    });

    return response.json();
}

注意すべきことの 1 つは、アクセストークンの有効期限はデフォルトで短いため、リクエストを送信する前にアクセストークンの更新が必要になることが場合があることです。このトークンを更新するには、updateToken() メソッドを呼び出します。このメソッドは、トークンが正常に更新された場合にのみサービスを呼び出し、そうでない場合にはユーザーにエラーを表示することを容易にする Promise を返します。以下に例を示します。

try {
    await keycloak.updateToken(30);
} catch (error) {
    console.error('Failed to refresh token:', error);
}

const users = await fetchUsers();

デフォルトでは、アダプターは、Single-Sign Out が発生したかどうかを検出するために使用される非表示の iframe を作成します。この iframe はネットワークトラフィックを必要としません。代わりに、ステータスは特別なステータス Cookie を参照して取得されます。init() メソッドに渡されるオプションで checkLoginIframe: false を設定すると、この機能を無効化できます。

このクッキーを直接参照する必要はありません。その形式は変更される可能性があり、アプリケーションではなく Red Hat build of Keycloak サーバーの URL にも関連付けられます。

デフォルトでは、アダプターは 認可コード フローを使用します。

このフローでは、Red Hat build of Keycloak は、認証トークンではなく認可コードをアプリケーションに返します。JavaScript アダプターは、ブラウザーがアプリケーションにリダイレクトされた後に、アクセストークンと更新トークンの コード を交換します。

Red Hat build of Keycloak は、Red Hat build of Keycloak で認証が成功した直後にアクセストークンが送信される Implicit フローもサポートしています。このフローは、コードをトークンと交換する追加のリクエストがないため、標準フローよりもパフォーマンスが向上する可能性がありますが、アクセストークンの有効期限が切れると影響があります。

ただし、URL フラグメントでアクセストークンを送信すると、セキュリティー脆弱性が発生する可能性があります。たとえば、トークンは Web サーバーログやブラウザー履歴によってリークされる可能性があります。

暗黙的フローを有効にするには、Red Hat build of Keycloak 管理コンソールで、クライアントの Implicit Flow Enabled フラグを有効にします。また、パラメーター flow を implicit の値とともに init メソッドに渡します。

keycloak.init({
    flow: 'implicit'
})

アクセストークンのみが提供され、更新トークンは存在しないことに注意してください。この状況は、アクセストークンの有効期限が切れると、アプリケーションは Red Hat build of Keycloak に再度リダイレクトして、新しいアクセストークンを取得する必要があることを意味します。

Red Hat build of Keycloak は、Hybrid フローもサポートしています。

このフローでは、クライアントは管理コンソールで 標準フロー と 暗黙的フロー の両方を有効にする必要があります。Red Hat build of Keycloak サーバーは、コードとトークンの両方をアプリケーションに送信します。アクセストークンは、コードのアクセスと更新トークンを交換して、すぐに使用できます。暗黙的なフローと同様に、アクセストークンがすぐに利用できるため、ハイブリッドフローはパフォーマンスに適しています。ただし、トークンは URL で依然として送信され、前述のセキュリティーの脆弱性は引き続き適用されます。

Hybrid フローの利点の 1 つは、更新トークンがアプリケーションで利用できることです。

ハイブリッドフローの場合は、パラメーター flow の値 hybrid を init メソッドに渡す必要があります。

keycloak.init({
    flow: 'hybrid'
});

Red Hat build of Keycloak は、Apache Cordova で開発されたハイブリッドモバイルアプリをサポートします。アダプターには、cordova と cordova-native という 2 つのモードがあります。

デフォルトは cordova で、アダプタータイプが明示的に設定されておらず、window.cordova が存在する場合、アダプターは自動的にこれを選択します。ログインすると、InApp Browser が開き、ユーザーは Red Hat build of Keycloak と対話できるようになります。その後 http://localhost にリダイレクトしてアプリに戻ります。この動作のために、管理コンソールのクライアント設定セクションで、この URL を有効な redirect-uri としてホワイトリスト化します。

このモードの設定は簡単ですが、いくつかの欠点もあります。

この例のアプリ (https://github.com/keycloak/keycloak/tree/master/examples/cordova) で初めてみましょう。

代替モードは、異なるアプローチをする `cordova-native` です。システムのブラウザーを使用してログインページが開きます。ユーザーが認証されると、ブラウザーは特別な URL を使用してアプリケーションにリダイレクトします。そこから、Red Hat build of Keycloak アダプターは、URL からコードまたはトークンを読み取り、ログインを終了できます。

init() メソッドにアダプター型の cordova-native を渡すことで、ネイティブモードを有効できます。

keycloak.init({
    adapter: 'cordova-native'
});

このアダプターには 2 つの追加プラグインが必要です。

アプリへのリンクの技術情報は、各プラットフォームや特別な設定によって異なります。詳細は、deeplinks プラグインのドキュメント の Android と iOS のセクションを参照してください。

アプリを開くためのリンクにはさまざまな種類があります: * myapp://login または android-app://com.example.myapp/https/example.com/login などのカスタムスキーム * Universal Links (iOS))/Deep Links (Android)。前者はセットアップが簡単で信頼性が高い傾向がありますが、後者は一意であり、ドメインの所有者のみが登録できるため、セキュリティーが強化されます。カスタム URL は iOS で非推奨になりました。最高の信頼性を得るためには、ユニバーサルリンクをカスタム URL リンクを仕様するフォールバックサイトと組み合わせて使用することが推奨されます。

さらに、アダプターとの互換性を改善するには、以下の手順が推奨されます。

<preference name="AndroidLaunchMode" value="singleTask" />

ネイティブモードの使い方を示すアプリの例 (https://github.com/keycloak/keycloak/tree/master/examples/cordova-native) があります。

状況によっては、Capacitor など、デフォルトでサポートされていない環境でアダプターを実行する必要がある場合があります。これらの環境で JavaScript クライアントを使用するには、カスタムアダプターを渡すことができます。たとえば、サードパーティーのライブラリーは、確実に実行できるようにするためのアダプターを提供できます。

import Keycloak from 'keycloak-js';
import KeycloakCapacitorAdapter from 'keycloak-capacitor-adapter';

const keycloak = new Keycloak();

keycloak.init({
    adapter: KeycloakCapacitorAdapter,
});

この特定のパッケージは存在しませんが、そのようなアダプターをクライアントに渡す方法に関する適切な例を示すことができます。

独自のアダプターを作成することもできます。そのためには、KeycloakAdapter インターフェイスで説明されているメソッドを実装する必要があります。たとえば、以下の TypeScript コードは、すべてのメソッドが適切に実装されていることを確認します。

import Keycloak, { KeycloakAdapter } from 'keycloak-js';

// Implement the 'KeycloakAdapter' interface so that all required methods are guaranteed to be present.
const MyCustomAdapter: KeycloakAdapter = {
    login(options) {
        // Write your own implementation here.
    }

    // The other methods go here...
};

const keycloak = new Keycloak();

keycloak.init({
    adapter: MyCustomAdapter,
});

タイプ情報を省略することで TypeScript を使用せずにこれを実行することもできますが、インターフェイスを確実に適切に実装することは、完全にユーザー次第となります。

一部のブラウザーの最新版では、Chrome の SameSite や完全にブロックされたサードパーティーの cookie など、サードパーティーによるユーザーの追跡を防ぐためにさまざまな cookie ポリシーが適用されています。これらのポリシーは、時間の経過とともにさらに制限が厳しくなり、他のブラウザーでも採用される可能性があります。最終的には、サードパーティーコンテキストの Cookie が完全にサポートされなくなり、ブラウザーによってブロックされる可能性があります。その結果、影響を受けるアダプター機能が、最終的に非推奨になる可能性があります。

アダプターは、セッションステータスの iframe、サイレント check-sso、および部分的に通常の (非サイレント) check-sso についても、サードパーティーの cookie に依存しています。これらの機能は、機能が制限されているか、ブラウザーが cookie に関してどのように制限されているかに基づいて完全に無効になっています。アダプターはこの設定を検出しようとし、それに応じて反応します。

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

mkdir myapp && cd myapp

npm init コマンドを使用して、アプリケーションの package.json を作成します。次に、依存関係リストに Red Hat build of Keycloak 接続アダプターを追加します。

    "dependencies": {
        "keycloak-connect": "file:keycloak-connect-22.0.11+redhat-00001.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 という名前のファイルを見つけ (ここではルートフォルダー)、Red Hat build of Keycloak 固有の設定を初期化します (公開鍵、レルム名、さまざまな URL など)。

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

Podman または Docker を使用して Red Hat build of Keycloak 管理コンソールをデプロイする方法の詳細は、それぞれのリンクを参照してください。

これで、Red Hat build of Keycloak 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',
        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() );

    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 を設定してアプリケーションリソースを保護する方法の詳細は、認証サービスガイド を参照してください。

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

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

高度なログイン設定:

デフォルトでは、クライアントがベアラーのみでない限り、承認されていないすべてのリクエストは Red Hat build of Keycloak のログインページにリダイレクトされます。ただし、機密またはパブリッククライアントは、閲覧可能なエンドポイントと 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 アダプターの完全な使用例は、Keycloak quickstarts for Node.js にあります。

クライアントが FAPI に準拠することを確認するには、サーバー管理ガイド の説明に従って、レルムにクライアントポリシーを設定し、そのポリシーを各レルムで自動的に利用できる FAPI サポートのグローバルクライアントプロファイルにリンクします。クライアントが準拠する必要のある FAPI プロファイルに基づいて、fapi-1-baseline または fapi-1-advanced プロファイルのいずれかを使用できます。

Pushed Authorization Request (PAR) を使用する場合は、クライアントが fapi-1-baseline プロファイルおよび fapi-1-advanced の両方を PAR 要求に使用することが推奨されます。具体的には、fapi-1-baseline プロファイルには、pkce-enforcer エグゼキューターが含まれています。これにより、クライアントはセキュリティーで保護された S256 アルゴリズムで PKCE を確実に使用します。これは、PAR 要求を使用しない限り、FAPI Advanced クライアントには必須ではありません。

FAPI に準拠する方法で CIBA を使用する場合は、クライアントが fapi-1-advanced および fapi-ciba クライアントプロファイルの両方を使用していることを確認してください。fapi-ciba プロファイルには CIBA 固有のエクゼキューターのみが含まれるため、fapi-1-advanced プロファイル、または要求されたエクゼキューターを含む他のクライアントプロファイルを使用する必要があります。FAPI CIBA 仕様の要件を実施する場合は、機密クライアントまたは証明書をバインドしたアクセストークンの適用など、より多くの要件が必要になります。

Red Hat build of Keycloak は、Open Finance Brasil Financial-grade API Security Profile 1.0 Implementers Draft 3 に準拠しています。これは、一部の要件では FAPI 1 Advanced 仕様よりも厳格であるため、一部の要件を適用するには、より厳格な方法で クライアントポリシー を設定する必要がある場合があります。以下の場合は、特にその必要があります。

機密情報が交換されるため、すべての対話は TLS (HTTPS) で暗号化される必要があります。さらに、使用される暗号スイートおよび TLS プロトコルバージョンの FAPI 仕様にはいくつかの要件があります。これらの要件に合致するには、許可された暗号を設定することを検討してください。これは、https-protocols および https-cipher-suites オプションで設定できます。Red Hat build of Keycloak はデフォルトで TLSv1.3 を使用し、このデフォルト設定は変更する必要がないこともあります。ただし、何らかの理由で下位の TLS バージョンにフォールバックする必要がある場合は、暗号化を調整する必要がある場合があります。詳細は、TLS の設定 の章を参照してください。

Red Hat build of Keycloak が発行したアクセストークンを手動で検証する必要がある場合は、イントロスペクションエンドポイント を呼び出せます。このアプローチの欠点は、Red Hat build of Keycloak サーバーに対してネットワーク呼び出しを行う必要があることです。同時に実行される検証要求が多すぎると、これは遅くなり、サーバーが過負荷になる可能性があります。Red Hat build of Keycloak が発行したアクセストークンは、JSON Web Signature (JWS) を使用してデジタル署名およびエンコードされた JSON Web Tokens (JWT) です。この方法でエンコードされるため、発行したレルムの公開鍵を使用してアクセストークンをローカルで検証できます。レルムの公開鍵を検証コードでハードコードするか、JWS 内に埋め込まれたキー ID (KID) で 証明書エンドポイント を使用して公開鍵を検索してキャッシュします。コーディングする言語に応じて、多くのサードパーティーライブラリーが存在し、JWS の検証に使用できます。

リダイレクトベースのフローを使用する場合は、必ずクライアントに有効なリダイレクト URI を使用してください。リダイレクト URI は可能な限り具体的にする必要があります。これは特に、クライアント側の (パブリッククライアント) アプリケーションに適用されます。これを行わないと、以下が発生する可能性があります。

Web アプリケーションで実稼働環境では常にすべてのリダイレクト URI に https を使用します。http へのリダイレクトを許可しないでください。

いくつかの特別なリダイレクト URI もあります。

ベアラートークンは、ユーザーまたは Service Account の代わりに発行できます。エンドポイントを呼び出すには、以下のパーミッションが必要です (詳細は サーバー管理ガイド を参照)。

ベアラートークンを使用してクライアントを作成する場合は、create-client ロールのみのサービスアカウントからトークンを使用することが推奨されます (詳細は サーバー管理ガイド を参照)。

新しいクライアントを登録するための推奨されるアプローチは、初期アクセストークンを使用することです。初期アクセストークンは、クライアントの作成にのみ使用でき、有効期限を設定できるほか、作成できるクライアントの数に制限を設定できます。

初期アクセストークンは管理コンソールを使用して作成できます。新しい初期アクセストークンを作成するには、最初に管理コンソールでレルムを選択し、左側のメニューで Client をクリックし、ページに表示されるタブの Initial access token をクリックします。

これで、既存の初期アクセストークンを確認できるようになります。アクセスがあれば、不要になったトークンを削除できます。トークンの作成時にのみ、トークンの値を取得できます。新規トークンを作成するには、Create をクリックします。オプションで、トークンの有効期間を追加できるようになりました。また、トークンを使用して作成できるクライアントの数も追加できます。Save をクリックすると、トークンの値が表示されます。

このトークンは後で取得できないため、今すぐこのトークンをコピーして貼り付けることが重要です。コピー/貼り付けを忘れた場合は、このトークンを削除して別のトークンを作成してください。

トークン値は、クライアント登録サービスを呼び出すときに、リクエストの Authorization ヘッダーに追加することにより、標準のベアラートークンとして使用されます。以下に例を示します。

Authorization: bearer eyJhbGciOiJSUz...

クライアント登録サービス経由でクライアントを作成する場合、応答には登録アクセストークンが含まれます。登録アクセストークンは、後でクライアント設定を取得するアクセスを提供しますが、クライアントを更新または削除するためのアクセスも提供します。登録アクセストークンは、ベアラートークンまたは初期アクセストークンと同じ方法でリクエストに含まれます。

デフォルトでは、登録アクセストークンのローテーションは有効になっています。これは、登録アクセストークンが 1 回だけ有効であることを意味します。トークンが使用されると、レスポンスには新しいトークンが含まれます。登録アクセストークンのローテーションは、クライアントポリシー を使用して無効化できます。

クライアント登録サービスの外部でクライアントが作成された場合、それに関連付けられた登録アクセストークンはありません。管理コンソールから作成できます。これは、特定のクライアントのトークンを失った場合にも便利です。新しいトークンを作成するには、管理コンソールでクライアントを見つけ、Credentials をクリックします。次に、Generate registration access token をクリックします。

ログイン方法に関係なく、ログインするアカウントには、クライアント登録操作を実行するための適切な権限が必要です。マスター以外のレルムのアカウントには、同じレルム内のクライアントを管理するためのパーミッションのみを持つことができる点に注意してください。異なるレルムを管理する必要がある場合は、異なるレルムで複数のユーザーを設定するか、master レルムで 1 つのユーザーを作成し、異なるレルムでクライアントを管理するロールを追加できます。

クライアント登録 CLI を使用してユーザーを設定することはできません。管理コンソールの Web インターフェイスまたは Admin Client CLI を使用してユーザーを設定します。詳細は、サーバー管理ガイド を参照してください。

kcreg が 正常にログインすると、認可トークンを受け取り、プライベート設定ファイルに保存します。これにより、後続の呼び出しにトークンを使用できます。設定ファイルの詳細については、「代替設定の使用」 を参照してください。

クライアント登録 CLI の使用方法についての詳細は、組み込みヘルプを参照してください。

たとえば、以下のようになります。

$ kcreg.sh help

c:\> kcreg help

認証セッションの開始に関する詳細は、kcreg config credentials --help を参照してください。

デフォルトでは、クライアント登録 CLI は、ユーザーのホームディレクトリーにあるデフォルトの場所 (./.keycloak/kcreg.config) で設定ファイルを自動的に維持します。--config オプションを使用して異なるファイルまたは場所を指定し、複数の認証セッションを並行して管理することができます。単一のスレッドから、単一の設定ファイルに関連付けられる操作を実行するための最も安全な方法です。

すべてのコマンドで --no-config オプションを使用すると、シークレットを設定ファイル内に格納しないようにすることができます。各 kcreg 呼び出しですべての認証情報を指定します。

使用する Red Hat build of Keycloak サーバーでアカウントを設定していない開発者は、クライアント登録 CLI を使用できます。これは、レルム管理者が開発者に初期アクセストークンを発行した場合にのみ可能です。これらのトークンを発行および配布する方法と時期を決定するのは、レルム管理者の責任になります。レルム管理者は、初期アクセストークンの最大有効期間と、それを使用して作成できるクライアントの総数を制限できます。

開発者に初期アクセストークンがある場合、開発者は kcreg config credentials で認証せずにこれを使用して新規クライアントを作成することができます。初期アクセストークンは、設定ファイルに保存するか、kcreg create コマンドの一部として指定できます。

たとえば、以下のようになります。

$ kcreg.sh config initial-token $TOKEN
$ kcreg.sh create -s clientId=myclient

または、以下を実行します。

$ kcreg.sh create -s clientId=myclient -t $TOKEN

c:\> kcreg config initial-token %TOKEN%
c:\> kcreg create -s clientId=myclient

または、以下を実行します。

c:\> kcreg create -s clientId=myclient -t %TOKEN%

初期アクセストークンを使用する場合、サーバーの応答には、新しく発行された登録アクセストークンが含まれます。そのクライアントの後続の操作は、そのトークンで認証することで実行する必要があります。これは、そのクライアントに対してのみ有効です。

クライアント登録 CLI は、プライベート設定ファイルを自動的に使用して、このトークンを保存し、関連付けられたクライアントで使用します。同じ設定ファイルがすべてのクライアント操作に使用される限り、開発者はこの方法で作成されたクライアントの読み取り、更新、または削除を行うために認証する必要はありません。

初期アクセスおよび登録アクセストークンの詳細は、クライアント登録 を参照してください。

クライアント登録 CLI でトークンを設定する方法についての詳細は、kcreg config initial-token --help コマンドおよび kcreg config registration-token --help コマンドを実行してください。

通常、認証情報を使用して認証するか、初期アクセストークンを設定した後の最初のタスクは、新しいクライアントを作成することです。多くの場合、準備した JSON ファイルをテンプレートとして使用し、一部の属性を設定したり、上書きすることを推奨します。

以下の例は、JSON ファイルの読み取り、含まれる可能性のあるクライアント ID の上書き、その他の属性の設定、正常な作成後に設定を標準出力に出力する方法を示しています。

$ kcreg.sh create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s 'redirectUris=["/myclient/*"]' -o

C:\> kcreg create -f client-template.json -s clientId=myclient -s baseUrl=/myclient -s "redirectUris=[\"/myclient/*\"]" -o

kcreg create コマンドの詳細は、kcreg create --help を実行します。

kcreg attrs を使用して利用可能な属性をリスト表示できます。多くの設定属性は、有効性または一貫性についてチェックされないことに注意してください。適切な値を指定することが推奨されます。テンプレートに id フィールドを使用せず、kcreg create コマンドに引数として指定しないでください。

kcreg get コマンドを使用して、既存のクライアントを取得できます。

たとえば、以下のようになります。

$ kcreg.sh get myclient

C:\> kcreg get myclient

クライアント設定をアダプター設定ファイルとして取得することもできます。これは Web アプリケーションでパッケージ化できます。

たとえば、以下のようになります。

$ kcreg.sh get myclient -e install > keycloak.json

C:\> kcreg get myclient -e install > keycloak.json

kcreg get コマンドの詳細は、kcreg get --help コマンドを実行してください。

クライアント設定の更新方法は 2 つあります。

1 つの方法は、現在の設定を取得してファイルに保存し、編集してサーバーにポストバックした後に、完全に新しい状態をサーバーに送信することです。

たとえば、以下のようになります。

$ kcreg.sh get myclient > myclient.json
$ vi myclient.json
$ kcreg.sh update myclient -f myclient.json

C:\> kcreg get myclient > myclient.json
C:\> notepad myclient.json
C:\> kcreg update myclient -f myclient.json

2 つ目の方法は、現在のクライアントをフェッチし、そのクライアントのフィールドを設定または削除して、1 つのステップでポストバックします。

たとえば、以下のようになります。

$ kcreg.sh update myclient -s enabled=false -d redirectUris

C:\> kcreg update myclient -s enabled=false -d redirectUris

適用する変更のみを含むファイルを使用することもできるため、引数として値を多く指定する必要はありません。この場合は、--merge を指定して、JSON ファイルを完全かつ新規の設定として処理するのではなく、既存の設定に適用する属性セットとして処理する必要があることをクライアント登録 CLI に指示します。

たとえば、以下のようになります。

$ kcreg.sh update myclient --merge -d redirectUris -f mychanges.json

C:\> kcreg update myclient --merge -d redirectUris -f mychanges.json

kcreg update コマンドの詳細は、kcreg update --help コマンドを実行してください。

クライアントを削除するには、以下の例を使用します。

$ kcreg.sh delete myclient

C:\> kcreg delete myclient

kcreg delete コマンドの詳細は、kcreg delete --help コマンドを実行してください。

--no-config モードを使用して作成、読み取り、更新、および削除 (CRUD) 操作を実行すると、クライアント登録 CLI はユーザーの登録アクセストークンを処理できません。この場合、クライアントに対して最近発行した Registration Access Token の追跡できなくなる可能性があり、manage-clients パーミッションを持つアカウントで認証を行わずに、そのクライアントでの CRUD 操作を追加で実行できなくなります。

パーミッションがある場合は、クライアントの新しい登録アクセストークンを発行し、標準出力に出力したり、任意の設定ファイルに保存したりできます。それ以外の場合は、レルム管理者に、クライアント用の新しい登録アクセストークンを発行して送信するよう依頼する必要があります。--token オプションを使用して、これをすべての CRUD コマンドに渡すことができます。kcreg config registration-token コマンドを使用して新規トークンを設定ファイルに保存し、クライアント登録 CLI にこの時点から自動的に処理させることもできます。

kcreg update-token コマンドの詳細は、kcreg update-token --help コマンドを実行してください。