2.2. JavaScript アダプター

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

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

デフォルトでは、JavaScript アダプターは Authorization Code フローを使用します。

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

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

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

暗黙のフローを有効にするには、Red Hat Single Sign-On 管理コンソールで、クライアントの Implicit Flow Enabled フラグを有効にする必要があります。また、init メソッドに implicit 値を持つパラメーター フロー を渡す必要があります。

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

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

注記 1 つは、アクセストークンのみが提供され、更新トークンはありません。そのため、アクセストークンの期限が切れると、アプリケーションが Red Hat Single Sign-On に再度リダイレクトして新しいアクセストークンを取得する必要があります。

Red Hat Single Sign-On は、Hybrid フローにも対応しています。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

const keycloak = new Keycloak();

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

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

const keycloak = new Keycloak();

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

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

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

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

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

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

const keycloak = new Keycloak();

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

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

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

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

const keycloak = new Keycloak();

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

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

JavaScript アダプターは、Base64 (window.btoa および window.atob)、HTML5 History API、およびオプションで Promise API に依存します。これらが利用できないブラウザーをサポートする必要がある場合 (例: IE9) は、polyfillers を追加する必要があります。

ポリフィルライブラリーの例:

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

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