2.2. JavaScript アダプター
Red Hat Single Sign-On には、クライアント側 JavaScript ライブラリーが同梱されており、これを使用して HTML5/JavaScript アプリケーションをセキュアにすることができます。JavaScript アダプターは、Cordova アプリケーションに対して組み込みサポートがあります。
ライブラリーは /auth/js/keycloak.js にある Red Hat Single Sign-On サーバーから直接取得でき、ZIP アーカイブとして配布されます。
ベストプラクティスは、サーバーのアップグレード時に自動的に更新されるため、Red Hat Single Sign-On Server から直接 JavaScript アダプターを読み込むことです。代わりにアダプターを Web アプリケーションにコピーする場合は、サーバーをアップグレードした後のみアダプターをアップグレードするようにしてください。
クライアント側のアプリケーションの使用に関する重要なことは、クライアントの認証情報をクライアント側のアプリケーションに保存する安全な方法がないため、クライアントがパブリッククライアントである必要があることです。これにより、クライアント用に構成したリダイレクト URI が正しく、可能な限り具体的であることを確認することが非常に重要になります。
JavaScript アダプターを使用するには、まず Red Hat Single Sign-On 管理コンソールでアプリケーションのクライアントを作成する必要があります。Access Type で public が選択されていることを確認してください。
また、Valid Redirect URI と Web Origins を設定する必要があります。そうしないと、セキュリティーの脆弱性が生じる可能性があるため、できるだけ具体的にしてください。
クライアントを作成したら、インストール タブをクリックして、Format Option の Keycloak OIDC JSON を選択し、Download をクリックします。ダウンロードした keycloak.json ファイルは、HTML ページと同じ場所にある Web サーバーでホストされている必要があります。
または、設定ファイルを省略し、アダプターを手動で設定することもできます。
以下の例は、JavaScript アダプターを初期化する方法を示しています。
<head>
<script src="keycloak.js"></script>
<script>
var keycloak = new Keycloak();
keycloak.init().then(function(authenticated) {
alert(authenticated ? 'authenticated' : 'not authenticated');
}).catch(function() {
alert('failed to initialize');
});
</script>
</head>
keycloak.json ファイルが別の場所にある場合は、それを指定することができます。
var keycloak = new Keycloak('http://localhost:8080/myapp/keycloak.json');代わりに、必要な設定で JavaScript オブジェクトを渡すことができます。
var keycloak = new Keycloak({
url: 'http://keycloak-server/auth',
realm: 'myrealm',
clientId: 'myapp'
});
デフォルトでは認証を行うには login 関数を呼び出す必要があります。ただし、アダプターが自動的に認証されるようにするオプションは 2 つあります。login-required または check-sso を init 関数に渡すことができます。ユーザーが Red Hat Single Sign-On にログインしている場合は、login-required がクライアントを認証します。そうでないと、ログインページが表示されます。check-sso は、ユーザーがログインしていない場合のみクライアントを認証します。ユーザーがログインしていない場合、ブラウザーはアプリケーションにリダイレクトされ、認証されていないままになります。
silent check-sso オプションを設定できます。この機能を有効にすると、ブラウザーは Red Hat Single Sign-On サーバーへのフルリダイレクトを行なさずにアプリケーションに戻りますが、このアクションは非表示の iframe で実行されるため、アプリケーションリソースを読み込むだけで済みます。アプリが初期化されたときにブラウザーによって 1 回解析され、Red Hat Single Sign-On からアプリにリダイレクトされた後に再度解析されることはありません。これは、SPA (Single Page Applications) の場合において特に便利です。
silent check-sso を有効にするには、init メソッドで silentCheckSsoRedirectUri 属性を指定する必要があります。この URI は、アプリケーションで有効なエンドポイントである必要があります (そして、Red Hat Single Sign-On 管理コンソールでクライアントの有効なリダイレクトとして設定する必要があります)。
keycloak.init({
onLoad: 'check-sso',
silentCheckSsoRedirectUri: window.location.origin + '/silent-check-sso.html'
})認証の状態が正常にチェックされ、Red Hat Single Sign-On サーバーからトークンを取得すると、サイレント check-sso リダイレクト URI のページが iframe に読み込まれます。受信したトークンをメインアプリケーションに送信する以外のタスクはなく、次のようになります。
<html>
<body>
<script>
parent.postMessage(location.href, location.origin)
</script>
</body>
</html>指定された場所にあるこのページは、アプリケーション自身が提供する必要があり、JavaScript アダプターの一部では ない ことに注意してください。
Chrome バージョン 80 (2020 年 2 月リリース) からは、Red Hat Single Sign-On 側で SSL/TLS 接続が設定されている場合のみ、サイレントの check-sso 機能が動作するようになります。
login-required を有効にするには、onLoad を login-required に設定し、init メソッドに渡します。
keycloak.init({
onLoad: 'login-required'
})
ユーザーが認証された後、アプリケーションは 認証 ヘッダーにベアラートークンを含めることで、Red Hat Single Sign-On で保護された RESTful サービスへのリクエストを行うことができます。以下に例を示します。
var loadData = function () {
document.getElementById('username').innerText = keycloak.subject;
var url = 'http://localhost:8080/restful-service';
var req = new XMLHttpRequest();
req.open('GET', url, true);
req.setRequestHeader('Accept', 'application/json');
req.setRequestHeader('Authorization', 'Bearer ' + keycloak.token);
req.onreadystatechange = function () {
if (req.readyState == 4) {
if (req.status == 200) {
alert('Success');
} else if (req.status == 403) {
alert('Forbidden');
}
}
}
req.send();
};
注意すべきことの 1 つは、アクセストークンの有効期限はデフォルトで短いため、リクエストを送信する前にアクセストークンの更新が必要になることが場合があることです。これは updateToken メソッドで行うことができます。updateToken メソッドは、トークンが正常に更新された場合にのみサービスを呼び出し、そうでない場合にはユーザーにエラーを表示することを容易にする Promise を返します。以下に例を示します。
keycloak.updateToken(30).then(function() {
loadData();
}).catch(function() {
alert('Failed to refresh token');
});2.2.1. セッションステータスの iframe
デフォルトでは、JavaScript アダプターは、Single-Sign Out が発生したかどうかを検出するために使用される非表示の iframe を作成します。これにはネットワークトラフィックは必要ありません。代わりに、特別なステータスクッキーを確認してステータスを取得します。init メソッドに渡されるオプションで checkLoginIframe: false を設定することで、この機能を無効できます。
このクッキーを直接参照する必要はありません。この形式は変更でき、アプリケーションではなく、Red Hat Single Sign-On サーバーの URL に関連付けられている可能性があります。
Chrome バージョン 80 以降 (2020 年 2 月にリリース)、ステータス iframe は、Red Hat Single Sign-On に設定された SSL / TLS 接続上で特別なクッキーのみを確認できます。非セキュアな接続を使用すると、iframe がステータスをチェックするたびに Red Hat Single Sign-On にリダイレクトされる可能性があります。iframe を無効にしたり、Red Hat のシングルサインオン側で SSL/TLS を設定 することで、この動作を回避できます。