第2章 OpenID Connect
本セクションでは、Red Hat Single Sign-On アダプターまたは汎用 OpenID Connect Relying Party ライブラリーを使用して、OpenID Connect でアプリケーションとサービスのセキュリティーを保護する方法を説明します。
2.1. Java アダプター
Red Hat Single Sign-On には、Java アプリケーションのさまざまなアダプターがあります。正しいアダプターの選択は、ターゲットプラットフォームによって異なります。
すべての Java アダプターは、「Java アダプター設定」の章で説明されている共通の設定オプションセットを共有します。
2.1.1. Java アダプターの設定
Red Hat Single Sign-On がサポートする各 Java アダプターは、単純な JSON ファイルで設定できます。これは次のようになります。
{
"realm" : "demo",
"resource" : "customer-portal",
"realm-public-key" : "MIGfMA0GCSqGSIb3D...31LwIDAQAB",
"auth-server-url" : "https://localhost:8443/auth",
"ssl-required" : "external",
"use-resource-role-mappings" : false,
"enable-cors" : true,
"cors-max-age" : 1000,
"cors-allowed-methods" : "POST, PUT, DELETE, GET",
"cors-exposed-headers" : "WWW-Authenticate, My-custom-exposed-Header",
"bearer-only" : false,
"enable-basic-auth" : false,
"expose-token" : true,
"verify-token-audience" : true,
"credentials" : {
"secret" : "234234-234234-234234"
},
"connection-pool-size" : 20,
"disable-trust-manager": false,
"allow-any-hostname" : false,
"truststore" : "path/to/truststore.jks",
"truststore-password" : "geheim",
"client-keystore" : "path/to/client-keystore.jks",
"client-keystore-password" : "geheim",
"client-key-password" : "geheim",
"token-minimum-time-to-live" : 10,
"min-time-between-jwks-requests" : 10,
"public-key-cache-ttl": 86400,
"redirect-rewrite-rules" : {
"^/wsmaster/api/(.*)$" : "/api/$1"
}
}
システムプロパティーの置き換えには ${…} エンクロージャーを使用できます。たとえば、${jboss.server.config.dir} は /path/to/Red Hat Single Sign-On に置き換えられます。環境変数の代替も、env 接頭辞 (例: ${env.MY_ENVIRONMENT_VARIABLE}) でサポートされます。
初期設定ファイルは管理コンソールから取得できます。これは、管理コンソールを開き、メニューから Clients を選択して、対応するクライアントをクリックします。クライアントのページが開いたら、インストール タブをクリックし、Keycloak OIDC JSON を選択します。
各設定オプションの説明は次のとおりです。
- realm
- レルムの名前これは 必須 です。
- resource
- アプリケーションの client-id各アプリケーションには、アプリケーションを識別するのに使用される client-id があります。これは 必須 です。
- realm-public-key
- レルム公開鍵の PEM 形式。これは管理コンソールから取得できます。これは 任意 ですが、設定することは推奨されません。設定しないと、アダプターは Red Hat Single Sign-On からダウンロードし、必要に応じて常に再ダウンロードを行います (例: Red Hat Single Sign-On の鍵をローテーション)。ただし、realm-public-key が設定されている場合、アダプターは Red Hat Single Sign-On から新しい鍵をダウンロードしません。そのため、Red Hat Single Sign-On が鍵をローテーションするとアダプターが中断されます。
- auth-server-url
-
Red Hat Single Sign-On サーバーのベース URL。他のすべての Red Hat シングルサインオンページおよび REST サービスエンドポイントはこれから派生します。通常、形式は
https://host:port/authです。これは 必須 です。 - ssl-required
-
Red Hat Single Sign-On サーバーとの間のすべての通信が HTTPS を介して行われるようにします。実稼働環境では、これを
allに設定する必要があります。これは 任意 です。デフォルト値は external です。つまり、外部要求に HTTPS がデフォルトで必要になります。有効な値は、「all」、「external」、および「none」です。 - confidential-port
- SSL/TLS を介してセキュアな接続のために、Red Hat Single Sign-On サーバーによって使用される機密ポート。これは 任意 です。デフォルト値は 8443 です。
- use-resource-role-mappings
- true に設定すると、アダプターはユーザーのアプリケーションレベルのロールマッピングのトークンを検索します。false の場合は、ユーザーロールマッピングのレルムレベルを確認します。これは 任意 です。デフォルト値は false です。
- public-client
- true に設定すると、アダプターはクライアントの認証情報を Red Hat Single Sign-On に送信しません。これは 任意 です。デフォルト値は false です。
- enable-cors
- これにより、CORS サポートが有効になります。CORS プリフライトリクエストを処理します。また、アクセストークンを調べて、有効な発信元を判別します。これは 任意 です。デフォルト値は false です。
- cors-max-age
-
CORS が有効な場合は、
Access-Control-Max-Ageヘッダーの値が設定されます。これは 任意 です。設定されていない場合、このヘッダーは CORS 応答で返されません。 - cors-allowed-methods
-
CORS が有効な場合は、
Access-Control-Allow-Methodsヘッダーの値が設定されます。これはコンマ区切りの文字列である必要があります。これは 任意 です。設定されていない場合、このヘッダーは CORS 応答で返されません。 - cors-allowed-headers
-
CORS が有効な場合は、
Access-Control-Allow-Headersヘッダーの値を設定します。これはコンマ区切りの文字列である必要があります。これは 任意 です。設定されていない場合、このヘッダーは CORS 応答で返されません。 - cors-exposed-headers
-
CORS が有効な場合は、
Access-Control-Expose-Headersヘッダーの値を設定します。これはコンマ区切りの文字列である必要があります。これは 任意 です。設定されていない場合、このヘッダーは CORS 応答で返されません。 - bearer-only
- これは、サービスに true に設定する必要があります。有効な場合、アダプターはユーザーの認証を試行しませんが、ベアラートークンのみを検証します。これは 任意 です。デフォルト値は false です。
- autodetect-bearer-only
-
アプリケーションが Web アプリケーションと Web サービス (例: SOAP または REST) の両方に対応する場合は、true に設定する必要があります。Web アプリケーションの認証されていないユーザーを Keycloak ログインページにリダイレクトできますが、認証されていない SOAP または REST クライアントに HTTP
401ステータスコードを送信することができます。ログインページへのリダイレクトは理解できません。Keycloak は、X-Requested-With、SOAPAction、Acceptなどの一般的なヘッダーに基づいて SOAP クライアントまたは REST クライアントを自動検出します。デフォルト値は false です。 - enable-basic-auth
- これは、Basic 認証もサポートするようにアダプターに指示します。このオプションが有効な場合には、シークレット も指定する必要があります。これは 任意 です。デフォルト値は false です。
- expose-token
-
trueの場合、(JavaScript HTTP 呼び出しを介して) 認証されたブラウザークライアントは、URLroot/k_query_bearer_tokenを使用して署名されたアクセストークンを取得できます。これは 任意 です。デフォルト値は false です。 - credentials
- アプリケーションの認証情報を指定します。これは、鍵が認証情報タイプであり、値が認証情報タイプの値であるオブジェクト表記です。現在、パスワードおよび jwt がサポートされています。これは、アクセスタイプが「Confidential」を持つクライアントにのみ 必須 になります。
- connection-pool-size
-
この設定オプションでは、Red Hat Single Sign-On サーバーへプールする接続の数を定義します。これは 任意 です。デフォルト値は
20です。 - disable-trust-manager
-
Red Hat Single Sign-On サーバーに HTTPS が必要で、この設定オプションが
trueに設定されている場合は、トラストストアを指定する必要はありません。この設定は開発時のみ使用してください。これは SSL 証明書の検証を無効にするため、実稼働環境では 使用しないで ください。これは 任意 です。デフォルト値はfalseです。 - allow-any-hostname
-
Red Hat Single Sign-On サーバーに HTTPS が必要で、この設定オプションが
trueに設定されている場合、Red Hat Single Sign-On サーバーの証明書はトラストストア経由で検証されますが、ホスト名の検証は行われません。この設定は開発時のみ使用してください。これは SSL 証明書の検証を無効にするため、実稼働環境では 使用しないで ください。この設定は、テスト環境で役に立つ場合があります。これは 任意 です。デフォルト値はfalseです。 - proxy-url
- HTTP プロキシーが使用されている場合はその URL。
- truststore
-
値は、トラストストアファイルへのファイルパスです。
classpath:でパスを接頭辞にすると、代わりにデプロイメントのクラスパスからトラストストアが取得されます。Red Hat Single Sign-On サーバーへの送信 HTTPS 通信に使用されます。HTTPS 要求を実行するクライアントでは、通信先のサーバーのホストを確認する方法が必要です。これは、トラストストアが行なうことです。キーストアには、1 つ以上の信頼できるホスト証明書または認証局が含まれます。Red Hat Single Sign-On サーバーの SSL キーストアの公開証明書を抽出して、このトラストストアを作成できます。これは、ssl-requiredがnone、またはdisable-trust-managerがtrueでない限り、必須 になります。 - truststore-password
-
トラストストアのパスワード。これは、
トラストストアが設定され、トラストストアにパスワードが必要な場合は 必須 になります。 - client-keystore
- これはキーストアファイルに対するファイルパスです。このキーストアには、アダプターが Red Hat Single Sign-On サーバーに対して HTTPS を要求する際に双方向 SSL のクライアント証明書が含まれます。これは 任意 です。
- client-keystore-password
-
クライアントキーストアのパスワード。これは、
client-keystoreが設定されている場合は 必須 になります。 - client-key-password
-
クライアントのキーのパスワードこれは、
client-keystoreが設定されている場合は 必須 になります。 - always-refresh-token
- true の場合、アダプターはすべてのリクエストでトークンを更新します。警告: これを有効にすると、アプリケーションへのリクエストごとに Red Hat Single Sign-On へのリクエストが行われます。
- register-node-at-startup
- true の場合、アダプターは登録リクエストを Red Hat Single Sign-On に送信します。デフォルトは false で、アプリケーションがクラスター化されている場合にのみ便利です。詳細は、「アプリケーションクラスタリング」を参照してください。
- register-node-period
- Red Hat Single Sign-On に再登録アダプターを使用する期間。アプリケーションがクラスター化されている場合に役立ちます。詳細は、「アプリケーションクラスタリング」を参照してください。
- token-store
- 使用できる値は session および cookie です。デフォルトは session で、アダプターはアカウント情報を HTTP セッションに保存します。代替 cookie とは、cookie への情報の格納を意味します。詳細は、「アプリケーションクラスタリング」を参照してください。
- token-cookie-path
- cookie ストアを使用する場合、このオプションはアカウント情報を保存するために使用される cookie のパスを設定します。相対パスの場合は、アプリケーションがコンテキストルートで実行されていることを前提とし、そのコンテキストルートへの相対的として解釈されます。絶対パスの場合は、クッキーパスの設定に絶対パスが使用されます。デフォルトは、コンテキストルートへの相対パスを使用します。
- principal-attribute
-
UserPrincipal 名を入力する OpenID Connect ID Token 属性。トークン属性が null の場合、デフォルトは
subに設定されます。使用できる値はsub、preferred_username、email、name、nickname、given_name、family_nameです。 - turn-off-change-session-id-on-login
- 一部のプラットフォームでログインに成功すると、セキュリティー攻撃ベクトルをプラグインするために、セッション ID がデフォルトで変更されます。これをオフにする場合は、これを true に変更します。これは 任意 です。デフォルト値は false です。
- token-minimum-time-to-live
-
Red Hat Single Sign-On サーバーでアクティブなアクセストークンを事前更新してから失効する時間 (秒単位)。これは、アクセストークンが別の REST クライアントに送信され、評価前に期限切れになる可能性がある場合に特に便利です。この値は、レルムのアクセストークンの有効期間を超えてはいけないはずです。これは 任意 です。デフォルト値は
0秒であるため、アダプターは期限切れの場合にのみアクセストークンを更新します。 - min-time-between-jwks-requests
-
新しい公開鍵を取得するための Red Hat Single Sign-On への2つの要求間の最小間隔を指定する時間 (秒単位)。デフォルトは 10 秒です。アダプターは、不明な
kidでトークンを認識すると、常に新しい公開鍵をダウンロードしようとします。ただし、10 秒に 1 回以上試行することはありません (デフォルト)。これは、攻撃者が不正なkid強制アダプターを使用して多数のトークンを送信し、Red Hat Single Sign-On に多数のリクエストを送信するときに DoS を回避するためです。 - public-key-cache-ttl
-
新しい公開鍵を取得する Red Hat Single Sign-On への 2 つのリクエストの最大間隔を指定する時間 (秒単位)。デフォルトは 86400 秒 (1 日) です。アダプターは、不明な
kidでトークンを認識すると、常に新しい公開鍵をダウンロードしようとします。既知のkidでトークンを認識すると、以前ダウンロードした公開鍵のみを使用します。ただし、この設定した間隔 (デフォルトでは 1 日) につき少なくとも 1 回は新しい公開鍵がダウンロードされます。トークンのkidの規模が分かっている場合でも、常に新しい公開鍵がダウンロードされます。 - ignore-oauth-query-parameter
-
デフォルトは
falseです。trueに設定すると、ベアラートークン処理のaccess_tokenクエリーパラメーターの処理がオフになります。access_tokenを渡すだけでは、ユーザーを認証できません - redirect-rewrite-rules
-
必要な場合は、リダイレクト URI の書き換えルールを指定します。これは、キーが Redirect URI を照合する正規表現で、値は代替文字列になります。
$文字は、代替 String の後方参照に使用できます。 - verify-token-audience
-
trueに設定すると、ベアラートークンを使用した認証中に、アダプターはトークンにこのクライアント名 (リソース) がオーディエンスとして含まれているかどうかを確認します。このオプションは特に、主にベアラートークンで認証された要求を提供するサービスに有用です。これは、デフォルトではfalseに設定されますが、セキュリティーを強化する場合は、これを有効にすることが推奨されます。オーディエンスサポートの詳細は、「オーディエンスサポート」を参照してください。
2.1.2. JBoss EAP Adapter
JBoss EAP にデプロイされた WAR アプリケーションのセキュリティーを保護するには、Red Hat Single Sign-On アダプターサブシステムをインストールおよび設定する必要があります。次に、WAR のセキュリティーを保護する 2 つのオプションがあります。
WAR でアダプター設定ファイルを指定し、auth-method を web.xml 内の KEYCLOAK に変更できます。
または、WAR を修正する必要がなく、standalone.xml などの設定ファイルの Red Hat Single Sign-On アダプターサブシステム設定を介してセキュリティー保護できます。本セクションでは、両方の方法を説明します。
2.1.2.1. アダプターのインストール
アダプターは、使用しているサーバーのバージョンに応じて、別のアーカイブとして利用できます。
JBoss EAP 7 にインストールします。
EAP 7 アダプターは、ZIP ファイルを展開するか、RPM を使用してインストールできます。
ZIP ファイルから EAP 7 アダプターをインストールします。
$ cd $EAP_HOME $ unzip rh-sso-7.4.10.GA-eap7-adapter.zip
JBoss EAP 6 にインストールします。
EAP 6 アダプターは、ZIP ファイルを展開するか、RPM を使用してインストールできます。
ZIP ファイルから EAP 6 アダプターをインストールします。
$ cd $EAP_HOME $ unzip rh-sso-7.4.10.GA-eap6-adapter.zip
この ZIP アーカイブには、Red Hat Single Sign-On アダプターに固有の JBoss モジュールが含まれています。また、アダプターサブシステムを設定するための JBoss CLI スクリプトも含まれています。
サーバーが実行していない場合は adapter サブシステムを設定します。
または、-Dserver.config=standalone-ha.xml などの異なる設定を使用してアダプターをインストールするために、コマンドラインからアダプターをインストールする際に server.config プロパティーを指定することもできます。
JBoss EAP 7.1 以降
$ ./bin/jboss-cli.sh --file=bin/adapter-elytron-install-offline.cli
JBoss EAP 6.4 ではオフラインスクリプトは利用できません。
または、サーバーが実行中の場合は、以下を実行します。
JBoss EAP 7.1 以降
$ ./bin/jboss-cli.sh -c --file=bin/adapter-elytron-install.cli
JBoss EAP 7.1 以上で従来の非 Elytron アダプターを使用することもできます。つまり、adapter-install-offline.cliを使用することができます。
JBoss EAP 6.4
$ ./bin/jboss-cli.sh -c --file=bin/adapter-install.cli
2.1.2.2. JBoss SSO
JBoss EAP は、同じ JBoss EAP インスタンスにデプロイされた web アプリケーションに対するシングルサインオンのサポートが組み込まれています。これは、Red Hat Single Sign-On を使用する場合に有効にしないでください。
2.1.2.3. 各 WAR に必要な設定
本セクションでは、WAR パッケージ内の設定ファイルを追加および編集して、WAR を直接保護する方法を説明します。
最初に、WAR の WEB-INF ディレクトリーに keycloak.json アダプター設定ファイルを作成する必要があります。
この設定ファイルの形式は、「Java アダプター設定」セクションで説明されています。
次に、web.xml で auth-method を KEYCLOAK に 設定する必要があります。また、標準のサーブレットセキュリティーを使用して URL に role-base 制約を指定する必要があります。
以下に例を示します。
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
version="3.0">
<module-name>application</module-name>
<security-constraint>
<web-resource-collection>
<web-resource-name>Admins</web-resource-name>
<url-pattern>/admin/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>admin</role-name>
</auth-constraint>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
<security-constraint>
<web-resource-collection>
<web-resource-name>Customers</web-resource-name>
<url-pattern>/customers/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>user</role-name>
</auth-constraint>
<user-data-constraint>
<transport-guarantee>CONFIDENTIAL</transport-guarantee>
</user-data-constraint>
</security-constraint>
<login-config>
<auth-method>KEYCLOAK</auth-method>
<realm-name>this is ignored currently</realm-name>
</login-config>
<security-role>
<role-name>admin</role-name>
</security-role>
<security-role>
<role-name>user</role-name>
</security-role>
</web-app>2.1.2.4. Adapter サブシステムによる WAR のセキュリティー保護
WAR を変更して Red Hat Single Sign-On で保護する必要はありません。代わりに、Red Hat Single Sign-On Adapter サブシステム経由で外部からセキュリティー保護することができます。Keycloak を auth-method として指定する必要はありませんが、web.xml で security-constraints を定義する必要があります。ただし、WEB-INF/keycloak.json ファイルを作成する必要がありません。このメタデータは、代わりに Red Hat Single Sign-On サブシステムのサーバー設定 (つまり standalone.xmlなど) で定義されます。
<extensions>
<extension module="org.keycloak.keycloak-adapter-subsystem"/>
</extensions>
<profile>
<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
<secure-deployment name="WAR MODULE NAME.war">
<realm>demo</realm>
<auth-server-url>http://localhost:8081/auth</auth-server-url>
<ssl-required>external</ssl-required>
<resource>customer-portal</resource>
<credential name="secret">password</credential>
</secure-deployment>
</subsystem>
</profile>
secure-deployment name 属性は、セキュリティーを保護する WAR を識別します。この値は web.xml に .war を追加した module-name です。残りの構成は、Javaアダプター構成 で定義された keycloak.json 構成オプションとほぼ 1 対 1 で対応しています。
例外は credential 要素です。
これを容易にするために、Red Hat Single Sign-On 管理コンソールに移動し、この WAR が連携しているアプリケーションのクライアント/インストールタブに移動します。ここでは、カットアンドペーストできる XML ファイルの例を提供します。
同じレルムでセキュア化された複数のデプロイメントがある場合は、レルム設定を個別の要素で共有できます。以下に例を示します。
<subsystem xmlns="urn:jboss:domain:keycloak:1.1">
<realm name="demo">
<auth-server-url>http://localhost:8080/auth</auth-server-url>
<ssl-required>external</ssl-required>
</realm>
<secure-deployment name="customer-portal.war">
<realm>demo</realm>
<resource>customer-portal</resource>
<credential name="secret">password</credential>
</secure-deployment>
<secure-deployment name="product-portal.war">
<realm>demo</realm>
<resource>product-portal</resource>
<credential name="secret">password</credential>
</secure-deployment>
<secure-deployment name="database.war">
<realm>demo</realm>
<resource>database-service</resource>
<bearer-only>true</bearer-only>
</secure-deployment>
</subsystem>2.1.2.5. セキュリティードメイン
セキュリティーコンテキストは EJB 階層に自動的に伝播されます。
2.1.3. RPM からの JBoss EAP アダプターのインストール
RPM から EAP 7 アダプターをインストールします。
Red Hat Enterprise Linux 7 では、チャンネル という用語はリポジトリーという用語に置き換えられました。これらの手順では、リポジトリーという用語のみが使用されています。
RPM から JBoss EAP 7 アダプターをインストールする前に、JBoss EAP 7.3 リポジトリーにサブスクライブする必要があります。
前提条件
- Red Hat Subscription Manager を使用して、Red Hat Enterprise Linux システムがお使いのアカウントに登録されている必要があります。詳細は、Red Hat Subscription Management のドキュメント を参照してください。
- すでに別の JBoss EAP リポジトリーにサブスクライブしている場合は、最初にそのリポジトリーからサブスクライブを解除する必要があります。
Red Hat Enterprise Linux 6、7 の場合: Red Hat Subscription Manager を使用して、以下のコマンドで JBoss EAP 7.3 リポジトリーにサブスクライブします。お使いの Red Hat Enterprise Linux のバージョンに応じて、<RHEL_VERSION> を 6 または 7 に置き換えてください。
$ sudo subscription-manager repos --enable=jb-eap-7-for-rhel-<RHEL_VERSION>-server-rpms
Red Hat Enterprise Linux 8 の場合: Red Hat Subscription Manager を使用して、以下のコマンドで JBoss EAP 7.3 リポジトリーにサブスクライブします。
$ sudo subscription-manager repos --enable=jb-eap-7.3-for-rhel-8-x86_64-rpms --enable=rhel-8-for-x86_64-baseos-rpms --enable=rhel-8-for-x86_64-appstream-rpms
Red Hat Enterprise Linux 6、7 で以下のコマンドを使用して OIDC の JBoss EAP 7 アダプターをインストールします。
$ sudo yum install eap7-keycloak-adapter-sso7_4
または、Red Hat Enterprise Linux 8 に以下のいずれかを使用します。
$ sudo dnf install eap7-keycloak-adapter-sso7_4
RPM インストールのデフォルトの EAP_HOME パスは /opt/rh/eap7/root/usr/share/wildfly です。
適切なモジュールインストールスクリプトを実行します。
OIDC モジュールの場合は、以下のコマンドを入力します。
$ $EAP_HOME/bin/jboss-cli.sh -c --file=$EAP_HOME/bin/adapter-install.cli
インストールが完了しました。
RPM から EAP 6 アダプターをインストールします。
Red Hat Enterprise Linux 7 では、チャンネル という用語はリポジトリーという用語に置き換えられました。これらの手順では、リポジトリーという用語のみが使用されています。
RPM から EAP 6 アダプターをインストールする前に、JBoss EAP 6 リポジトリーにサブスクライブする必要があります。
前提条件
- Red Hat Subscription Manager を使用して、Red Hat Enterprise Linux システムがお使いのアカウントに登録されている必要があります。詳細は、Red Hat Subscription Management のドキュメント を参照してください。
- すでに別の JBoss EAP リポジトリーにサブスクライブしている場合は、最初にそのリポジトリーからサブスクライブを解除する必要があります。
Red Hat Subscription Manager を使用して、以下のコマンドを使用して JBoss EAP 6 リポジトリーにサブスクライブします。お使いの Red Hat Enterprise Linux のバージョンに応じて、<RHEL_VERSION> を 6 または 7 に置き換えてください。
$ sudo subscription-manager repos --enable=jb-eap-6-for-rhel-<RHEL_VERSION>-server-rpms
以下のコマンドを使用して、OIDC の EAP 6 アダプターをインストールします。
$ sudo yum install keycloak-adapter-sso7_4-eap6
RPM インストールのデフォルトの EAP_HOME パスは /opt/rh/eap6/root/usr/share/wildfly です。
適切なモジュールインストールスクリプトを実行します。
OIDC モジュールの場合は、以下のコマンドを入力します。
$ $EAP_HOME/bin/jboss-cli.sh -c --file=$EAP_HOME/bin/adapter-install.cli
インストールが完了しました。
2.1.4. JBoss Fuse 6 Adapter
Red Hat Single Sign-On は、JBoss Fuse 6 内で実行される Web アプリケーションのセキュリティー保護をサポートします。
Fuse 6 のサポートされるバージョンは最新リリースのみです。以前のバージョンの Fuse 6 を使用する場合は、一部の関数が正常に機能しない可能性があります。特に、Hawtio 統合は Fuse 6 の以前のバージョンでは機能しません。
以下の項目のセキュリティーは Fuse でサポートされます。
- Pax Web War Extender を使用して Fuse にデプロイされた Classic WAR アプリケーション
- Pax Web Whiteboard Extender で OSGI として Fuse にデプロイされたサーブレット
- Camel Jetty コンポーネントで実行している Apache Camel エンドポイント
- 独自の個別 Jetty エンジン で実行される Apache CXF エンドポイント
- CXF サーブレットによって提供されるデフォルトのエンジンで実行される Apache CXF エンドポイント
- SSH および JMX 管理者アクセス
- Hawtio 管理コンソール
2.1.4.1. Fuse 6 での Web アプリケーションのセキュリティー保護
最初に Red Hat Single Sign-On Karaf 機能をインストールする必要があります。次に、セキュリティー保護するアプリケーションのタイプに応じて手順を実行する必要があります。参照されるすべての Web アプリケーションには、Red Hat Single Sign-On Jetty オーセンティケーターを基盤の Jetty サーバーに挿入する必要があります。これを行う手順は、アプリケーションの種別によって異なります。詳細は、以下を参照してください。
2.1.4.2. Keycloak 機能のインストール
最初に JBoss Fuse 環境に keycloak 機能をインストールする必要があります。keycloak 機能には、Fuse アダプターとサードパーティーのすべての依存関係が含まれます。Maven リポジトリーまたはアーカイブからインストールできます。
2.1.4.2.1. Maven リポジトリーからのインストール
前提条件として、オンラインで Maven リポジトリーにアクセスできる必要がある。
Red Hat Single Sign-On では、最初に適切な Maven リポジトリーを設定して、アーティファクトをインストールできます。詳細は、「JBoss Enterprise Maven リポジトリーページ」を参照してください。
Maven リポジトリーが https://maven.repository.redhat.com/ga/ であるとします。 $FUSE_HOME/etc/org.ops4j.pax.url.mvn.cfg ファイルに以下を追加し、サポートされているリポジトリーの一覧にリポジトリーを追加します。以下に例を示します。
org.ops4j.pax.url.mvn.repositories= \
https://maven.repository.redhat.com/ga/@id=redhat.product.repo
http://repo1.maven.org/maven2@id=maven.central.repo, \
...Maven リポジトリーを使用して keycloak 機能をインストールするには、以下の手順を実行します。
JBoss Fuse 6.3.0 を起動し、Karaf 端末タイプで以下を行います。
features:addurl mvn:org.keycloak/keycloak-osgi-features/9.0.17.redhat-00001/xml/features features:install keycloak
また、Jetty 9 機能をインストールする必要がある場合があります。
features:install keycloak-jetty9-adapter
- 機能がインストールされていることを確認します。
features:list | grep keycloak
2.1.4.2.2. ZIP バンドルからのインストール
これは、オフラインの場合、または Maven を使用して JAR ファイルやその他のアーティファクトを取得したくない場合に便利です。
ZIP アーカイブから Fuse アダプターをインストールするには、以下の手順を行います。
- Red Hat Single Sign-On Fuse アダプター ZIP アーカイブをダウンロードします。
これを JBoss Fuse のルートディレクトリーに展開します。次に、依存関係が
systemディレクトリーにインストールされます。既存の jar ファイルをすべて上書きできます。これは JBoss Fuse 6.3.0 に使用します。
cd /path-to-fuse/jboss-fuse-6.3.0.redhat-XXX unzip -q /path-to-adapter-zip/rh-sso-7.4.10.GA-fuse-adapter.zip
Fuse を起動し、fuse/karaf ターミナルでこれらのコマンドを実行します。
features:addurl mvn:org.keycloak/keycloak-osgi-features/9.0.17.redhat-00001/xml/features features:install keycloak
-
対応する Jetty アダプターをインストールします。アーティファクトは JBoss Fuse
systemディレクトリーで直接利用できるため、Maven リポジトリーを使用する必要はありません。
2.1.4.3. クラシック WAR アプリケーションのセキュリティー保護
WAR アプリケーションをセキュアにするのに必要な手順は次のとおりです。
/WEB-INF/web.xmlファイルで、必要を宣言します。- <security-constraint> 要素のセキュリティー制約
- <login-config> 要素のログイン設定
<security-role> 要素のセキュリティーロール
以下に例を示します。
<?xml version="1.0" encoding="UTF-8"?> <web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" version="3.0"> <module-name>customer-portal</module-name> <welcome-file-list> <welcome-file>index.html</welcome-file> </welcome-file-list> <security-constraint> <web-resource-collection> <web-resource-name>Customers</web-resource-name> <url-pattern>/customers/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>user</role-name> </auth-constraint> </security-constraint> <login-config> <auth-method>BASIC</auth-method> <realm-name>does-not-matter</realm-name> </login-config> <security-role> <role-name>admin</role-name> </security-role> <security-role> <role-name>user</role-name> </security-role> </web-app>
/WEB-INF/jetty-web.xmlファイルにオーセンティケーターのあるjetty-web.xmlファイルを追加します。以下に例を示します。
<?xml version="1.0"?> <!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//DTD Configure//EN" "http://www.eclipse.org/jetty/configure_9_0.dtd"> <Configure class="org.eclipse.jetty.webapp.WebAppContext"> <Get name="securityHandler"> <Set name="authenticator"> <New class="org.keycloak.adapters.jetty.KeycloakJettyAuthenticator"> </New> </Set> </Get> </Configure>-
WAR の
/WEB-INF/ディレクトリー内で、新しいファイル keycloak.json を作成します。この設定ファイルの形式は、「Java アダプター設定」のセクションで説明されています。「外部アダプターの設定」で説明されているように、このファイルを外部から利用できるようにすることもできます。 WAR アプリケーションが
org.keycloak.adapters.jettyをインポートし、さらにImport-PackageヘッダーでMETA-INF/MANIFEST.MFファイルに含まれるパッケージをインポートするようにしてください。プロジェクトにmaven-bundle-pluginを使用すると、OSGI ヘッダーがマニフェストに適切に生成されます。パッケージの「*」解決は、アプリケーションや Blueprint または Spring 記述子で使用されていないため、org.keycloak.adapters.jettyパッケージはインポートしませんが、jetty-web.xmlファイルで使用されます。インポートするパッケージの一覧は、以下のようになります。
org.keycloak.adapters.jetty;version="9.0.17.redhat-00001", org.keycloak.adapters;version="9.0.17.redhat-00001", org.keycloak.constants;version="9.0.17.redhat-00001", org.keycloak.util;version="9.0.17.redhat-00001", org.keycloak.*;version="9.0.17.redhat-00001", *;resolution:=optional
2.1.4.3.1. 外部アダプターの設定
keycloak.json アダプター設定ファイルを WAR アプリケーション内にバンドルせず、命名規則に基づいて外部に利用可能にし、読み込む場合は、この設定方法を使用します。
この機能を有効にするには、このセクションを /WEB_INF/web.xml ファイルに追加します。
<context-param>
<param-name>keycloak.config.resolver</param-name>
<param-value>org.keycloak.adapters.osgi.PathBasedKeycloakConfigResolver</param-value>
</context-param>
そのコンポーネントは、java プロパティー keycloak.config または karaf.etc を使用してベースフォルダーを検索し、設定を見つけます。次に、フォルダーのいずれかで <your_web_context>-keycloak.json という名前のファイルを検索します。
たとえば、Web アプリケーションにコンテキスト my-portal がある場合、アダプター設定は $FUSE_HOME/etc/my-portal-keycloak.json ファイルから読み込まれます。
2.1.4.4. OSGI サービスとしてデプロイされたサーブレットのセキュア化
従来の WAR アプリケーションとしてデプロイされていない OSGI バンドルプロジェクトにサーブレットクラスがある場合は、このメソッドを使用できます。Fuse は Pax Web Whiteboard Extender を使用して、このようなサーブレットを Web アプリケーションとしてデプロイします。
Red Hat Single Sign-On でサーブレットをセキュアにするには、以下の手順を実行します。
Red Hat Single Sign-On は、jetty-web.xml を挿入し、アプリケーションのセキュリティー制約の設定を可能にする PaxWebIntegrationService を提供します。このようなサービスをアプリケーション内の
OSGI-INF/blueprint/blueprint.xmlファイルで宣言する必要があります。サーブレットはそれに依存する必要があることに注意してください。設定例:<?xml version="1.0" encoding="UTF-8"?> <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd"> <!-- Using jetty bean just for the compatibility with other fuse services --> <bean id="servletConstraintMapping" class="org.eclipse.jetty.security.ConstraintMapping"> <property name="constraint"> <bean class="org.eclipse.jetty.util.security.Constraint"> <property name="name" value="cst1"/> <property name="roles"> <list> <value>user</value> </list> </property> <property name="authenticate" value="true"/> <property name="dataConstraint" value="0"/> </bean> </property> <property name="pathSpec" value="/product-portal/*"/> </bean> <bean id="keycloakPaxWebIntegration" class="org.keycloak.adapters.osgi.PaxWebIntegrationService" init-method="start" destroy-method="stop"> <property name="jettyWebXmlLocation" value="/WEB-INF/jetty-web.xml" /> <property name="bundleContext" ref="blueprintBundleContext" /> <property name="constraintMappings"> <list> <ref component-id="servletConstraintMapping" /> </list> </property> </bean> <bean id="productServlet" class="org.keycloak.example.ProductPortalServlet" depends-on="keycloakPaxWebIntegration"> </bean> <service ref="productServlet" interface="javax.servlet.Servlet"> <service-properties> <entry key="alias" value="/product-portal" /> <entry key="servlet-name" value="ProductServlet" /> <entry key="keycloak.config.file" value="/keycloak.json" /> </service-properties> </service> </blueprint>-
(プロジェクトが Web アプリケーションではない場合でも) プロジェクト内に
WEB-INFディレクトリーがあり、Classic WAR application セクションに、/WEB-INF/jetty-web.xmlファイルおよび/WEB-INF/keycloak.jsonファイルを作成します。security-constraints が Blueprint 設定ファイルで宣言されているため、web.xmlファイルは必要ありません。
-
(プロジェクトが Web アプリケーションではない場合でも) プロジェクト内に
META-INF/MANIFEST.MFのImport-Packageには、少なくとも以下のインポートが含まれている必要があります。org.keycloak.adapters.jetty;version="9.0.17.redhat-00001", org.keycloak.adapters;version="9.0.17.redhat-00001", org.keycloak.constants;version="9.0.17.redhat-00001", org.keycloak.util;version="9.0.17.redhat-00001", org.keycloak.*;version="9.0.17.redhat-00001", *;resolution:=optional
2.1.4.5. Apache Camel アプリケーションのセキュリティー保護
camel-jetty コンポーネントで実装された Apache Camel エンドポイントのセキュリティーを保護するには、KeycloakJettyAuthenticator で securityHandler を追加し、適切なセキュリティー制約を挿入します。OSGI-INF/blueprint/blueprint.xml ファイルを以下のような設定を持つ Camel アプリケーションに追加できます。ロール、セキュリティー制約のマッピング、および Red Hat Single Sign-On アダプター設定は、お使いの環境とニーズに合わせて若干異なる可能性があります。
以下に例を示します。
<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:camel="http://camel.apache.org/schema/blueprint"
xsi:schemaLocation="
http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
http://camel.apache.org/schema/blueprint http://camel.apache.org/schema/blueprint/camel-blueprint.xsd">
<bean id="kcAdapterConfig" class="org.keycloak.representations.adapters.config.AdapterConfig">
<property name="realm" value="demo"/>
<property name="resource" value="admin-camel-endpoint"/>
<property name="bearerOnly" value="true"/>
<property name="authServerUrl" value="http://localhost:8080/auth" />
<property name="sslRequired" value="EXTERNAL"/>
</bean>
<bean id="keycloakAuthenticator" class="org.keycloak.adapters.jetty.KeycloakJettyAuthenticator">
<property name="adapterConfig" ref="kcAdapterConfig"/>
</bean>
<bean id="constraint" class="org.eclipse.jetty.util.security.Constraint">
<property name="name" value="Customers"/>
<property name="roles">
<list>
<value>admin</value>
</list>
</property>
<property name="authenticate" value="true"/>
<property name="dataConstraint" value="0"/>
</bean>
<bean id="constraintMapping" class="org.eclipse.jetty.security.ConstraintMapping">
<property name="constraint" ref="constraint"/>
<property name="pathSpec" value="/*"/>
</bean>
<bean id="securityHandler" class="org.eclipse.jetty.security.ConstraintSecurityHandler">
<property name="authenticator" ref="keycloakAuthenticator" />
<property name="constraintMappings">
<list>
<ref component-id="constraintMapping" />
</list>
</property>
<property name="authMethod" value="BASIC"/>
<property name="realmName" value="does-not-matter"/>
</bean>
<bean id="sessionHandler" class="org.keycloak.adapters.jetty.spi.WrappingSessionHandler">
<property name="handler" ref="securityHandler" />
</bean>
<bean id="helloProcessor" class="org.keycloak.example.CamelHelloProcessor" />
<camelContext id="blueprintContext"
trace="false"
xmlns="http://camel.apache.org/schema/blueprint">
<route id="httpBridge">
<from uri="jetty:http://0.0.0.0:8383/admin-camel-endpoint?handlers=sessionHandler&matchOnUriPrefix=true" />
<process ref="helloProcessor" />
<log message="The message from camel endpoint contains ${body}"/>
</route>
</camelContext>
</blueprint>-
META-INF/MANIFEST.MFのImport-Packageには以下のインポートが含まれる必要があります。
javax.servlet;version="[3,4)", javax.servlet.http;version="[3,4)", org.apache.camel.*, org.apache.camel;version="[2.13,3)", org.eclipse.jetty.security;version="[9,10)", org.eclipse.jetty.server.nio;version="[9,10)", org.eclipse.jetty.util.security;version="[9,10)", org.keycloak.*;version="9.0.17.redhat-00001", org.osgi.service.blueprint, org.osgi.service.blueprint.container, org.osgi.service.event,
2.1.4.6. Camel RestDSL
Camel RestDSL は、REST エンドポイントを定義するのに使用される Camel 機能です。しかし、引き続き特定の実装クラスを使用し、Red Hat Single Sign-On との統合方法を説明します。
インテグレーションメカニズムを設定する方法は、RestDSL 定義のルートを設定する Camel コンポーネントに依存します。
以下の例は、Jetty コンポーネントを使用して統合を設定する方法を示しています。これには、上述の Blueprint の例で定義された一部の Bean への参照が含まれます。
<bean id="securityHandlerRest" class="org.eclipse.jetty.security.ConstraintSecurityHandler">
<property name="authenticator" ref="keycloakAuthenticator" />
<property name="constraintMappings">
<list>
<ref component-id="constraintMapping" />
</list>
</property>
<property name="authMethod" value="BASIC"/>
<property name="realmName" value="does-not-matter"/>
</bean>
<bean id="sessionHandlerRest" class="org.keycloak.adapters.jetty.spi.WrappingSessionHandler">
<property name="handler" ref="securityHandlerRest" />
</bean>
<camelContext id="blueprintContext"
trace="false"
xmlns="http://camel.apache.org/schema/blueprint">
<restConfiguration component="jetty" contextPath="/restdsl"
port="8484">
<!--the link with Keycloak security handlers happens here-->
<endpointProperty key="handlers" value="sessionHandlerRest"></endpointProperty>
<endpointProperty key="matchOnUriPrefix" value="true"></endpointProperty>
</restConfiguration>
<rest path="/hello" >
<description>Hello rest service</description>
<get uri="/{id}" outType="java.lang.String">
<description>Just an helllo</description>
<to uri="direct:justDirect" />
</get>
</rest>
<route id="justDirect">
<from uri="direct:justDirect"/>
<process ref="helloProcessor" />
<log message="RestDSL correctly invoked ${body}"/>
<setBody>
<constant>(__This second sentence is returned from a Camel RestDSL endpoint__)</constant>
</setBody>
</route>
</camelContext>2.1.4.7. 別の Jetty Engine での Apache CXF エンドポイントのセキュリティー保護
別の Jetty エンジンで Red Hat Single Sign-On によってセキュア化された CXF エンドポイントを実行するには、以下の手順を実行します。
META-INF/spring/beans.xmlをアプリケーションに追加し、そのアプリケーションで、httpj:engine-factoryが注入された Jetty SecurityHandler でKeycloakJettyAuthenticatorを宣言します。CFX JAX-WS アプリケーションの設定は以下のようになります。<?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jaxws="http://cxf.apache.org/jaxws" xmlns:httpj="http://cxf.apache.org/transports/http-jetty/configuration" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd http://cxf.apache.org/jaxws http://cxf.apache.org/schemas/jaxws.xsd http://www.springframework.org/schema/osgi http://www.springframework.org/schema/osgi/spring-osgi.xsd http://cxf.apache.org/transports/http-jetty/configuration http://cxf.apache.org/schemas/configuration/http-jetty.xsd"> <import resource="classpath:META-INF/cxf/cxf.xml" /> <bean id="kcAdapterConfig" class="org.keycloak.representations.adapters.config.AdapterConfig"> <property name="realm" value="demo"/> <property name="resource" value="custom-cxf-endpoint"/> <property name="bearerOnly" value="true"/> <property name="authServerUrl" value="http://localhost:8080/auth" /> <property name="sslRequired" value="EXTERNAL"/> </bean> <bean id="keycloakAuthenticator" class="org.keycloak.adapters.jetty.KeycloakJettyAuthenticator"> <property name="adapterConfig"> <ref local="kcAdapterConfig" /> </property> </bean> <bean id="constraint" class="org.eclipse.jetty.util.security.Constraint"> <property name="name" value="Customers"/> <property name="roles"> <list> <value>user</value> </list> </property> <property name="authenticate" value="true"/> <property name="dataConstraint" value="0"/> </bean> <bean id="constraintMapping" class="org.eclipse.jetty.security.ConstraintMapping"> <property name="constraint" ref="constraint"/> <property name="pathSpec" value="/*"/> </bean> <bean id="securityHandler" class="org.eclipse.jetty.security.ConstraintSecurityHandler"> <property name="authenticator" ref="keycloakAuthenticator" /> <property name="constraintMappings"> <list> <ref local="constraintMapping" /> </list> </property> <property name="authMethod" value="BASIC"/> <property name="realmName" value="does-not-matter"/> </bean> <httpj:engine-factory bus="cxf" id="kc-cxf-endpoint"> <httpj:engine port="8282"> <httpj:handlers> <ref local="securityHandler" /> </httpj:handlers> <httpj:sessionSupport>true</httpj:sessionSupport> </httpj:engine> </httpj:engine-factory> <jaxws:endpoint implementor="org.keycloak.example.ws.ProductImpl" address="http://localhost:8282/ProductServiceCF" depends-on="kc-cxf-endpoint" /> </beans>CXF JAX-RS アプリケーションの場合、唯一の違いは、エンジンファクトリーに依存するエンドポイントの構成にある可能性があります。
<jaxrs:server serviceClass="org.keycloak.example.rs.CustomerService" address="http://localhost:8282/rest" depends-on="kc-cxf-endpoint"> <jaxrs:providers> <bean class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider" /> </jaxrs:providers> </jaxrs:server>-
META-INF/MANIFEST.MFのImport-Packageには、これらのインポートが含まれる必要があります。
META-INF.cxf;version="[2.7,3.2)", META-INF.cxf.osgi;version="[2.7,3.2)";resolution:=optional, org.apache.cxf.bus;version="[2.7,3.2)", org.apache.cxf.bus.spring;version="[2.7,3.2)", org.apache.cxf.bus.resource;version="[2.7,3.2)", org.apache.cxf.transport.http;version="[2.7,3.2)", org.apache.cxf.*;version="[2.7,3.2)", org.springframework.beans.factory.config, org.eclipse.jetty.security;version="[9,10)", org.eclipse.jetty.util.security;version="[9,10)", org.keycloak.*;version="9.0.17.redhat-00001"
2.1.4.8. デフォルトの Jetty Engine での Apache CXF エンドポイントのセキュリティー保護
一部のサービスは、起動時にデプロイされたサーブレットが自動的に含まれる場合があります。このようなサービスの 1 つは、http://localhost:8181/cxf コンテキストで実行している CXF サーブレットです。このようなエンドポイントの保護は複雑になる可能性があります。現在 Red Hat Single Sign-On が使用している 1 つの方法は ServletReregistrationService で、起動時に組み込みサーブレットをアンデプロイし、Red Hat Single Sign-On がセキュア化されたコンテキストに再デプロイできるようにします。
アプリケーション内の構成ファイル OSGI-INF/blueprint/blueprint.xml は、以下のようになります。アプリケーションにエンドポイント固有の JAX-RS customerservice エンドポイントを追加しますが、/cxf コンテキスト全体を保護することに注意してください。
<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jaxrs="http://cxf.apache.org/blueprint/jaxrs"
xsi:schemaLocation="
http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
http://cxf.apache.org/blueprint/jaxrs http://cxf.apache.org/schemas/blueprint/jaxrs.xsd">
<!-- JAXRS Application -->
<bean id="customerBean" class="org.keycloak.example.rs.CxfCustomerService" />
<jaxrs:server id="cxfJaxrsServer" address="/customerservice">
<jaxrs:providers>
<bean class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider" />
</jaxrs:providers>
<jaxrs:serviceBeans>
<ref component-id="customerBean" />
</jaxrs:serviceBeans>
</jaxrs:server>
<!-- Securing of whole /cxf context by unregister default cxf servlet from paxweb and re-register with applied security constraints -->
<bean id="cxfConstraintMapping" class="org.eclipse.jetty.security.ConstraintMapping">
<property name="constraint">
<bean class="org.eclipse.jetty.util.security.Constraint">
<property name="name" value="cst1"/>
<property name="roles">
<list>
<value>user</value>
</list>
</property>
<property name="authenticate" value="true"/>
<property name="dataConstraint" value="0"/>
</bean>
</property>
<property name="pathSpec" value="/cxf/*"/>
</bean>
<bean id="cxfKeycloakPaxWebIntegration" class="org.keycloak.adapters.osgi.PaxWebIntegrationService"
init-method="start" destroy-method="stop">
<property name="bundleContext" ref="blueprintBundleContext" />
<property name="jettyWebXmlLocation" value="/WEB-INF/jetty-web.xml" />
<property name="constraintMappings">
<list>
<ref component-id="cxfConstraintMapping" />
</list>
</property>
</bean>
<bean id="defaultCxfReregistration" class="org.keycloak.adapters.osgi.ServletReregistrationService" depends-on="cxfKeycloakPaxWebIntegration"
init-method="start" destroy-method="stop">
<property name="bundleContext" ref="blueprintBundleContext" />
<property name="managedServiceReference">
<reference interface="org.osgi.service.cm.ManagedService" filter="(service.pid=org.apache.cxf.osgi)" timeout="5000" />
</property>
</bean>
</blueprint>
そのため、デフォルトの CXF HTTP 宛先で実行している他のすべての CXF サービスもセキュア化されます。同様に、アプリケーションがアンデプロイされると、/cxf コンテキスト全体のセキュリティーも保護されなくなります。このため、「別の Jetty Engine で CXF アプリケーションのセキュリティーを保護」で説明されているように、各アプリケーションに独自の Jetty エンジンを使用すると、各アプリケーションのセキュリティーをより詳細に制御できます。
-
WEB-INFディレクトリーは、(プロジェクトが web アプリケーションではない場合でも) プロジェクト内に置く必要がある場合があります。また、Classic WAR アプリケーション と同様の方法で/WEB-INF/keycloak.jsonファイルおよび/WEB-INF/keycloak.jsonファイルを編集する必要もあります。セキュリティー制約がブループリント設定ファイルで宣言されているため、web.xmlファイルは必要ありません。 -
META-INF/MANIFEST.MFのImport-Packageには以下のインポートが含まれる必要があります。
META-INF.cxf;version="[2.7,3.2)", META-INF.cxf.osgi;version="[2.7,3.2)";resolution:=optional, org.apache.cxf.transport.http;version="[2.7,3.2)", org.apache.cxf.*;version="[2.7,3.2)", com.fasterxml.jackson.jaxrs.json;version="[2.5,3)", org.eclipse.jetty.security;version="[9,10)", org.eclipse.jetty.util.security;version="[9,10)", org.keycloak.*;version="9.0.17.redhat-00001", org.keycloak.adapters.jetty;version="9.0.17.redhat-00001", *;resolution:=optional
2.1.4.9. Fuse 管理サービスのセキュリティー保護
2.1.4.9.1. Fuse ターミナルへの SSH 認証の使用
Red Hat Single Sign-On は、主に Web アプリケーションの認証のユースケースに対応しています。ただし、他の Web サービスおよびアプリケーションが Red Hat Single Sign-On で保護されている場合は、SSH などの非 Web 管理サービスを Red Hat Single Sign-On の認証情報で保護するのが最善の方法です。これは、Red Hat Single Sign-On へのリモート接続を可能にする JAAS ログインモジュールを使用して実行できます。また、「リソース所有者のパスワード認証情報」に基づいて認証情報を検証できます。
SSH 認証を有効にするには、以下の手順を実行します。
-
Red Hat Single Sign-On では、SSH 認証に使用されるクライアント (
ssh-jmx-admin-clientなど) を作成します。このクライアントでは、Direct Access Grants EnabledをOnに選択する必要があります。 $FUSE_HOME/etc/org.apache.karaf.shell.cfgファイルで、以下のプロパティーを更新または指定します。sshRealm=keycloak
以下のような内容で
$FUSE_HOME/etc/keycloak-direct-access.jsonファイルを追加します (環境と Red Hat Single Sign-On クライアント設定に基づきます)。{ "realm": "demo", "resource": "ssh-jmx-admin-client", "ssl-required" : "external", "auth-server-url" : "http://localhost:8080/auth", "credentials": { "secret": "password" } }このファイルは、SSH 認証の JAAS レルム
keycloakから JAAS DirectAccessGrantsLoginModule によって使用されるクライアントアプリケーション設定を指定します。Fuse を起動し、
keycloakJAAS レルムをインストールします。最も簡単な方法は、JAAS レルムが事前定義されているkeycloak-jaas機能をインストールすることです。より高いランクの独自の JAAS レルムkeycloakを使用すると、機能の定義済みレルムをオーバーライドできます。詳細は、JBoss Fuse ドキュメント を参照してください。Fuse 端末で以下のコマンドを使用します。
features:addurl mvn:org.keycloak/keycloak-osgi-features/9.0.17.redhat-00001/xml/features features:install keycloak-jaas
端末に以下を入力して、
adminユーザーとして SSH を使用してログインします。ssh -o PubkeyAuthentication=no -p 8101 admin@localhost
-
パスワード
passwordでログインします。
一部のオペレーティングシステムでは、SSH コマンドの -o オプション -o オプション -o HostKeyAlgorithms=+ssh-dss を使用する必要もあります。これは、後の SSH クライアントはデフォルトで ssh-dss アルゴリズムを使用できないためです。しかし、デフォルトでは JBoss Fuse 6.3.0 は現在使用されています。
ユーザーには、すべての操作を実行するためのレルムロール admin、または操作のサブセットを実行するための別のロール (たとえば、読み取り専用の Karaf コマンドのみを実行するようにユーザーを制限する viewer ロール) が必要であることに注意してください。利用可能なロールは $FUSE_HOME/etc/org.apache.karaf.shell.cfg または $FUSE_HOME/etc/system.properties で設定されます。
2.1.4.9.2. JMX 認証の使用
jconsole または他の外部ツールを使用して RMI 経由で JMX にリモートで接続する場合は、JMX 認証が必要な場合があります。jolokia エージェントはデフォルトで hawt.io にインストールされているため、hawt.io/jolokia を使用する方が良いでしょう。詳細は「Hawtio 管理コンソール」を参照してください。
JMX 認証を使用するには、以下の手順を実行します。
$FUSE_HOME/etc/org.apache.karaf.management.cfgファイルで、jmxRealm プロパティーを以下のように変更します。jmxRealm=keycloak
-
上記の SSH セクションで説明されているように、
keycloak-jaas機能をインストールして$FUSE_HOME/etc/keycloak-direct-access.jsonファイルを設定します。 - jconsole では、以下のような URL を使用できます。
service:jmx:rmi://localhost:44444/jndi/rmi://localhost:1099/karaf-root
および認証情報: admin/password (環境に応じて管理者権限を持つユーザーに基づきます)。
2.1.4.10. Hawtio 管理コンソールのセキュリティー保護
Red Hat Single Sign-On で Hawtio 管理コンソールをセキュアにするには、以下の手順を実行します。
これらのプロパティーを
$FUSE_HOME/etc/system.propertiesファイルに追加します。hawtio.keycloakEnabled=true hawtio.realm=keycloak hawtio.keycloakClientConfig=file://${karaf.base}/etc/keycloak-hawtio-client.json hawtio.rolePrincipalClasses=org.keycloak.adapters.jaas.RolePrincipal,org.apache.karaf.jaas.boot.principal.RolePrincipal-
レルムの Red Hat Single Sign-On 管理コンソールでクライアントを作成します。たとえば、Red Hat Single Sign-On の
demoレルムでは、クライアントhawtio-clientを作成し、アクセスタイプとしてpublicを指定し、Hawtio を参照するリダイレクト URI (http://localhost:8181/hawtio/*) を指定します。対応する Web Origin も設定する必要があります (この場合は http://localhost:8181)。 以下の例のような内容を使用して、
$FUSE_HOME/etcディレクトリーにkeycloak-hawtio-client.jsonファイルを作成します。Red Hat Single Sign-On 環境に応じて、realm、resource、およびauth-server-urlプロパティーを変更します。resourceプロパティーは、前のステップで作成したクライアントを参照する必要があります。このファイルは、クライアント (Hawtio JavaScript アプリケーション) で使用されます。{ "realm" : "demo", "resource" : "hawtio-client", "auth-server-url" : "http://localhost:8080/auth", "ssl-required" : "external", "public-client" : true }以下の例のような内容を使用して、
$FUSE_HOME/etcディレクトリーにkeycloak-hawtio.jsonファイルを作成します。Red Hat Single Sign-On 環境に応じて、realmプロパティーおよびauth-server-urlプロパティーを変更します。このファイルは、サーバーのアダプター (JAAS ログインモジュール) 側で使用します。{ "realm" : "demo", "resource" : "jaas", "bearer-only" : true, "auth-server-url" : "http://localhost:8080/auth", "ssl-required" : "external", "use-resource-role-mappings": false, "principal-attribute": "preferred_username" }JBoss Fuse 6.3.0 を起動し、まだ実行していない場合は keycloak 機能をインストールします。Karaf ターミナルのコマンドの例を以下に示します。
features:addurl mvn:org.keycloak/keycloak-osgi-features/9.0.17.redhat-00001/xml/features features:install keycloak
http://localhost:8181/hawtio にアクセスし、Red Hat Single Sign-On レルムからユーザーとしてログインします。
Hawtio に対して正常に認証するには、適切なレルムロールが必要です。利用可能なロールは、
hawtio.rolesの$FUSE_HOME/etc/system.propertiesファイルで設定されます。
2.1.4.10.1. JBoss EAP 6.4 での Hawtio のセキュリティー保護
JBoss EAP 6.4 サーバーで Hawtio を実行するには、以下の手順を実行します。
前述したように Red Hat Single Sign-On を設定します (Hawtio 管理コンソールのセキュア化)。以下が前提となります。
-
Red Hat Single Sign-On レルムの
demoおよびクライアントhawtio-clientがある。 -
Red Hat Single Sign-On が
localhost:8080で実行されている。 -
デプロイされた Hawtio を持つ JBoss EAP 6.4 サーバーは
localhost:8181で実行されます。このサーバーのディレクトリーは、次のステップで$EAP_HOMEと呼ばれます。
-
Red Hat Single Sign-On レルムの
-
JBoss Fuse 6.3.0 バージョンに一致する Hawtio Web アーカイブを
$EAP_HOME/standalone/configurationディレクトリーにコピーします。Hawtio のデプロイメントに関する詳細は、Fuse Hawtio のドキュメント を参照してください。 -
上記の内容の
keycloak-hawtio.jsonおよびkeycloak-hawtio-client.jsonファイルを$EAP_HOME/standalone/configurationディレクトリーにコピーします。 - JBoss アダプターのドキュメント で説明されているように、Red Hat Single Sign-On アダプターサブシステムを JBoss EAP 6.4 サーバーにインストールします。
$EAP_HOME/standalone/configuration/standalone.xmlファイルで、以下の例のようにシステムプロパティーを設定します。<extensions> ... </extensions> <system-properties> <property name="hawtio.authenticationEnabled" value="true" /> <property name="hawtio.realm" value="hawtio" /> <property name="hawtio.roles" value="admin,viewer" /> <property name="hawtio.rolePrincipalClasses" value="org.keycloak.adapters.jaas.RolePrincipal" /> <property name="hawtio.keycloakEnabled" value="true" /> <property name="hawtio.keycloakClientConfig" value="${jboss.server.config.dir}/keycloak-hawtio-client.json" /> <property name="hawtio.keycloakServerConfig" value="${jboss.server.config.dir}/keycloak-hawtio.json" /> </system-properties>Hawtio レルムを
security-domainsセクションの同じファイルに追加します。<security-domain name="hawtio" cache-type="default"> <authentication> <login-module code="org.keycloak.adapters.jaas.BearerTokenLoginModule" flag="required"> <module-option name="keycloak-config-file" value="${hawtio.keycloakServerConfig}"/> </login-module> </authentication> </security-domain>Secure-deploymentセクションhawtioをアダプターサブシステムに追加します。これにより、Hawtio WAR が JAAS ログインモジュールクラスを検索できるようになります。<subsystem xmlns="urn:jboss:domain:keycloak:1.1"> <secure-deployment name="your-hawtio-webarchive.war" /> </subsystem>Hawtio を使用して JBoss EAP 6.4 サーバーを再起動します。
cd $EAP_HOME/bin ./standalone.sh -Djboss.socket.binding.port-offset=101
- Hawtio (http://localhost:8181/hawtio) にアクセスします。Red Hat Single Sign-On でセキュリティーが保護されています。
2.1.5. JBoss Fuse 7 Adapter
Red Hat Single Sign-On は、JBoss Fuse 7 内で実行している Web アプリケーションのセキュリティー保護をサポートします。
JBoss Fuse 7.x は Undertow HTTP エンジン にバンドルされ、Undertow はさまざまな種類の Web アプリケーションの実行に使用されるため、JBoss Fuse 7 は基本的に JBoss EAP 7 アダプター と同じ Undertow アダプターを使用します。
唯一サポートされるのは Fuse 7 の最新バージョンです。以前のバージョンの Fuse 7 を使用する場合は、一部の関数が正常に機能しない可能性があります。特に、統合は 7.0.1 未満の Fuse 7 バージョンですべてのバージョンで機能しません。
以下の項目のセキュリティーは Fuse でサポートされます。
- Pax Web War Extender を使用して Fuse にデプロイされた Classic WAR アプリケーション
- Pax Web Whiteboard Extender で Fuse に OSGI サービスとしてデプロイされたサーブレットと、標準の OSGi Enterprise HTTP Service である org.osgi.service.http.HttpService#registerServlet() 経由で登録された追加サーブレット
- Camel Undertow コンポーネントで実行している Apache Camel Undertow エンドポイント
- 独自の個別の Undertow エンジンで実行される Apache CXF エンドポイント
- CXF サーブレットによって提供されるデフォルトのエンジンで実行される Apache CXF エンドポイント
- SSH および JMX 管理者アクセス
- Hawtio 管理コンソール
2.1.5.1. Fuse 7 での Web アプリケーションのセキュリティー保護
最初に Red Hat Single Sign-On Karaf 機能をインストールする必要があります。次に、セキュリティー保護するアプリケーションのタイプに応じて手順を実行する必要があります。参照されるすべての Web アプリケーションには、Red Hat Single Sign-On の Undertow 認証メカニズムを基盤の Web サーバーに挿入する必要があります。これを行う手順は、アプリケーションの種別によって異なります。詳細は、以下を参照してください。
2.1.5.2. Keycloak 機能のインストール
最初に、JBoss Fuse 環境に keycloak-pax-http-undertow 機能および keycloak-jaas 機能をインストールする必要があります。keycloak-pax-http-undertow 機能には、Fuse アダプターとサードパーティーのすべての依存関係が含まれます。keycloak-jaas には、SSH および JMX 認証にレルムで使用される JAAS モジュールが含まれます。Maven リポジトリーまたはアーカイブからインストールできます。
2.1.5.2.1. Maven リポジトリーからのインストール
前提条件として、オンラインで Maven リポジトリーにアクセスできる必要がある。
Red Hat Single Sign-On では、最初に適切な Maven リポジトリーを設定して、アーティファクトをインストールできます。詳細は、「JBoss Enterprise Maven リポジトリーページ」を参照してください。
Maven リポジトリーが https://maven.repository.redhat.com/ga/ であるとします。 $FUSE_HOME/etc/org.ops4j.pax.url.mvn.cfg ファイルに以下を追加し、サポートされているリポジトリーの一覧にリポジトリーを追加します。以下に例を示します。
config:edit org.ops4j.pax.url.mvn config:property-append org.ops4j.pax.url.mvn.repositories ,https://maven.repository.redhat.com/ga/@id=redhat.product.repo config:update feature:repo-refresh
Maven リポジトリーを使用して keycloak 機能をインストールするには、以下の手順を実行します。
JBoss Fuse 7.x を起動し、Karaf 端末タイプで以下を行います。
feature:repo-add mvn:org.keycloak/keycloak-osgi-features/9.0.17.redhat-00001/xml/features feature:install keycloak-pax-http-undertow keycloak-jaas
Undertow 機能のインストールが必要になる場合があります。
feature:install pax-http-undertow
- 機能がインストールされていることを確認します。
feature:list | grep keycloak
2.1.5.2.2. ZIP バンドルからのインストール
これは、オフラインの場合、または Maven を使用して JAR ファイルやその他のアーティファクトを取得したくない場合に便利です。
ZIP アーカイブから Fuse アダプターをインストールするには、以下の手順を行います。
- Red Hat Single Sign-On Fuse アダプター ZIP アーカイブをダウンロードします。
これを JBoss Fuse のルートディレクトリーに展開します。次に、依存関係が
systemディレクトリーにインストールされます。既存の jar ファイルをすべて上書きできます。これは JBoss Fuse 7.x に使用します。
cd /path-to-fuse/fuse-karaf-7.x unzip -q /path-to-adapter-zip/rh-sso-7.4.10.GA-fuse-adapter.zip
Fuse を起動し、fuse/karaf ターミナルでこれらのコマンドを実行します。
feature:repo-add mvn:org.keycloak/keycloak-osgi-features/9.0.17.redhat-00001/xml/features feature:install keycloak-pax-http-undertow keycloak-jaas
-
対応する Undertow アダプターをインストールします。アーティファクトは JBoss Fuse
systemディレクトリーで直接利用できるため、Maven リポジトリーを使用する必要はありません。
2.1.5.3. クラシック WAR アプリケーションのセキュリティー保護
WAR アプリケーションをセキュアにするのに必要な手順は次のとおりです。
/WEB-INF/web.xmlファイルで、必要を宣言します。- <security-constraint> 要素のセキュリティー制約
-
<login-config> 要素のログイン設定。
<auth-method>がKEYCLOAKであることを確認します。 <security-role> 要素のセキュリティーロール
以下に例を示します。
<?xml version="1.0" encoding="UTF-8"?> <web-app xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd" version="3.0"> <module-name>customer-portal</module-name> <welcome-file-list> <welcome-file>index.html</welcome-file> </welcome-file-list> <security-constraint> <web-resource-collection> <web-resource-name>Customers</web-resource-name> <url-pattern>/customers/*</url-pattern> </web-resource-collection> <auth-constraint> <role-name>user</role-name> </auth-constraint> </security-constraint> <login-config> <auth-method>KEYCLOAK</auth-method> <realm-name>does-not-matter</realm-name> </login-config> <security-role> <role-name>admin</role-name> </security-role> <security-role> <role-name>user</role-name> </security-role> </web-app>
WAR の
/WEB-INF/ディレクトリー内で、新しいファイル keycloak.json を作成します。この設定ファイルの形式は、「Java アダプター設定」のセクションで説明されています。「外部アダプターの設定」で説明されているように、このファイルを外部から利用できるようにすることもできます。以下に例を示します。
{ "realm": "demo", "resource": "customer-portal", "auth-server-url": "http://localhost:8080/auth", "ssl-required" : "external", "credentials": { "secret": "password" } }- Fuse 6 アダプターとは異なり、MANIFEST.MF には特別な OSGi インポートは必要ありません。
2.1.5.3.1. 設定リゾルバー
keycloak.json アダプター設定ファイルは、バンドル内に保存する (デフォルトの動作) が、ファイルシステムのディレクトリーに保存することができます。設定ファイルの実際のソースを指定するには、keycloak.config.resolver デプロイメントパラメーターを希望の設定リゾルバークラスに設定します。たとえば、従来の WAR アプリケーションで、以下のように web.xml ファイルに keycloak.config.resolver コンテキストパラメーターを設定します。
<context-param>
<param-name>keycloak.config.resolver</param-name>
<param-value>org.keycloak.adapters.osgi.PathBasedKeycloakConfigResolver</param-value>
</context-param>
以下のリゾルバーは keycloak.config.resolver で利用できます。
- org.keycloak.adapters.osgi.BundleBasedKeycloakConfigResolver
-
これはデフォルトのリゾルバーです。設定ファイルは、セキュリティーが保護されている OSGi バンドル内に想定されるものです。デフォルトでは、
WEB-INF/keycloak.jsonという名前のファイルを読み込みますが、このファイル名はconfigLocationプロパティーで設定できます。 - org.keycloak.adapters.osgi.PathBasedKeycloakConfigResolver
このリゾルバーは、
keycloak.configシステムプロパティーで指定されるディレクトリー内の<your_web_context>-keycloak.jsonという名前のファイルを検索します。keycloak.configが設定されていない場合は、代わりにkaraf.etcシステムプロパティーが使用されます。たとえば、Web アプリケーションがコンテキスト
my-portalにデプロイされている場合、アダプター設定は、${keycloak.config}/my-portal-keycloak.jsonファイルまたは${karaf.etc}/my-portal-keycloak.jsonファイルから読み込まれます。- org.keycloak.adapters.osgi.HierarchicalPathBasedKeycloakConfigResolver
このリゾルバーは、上記の
PathBasedKeycloakConfigResolverと似ています。指定されたURIパスについて、構成場所が最も具体的なものから順にチェックされます。たとえば、
/my/web-app/contextURI の場合は、最初の値が見つかるまで、以下の設定場所が検索されます。-
${karaf.etc}/my-web-app-context-keycloak.json -
${karaf.etc}/my-web-app-keycloak.json -
${karaf.etc}/my-keycloak.json -
${karaf.etc}/keycloak.json
-
2.1.5.4. OSGI サービスとしてデプロイされたサーブレットのセキュア化
従来の WAR アプリケーションとしてデプロイされていない OSGI バンドルプロジェクトにサーブレットクラスがある場合は、このメソッドを使用できます。Fuse は Pax Web Whiteboard Extender を使用して、このようなサーブレットを Web アプリケーションとしてデプロイします。
Red Hat Single Sign-On でサーブレットをセキュアにするには、以下の手順を実行します。
Red Hat Single Sign-On は、
org.keycloak.adapters.osgi.undertow.PaxWebIntegrationServiceを提供します。これにより、アプリケーションの認証方法とセキュリティー制約を設定できます。このようなサービスをアプリケーション内のOSGI-INF/blueprint/blueprint.xmlファイルで宣言する必要があります。サーブレットはそれに依存する必要があることに注意してください。設定例:<?xml version="1.0" encoding="UTF-8"?> <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd"> <bean id="servletConstraintMapping" class="org.keycloak.adapters.osgi.PaxWebSecurityConstraintMapping"> <property name="roles"> <list> <value>user</value> </list> </property> <property name="authentication" value="true"/> <property name="url" value="/product-portal/*"/> </bean> <!-- This handles the integration and setting the login-config and security-constraints parameters --> <bean id="keycloakPaxWebIntegration" class="org.keycloak.adapters.osgi.undertow.PaxWebIntegrationService" init-method="start" destroy-method="stop"> <property name="bundleContext" ref="blueprintBundleContext" /> <property name="constraintMappings"> <list> <ref component-id="servletConstraintMapping" /> </list> </property> </bean> <bean id="productServlet" class="org.keycloak.example.ProductPortalServlet" depends-on="keycloakPaxWebIntegration" /> <service ref="productServlet" interface="javax.servlet.Servlet"> <service-properties> <entry key="alias" value="/product-portal" /> <entry key="servlet-name" value="ProductServlet" /> <entry key="keycloak.config.file" value="/keycloak.json" /> </service-properties> </service> </blueprint>-
(プロジェクトが Web アプリケーションではない場合でも) プロジェクト内に
WEB-INFディレクトリーがあり、Classic WAR application で説明されているように、/WEB-INF/keycloak.jsonファイルを作成します。security-constraints が Blueprint 設定ファイルで宣言されているため、web.xmlファイルは必要ありません。
-
(プロジェクトが Web アプリケーションではない場合でも) プロジェクト内に
- Fuse 6 アダプターとは異なり、MANIFEST.MF には特別な OSGi インポートは必要ありません。
2.1.5.5. Apache Camel アプリケーションのセキュリティー保護
Blueprint で適切なセキュリティー制約を注入し、使用されているコンポーネントを undertow-keycloak に更新することで、camel-undertow コンポーネントで実装された Apache Camel エンドポイントのセキュリティーを保護できます。OSGI-INF/blueprint/blueprint.xml ファイルを、以下のような設定を持つ Camel アプリケーションに追加する必要があります。ロール、セキュリティー制約のマッピング、およびアダプター設定は、お使いの環境とニーズに合わせて若干異なる可能性があります。
undertow-keycloak コンポーネントは、標準の undertow コンポーネントと比較すると、2 つの新しいプロパティーを追加します。
-
configResolverは、Red Hat Single Sign-On アダプター設定を提供するリゾルバー Bean です。利用可能なリゾルバーは Configuration Resolvers セクションに記載されています。 -
allowedRolesはロールのコンマ区切りの一覧です。サービスにアクセスするユーザーは、アクセスを許可するために少なくとも 1 つのロールが必要です。
以下に例を示します。
<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:camel="http://camel.apache.org/schema/blueprint"
xsi:schemaLocation="
http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
http://camel.apache.org/schema/blueprint http://camel.apache.org/schema/blueprint/camel-blueprint-2.17.1.xsd">
<bean id="keycloakConfigResolver" class="org.keycloak.adapters.osgi.BundleBasedKeycloakConfigResolver" >
<property name="bundleContext" ref="blueprintBundleContext" />
</bean>
<bean id="helloProcessor" class="org.keycloak.example.CamelHelloProcessor" />
<camelContext id="blueprintContext"
trace="false"
xmlns="http://camel.apache.org/schema/blueprint">
<route id="httpBridge">
<from uri="undertow-keycloak:http://0.0.0.0:8383/admin-camel-endpoint?matchOnUriPrefix=true&configResolver=#keycloakConfigResolver&allowedRoles=admin" />
<process ref="helloProcessor" />
<log message="The message from camel endpoint contains ${body}"/>
</route>
</camelContext>
</blueprint>-
META-INF/MANIFEST.MFのImport-Packageには以下のインポートが含まれる必要があります。
javax.servlet;version="[3,4)", javax.servlet.http;version="[3,4)", javax.net.ssl, org.apache.camel.*, org.apache.camel;version="[2.13,3)", io.undertow.*, org.keycloak.*;version="9.0.17.redhat-00001", org.osgi.service.blueprint, org.osgi.service.blueprint.container
2.1.5.6. Camel RestDSL
Camel RestDSL は、REST エンドポイントを定義するのに使用される Camel 機能です。しかし、引き続き特定の実装クラスを使用し、Red Hat Single Sign-On との統合方法を説明します。
インテグレーションメカニズムを設定する方法は、RestDSL 定義のルートを設定する Camel コンポーネントに依存します。
以下の例は、undertow-keycloak コンポーネントを使用して統合を設定する方法を示しています。これには、上述の Blueprint の例で定義された一部の Bean への参照が含まれます。
<camelContext id="blueprintContext"
trace="false"
xmlns="http://camel.apache.org/schema/blueprint">
<!--the link with Keycloak security handlers happens by using undertow-keycloak component -->
<restConfiguration apiComponent="undertow-keycloak" contextPath="/restdsl" port="8484">
<endpointProperty key="configResolver" value="#keycloakConfigResolver" />
<endpointProperty key="allowedRoles" value="admin,superadmin" />
</restConfiguration>
<rest path="/hello" >
<description>Hello rest service</description>
<get uri="/{id}" outType="java.lang.String">
<description>Just a hello</description>
<to uri="direct:justDirect" />
</get>
</rest>
<route id="justDirect">
<from uri="direct:justDirect"/>
<process ref="helloProcessor" />
<log message="RestDSL correctly invoked ${body}"/>
<setBody>
<constant>(__This second sentence is returned from a Camel RestDSL endpoint__)</constant>
</setBody>
</route>
</camelContext>2.1.5.7. 別の Undertow エンジンでの Apache CXF エンドポイントのセキュリティー保護
別の Undertow エンジンで Red Hat Single Sign-On によってセキュア化された CXF エンドポイントを実行するには、以下の手順を実行します。
OSGI-INF/blueprint/blueprint.xmlをアプリケーションに追加し、Camel 設定 と同様に適切な設定リゾルバー Bean を追加します。httpu:engine-factoryでは、camel 設定を使用したorg.keycloak.adapters.osgi.undertow.CxfKeycloakAuthHandlerハンドラーを宣言します。CFX JAX-WS アプリケーションの設定は以下のようになります。<?xml version="1.0" encoding="UTF-8"?> <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:jaxws="http://cxf.apache.org/blueprint/jaxws" xmlns:cxf="http://cxf.apache.org/blueprint/core" xmlns:httpu="http://cxf.apache.org/transports/http-undertow/configuration". xsi:schemaLocation=" http://cxf.apache.org/transports/http-undertow/configuration http://cxf.apache.org/schemas/configuration/http-undertow.xsd http://cxf.apache.org/blueprint/core http://cxf.apache.org/schemas/blueprint/core.xsd http://cxf.apache.org/blueprint/jaxws http://cxf.apache.org/schemas/blueprint/jaxws.xsd"> <bean id="keycloakConfigResolver" class="org.keycloak.adapters.osgi.BundleBasedKeycloakConfigResolver" > <property name="bundleContext" ref="blueprintBundleContext" /> </bean> <httpu:engine-factory bus="cxf" id="kc-cxf-endpoint"> <httpu:engine port="8282"> <httpu:handlers> <bean class="org.keycloak.adapters.osgi.undertow.CxfKeycloakAuthHandler"> <property name="configResolver" ref="keycloakConfigResolver" /> </bean> </httpu:handlers> </httpu:engine> </httpu:engine-factory> <jaxws:endpoint implementor="org.keycloak.example.ws.ProductImpl" address="http://localhost:8282/ProductServiceCF" depends-on="kc-cxf-endpoint"/> </blueprint>CXF JAX-RS アプリケーションの場合、唯一の違いは、エンジンファクトリーに依存するエンドポイントの構成にある可能性があります。
<jaxrs:server serviceClass="org.keycloak.example.rs.CustomerService" address="http://localhost:8282/rest" depends-on="kc-cxf-endpoint"> <jaxrs:providers> <bean class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider" /> </jaxrs:providers> </jaxrs:server>-
META-INF/MANIFEST.MFのImport-Packageには、これらのインポートが含まれる必要があります。
META-INF.cxf;version="[2.7,3.3)", META-INF.cxf.osgi;version="[2.7,3.3)";resolution:=optional, org.apache.cxf.bus;version="[2.7,3.3)", org.apache.cxf.bus.spring;version="[2.7,3.3)", org.apache.cxf.bus.resource;version="[2.7,3.3)", org.apache.cxf.transport.http;version="[2.7,3.3)", org.apache.cxf.*;version="[2.7,3.3)", org.springframework.beans.factory.config, org.keycloak.*;version="9.0.17.redhat-00001"
2.1.5.8. デフォルトの Undertow エンジンでの Apache CXF エンドポイントのセキュリティー保護
一部のサービスは、起動時にデプロイされたサーブレットが自動的に含まれる場合があります。このようなサービスの 1 つは、http://localhost:8181/cxf コンテキストで実行している CXF サーブレットです。Fuse の Pax Web は、設定 admin を使用した既存のコンテキストの変更をサポートします。これは、Red Hat Single Sign-On によるエンドポイントを保護するのに使用できます。
アプリケーション内の構成ファイル OSGI-INF/blueprint/blueprint.xml は、以下のようになります。アプリケーションへのエンドポイント固有の JAX-RS customerservice エンドポイントを追加することに注意してください。
<?xml version="1.0" encoding="UTF-8"?>
<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jaxrs="http://cxf.apache.org/blueprint/jaxrs"
xsi:schemaLocation="
http://www.osgi.org/xmlns/blueprint/v1.0.0 http://www.osgi.org/xmlns/blueprint/v1.0.0/blueprint.xsd
http://cxf.apache.org/blueprint/jaxrs http://cxf.apache.org/schemas/blueprint/jaxrs.xsd">
<!-- JAXRS Application -->
<bean id="customerBean" class="org.keycloak.example.rs.CxfCustomerService" />
<jaxrs:server id="cxfJaxrsServer" address="/customerservice">
<jaxrs:providers>
<bean class="com.fasterxml.jackson.jaxrs.json.JacksonJsonProvider" />
</jaxrs:providers>
<jaxrs:serviceBeans>
<ref component-id="customerBean" />
</jaxrs:serviceBeans>
</jaxrs:server>
</blueprint>
${karaf.etc}/org.ops4j.pax.web.context-anyName.cfg ファイル を作成する必要があります。これは、pax-web-runtime バンドルによって追跡されるファクトリー PID 設定として処理されます。このような設定には、標準の web.xml のプロパティーの一部に対応する以下のプロパティーが含まれる場合があります。
bundle.symbolicName = org.apache.cxf.cxf-rt-transports-http context.id = default context.param.keycloak.config.resolver = org.keycloak.adapters.osgi.HierarchicalPathBasedKeycloakConfigResolver login.config.authMethod = KEYCLOAK security.cxf.url = /cxf/customerservice/* security.cxf.roles = admin, user
設定管理ファイルで利用可能なプロパティーの完全な説明は、Fuse のドキュメントを参照してください。上記のプロパティーは以下の意味になります。
bundle.symbolicNameおよびcontext.id-
org.ops4j.pax.web.service.WebContainer内のバンドルおよびそのデプロイメントコンテキストを特定します。 context.param.keycloak.config.resolver-
keycloak.config.resolverコンテキストパラメーターの値を、従来の WAR のweb.xmlと同じバンドルに提供します。利用可能なリゾルバーは、「設定リゾルバー」を参照してください。 login.config.authMethod-
認証方法。
KEYCLOAKでなければなりません。 security.anyName.urlおよびsecurity.anyName.roles個別のセキュリティー制約のプロパティーの値は、
web.xmlのsecurity-constraint/web-resource-collection/url-patternおよびsecurity-constraint/auth-constraint/role-nameに設定されます。ロールは、コンマとその周囲の空白で区切られます。anyName識別子は任意ですが、同じセキュリティー制約の個別のプロパティーに一致する必要があります。注記一部の Fuse バージョンには、ロールを
", "(コンマと単一スペース) で区切る必要のあるバグが含まれています。ロールを分離するには、必ずこの表記を使用してください。
META-INF/MANIFEST.MF の Import-Package には、少なくとも以下のインポートが含まれている必要があります。
javax.ws.rs;version="[2,3)",
META-INF.cxf;version="[2.7,3.3)",
META-INF.cxf.osgi;version="[2.7,3.3)";resolution:=optional,
org.apache.cxf.transport.http;version="[2.7,3.3)",
org.apache.cxf.*;version="[2.7,3.3)",
com.fasterxml.jackson.jaxrs.json;version="${jackson.version}"2.1.5.9. Fuse 管理サービスのセキュリティー保護
2.1.5.9.1. Fuse ターミナルへの SSH 認証の使用
Red Hat Single Sign-On は、主に Web アプリケーションの認証のユースケースに対応しています。ただし、他の Web サービスおよびアプリケーションが Red Hat Single Sign-On で保護されている場合は、SSH などの非 Web 管理サービスを Red Hat Single Sign-On の認証情報で保護するのが最善の方法です。これは、Red Hat Single Sign-On へのリモート接続を可能にする JAAS ログインモジュールを使用して実行できます。また、「リソース所有者のパスワード認証情報」に基づいて認証情報を検証できます。
SSH 認証を有効にするには、以下の手順を実行します。
-
Red Hat Single Sign-On では、SSH 認証に使用されるクライアント (
ssh-jmx-admin-clientなど) を作成します。このクライアントでは、Direct Access Grants EnabledをOnに選択する必要があります。 $FUSE_HOME/etc/org.apache.karaf.shell.cfgファイルで、以下のプロパティーを更新または指定します。sshRealm=keycloak
以下のような内容で
$FUSE_HOME/etc/keycloak-direct-access.jsonファイルを追加します (環境と Red Hat Single Sign-On クライアント設定に基づきます)。{ "realm": "demo", "resource": "ssh-jmx-admin-client", "ssl-required" : "external", "auth-server-url" : "http://localhost:8080/auth", "credentials": { "secret": "password" } }このファイルは、SSH 認証の JAAS レルム
keycloakから JAAS DirectAccessGrantsLoginModule によって使用されるクライアントアプリケーション設定を指定します。Fuse を起動し、
keycloakJAAS レルムをインストールします。最も簡単な方法は、JAAS レルムが事前定義されているkeycloak-jaas機能をインストールすることです。より高いランクの独自の JAAS レルムkeycloakを使用すると、機能の定義済みレルムをオーバーライドできます。詳細は、JBoss Fuse ドキュメント を参照してください。Fuse 端末で以下のコマンドを使用します。
features:addurl mvn:org.keycloak/keycloak-osgi-features/9.0.17.redhat-00001/xml/features features:install keycloak-jaas
端末に以下を入力して、
adminユーザーとして SSH を使用してログインします。ssh -o PubkeyAuthentication=no -p 8101 admin@localhost
-
パスワード
passwordでログインします。
一部のオペレーティングシステムでは、SSH コマンドの -o オプション -o オプション -o HostKeyAlgorithms=+ssh-dss を使用する必要もあります。これは、後の SSH クライアントはデフォルトで ssh-dss アルゴリズムを使用できないためです。しかし、デフォルトでは JBoss Fuse 7.x で使用されています。
ユーザーには、すべての操作を実行するためのレルムロール admin、または操作のサブセットを実行するための別のロール (たとえば、読み取り専用の Karaf コマンドのみを実行するようにユーザーを制限する viewer ロール) が必要であることに注意してください。利用可能なロールは $FUSE_HOME/etc/org.apache.karaf.shell.cfg または $FUSE_HOME/etc/system.properties で設定されます。
2.1.5.9.2. JMX 認証の使用
jconsole または他の外部ツールを使用して RMI 経由で JMX にリモートで接続する場合は、JMX 認証が必要な場合があります。jolokia エージェントはデフォルトで hawt.io にインストールされているため、hawt.io/jolokia を使用する方が良いでしょう。詳細は「Hawtio 管理コンソール」を参照してください。
JMX 認証を使用するには、以下の手順を実行します。
$FUSE_HOME/etc/org.apache.karaf.management.cfgファイルで、jmxRealm プロパティーを以下のように変更します。jmxRealm=keycloak
-
上記の SSH セクションで説明されているように、
keycloak-jaas機能をインストールして$FUSE_HOME/etc/keycloak-direct-access.jsonファイルを設定します。 - jconsole では、以下のような URL を使用できます。
service:jmx:rmi://localhost:44444/jndi/rmi://localhost:1099/karaf-root
および認証情報: admin/password (環境に応じて管理者権限を持つユーザーに基づきます)。
2.1.5.10. Hawtio 管理コンソールのセキュリティー保護
Red Hat Single Sign-On で Hawtio 管理コンソールをセキュアにするには、以下の手順を実行します。
-
レルムの Red Hat Single Sign-On 管理コンソールでクライアントを作成します。たとえば、Red Hat Single Sign-On の
demoレルムでは、クライアントhawtio-clientを作成し、アクセスタイプとしてpublicを指定し、Hawtio を参照するリダイレクト URI (http://localhost:8181/hawtio/*) を指定します。対応する Web Origin (この場合は http://localhost:8181) を設定します。hawtio-clientクライアント詳細の Scope タブにある account クライアントの view-profile クライアントロールを含むように、クライアントスコープマッピングを設定します。 以下の例のような内容を使用して、
$FUSE_HOME/etcディレクトリーにkeycloak-hawtio-client.jsonファイルを作成します。Red Hat Single Sign-On 環境に応じて、realm、resource、およびauth-server-urlプロパティーを変更します。resourceプロパティーは、前のステップで作成したクライアントを参照する必要があります。このファイルは、クライアント (Hawtio JavaScript アプリケーション) で使用されます。{ "realm" : "demo", "clientId" : "hawtio-client", "url" : "http://localhost:8080/auth", "ssl-required" : "external", "public-client" : true }以下の例のような内容を使用して、
$FUSE_HOME/etcディレクトリーにkeycloak-direct-access.jsonファイルを作成します。Red Hat Single Sign-On 環境に応じて、realmプロパティーおよびurlプロパティーを変更します。このファイルは JavaScript クライアントによって使用されます。{ "realm" : "demo", "resource" : "ssh-jmx-admin-client", "auth-server-url" : "http://localhost:8080/auth", "ssl-required" : "external", "credentials": { "secret": "password" } }以下の例のような内容を使用して、
$FUSE_HOME/etcディレクトリーにkeycloak-hawtio.jsonファイルを作成します。Red Hat Single Sign-On 環境に応じて、realmプロパティーおよびauth-server-urlプロパティーを変更します。このファイルは、サーバーのアダプター (JAAS ログインモジュール) 側で使用します。{ "realm" : "demo", "resource" : "jaas", "bearer-only" : true, "auth-server-url" : "http://localhost:8080/auth", "ssl-required" : "external", "use-resource-role-mappings": false, "principal-attribute": "preferred_username" }JBoss Fuse 7.x を起動し、Keycloak 機能をインストールし ます。次に、Karaf ターミナルで以下を入力します。
system:property -p hawtio.keycloakEnabled true system:property -p hawtio.realm keycloak system:property -p hawtio.keycloakClientConfig file://\${karaf.base}/etc/keycloak-hawtio-client.json system:property -p hawtio.rolePrincipalClasses org.keycloak.adapters.jaas.RolePrincipal,org.apache.karaf.jaas.boot.principal.RolePrincipal restart io.hawt.hawtio-warhttp://localhost:8181/hawtio にアクセスし、Red Hat Single Sign-On レルムからユーザーとしてログインします。
Hawtio に対して正常に認証するには、適切なレルムロールが必要です。利用可能なロールは、
hawtio.rolesの$FUSE_HOME/etc/system.propertiesファイルで設定されます。
2.1.6. Spring Boot アダプター
Spring Boot アプリケーションのセキュリティーを保護するには、Keycloak Spring Boot アダプター JAR をアプリケーションに追加する必要があります。その後、通常の Spring Boot 設定 (application.properties) を使用して追加の設定を提供する必要があります。以下の手順を実施します。
Spring Boot アダプターは非推奨となり、RH-SSO の 8.0 以降のバージョンには含まれません。このアダプターは、RH-SSO 7.x のライフサイクル期間、メンテナンスされます。ユーザーは Spring Security に移行して、Spring Boot アプリケーションを RH-SSO と統合する必要があります。
2.1.6.1. アダプターのインストール
Keycloak Spring Boot アダプターは Spring Boot の自動設定を活用するため、Keycloak Spring Boot スターターをプロジェクトに追加する必要があります。
Maven を使用して追加するには、以下を依存関係に追加します。
<dependency>
<groupId>org.keycloak</groupId>
<artifactId>keycloak-spring-boot-starter</artifactId>
</dependency>アダプター BOM 依存関係を追加します。
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.keycloak.bom</groupId>
<artifactId>keycloak-adapter-bom</artifactId>
<version>9.0.17.redhat-00001</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>現在、以下の埋め込みコンテナーはサポートされており、Starter の使用時には追加の依存関係は必要ありません。
- Tomcat
- Undertow
- Jetty
2.1.6.2. 必要な Spring Boot アダプター設定
本セクションでは、Keycloak を使用するように Spring Boot アプリケーションを設定する方法を説明します。
keycloak.json ファイルの代わりに、通常の Spring Boot 設定を介して Spring Boot アダプターのレルムを設定します。以下に例を示します。
keycloak.realm = demorealm keycloak.auth-server-url = http://127.0.0.1:8080/auth keycloak.ssl-required = external keycloak.resource = demoapp keycloak.credentials.secret = 11111111-1111-1111-1111-111111111111 keycloak.use-resource-role-mappings = true
keycloak.enabled = false を設定して、Keycloak Spring Boot Adapter (テストなど) を無効できます。
Policy Enforcer を設定するには、keycloak.json とは異なり、policy-enforcer ではなく policy-enforcer-config を使用する必要があります。
また、通常 web.xml にある Java EE セキュリティー設定を指定する必要があります。Spring Boot Adapter は login-method を KEYCLOAK に設定し、起動時に security-constraints を設定します。以下は、設定例です。
keycloak.securityConstraints[0].authRoles[0] = admin keycloak.securityConstraints[0].authRoles[1] = user keycloak.securityConstraints[0].securityCollections[0].name = insecure stuff keycloak.securityConstraints[0].securityCollections[0].patterns[0] = /insecure keycloak.securityConstraints[1].authRoles[0] = admin keycloak.securityConstraints[1].securityCollections[0].name = admin stuff keycloak.securityConstraints[1].securityCollections[0].patterns[0] = /admin
Spring アプリケーションを WAR としてデプロイする予定の場合は、Spring Boot アダプターを使用せず、使用しているアプリケーションサーバーまたはサーブレットコンテナーの専用アダプターを使用してください。Spring Boot には web.xml ファイルも含まれている必要があります。
2.1.7. Java Servlet Filter Adapter
Java Servlet アプリケーションをプラットフォームにデプロイする場合は、Red Hat Single Sign-On アダプターがないため、サーブレットフィルターアダプターを使用できます。このアダプターは、他のアダプターとは異なります。web.xml ではセキュリティー制約を定義しません。代わりに、Red Hat Single Sign-On サーブレットフィルターアダプターを使用してフィルターマッピングを定義し、セキュリティーを保護する url パターンを保護します。
Backchannel ログアウトの動作は、標準アダプターとは少々異なります。HTTP セッションを無効にする代わりに、セッション ID をログアウトとしてマークします。セッション ID に基づいて HTTP セッションを無効にする標準的な方法はありません。
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
version="3.0">
<module-name>application</module-name>
<filter>
<filter-name>Keycloak Filter</filter-name>
<filter-class>org.keycloak.adapters.servlet.KeycloakOIDCFilter</filter-class>
</filter>
<filter-mapping>
<filter-name>Keycloak Filter</filter-name>
<url-pattern>/keycloak/*</url-pattern>
<url-pattern>/protected/*</url-pattern>
</filter-mapping>
</web-app>上記のスニペットには、url-patterns が 2 つあります。/protected/* は保護する必要のあるファイルですが、/keycloak/* url-pattern は Red Hat Single Sign-On サーバーからコールバックを処理します。
構成された url-patternsの 下の一部のパスを除外する必要がある場合は、フィルターの init パラメーター keycloak.config.skipPatternを使用して、keycloak フィルターがフィルターチェーンにすぐに委譲するパスパターンを記述する正規表現を構成できます。デフォルトでは skipPattern が設定されていません。
パターンは、context-path なしで requestURI に対して一致します。コンテキストパス /myapp を指定すると、/myapp/index.html のリクエストはスキップパターンに対して /index.html と照合されます。
<init-param>
<param-name>keycloak.config.skipPattern</param-name>
<param-value>^/(path1|path2|path3).*</param-value>
</init-param>フィルターの url-pattern で対応しているセキュアなセクションを参照する管理 URL を使用して、Red Hat Single Sign-On 管理コンソールでクライアントを設定する必要があります。
管理 URL は、バックチャネルログアウトなどを行うための管理 URL へのコールバックを作成します。この例の管理 URL は http[s]://hostname/{context-root}/keycloak となります。
Red Hat Single Sign-On フィルターには、他のアダプターと同じ設定パラメーターがあります。ただし、コンテキストパラメーターではなく、フィルター init パラメーターとして定義する必要があります。
このフィルターを使用するには、この maven アーティファクトを WAR pom に組み込みます。
<dependency>
<groupId>org.keycloak</groupId>
<artifactId>keycloak-servlet-filter-adapter</artifactId>
<version>9.0.17.redhat-00001</version>
</dependency>2.1.8. セキュリティコンテキスト
KeycloakSecurityContext インターフェースは、トークンに直接アクセスする必要がある場合に利用できます。これは、トークン (ユーザープロファイル情報など) から追加情報を取得する場合や、Red Hat Single Sign-On が保護する RESTful サービスを呼び出す場合に便利です。
サーブレット環境では、HttpServletRequest の属性としてセキュアな呼び出しを利用できます。
httpServletRequest
.getAttribute(KeycloakSecurityContext.class.getName());または、HttpSession のセキュアでない要求で利用できます。
httpServletRequest.getSession()
.getAttribute(KeycloakSecurityContext.class.getName());2.1.9. エラー処理
Red Hat Single Sign-On には、サーブレットベースのクライアントアダプターに対するエラー処理機能があります。認証でエラーが発生した場合、Red Hat Single Sign-On は HttpServletResponse.sendError() を呼び出します。web.xml ファイル内にエラーページを設定して、必要なエラーを処理できます。Red Hat Single Sign-On は 400、401、403、および 500 のエラーをスローできます。
<error-page>
<error-code>403</error-code>
<location>/ErrorHandler</location>
</error-page>
Red Hat Single Sign-On は、取得可能な HttpServletRequest 属性も設定します。属性名は org.keycloak.adapters.spi.AuthenticationError で、org.keycloak.adapters.OIDCAuthenticationError にキャストする必要があります。
以下に例を示します。
import org.keycloak.adapters.OIDCAuthenticationError;
import org.keycloak.adapters.OIDCAuthenticationError.Reason;
...
OIDCAuthenticationError error = (OIDCAuthenticationError) httpServletRequest
.getAttribute('org.keycloak.adapters.spi.AuthenticationError');
Reason reason = error.getReason();
System.out.println(reason.name());2.1.10. ログアウト
Web アプリケーションからログアウトするには、複数の方法でログアウトできます。Java EE サーブレットコンテナーでは、HttpServletRequest.logout() を呼び出すことができます。他のブラウザーアプリケーションの場合は、ブラウザーを http://auth-server/auth/realms/{realm-name}/protocol/openid-connect/logout?redirect_uri=encodedRedirectUri にリダイレクトできます。これは、ブラウザーに SSO セッションがある場合にログアウトします。
HttpServletRequest.logout() オプションを使用する場合、アダプターはリフレッシュトークンを渡す Red Hat Single Sign-On サーバーに対してバックチャンネル POST 呼び出しを実行します。保護されていないページ (有効なトークンを確認しないページ) からメソッドが実行されると、更新トークンは利用できません。その場合、アダプターは呼び出しをスキップします。このため、現在のトークンが常に考慮され、必要に応じて Red Hat Single Sign-On server サーバーとの対話が実行されるように、保護されたページを使用して HttpServletRequest.logout() を実行することが推奨されます。
ログアウト処理の一部として外部 ID プロバイダからのログアウトを回避したい場合は、パラメータ initiating_idp を指定して、値を問題の ID プロバイダーの ID (エイリアス) にすることができます。これは、ログアウトエンドポイントが外部アイデンティティープロバイダーによって開始される単一ログアウトの一部として呼び出される場合に便利です。
2.1.11. パラメーター転送
Red Hat Single Sign-On の初期承認エンドポイントリクエストでは、さまざまなパラメーターがサポートされます。ほとんどのパラメーターは、OIDC 仕様 に記載されています。一部のパラメーターは、アダプター設定に基づいてアダプターによって自動的に追加されます。ただし、呼び出しごとに追加できるパラメーターはいくつかあります。セキュアなアプリケーション URI を開くと、特定のパラメーターは Red Hat Single Sign-On 承認エンドポイントに転送されます。
例えば、オフライントークンを要求する場合は、次のように scope パラメーターを指定してセキュアなアプリケーションの URI を開くことができます。
http://myappserver/mysecuredapp?scope=offline_access
およびパラメーター scope=offline_access を指定すると、Red Hat Single Sign-On 認証エンドポイントに自動的に転送されます。
サポートされるパラメーターは以下のとおりです。
-
scope - スコープのスペースで区切られたリストを使用します。スペースで区切られたリストは、通常、特定のクライアントで定義された クライアントスコープ を参照します。スコープの
openidは、アダプターによって常にスコープのリストに追加されることに注意してください。例えば、スコープオプションのaddress phoneを入力すると、Red Hat Single Sign-On へのリクエストにはスコープパラメーターscope=openid address phoneが含まれます。 prompt - Red Hat Single Sign-On では、以下の設定がサポートされます。
-
login- SSO は無視され、ユーザーがすでに認証済みであっても Red Hat Single Sign-On ログインページが常に表示されます。 -
consent-同意が必要なクライアントにのみ適用されます。これを使用すると、ユーザーが以前にこのクライアントに同意した場合でも、Consent ページが常に表示されます。 -
none- ログインページは表示されません。その代わりに、ユーザはアプリケーションにリダイレクトされ、ユーザーが認証されていない場合はエラーが表示されます。この設定により、アプリケーション側でフィルター/インターセプターを作成し、ユーザーにカスタムのエラーページを表示できます。詳細は、仕様を参照してください。
-
-
max_age - ユーザーがすでに認証されている場合にのみ使用します。認証が永続する最大時間を指定します。ユーザーの認証時から測定されます。ユーザーが
maxAgeより長く認証されると、SSO は無視され、再認証が必要となります。 - login_hint - ログインフォームの username/email フィールドを事前に入力するのに使用されます。
- kc_idp_hint - Red Hat Single Sign-On に対して、ログインページの表示をスキップし、指定のアイデンティティープロバイダーに自動的にリダイレクトするために使用されます。詳細は、Identity Providerのドキュメントを参照してください。
ほとんどのパラメーターは、OIDC 仕様 に記載されています。唯一の例外は kc_idp_hint パラメーターで、これは Red Hat Single Sign-On に固有のもので、自動的に使用する ID プロバイダーの名前が含まれています。詳細は、『サーバー管理ガイド』の「Identity Brokering」のセクションを参照してください。
割り当てられたパラメーターを使用して URL を開くと、アダプターはアプリケーションで認証されている場合に Red Hat Single Sign-On にリダイレクトしません。たとえば、http://myappserver/mysecuredapp?prompt=login を開いても、アプリケーション mysecredapp に対して認証済みの場合は、Red Hat Single Sign-On のログインページに自動的にリダイレクトされません。この動作は今後変更される可能性があります。
2.1.12. クライアント認証
機密 OIDC クライアントがバックチャネル要求を送信する必要がある場合 (トークンのコードを交換したり、トークンを更新する場合など)、Red Hat Single Sign-On サーバーに対して認証する必要があります。デフォルトでは、クライアント ID およびクライアントシークレット、署名済み JWT によるクライアント認証、またはクライアントシークレットを使用した署名済み JWT によるクライアント認証の 3 つの方法があります。
2.1.12.1. クライアント ID およびクライアントシークレット
これは、OAuth2 仕様で説明されている従来の方法です。クライアントには、アダプター (アプリケーション) サーバーと Red Hat Single Sign-On サーバーの両方を認識する必要があるシークレットがあります。Red Hat Single Sign-On 管理コンソールで特定のクライアントのシークレットを生成し、このシークレットをアプリケーション側の keycloak.json ファイルに貼り付けることができます。
"credentials": {
"secret": "19666a4f-32dd-4049-b082-684c74115f28"
}2.1.12.2. 署名済み JWT によるクライアント認証
これは RFC7523の の仕様に基づいています。これは、以下のように動作します。
-
クライアントには、秘密鍵と証明書が必要です。Red Hat シングルサインオンでは、クライアントアプリケーションのクラスパスかファイルシステムのどこかにある従来の
keystoreファイルから利用できます。 - クライアントアプリケーションを起動すると、がクライアントアプリケーションのベース URL であると仮定して、http://myhost.com/myapp/k_jwks のような URL を使用して JWKS 形式で公開鍵をダウンロードすることができます。この URL は Red Hat Single Sign-On で使用できます (下記参照)。
-
認証中、クライアントは JWT トークンを生成し、その秘密鍵で署名し、
client_assertionパラメーターの特定のバックチャンネル要求 (たとえば、code-to-token 要求) で Red Hat Single Sign-On に送信します。 Red Hat Single Sign-On には、JWT で署名を検証できるように、クライアントの公開鍵または証明書が必要です。Red Hat Single Sign-On では、クライアントの認証情報を設定する必要があります。まず、管理コンソールの
Credentialsタブで、クライアントの認証方法として「Signed JWT」を選択する必要があります。次に、以下のいずれかを選択できます。-
Red Hat Single Sign-On がクライアントの公開鍵をダウンロードできる JWKS URL を設定します。これは、http://myhost.com/myapp/k_jwks などの URL を指定できます (詳細は上記を参照してください)。クライアントはキーをいつでもローテーションできるため、このオプションは最も柔軟性の高いものであり、Red Hat Single Sign-On は設定を変更しなくても、必要に応じていつでも新しいキーをダウンロードします。より正確には、Red Hat Single Sign-On は、未知の
kid(キー ID) 署名したトークンを見つけると、新しいキーをダウンロードします。 - クライアントの公開鍵または証明書を、PEM 形式、JWK 形式、またはキーストアからアップロードします。このオプションを使用すると、公開鍵はハードコーディングされ、クライアントが新しいキーペアを生成する際に変更する必要があります。自分自身が利用可能でない場合は、Red Hat Single Sign-On の管理コンソールから独自のキーストアを生成することもできます。Red Hat Single Sign-On 管理コンソールの設定方法の詳細は、「サーバー管理ガイド」を参照してください。
-
Red Hat Single Sign-On がクライアントの公開鍵をダウンロードできる JWKS URL を設定します。これは、http://myhost.com/myapp/k_jwks などの URL を指定できます (詳細は上記を参照してください)。クライアントはキーをいつでもローテーションできるため、このオプションは最も柔軟性の高いものであり、Red Hat Single Sign-On は設定を変更しなくても、必要に応じていつでも新しいキーをダウンロードします。より正確には、Red Hat Single Sign-On は、未知の
アダプター側で設定するには、keycloak.json ファイルに以下のようなものを記述する必要があります。
"credentials": {
"jwt": {
"client-keystore-file": "classpath:keystore-client.jks",
"client-keystore-type": "JKS",
"client-keystore-password": "storepass",
"client-key-password": "keypass",
"client-key-alias": "clientkey",
"token-expiration": 10
}
}
この設定では、WAR のクラスパスに keystore-client.jks というキーストアファイルがある必要があります。接頭辞 classpath: を使用しない場合は、クライアントアプリケーションが実行しているファイルシステム上の任意のファイルを指定できます。
2.1.13. マルチテナンシー
この場合、複数の Red Hat Single Sign-On レルムを使用して、1 つのターゲットアプリケーション (WAR) をセキュアにできることを意味します。レルムは、同じ Red Hat Single Sign-On インスタンスまたは別のインスタンスに配置できます。
実際には、これはアプリケーションが複数の keycloak.json アダプター設定ファイルを持つ必要があることを意味します。
異なるアダプター構成ファイルが異なるコンテキストパスにデプロイされた WAR の複数のインスタンスを持つことができます。しかし、これは不便である可能性があります。また、context-path 以外の項目に基づいてレルムを選択することもできます。
Red Hat Single Sign-On では、カスタム設定リゾルバーを設定して、リクエストごとに使用するアダプター設定を選択できるようになります。
これを実現するには、まず org.keycloak.adapterers.KeycloakConfigResolver の実装を作成する必要があります。以下に例を示します。
package example;
import org.keycloak.adapters.KeycloakConfigResolver;
import org.keycloak.adapters.KeycloakDeployment;
import org.keycloak.adapters.KeycloakDeploymentBuilder;
public class PathBasedKeycloakConfigResolver implements KeycloakConfigResolver {
@Override
public KeycloakDeployment resolve(OIDCHttpFacade.Request request) {
if (path.startsWith("alternative")) {
KeycloakDeployment deployment = cache.get(realm);
if (null == deployment) {
InputStream is = getClass().getResourceAsStream("/tenant1-keycloak.json");
return KeycloakDeploymentBuilder.build(is);
}
} else {
InputStream is = getClass().getResourceAsStream("/default-keycloak.json");
return KeycloakDeploymentBuilder.build(is);
}
}
}
また、どの KeycloakConfigResolver 実装を web.xml のコンテキストパラメーター keycloak.config.resolver で使用するかを設定する必要があります。
<web-app>
...
<context-param>
<param-name>keycloak.config.resolver</param-name>
<param-value>example.PathBasedKeycloakConfigResolver</param-value>
</context-param>
</web-app>2.1.14. アプリケーションクラスタリング
本章では、JBoss EAP にデプロイされたクラスター化されたアプリケーションのサポートに関連します。
アプリケーションが次のいずれであるかに応じて、いくつかのオプションを利用できます。
- ステートレスまたはステートフル
- 分散可能 (複製可能 http セッション) または非分散可能
- ロードバランサーが提供するスティッキーセッションへの依存
- Red Hat Single Sign-On と同じドメインでホストされる
クラスタリングの処理は、通常のアプリケーションほど単純ではありません。主に、ブラウザーとサーバー側のアプリケーションがリクエストを Red Hat Single Sign-On に送信するため、ロードバランサーでスティッキーセッションを有効にするのは単純ではありません。
2.1.14.1. ステートレストークンストア
デフォルトでは、Red Hat Single Sign-On によってセキュア化された web アプリケーションは HTTP セッションを使用してセキュリティーコンテキストを保存します。つまり、スティッキーセッションを有効にするか、HTTP セッションを複製する必要があります。
HTTP セッションにセキュリティーコンテキストを保存する代わりに、アダプターを設定して Cookie にこれを保存するように設定できます。これは、アプリケーションをステートレスにしたい場合、またはセキュリティコンテキストを HTTP セッションに保存したくない場合に役立ちます。
セキュリティコンテキストの保存に cookie ストアを使用するには、アプリケーションの WEB-INF/keycloak.json を編集して、以下を追加してください。
"token-store": "cookie"
token-storeのデフォルト値は sessionで、HTTP セッションにセキュリティーコンテキストを保存します。
クッキーストアを使用する 1 つの制限は、すべての HTTP リクエストに対してセキュリティーコンテキスト全体がクッキーに渡されることです。これにより、パフォーマンスに影響する可能性があります。
別の小さな制限については、Single-Sign Out のサポートは限定されています。アダプターにより KEYCLOAK_ADAPTER_STATE cookie が削除されるため、アプリケーション自体からの init servlet logout (HttpServletRequest.logout) がアプリケーション自体からも問題なく機能します。ただし、別のアプリケーションから初期化されたバックチャネルログアウトは、cookie ストアを使用して Red Hat Single Sign-On によって伝播されません。そのため、アクセストークンのタイムアウトに short 値を使用することが推奨されます (例: 1 分)。
一部のロードバランサーでは、Amazon ALB などのスティッキーセッション cookie 名またはコンテンツの設定は許可されません。これらの場合は、shouldAttachRoute オプションを false に設定することが推奨されます。
2.1.14.2. 相対 URI の最適化
Red Hat Single Sign-On およびアプリケーションが同じドメイン (リバースプロキシーまたはロードバランサー経由) でホストされるデプロイメントシナリオでは、クライアント設定で相対 URI オプションを使用すると便利です。
相対 URI を使用すると、URI は Red Hat Single Sign-On へのアクセスに使用する URL と相対的に解決されます。
例えば、アプリケーションの URL が https://acme.org/myapp で、Red Hat Single Sign-On の URL が https://acme.org/auth の場合は、https://acme.org/myapp 代わりに redirect-uri /myapp を使用できます。
2.1.14.3. 管理 URL の設定
特定のクライアントの管理者 URL は、Red Hat Single Sign-On の管理コンソールで設定できます。これは、Red Hat Single Sign-On サーバーが、ユーザーのログアウトや失効ポリシーのプッシュなどのさまざまなタスクのためにアプリケーションにバックエンドリクエストを送信するのに使用されます。
たとえば、バックチャネルログアウトの仕組みは以下のようになります。
- ユーザーが 1 つのアプリケーションからログアウトリクエストを送信します。
- アプリケーションはログアウトリクエストを Red Hat Single Sign-On に送信します。
- Red Hat Single Sign-On サーバーは、ユーザーセッションを無効にします。
- 次に、Red Hat Single Sign-On サーバーは、セッションに関連付けられた管理 URL を持つアプリケーションにバックチャネルリクエストを送信します。
- アプリケーションがログアウトリクエストを受け取ると、対応する HTTP セッションが無効になります。
管理の URL に ${application.session.host} が含まれている場合は、HTTP セッションに関連するノードの URL に置き換えられます。
2.1.14.4. アプリケーションノードの登録
前のセクションでは、Red Hat Single Sign-On が特定の HTTP セッションに関連付けられたノードにログアウトリクエストを送信する方法を説明します。ただし、場合によっては、管理者は、管理タスクを 1 つだけでなく、登録されているすべてのクラスターノードに伝達したいことがあります。たとえば、新しい not before ポリシーをアプリケーションにプッシュしたり、アプリケーションからすべてのユーザーをログアウトしたりするには、以下を実行します。
この場合、Red Hat Single Sign-On はすべてのアプリケーションクラスターノードを認識して、イベントをすべてのノードに送信できるようにします。これを行うには、自動検出メカニズムをサポートします。
- 新規アプリケーションノードがクラスターに参加すると、登録要求を Red Hat Single Sign-On サーバーに送信します。
- 要求は、定期的な間隔で Red Hat Single Sign-On に再送される場合があります。
- Red Hat Single Sign-On サーバーが、指定のタイムアウト内で再登録要求を受信しない場合は、自動的に特定のノードの登録を解除します。
- このノードは、登録されていないリクエストを送信する際に、Red Hat Single Sign-On でも登録が解除されます。これは通常、ノードのシャットダウンまたはアプリケーションのアンデプロイメント中に行われます。これは、アンデプロイメントリスナーが呼び出されていない場合に強制シャットダウンが適切に動作しないため、自動登録解除が必要になります。
一部のクラスターアプリケーションでのみ必要であるため、起動登録および定期的な再登録はデフォルトでは無効になっています。
この機能を有効にするには、アプリケーションの WEB-INF/keycloak.json ファイルを編集し、以下を追加します。
"register-node-at-startup": true, "register-node-period": 600,
これは、アダプターが起動時に登録要求を送信し、10 分ごとに再登録します。
Red Hat Single Sign-On 管理コンソールでは、ノード再登録タイムアウトの最大数を指定できます (アダプター設定の register-node-period よりも大きくする必要があります)。管理コンソールを使用してクラスターノードを手動で追加および削除することもできます。これは、自動登録機能に依存したくない場合、または自動登録解除機能を使用せずに古いアプリケーションノードを削除する場合に便利です。
2.1.14.5. 各リクエストでトークンを更新する
デフォルトでは、アプリケーションアダプターは、有効期限が切れている場合にのみアクセストークンを更新します。ただし、すべてのリクエストでトークンを更新するようにアダプターを設定することもできます。アプリケーションが Red Hat Single Sign-On サーバーにより多くのリクエストを送信するため、パフォーマンスに影響する可能性があります。
この機能を有効にするには、アプリケーションの WEB-INF/keycloak.json ファイルを編集し、以下を追加します。
"always-refresh-token": true
これは、パフォーマンスに大きく影響することがあります。ポリシーの前にログアウトを伝播するのにバックチャネルメッセージに依存しない場合にのみ、この機能を有効にします。考慮すべきもう 1 つの点は、デフォルトではアクセストークンの有効期限が短いため、ログアウトが伝播されなくても、トークンはログアウトから数分以内に有効期限が切れることです。