6.4. オフラインアクセス

オフラインアクセス ログイン時に、クライアントアプリケーションは更新トークンではなくオフライントークンを要求します。クライアントアプリケーションは、このオフライントークンを保存し、ユーザーがログアウトした場合に今後のログインに使用できます。このアクションは、ユーザーがオンラインにない場合でも、アプリケーションがユーザーの代わりにオフライン操作を実行する必要がある場合に便利です。たとえば、通常のデータバックアップです。

クライアントアプリケーションは、ストレージでオフライントークンを永続化し、これを使用して Red Hat build of Keycloak サーバーから新しいアクセストークンを取得します。

更新トークンとオフライントークンの相違点は、オフライントークンの期限が切れず、SSO Session Idle timeout および SSO Session Max lifespan の対象でないことです。オフライントークンは、ユーザーのログアウトまたはサーバーの再起動後に有効になります。オフライントークンは、少なくとも 30 日に 1 回の更新トークンアクション、または Offline Session Idle の値に使用する必要があります。

Offline Session Max Limited を有効にすると、トークンの更新アクションにオフライントークンを使用した場合でも、オフライントークンは 60 日後に期限切れになります。この値 Offline Session Max は、管理コンソールで変更できます。

オフラインアクセスを使用する場合、クライアントのアイドル状態と最大タイムアウトは クライアントレベル でオーバーライドできます。クライアントの Advanced Settings タブにある Client Offline Session Idle オプションと Client Offline Session Max オプションを使用すると、特定のアプリケーションのオフラインタイムアウトを短くすることができます。クライアントセッション値は更新トークンの有効期限も制御しますが、グローバルオフラインユーザー SSO セッションに影響を与えることはありません。Client Offline Session Max オプションは、レルムレベルで Offline Session Max Limited が Enabled の場合にのみクライアントで評価されます。

Revoke Refresh Token オプションを有効にすると、各オフライントークンを 1 回だけ使用できます。更新後、前の 1 つではなく、更新応答から新しいオフライントークンを保存する必要があります。

ユーザーは User Account Console で、Red Hat build of Keycloak が付与したオフライントークンの表示と取り消しを行えます。管理者は、Consents タブで 管理コンソールの個々のユーザーのオフライントークンを取り消すことができます。管理者は、各クライアントの Offline Access タブで発行されたオフライントークンすべてを表示できます。管理者は、失効ポリシー を設定して、オフライントークンを取り消すことができます。

オフライントークンを発行するには、ユーザーは realm-level offline_access ロールのロールマッピングが必要です。クライアントには、そのロールをスコープで割り当てる必要もあります。クライアントは、offline_access クライアント スコープを Optional client scope としてロールに追加し、デフォルトでは実行する必要があります。

クライアントは、認可要求を Red Hat build of Keycloak に送信するときに scope=offline_access パラメーターを追加することで、オフライントークンを要求できます。Red Hat build of Keycloak OIDC クライアントアダプターは、アプリケーションのセキュアな URL (例: http://localhost:8080/customer-portal/secured?scope=offline_access) にアクセスするために使用すると、このパラメーターを自動的に追加します。認証要求の本文に scope=offline_access が含まれている場合、Direct Access Grant および Service Accounts はオフライントークンをサポートします。

オフラインセッションは、Infinispan キャッシュのほかに、データベースにも保存されます。Red Hat build of Keycloak サーバーが再起動するか、オフラインセッションが Infinispan キャッシュからエビクトする場合でも、データベースでは引き続き利用できます。オフラインセッションへのアクセスを試みると、データベースからセッションがロードされ、Infinispan キャッシュにもインポートされます。メモリー要件を削減するために、インポートされたオフラインセッションの有効期間を短縮する設定オプションを導入しました。このようなセッションは、指定された有効期間が経過すると Infinispan キャッシュからエビクトされますが、データベースでは引き続き利用可能です。これにより、特にオフラインセッションが多数あるデプロイメントでは、メモリー消費量が削減されます。現在、オフラインセッションの有効期間のオーバーライドはデフォルトで無効になっています。オフラインユーザーセッションの有効期間のオーバーライドを指定するには、次のパラメーターを使用して Red Hat build of Keycloak サーバーを起動します。

--spi-user-sessions-infinispan-offline-session-cache-entry-lifespan-override=<lifespan-in-seconds>

オフラインクライアントセッションの場合も同様です。

--spi-user-sessions-infinispan-offline-client-session-cache-entry-lifespan-override=<lifespan-in-seconds>