移行ガイド

Red Hat Single Sign-On 7.6 とは対照的に、Red Hat build of Keycloak には、サポート対象データベースのサポートが組み込まれているため、データベースドライバーを手動でインストールして設定する必要がありません。例外は Oracle と Microsoft SQL Server です。これらについては、ドライバーを手動でインストールする必要があります。

設定に関しては、Red Hat Single Sign-On 7.6 の既存インストールのデータソースサブシステムを考慮し、その設定を、Red Hat build of Keycloak のデータベース設定カテゴリーで利用可能なオプションにマッピングします。たとえば、以前の設定として、次のようなものがあるとします。

<datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true" statistics-enabled="true">
    <connection-url>jdbc:postgresql://mypostgres:5432/mydb?currentSchema=myschema</connection-url>
    <driver>postgresql</driver>
    <pool>
        <min-pool-size>5</min-pool-size>
        <max-pool-size>50</max-pool-size>
    </pool>
    <security>
        <user-name>myuser</user-name>
        <password>myuser</password>
    </security>
</datasource>

<datasource jndi-name="java:jboss/datasources/KeycloakDS" pool-name="KeycloakDS" enabled="true" use-java-context="true" statistics-enabled="true">
    <connection-url>jdbc:postgresql://mypostgres:5432/mydb?currentSchema=myschema</connection-url>
    <driver>postgresql</driver>
    <pool>
        <min-pool-size>5</min-pool-size>
        <max-pool-size>50</max-pool-size>
    </pool>
    <security>
        <user-name>myuser</user-name>
        <password>myuser</password>
    </security>
</datasource>

Red Hat build of Keycloak では、CLI パラメーターを使用した同等の設定は、次のようなものになります。

kc.sh start
   --db postgres
   --db-url-host mypostgres
   --db-url-port 5432
   --db-url-database mydb
   --db-schema myschema
   --db-pool-min-size 5 --db-pool-max-size 50
   --db-username myser --db-password myuser

kc.sh start
   --db postgres
   --db-url-host mypostgres
   --db-url-port 5432
   --db-url-database mydb
   --db-schema myschema
   --db-pool-min-size 5 --db-pool-max-size 50
   --db-username myser --db-password myuser

実稼働モード (start オプションで表される) を使用する場合は常に、HTTP が無効になり、TLS 設定がデフォルトで必要になります。

--http-enabled=true 設定オプションを使用すると、HTTP を有効にできます。ただし、Red Hat build of Keycloak サーバーが完全に分離されたネットワーク内にあり、内部または外部の攻撃者がネットワークトラフィックを監視できるリスクがない場合を除き、このオプションの使用は推奨されません。

Red Hat build of Keycloak インスタンスは、サーバーのルートを使用するため、異なるコンテキストルート (URL パス) を持ちます。一方、Red Hat Single Sign-On 7.6 はデフォルトで /auth を追加します。以前の動作を再現するには、--http-relative-path=/auth 設定オプションを使用できます。デフォルトのポートは同じままです。ただし、--http-port および --https-port オプションによって変更することもできます。

TLS を設定するには 2 つの方法があります。PEM 形式のファイルを使用するか、Java キーストアを使用します。たとえば、Java キーストアによる以前の設定として、次のようなものがあるとします。

<tls>
	<key-stores>
            <key-store name="applicationKS">
                 <credential-reference
		 clear-text="password"/>
		 <implementation type="JKS"/>
                 <file
   path="/path/to/application.keystore”/>
            </key-store>
     </key-stores>
     <key-managers>
        <key-manager name="applicationKM"
         key-store="applicationKS">
               <credential-reference
          clear-text="password"/>
        </key-manager>
     </key-managers>
     <server-ssl-contexts>
         <server-ssl-context name="applicationSSC"
     key-manager="applicationKM"/>
     </server-ssl-contexts>
</tls>

<tls>
	<key-stores>
            <key-store name="applicationKS">
                 <credential-reference
		 clear-text="password"/>
		 <implementation type="JKS"/>
                 <file
   path="/path/to/application.keystore”/>
            </key-store>
     </key-stores>
     <key-managers>
        <key-manager name="applicationKM"
         key-store="applicationKS">
               <credential-reference
          clear-text="password"/>
        </key-manager>
     </key-managers>
     <server-ssl-contexts>
         <server-ssl-context name="applicationSSC"
     key-manager="applicationKM"/>
     </server-ssl-contexts>
</tls>

Red Hat build of Keycloak では、CLI パラメーターを使用した同等の設定は、次のようなものになります。

kc.sh start
   --https-key-store-file /path/to/application.keystore
   --https-key-store-password password

kc.sh start
   --https-key-store-file /path/to/application.keystore
   --https-key-store-password password

Red Hat build of Keycloak では、次のように PEM 形式の証明書を指定することで TLS を設定できます。

kc.sh start
   --https-certificate-file /path/to/certfile.pem
   --https-certificate-key-file /path/to/keyfile.pem

kc.sh start
   --https-certificate-file /path/to/certfile.pem
   --https-certificate-key-file /path/to/keyfile.pem

Red Hat Single Sign-On 7.6 は、サーバーをスタンドアロン、スタンドアロンクラスター、およびドメインクラスターとして実行するための個別の動作モードを備えていました。これらのモードは、起動スクリプトと設定ファイルが異なります。Red Hat build of Keycloak では、単一の起動スクリプト kc.sh を使用したシンプルな方法を利用できます。

サーバーをスタンドアロンまたはクラスター化されたスタンドアロンとして実行するには、kc.sh スクリプトを使用します。

--cache パラメーターのデフォルト値は、起動モードを認識します。

Red Hat Single Sign-On 7.6 では、クラスタリングとキャッシュの設定を Infinispan サブシステムを通じて行っていました。一方、Red Hat build of Keycloak では、設定の大部分を、別の Infinispan 設定ファイルを通じて行います。たとえば、Infinispan の以前の設定として、次のようなものがあるとします。

<subsystem xmlns="urn:jboss:domain:infinispan:13.0">
<cache-container name="keycloak" marshaller="JBOSS" modules="org.keycloak.keycloak-model-infinispan">
                <local-cache name="realms">
                    <heap-memory size="10000"/>
                </local-cache>
                <local-cache name="users">
                    <heap-memory size="10000"/>
                </local-cache>
                <local-cache name="sessions"/>
                <local-cache name="authenticationSessions"/>
                <local-cache name="offlineSessions"/>
			...
</cache-container>
</subsystem>

<subsystem xmlns="urn:jboss:domain:infinispan:13.0">
<cache-container name="keycloak" marshaller="JBOSS" modules="org.keycloak.keycloak-model-infinispan">
                <local-cache name="realms">
                    <heap-memory size="10000"/>
                </local-cache>
                <local-cache name="users">
                    <heap-memory size="10000"/>
                </local-cache>
                <local-cache name="sessions"/>
                <local-cache name="authenticationSessions"/>
                <local-cache name="offlineSessions"/>
			...
</cache-container>
</subsystem>

Red Hat build of Keycloak では、デフォルトの Infinispan 設定ファイルは conf/cache-ispn.xml ファイルにあります。独自の Infinispan 設定ファイルを用意し、次のように CLI パラメーターを使用して指定できます。

kc.sh start --cache-config-file my-cache-file.xml

kc.sh start --cache-config-file my-cache-file.xml

唯一の改善点は、CLI オプションのキャッシュスタックを指定することで、キャッシュ設定ファイルで定義されたスタックをオーバーライドできることです。指定すると、そのキャッシュスタックが優先されます。カスタム JGroups トランスポートスタックを使用した上記の Infinispan 設定ファイル my-cache-file.xml の一部として、次のようなものがあるとします。

keycloak キャッシュコンテナーのトランスポートスタックが tcp に設定されていますが、次のように CLI オプションを使用してこのスタックをオーバーライドできます。

<jgroups>
	<stack name=”my-encrypt-udp” extends=”udp”>
		…
	</stack>
</jgroups>

<cache-container name=”keycloak”>
	<transport stack=”tcp”/>
	…
</cache-container>

<jgroups>
	<stack name=”my-encrypt-udp” extends=”udp”>
		…
	</stack>
</jgroups>

<cache-container name=”keycloak”>
	<transport stack=”tcp”/>
	…
</cache-container>

kc.sh start
   --cache-config-file my-cache-file.xml
   --cache-stack my-encrypt-udp

kc.sh start
   --cache-config-file my-cache-file.xml
   --cache-stack my-encrypt-udp

上記のコマンドを実行すると、my-encrypt-udp トランスポートスタックが使用されます。

Red Hat build of Keycloak では、ホスト名 SPI の設定が必須です。これは、ユーザーをリダイレクトするとき、またはユーザーのクライアントと通信するときに、サーバーによってフロントエンド URL とバックエンド URL をどのように作成するかを設定するために必要です。

たとえば、Red Hat Single Sign-On 7.6 インストールに次のような設定があるとします。

<spi name="hostname">
      <default-provider>default</default-provider>
      <provider name="default" enabled="true">
           <properties>
              <property name="frontendUrl" value="myFrontendUrl"/>
              <property name="forceBackendUrlToFrontendUrl" value="true"/>
           </properties>
      </provider>
</spi>

<spi name="hostname">
      <default-provider>default</default-provider>
      <provider name="default" enabled="true">
           <properties>
              <property name="frontendUrl" value="myFrontendUrl"/>
              <property name="forceBackendUrlToFrontendUrl" value="true"/>
           </properties>
      </provider>
</spi>

Red Hat build of Keycloak では、これは次のような設定オプションに変換できます。

kc.sh start
    --hostname-url myFrontendUrl
    --hostname-strict-backchannel true

kc.sh start
    --hostname-url myFrontendUrl
    --hostname-strict-backchannel true

hostname-url 設定オプションを使用すると、クラスターの前で実行されているイングレス層からクラスターをパブリックに公開する場所となるベース URL を設定できます。hostname-admin-url 設定オプションを設定して、管理リソースの URL を設定することもできます。

Red Hat build of Keycloak を使用すると、どのリバースプロキシーヘッダーを反映するかを設定できます。Forwarded ヘッダーまたは X-Forwarded-* ヘッダーのセットのいずれかを使用できます。以下に例を示します。

kc.sh start --proxy-headers xforwarded

kc.sh start --proxy-headers xforwarded

トラストストアは、HTTPS 要求や LDAP サーバーなどの外部 TLS 通信に使用します。トラストストアを使用するには、リモートサーバーまたは CA の証明書をトラストストアにインポートします。その後、システムのトラストストアを指定して Red Hat build of Keycloak サーバーを起動できます。

たとえば、以前の設定として、次のようなものがあるとします。

<spi name="truststore">
    <provider name="file" enabled="true">
        <properties>
            <property name="file" value="path/to/myTrustStore.jks"/>
            <property name="password" value="password"/>
            <property name="hostname-verification-policy" value="WILDCARD"/>
        </properties>
    </provider>
</spi>

<spi name="truststore">
    <provider name="file" enabled="true">
        <properties>
            <property name="file" value="path/to/myTrustStore.jks"/>
            <property name="password" value="password"/>
            <property name="hostname-verification-policy" value="WILDCARD"/>
        </properties>
    </provider>
</spi>

Red Hat build of Keycloak は、PEM ファイル、または拡張子が .p12 および .pfx の PKCS12 ファイル形式のトラストストアをサポートしています。PKCS12 ファイルの場合は、暗号化されている証明書は使用できません。つまり、パスワードは必要ありません。JKS トラストストアを変換する必要があります。Java keytool ではパスワードの最小長が 6 文字に制限されるため、暗号化されていない PKCS12 トラストストアを作成する代わりに openssl を使用できます。

kc.sh start
    --truststore-paths path/to/myUnencryptedTrustStore.p12
    --tls-hostname-verifier WILDCARD

kc.sh start
    --truststore-paths path/to/myUnencryptedTrustStore.p12
    --tls-hostname-verifier WILDCARD

キーストア Vault は Vault SPI の実装であり、ベアメタルインストールにシークレットを保存するのに役立ちます。この Vault は、Red Hat Single Sign-On 7.6 の Elytron 認証情報ストアに代わるものです。

<spi name="vault">
     <provider name="elytron-cs-keystore" enabled="true">
        <properties>
            <property name="location" value="path/to/keystore.p12"/>
             <property name="secret" value="password"/>
     </properties>
   </provider>
</spi>

<spi name="vault">
     <provider name="elytron-cs-keystore" enabled="true">
        <properties>
            <property name="location" value="path/to/keystore.p12"/>
             <property name="secret" value="password"/>
     </properties>
   </provider>
</spi>

Red Hat build of Keycloak では、CLI パラメーターを使用した同等の設定は、次のようなものになります。

kc.sh start
   --vault keystore
   --vault-file /path/to/keystore.p12
   --vault-pass password

kc.sh start
   --vault keystore
   --vault-file /path/to/keystore.p12
   --vault-pass password

Vault に保存されたシークレットには、管理コンソール内の複数の場所からアクセスできます。既存の Elytron Vault から新しい Java KeyStore ベースの Vault への移行に関しては、レルム設定の変更は必要ありません。新しく作成された Java キーストアに同じシークレットが含まれている場合は、既存のレルム設定が機能するはずです。

デフォルトの REALM_UNDERSCORE_KEY キーリゾルバーを使用すると、以前と同じ方法で ${vault.realm-name_alias} によって (たとえば、LDAP ユーザーフェデレーション設定内で) シークレットにアクセスできます。

Red Hat build of Keycloak での JVM 設定方法は、Red Hat Single Sign-On 7.6 の方法と似ています。引き続き特定の環境変数を設定する必要がありますが、/bin フォルダーに standalone.conf などの設定ファイルが含まれません。

Red Hat build of Keycloak は、さまざまなデフォルトの JVM 引数を提供します。これは、メモリー割り当てと CPU オーバーヘッドの面で優れたスループットと効率を実現するため、ほとんどのデプロイメントに適していることが判明しています。また、他のデフォルトの JVM 引数は、Red Hat build of Keycloak インスタンスをスムーズに実行するためのものであり、ユースケースに合わせて引数を変更する場合は注意が必要です。

JVM 引数または GC 設定を変更するには、Java オプションとして指定する特定の環境変数を設定します。これらの設定を完全にオーバーライドするには、JAVA_OPTS 環境変数を指定します。

特定の Java プロパティーの追加のみが必要な場合は、JAVA_OPTS_APPEND 環境変数を指定します。JAVA_OPTS 環境変数が指定されていない場合は、./kc.sh スクリプト内にあるデフォルトの Java プロパティーが使用されます。

たとえば、次のように特定の Java オプションを指定できます。

export JAVA_OPTS_APPEND=-XX:+HeapDumpOnOutOfMemoryError
kc.sh start

export JAVA_OPTS_APPEND=-XX:+HeapDumpOnOutOfMemoryError
kc.sh start

SPI プロバイダーの設定は、新しい設定システムを通じて行います。以下は古い形式です。

<spi name="<spi-id>">
    <provider name="<provider-id>" enabled="true">
        <properties>
            <property name="<property>" value="<value>"/>
        </properties>
    </provider>
</spi>

<spi name="<spi-id>">
    <provider name="<provider-id>" enabled="true">
        <properties>
            <property name="<property>" value="<value>"/>
        </properties>
    </provider>
</spi>

以下は新しい形式です。

spi-<spi-id>-<provider-id>-<property>=<value>

spi-<spi-id>-<provider-id>-<property>=<value>

トラブルシューティングには次のコマンドを使用します。

自動移行を実行するには、目的のデータベースに接続されているサーバーを起動します。新しいバージョンのサーバーのデータベーススキーマが変更された場合は、データベースが移行されます。

データベーススキーマを手動でアップグレードするには、デフォルトの connections-jpa プロバイダーの migration-strategy プロパティー値を manual に設定します。

kc.sh start --spi-connections-jpa-legacy-migration-strategy manual

kc.sh start --spi-connections-jpa-legacy-migration-strategy manual

この設定でサーバーを起動すると、データベースを移行する必要があるかどうかがチェックされます。必要な変更は bin/keycloak-database-update.sql SQL ファイルに書き込まれます。このファイルを確認してデータベースに対して手動で実行できます。

エクスポートされた SQL ファイルのパスと名前を変更するには、デフォルトの connections-jpa プロバイダーの migration-export プロパティーを設定します。

kc.sh start
   --spi-connections-jpa-legacy-migration-export <path>/<file.sql>

kc.sh start
   --spi-connections-jpa-legacy-migration-export <path>/<file.sql>

このファイルをデータベースに適用する方法の詳細は、使用しているリレーショナルデータベースのドキュメントを参照してください。変更がファイルに書き込まれると、サーバーは終了します。

プロパティーの指定を気にせずに Red Hat build of Keycloak を試すには、以下の表の説明に従って開発モードでディストリビューションを起動できます。ただし、このモードは開発専用であり、実稼働環境では使用しないでください。

Red Hat build of Keycloak には、実稼働用の専用の起動モード ./kc.sh start があります。start-dev で実行する場合の違いは、デフォルトの設定値が異なることです。デフォルトでセキュリティー保護された厳密な設定セットアップが自動的に使用されます。実稼働モードでは、HTTP が無効になり、明示的な TLS とホスト名の設定が必要です。

Red Hat build of Keycloak は、以前に Red Hat Single Sign-On 7.6 で使用されていたのと同じデータベースインスタンスを使用できます。データベーススキーマは、Red Hat build of Keycloak が初めてデータベースに接続するときに自動的に移行されます。

Red Hat Single Sign-On 7.6 Operator では、外部データベース接続はシークレットを使用して設定していました。次に例を示します。

apiVersion: v1
kind: Secret
metadata:
  name: keycloak-db-secret
  namespace: keycloak
  labels:
    app: sso
stringData:
  POSTGRES_DATABASE:  kc-db-name
  POSTGRES_EXTERNAL_ADDRESS: my-postgres-hostname
  POSTGRES_EXTERNAL_PORT: 5432
  POSTGRES_USERNAME: user
  POSTGRES_PASSWORD: pass
type: Opaque

apiVersion: v1
kind: Secret
metadata:
  name: keycloak-db-secret
  namespace: keycloak
  labels:
    app: sso
stringData:
  POSTGRES_DATABASE:  kc-db-name
  POSTGRES_EXTERNAL_ADDRESS: my-postgres-hostname
  POSTGRES_EXTERNAL_PORT: 5432
  POSTGRES_USERNAME: user
  POSTGRES_PASSWORD: pass
type: Opaque

Red Hat build of Keycloak では、データベースは、シークレットとして参照される認証情報を使用して Keycloak CR に直接設定されます。次に例を示します。

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  db:
    vendor: postgres
    host: my-postgres-hostname
    port: 5432
    usernameSecret:
      name: keycloak-db-secret
      key: username
    passwordSecret:
      name: keycloak-db-secret
      key: password
  ...

apiVersion: v1
kind: Secret
metadata:
  name: keycloak-db-secret
stringData:
  username: "user"
  password: "pass"
type: Opaque

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  db:
    vendor: postgres
    host: my-postgres-hostname
    port: 5432
    usernameSecret:
      name: keycloak-db-secret
      key: username
    passwordSecret:
      name: keycloak-db-secret
      key: password
  ...

apiVersion: v1
kind: Secret
metadata:
  name: keycloak-db-secret
stringData:
  username: "user"
  password: "pass"
type: Opaque

Red Hat Single Sign-On 7.6 Operator では、デフォルトで、OpenShift CA によって生成された TLS シークレットを使用するようにサーバーが設定されていました。Red Hat build of Keycloak Operator では、実稼働環境のベストプラクティスを実現するために、TLS については何も前提を設けておらず、ユーザーが独自の TLS 証明書とキーペアを提供する必要があります。次に例を示します。

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  http:
    tlsSecret: example-tls-secret
  ...

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  http:
    tlsSecret: example-tls-secret
  ...

tlsSecret で参照されるシークレットの形式には、標準の Kubernetes TLS シークレット (kubernetes.io/tls) タイプを使用する必要があります。

Red Hat Single Sign-On 7.6 Operator は、デフォルトで、ルートで再暗号化 TLS Termination ストラテジーを使用していました。Red Hat build of Keycloak Operator は、デフォルトでパススルーストラテジーを使用します。また、Red Hat Single Sign-On 7.6 Operator は、TLS Termination の設定をサポートしていました。Red Hat build of Keycloak Operator は、現在のリリースでは TLS Termination をサポートしていません。

デフォルトの Operator 管理のルートが必要な TLS 設定を満たさない場合は、ユーザーがカスタムルートを作成し、デフォルトのルートを次のようにして無効にする必要があります。

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ingress:
    enabled: false
  ...

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  ingress:
    enabled: false
  ...

Red Hat build of Keycloak Operator では、ベストプラクティスを反映し、イミュータブルコンテナーをサポートするために、Keycloak CR でのエクステンションの指定がサポートされていません。エクステンションをデプロイするには、最適化されたカスタムイメージをビルドする必要があります。Keycloak CR には、Red Hat build of Keycloak イメージを指定するための専用フィールドが含まれるようになりました。次に例を示します。

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  image: quay.io/my-company/my-keycloak:latest
  ...

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  image: quay.io/my-company/my-keycloak:latest
  ...

Red Hat Single Sign-On 7.6 Operator は、サーバーのアップグレード実行時の再作成およびローリングストラテジーをサポートしていました。このアプローチは現実的ではありませんでした。Red Hat Single Sign-On 7.6 Operator がアップグレードとデータベース移行を実行する前にデプロイメントをスケールダウンするかどうかは、ユーザーが選択する必要がありました。ローリングストラテジーがいつ安全に使用できるかは、ユーザーには明らかではありませんでした。

したがって、このオプションは Red Hat build of Keycloak Operator では削除され、再作成ストラテジーは常に暗黙的に実行されるようになりました。これにより、新しいサーバーコンテナーイメージで Pod を作成する前にデプロイメント全体がスケールダウンされ、単一のサーバーバージョンのみがデータベースにアクセスできるようになります。

Red Hat build of Keycloak は、OpenShift プローブによって使用される単純なヘルスエンドポイントをデフォルトで公開するようにサーバーを設定します。エンドポイントはデプロイメントに関するセキュリティー上の機密データを公開しませんが、エンドポイントには認証なしでアクセスできます。代替策として、<your-server-context-root>/health エンドポイントをカスタムルートでブロックできます。

以下に例を示します。

Red Hat Single Sign-On 7.6 Operator は、ボリュームなどのデプロイメント設定用の複数の低レベルフィールドを公開していました。Red Hat build of Keycloak Operator は事前設定される部分が多く、これらのフィールドのほとんどは公開されません。ただし、podTemplate として指定されたデプロイメントフィールドを設定することは可能です。次に例を示します。

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  unsupported:
    podTemplate:
      metadata:
        labels:
          foo: "bar"
      spec:
        containers:
          - volumeMounts:
              - name: test-volume
                mountPath: /mnt/test
        volumes:
          - name: test-volume
            secret:
              secretName: test-secret
  ...

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  name: example-kc
spec:
  unsupported:
    podTemplate:
      metadata:
        labels:
          foo: "bar"
      spec:
        containers:
          - volumeMounts:
              - name: test-volume
                mountPath: /mnt/test
        volumes:
          - name: test-volume
            secret:
              secretName: test-secret
  ...

Red Hat Single Sign-On 7.6 Operator では、Red Hat Single Sign-On 7.6 の外部インスタンスへの接続がサポートされていました。Red Hat build of Keycloak Operator では、たとえば、クライアント CR を使用して既存のレルム内にクライアントを作成することは、サポートされなくなりました。

Red Hat Single Sign-On 7.6 で Horizontal Pod Autoscaler (HPA) を使用するには、Keycloak CR の disableReplicasSyncing: true フィールドを設定し、サーバーの StatefulSet をスケーリングする必要がありました。これは不要になりました。Red Hat build of Keycloak Operator の Keycloak CR は、HPA によって直接スケーリングできるためです。

POSTGRESQL_IMAGE_STREAM_TAG、POSTGRESQL_MAX_CONNECTIONS、VOLUME_CAPACITY、および POSTGRESQL_SHARED_BUFFERS は、データベースデプロイメントを作成するために選択した代替パラメーターに移行する必要があります。

Red Hat build of Keycloak Operator は現在、TLS Termination を設定する方法をサポートしていないことに注意してください。デフォルトでは、パススルーストラテジーが使用されます。したがって、パススルーストラテジーと再暗号化ストラテジーのどちらが使用されるかは問題ではないため、プロキシーオプションは、まだファーストクラスシチズンオプションフィールドとして公開されていません。ただし、このオプションが必要な場合は、Red Hat build of Keycloak の証明書を信頼するために、デフォルトの Ingress Operator 証明書を置き換えてルートを手動で設定できます。

Red Hat build of Keycloak Operator のデフォルトの動作は、次のように指定することででオーバーライドできます。

additionalOptions:
   name: proxy
   value: reencrypt

additionalOptions:
   name: proxy
   value: reencrypt

JGROUPS_ENCRYPT_SECRET、JGROUPS_ENCRYPT_KEYSTORE、JGROUPS_ENCRYPT_NAME、JGROUPS_ENCRYPT_PASSWORD、および JGROUPS_CLUSTER_PASSWORD には、Keycloak CR のファーストクラス表現がありません。キャッシュ通信の保護は、キャッシュ設定ファイルを使用して引き続き可能です。

Valid Post Logout Redirect URIs 設定オプションが OIDC クライアントに追加されました。これは、OIDC 仕様に準拠しています。ログインおよびログアウト後のリダイレクトには、別のリダイレクト URI セットを使用できます。Valid Post Logout Redirect URIs に使用される値 + は、Valid Redirect URIs オプションで指定されたのと同じリダイレクト URI のセットがログアウトに使用されることを意味します。この変更は、下位互換性のため、以前のバージョンから移行するときのデフォルトの動作にも一致します。

アプリケーションに、Red Hat build of Keycloak やその他の OpenID プロバイダーと統合するための追加の依存関係が不要になりました。

代わりに、JBoss EAP のネイティブ OpenID Connect クライアントからの OpenID Connect サポートを利用できます。詳細は、JBoss EAP での OpenID Connect を参照してください。

JBoss EAP のネイティブアダプターは、Red Hat build of Keycloak のアダプター JSON 設定によく似た設定スキーマに依存します。たとえば、keycloak.json 設定ファイルを使用したデプロイメントは、JBoss EAP の次の設定にマッピングできます。

{
  "realm": "quickstart",
  "auth-server-url": "http://localhost:8180",
  "ssl-required": "external",
  "resource": "jakarta-servlet-authz-client",
  "credentials": {
    "secret": "secret"
  }
}

{
  "realm": "quickstart",
  "auth-server-url": "http://localhost:8180",
  "ssl-required": "external",
  "resource": "jakarta-servlet-authz-client",
  "credentials": {
    "secret": "secret"
  }
}

JBoss EAP のネイティブアダプターを使用して Jakarta ベースのアプリケーションを Red Hat build of Keycloak と統合する例については、Red Hat build of Keycloak クイックスタートリポジトリーにある次の例を参照してください。

JBoss EAP のネイティブ OpenID Connect クライアントに移行することを強く推奨します。これは JBoss EAP 8 以降にデプロイされた Jakarta アプリケーションに最適です。

Red Hat JBoss Enterprise Application Platform 7.x は、フルサポートの終了に近づいているため、Red Hat build of Keycloak ではサポートされません。Red Hat JBoss Enterprise Application Platform 7.x にデプロイされた既存のアプリケーションについては、メンテナンスサポート対象のアダプターが Red Hat Single Sign-On 7.6 を通じて利用可能です。

Red Hat Single Sign-On 7.6 アダプターは、Red Hat build of Keycloak 24.0 サーバーと組み合わせて使用することがサポートされています。

Red Hat JBoss Enterprise Application Platform JBoss EAP 6.x はメンテナンスサポートの終了に達したため、今後は Red Hat Single Sign-On 7.6 でも Red Hat build of Keycloak でもサポートされません。

このリリースでは、Red Hat build of Keycloak JS アダプターからレガシー Promise API メソッドが削除されました。そのため、アダプターから返された Promise で .success() および .error() を呼び出すことができなくなりました。

以前のリリースでは、Red Hat build of Keycloak JS アダプターを新しい Operator を使用せずに構築すると、非推奨の警告がログに記録されていました。このリリース以降、これを行うと代わりに例外が出力されます。この変更は、JavaScript クラス の想定される動作との整合性を確保し、将来的にアダプターのさらなるリファクタリングを可能にするためのものです。

Red Hat Single Sign-On 7.6 アダプターでセキュリティー保護されたアプリケーションを移行するには、より新しいバージョンのアダプターを提供する Red Hat build of Keycloak 24.0 にアップグレードします。

(o.k. は org.keycloak. パッケージを表します)

Red Hat build of Keycloak では、API の使用を簡素化するために大規模なリファクタリングが行われました。これは既存のコードに影響を与えます。以下の変更の中には、既存のコードの更新が必要なものもあります。以下のセクションでさらに詳しく説明します。

削除されたメソッドを呼び出さない場合、既存のプロバイダーを移行する必要はありません。これはほとんどのプロバイダーに当てはまります。

プロバイダーが削除されたメソッドを使用しているが、ローカルストレージと非ローカルストレージに依存していない場合は、削除された userLocalStorage() から users() メソッドに呼び出しを変更するのが最適です。ここでは、セマンティクスの変更に注意してください。ローカル設定でキャッシュが有効になっている場合、新しいメソッドにキャッシュが含まれるためです。

session.userLocalStorage();

session.userLocalStorage();

session.users();

session.users();

カスタムプロバイダーが特定のプロバイダーのモードを区別する必要がある稀なケースでは、非推奨オブジェクトへのアクセスを、LegacyStoreManagers データストアプロバイダーを使用して提供します。これに該当するのは、プロバイダーがローカルストレージに直接アクセスする場合や、プロバイダーがキャッシュをスキップする場合などです。この方法は、レガシーモジュールがデプロイメントの一部である場合にのみ使用できます。

session.userLocalStorage();

session.userLocalStorage();

((LegacyDatastoreProvider) session.getProvider(DatastoreProvider.class)).userLocalStorage();

((LegacyDatastoreProvider) session.getProvider(DatastoreProvider.class)).userLocalStorage();

一部のユーザーストレージ関連の API は、便宜上 org.keycloak.storage.UserStorageUtil にラップされています。

メソッド getUserStorageProviders、getUserStorageProvidersStream、getClientStorageProviders、getClientStorageProvidersStream、getRoleStorageProviders、および getRoleStorageProvidersStream が削除されました。これらのメソッドに依存するコードは、次のようにインスタンスをキャストする必要があります。

realm.getClientStorageProvidersStream()...;

realm.getClientStorageProvidersStream()...;

((LegacyRealmModel) realm).getClientStorageProvidersStream()...;

((LegacyRealmModel) realm).getClientStorageProvidersStream()...;

同様に、以前 RealmModel インターフェイスを実装していて、これらのメソッドを提供するコードは、新しいインターフェイス LegacyRealmModel を実装する必要があります。このインターフェイスは RealmModel のサブインターフェイスであり、古いメソッドを含んでいます。

public class MyClass extends RealmModel {
    /* might not compile due to @Override annotations for methods no longer present
       in the interface RealmModel. / / ... */
}

public class MyClass extends RealmModel {
    /* might not compile due to @Override annotations for methods no longer present
       in the interface RealmModel. / / ... */
}

public class MyClass extends LegacyRealmModel {
    /* ... */
}

public class MyClass extends LegacyRealmModel {
    /* ... */
}

オブジェクトのキャッシュステータスがサービスに対して透過的になるため、インターフェイス UserCache がモジュール keycloak-model-legacy に移動しました。

レガシー実装に依存するコードは、UserCache に直接アクセスする必要があります。

session**.userCache()**.evict(realm, user);

session**.userCache()**.evict(realm, user);

UserStorageUitl.userCache(session);

UserStorageUitl.userCache(session);

レルムの無効化をトリガーするには、UserCache API を使用する代わりに、イベントをトリガーすることを検討してください。

UserCache cache = session.getProvider(UserCache.class);
if (cache != null) cache.evict(realm)();

UserCache cache = session.getProvider(UserCache.class);
if (cache != null) cache.evict(realm)();

session.invalidate(InvalidationHandler.ObjectType.REALM, realm.getId());

session.invalidate(InvalidationHandler.ObjectType.REALM, realm.getId());

ユーザーの認証情報は、以前は session.userCredentialManager().method(realm, user, ...) を使用して管理されていました。新しい方法では、user.credentialManager().method(...) を使用します。この形式は、認証情報の機能をユーザーの API に近づけるものであり、レルムとストレージに関するユーザー認証情報の場所の知識を前提としていません。

古い API は削除されました。

session.userCredentialManager().createCredential(realm, user, credentialModel)

session.userCredentialManager().createCredential(realm, user, credentialModel)

user.credentialManager().createStoredCredential(credentialModel)

user.credentialManager().createStoredCredential(credentialModel)

カスタムの UserStorageProvider の場合、UserModel を返すときに、新しいメソッド credentialManager() を実装する必要があります。このメソッドは、LegacyUserCredentialManager のインスタンスを返す必要があります。

public class MyUserStorageProvider implements UserLookupProvider, ... {
    /* ... */
    protected UserModel createAdapter(RealmModel realm, String username) {
        return new AbstractUserAdapter(session, realm, model) {
            @Override
            public String getUsername() {
                return username;
            }
        };
    }
}

public class MyUserStorageProvider implements UserLookupProvider, ... {
    /* ... */
    protected UserModel createAdapter(RealmModel realm, String username) {
        return new AbstractUserAdapter(session, realm, model) {
            @Override
            public String getUsername() {
                return username;
            }
        };
    }
}

public class MyUserStorageProvider implements UserLookupProvider, ... {
    /* ... */
    protected UserModel createAdapter(RealmModel realm, String username) {
        return new AbstractUserAdapter(session, realm, model) {
            @Override
            public String getUsername() {
                return username;
            }

            @Override
            public SubjectCredentialManager credentialManager() {
                return new LegacyUserCredentialManager(session, realm, this);
            }
        };
    }
}

public class MyUserStorageProvider implements UserLookupProvider, ... {
    /* ... */
    protected UserModel createAdapter(RealmModel realm, String username) {
        return new AbstractUserAdapter(session, realm, model) {
            @Override
            public String getUsername() {
                return username;
            }

            @Override
            public SubjectCredentialManager credentialManager() {
                return new LegacyUserCredentialManager(session, realm, this);
            }
        };
    }
}

Java EE のサポートを備えた新しいアーティファクトは、org.keycloak:keycloak-admin-client-jee です。Jakarta EE のサポート

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-admin-client-jakarta</artifactId>
    <version>18.0.0.redhat-00001</version>
</dependency>

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-admin-client-jakarta</artifactId>
    <version>18.0.0.redhat-00001</version>
</dependency>

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-admin-client</artifactId>
    <version>22.0.0.redhat-00001</version>
</dependency>

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-admin-client</artifactId>
    <version>22.0.0.redhat-00001</version>
</dependency>