第2章 OpenID Connect を使用したアプリケーションとサービスのセキュア化

JBoss EAP は、同じ JBoss EAP インスタンスにデプロイされた web アプリケーションに対するシングルサインオンのサポートが組み込まれています。これは、Red Hat Single Sign-On を使用する場合に有効にしないでください。

本セクションでは、WAR パッケージ内の設定ファイルを追加および編集して、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>

セキュリティーコンテキストは EJB 階層に自動的に伝播されます。

最初に Red Hat Single Sign-On Karaf 機能をインストールする必要があります。次に、セキュリティー保護するアプリケーションのタイプに応じて手順を実行する必要があります。参照されるすべての Web アプリケーションには、Red Hat Single Sign-On Jetty オーセンティケーターを基盤の Jetty サーバーに挿入する必要があります。これを行う手順は、アプリケーションの種別によって異なります。詳細は、以下を参照してください。

最初に JBoss Fuse 環境に keycloak 機能をインストールする必要があります。keycloak 機能には、Fuse アダプターとサードパーティーのすべての依存関係が含まれます。Maven リポジトリーまたはアーカイブからインストールできます。

従来の WAR アプリケーションとしてデプロイされていない OSGI バンドルプロジェクトにサーブレットクラスがある場合は、このメソッドを使用できます。Fuse は Pax Web Whiteboard Extender を使用して、このようなサーブレットを Web アプリケーションとしてデプロイします。

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&amp;matchOnUriPrefix=true" />
            <process ref="helloProcessor" />
            <log message="The message from camel endpoint contains ${body}"/>
        </route>
    </camelContext>

</blueprint>

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="18.0.18.redhat-00001",
org.osgi.service.blueprint,
org.osgi.service.blueprint.container,
org.osgi.service.event,

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>

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="18.0.18.redhat-00001"

一部のサービスは、起動時にデプロイされたサーブレットが自動的に含まれる場合があります。このようなサービスの 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 エンジンを使用すると、各アプリケーションのセキュリティーをより詳細に制御できます。

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="18.0.18.redhat-00001",
org.keycloak.adapters.jetty;version="18.0.18.redhat-00001",
*;resolution:=optional

Red Hat Single Sign-On で Hawtio 管理コンソールのセキュリティーを保護するには、次の手順を実行します。

{
  "realm" : "demo",
  "resource" : "hawtio-client",
  "auth-server-url" : "http://localhost:8080/auth",
  "ssl-required" : "external",
  "public-client" : true
}

最初に Red Hat Single Sign-On Karaf 機能をインストールする必要があります。次に、セキュリティー保護するアプリケーションのタイプに応じて手順を実行する必要があります。参照されるすべての Web アプリケーションには、Red Hat Single Sign-On の Undertow 認証メカニズムを基盤の Web サーバーに挿入する必要があります。これを行う手順は、アプリケーションの種別によって異なります。詳細は、以下を参照してください。

最初に、JBoss Fuse 環境に keycloak-pax-http-undertow 機能および keycloak-jaas 機能をインストールする必要があります。keycloak-pax-http-undertow 機能には、Fuse アダプターとサードパーティーのすべての依存関係が含まれます。keycloak-jaas には、SSH および JMX 認証にレルムで使用される JAAS モジュールが含まれます。Maven リポジトリーまたはアーカイブからインストールできます。

従来の WAR アプリケーションとしてデプロイされていない OSGI バンドルプロジェクトにサーブレットクラスがある場合は、このメソッドを使用できます。Fuse は Pax Web Whiteboard Extender を使用して、このようなサーブレットを Web アプリケーションとしてデプロイします。

Blueprint で適切なセキュリティー制約を注入し、使用されているコンポーネントを undertow-keycloak に更新することで、camel-undertow コンポーネントで実装された Apache Camel エンドポイントのセキュリティーを保護できます。OSGI-INF/blueprint/blueprint.xml ファイルを、以下のような設定を持つ Camel アプリケーションに追加する必要があります。ロール、セキュリティー制約のマッピング、およびアダプター設定は、お使いの環境とニーズに合わせて若干異なる可能性があります。

undertow-keycloak コンポーネントは、標準の undertow コンポーネントと比較すると、2 つの新しいプロパティーを追加します。

以下に例を示します。

<?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&amp;configResolver=#keycloakConfigResolver&amp;allowedRoles=admin" />
            <process ref="helloProcessor" />
            <log message="The message from camel endpoint contains ${body}"/>
        </route>

    </camelContext>

</blueprint>

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="18.0.18.redhat-00001",
org.osgi.service.blueprint,
org.osgi.service.blueprint.container

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>

別の Undertow エンジンで Red Hat Single Sign-On でセキュリティー保護された CXF エンドポイントを実行するには、以下の手順を実行します。

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="18.0.18.redhat-00001"

一部のサービスは、起動時にデプロイされたサーブレットが自動的に含まれる場合があります。このようなサービスの 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 のドキュメントを参照してください。上記のプロパティーは以下の意味になります。

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}"

Red Hat Single Sign-On で Hawtio 管理コンソールのセキュリティーを保護するには、次の手順を実行します。

Spring Boot アプリケーションのセキュリティーを保護するには、Keycloak Spring Boot アダプター JAR をアプリケーションに追加する必要があります。その後、通常の Spring Boot 設定 (application.properties) を使用して追加の設定を提供する必要があります。

Keycloak Spring Boot アダプターは Spring Boot の自動設定を活用するため、このアダプター Keycloak Spring Boot スターターをプロジェクトに追加する必要があります。

現在、以下の埋め込みコンテナーはサポートされており、Starter の使用時には追加の依存関係は必要ありません。

以下の手順を使用して、Red Hat Single Sign-On を使用するように Spring Boot アプリケーションを設定します。

これは、OAuth2 仕様で説明されている従来の方法です。クライアントには、アダプター (アプリケーション) サーバーと Red Hat Single Sign-On サーバーの両方を認識する必要があるシークレットがあります。Red Hat Single Sign-On 管理コンソールで特定のクライアントのシークレットを生成し、このシークレットをアプリケーション側の keycloak.json ファイルに貼り付けることができます。

"credentials": {
    "secret": "19666a4f-32dd-4049-b082-684c74115f28"
}

これは RFC7523 の仕様に基づいています。これは、以下のように動作します。

アダプター側で設定するには、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",
    "algorithm": "RS256",
    "token-expiration": 10
  }
}

この設定では、WAR のクラスパスに keystore-client.jks というキーストアファイルがある必要があります。接頭辞 classpath: を使用しない場合は、クライアントアプリケーションが実行しているファイルシステム上の任意のファイルを指定できます。

algorithm フィールドは、署名済み JWT に使用されるアルゴリズムを指定し、デフォルトは RS256 です。このフィールドは、キーペアと同期する必要があります。たとえば、RS256 アルゴリズムには RSA 鍵ペアが必要で、ES256 アルゴリズムには EC キーペアが必要です。詳細は、Cryptographic Algorithms for Digital Signatures and MACs を参照してください。

デフォルトでは、Red Hat Single Sign-On によってセキュア化された web アプリケーションは HTTP セッションを使用してセキュリティーコンテキストを保存します。つまり、スティッキーセッションを有効にするか、HTTP セッションを複製する必要があります。

HTTP セッションにセキュリティーコンテキストを保存する代わりに、アダプターを設定して Cookie にこれを保存するように設定できます。これは、アプリケーションをステートレスにしたい場合、またはセキュリティーコンテキストを HTTP セッションに保存したくない場合に役立ちます。

セキュリティーコンテキストの保存に cookie ストアを使用するには、アプリケーションの WEB-INF/keycloak.json を 編集して、以下を追加してください。

"token-store": "cookie"

クッキーストアを使用する 1 つの制限は、すべての HTTP リクエストに対してセキュリティーコンテキスト全体がクッキーに渡されることです。これにより、パフォーマンスに影響する可能性があります。

別の小さな制限については、Single-Sign Out のサポートは限定されています。アダプターにより KEYCLOAK_ADAPTER_STATE cookie が削除されるため、アプリケーション自体からの init servlet logout (HttpServletRequest.logout) がアプリケーション自体からも問題なく機能します。ただし、別のアプリケーションから初期化されたバックチャネルログアウトは、cookie ストアを使用して Red Hat Single Sign-On によって伝播されません。そのため、アクセストークンのタイムアウトに short 値を使用することが推奨されます (例: 1 分)。

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 を使用できます。

特定のクライアントの管理者 URL は、Red Hat Single Sign-On の管理コンソールで設定できます。これは、Red Hat Single Sign-On サーバーが、ユーザーのログアウトや失効ポリシーのプッシュなどのさまざまなタスクのためにアプリケーションにバックエンドリクエストを送信するのに使用されます。

たとえば、バックチャネルログアウトの仕組みは以下のようになります。

管理の URL に ${application.session.host} が含まれている場合は、HTTP セッションに関連するノードの URL に置き換えられます。

前のセクションでは、Red Hat Single Sign-On が特定の HTTP セッションに関連付けられたノードにログアウトリクエストを送信する方法を説明します。ただし、場合によっては、管理者は、管理タスクを 1 つだけでなく、登録されているすべてのクラスターノードに伝達したいことがあります。たとえば、新しい not before ポリシーをアプリケーションにプッシュしたり、アプリケーションからすべてのユーザーをログアウトしたりするには、以下を実行します。

この場合、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 よりも大きくする必要があります)。管理コンソールを使用してクラスターノードを手動で追加および削除することもできます。これは、自動登録機能に依存したくない場合、または自動登録解除機能を使用せずに古いアプリケーションノードを削除する場合に便利です。

デフォルトでは、アプリケーションアダプターは、有効期限が切れている場合にのみアクセストークンを更新します。ただし、すべてのリクエストでトークンを更新するようにアダプターを設定することもできます。アプリケーションが Red Hat Single Sign-On サーバーにより多くのリクエストを送信するため、パフォーマンスに影響する可能性があります。

この機能を有効にするには、アプリケーションの WEB-INF/keycloak.json ファイルを編集し、以下を追加します。

"always-refresh-token": true