1. 概要

このガイドの目的は、様々な機能を試用、検証できるように、できるだけ早くKeycloakを起動することです。内容は、デフォルトのデータベースとサーバーの設定に大きく依存しており、複雑な配備のオプションについては言及しません。機能や設定オプションの詳細については、各種リファレンスガイドを参照してください。

2. インストールと起動

この非常に短いチュートリアルでは、スタンドアロン・モードにてサーバーを起動して、初期管理者ユーザーを設定し、Keycloak管理コンソールにログインする方法について、説明します。

2.1. 配布ファイルのインストール

Keycloakサーバーは以下の 配布ファイル に含まれています。

  • 'keycloak-3.4.3.Final.[zip|tar.gz]'

'keycloak-3.4.3.Final.[zip|tar.gz]'ファイルはサーバーのみの配布物です。Keycloakサーバーを実行させるスクリプトとバイナリ以外は含んでおりません。

これらのファイルを解凍するには、unzip または gunzip および tar ユーティリティを実行します。

2.2. サーバーの起動

Keycloakサーバーを起動するには、サーバー配布物の bin/ ディレクトリに移動します。

Standalone Boot Scripts

standalone boot files

サーバーを起動するには下記を実行します

Linux/Unix
$ .../bin/standalone.sh
Windows
> ...\bin\standalone.bat

2.3. 管理者アカウントの作成

サーバーが起動したあと、ブラウザーを開きURL http://localhost:8080/auth へ移動します。ページは以下のようになります。

ウェルカムページ

initial welcome page

Keycloakにはデフォルト設定された管理者アカウントはありません。ウェルカムページにて作成する必要があります。当アカウントを使用して、 master レルムの管理コンソールへのログインが可能となる管理者を作成できます。それにより、レルムとユーザーの作成およびKeycloakに保護されるアプリケーションの登録を始めることができます。

localhost を使用して接続する場合は、初期管理者ユーザーのみを作成できます。これはセキュリティ対策のためです。また、スクリプト add-user-keycloak.sh を使用してコマンドラインにて初期管理者ユーザーの作成をすることも可能です。詳しくはServer Installation and Configuration GuideならびにServer Administration Guideを参照してください。

2.4. 管理コンソールへのログイン

初期管理者アカウントを作成したあと、以下の手順に沿って、管理コンソールにログインすることができます。

  1. ウェルカムページの一番下にある 管理コンソール のリンクをクリックします。もしくは、 http://localhost:8080/auth/admin/ にてコンソールのURLに直接アクセスすることも可能です。

    ログインページ

    login page

  2. ウェルカムページにて作成したユーザー名とパスワードを入力します。Keycloak管理コンソールページが開きます。

    管理コンソール

    admin console

管理コンソール内の機能、ボタンまたはフィールドについて知りたい場合は、クエスチョンマーク ? のアイコンにマウスオーバーします。そうすると、興味のある項目を説明するツールチップ・テキストがポップアップ表示されます。 このとおり実行すると、ツールチップは上記のようになります。

3. レルムとユーザーの作成

このチュートリアルでは、Keycloak管理コンソール内に新規レルムを作成し、そのレルムに新規ユーザーを追加する方法を説明します。この新規ユーザーを使用して、新規レルムにログインし、全ユーザーがアクセス可能なビルトインのユーザー・アカウント・サービスへと進みます。

3.1. 始める前に

このチュートリアルの操作を始める前に、Keycloakのインストールを完了し、インストールと起動のチュートリアルに沿って初期管理者ユーザーを作成する必要があります。

3.2. 新規レルムの作成

新規レルムを作成するには、以下の手順に従います。

  1. インストールと起動のチュートリアルに沿って作成したアカウントを使用して、Keycloak管理コンソールにログインします。

    管理コンソールリンク

    http://localhost:8080/auth/admin/

  2. 左側の一番上コーナーにある Master というタイトルのドロップダウンメニューにて、Add Realm をクリックします。Master レルムにログインした場合は、このドロップダウンメニューには作成された全レルムがリスト表示されます。レルム追加ページが開きます。

    レルムの追加メニュー

    add realm menu

  3. はじめから新規レルムを作成しますので、レルム名に demo と入力して Create をクリックします。

    レルムの作成

    create realm

レルムを作成すると、管理コンソールのメインページが開きます。現在のレルムは demo と設定されます。左上隅のドロップダインメニューをクリックして、管理下にある master レルムといま作成したレルムを切替えることができます。

3.3. 新規ユーザーの作成

以下の手順に沿って、demo レルムに新規ユーザーを作成し、そのアカウントの仮パスワードを設定します。

  1. 左メニューバーで Users をクリックします。ユーザー一覧ページが開きます。

    Users

    users

  2. 空のユーザーリストの右側にある Add User をクリックします。

    Add User

    add user

  3. 入力が必要な欄は、Username のみです。入力が終わりましたら、Save をクリックします。新規ユーザーの管理ページが開きます。

  4. 次に、新規ユーザーの仮パスワードを設定します。Credentials タブをクリックします。

    仮パスワードの設定

    credentials

  5. 新しいパスワードとパスワード（確認）の入力を行います。赤い Reset Password ボタンが表示されます。

  6. ユーザー・パスワードを指定した新しいパスワードにリセットするには、Reset Password をクリックします。

このパスワードは一時的なもので、最初のログイン時に変更する必要があります。Reset Password をクリックする前に、Temporary のスイッチを On から Off に切替えることで、永続的なものにすることができます。

3.4. ユーザー・アカウント・サービス

  1. ユーザーを作成した後、右側のドロップダウン・メニューをクリックして Sign Off を選び、管理コンソールをログアウトします。

  2. 以下のリンクをクリックして、今作成したユーザーで demo レルムのユーザー・アカウント・サービスにログインします。

    ユーザー・アカウント・リンク

    http://localhost:8080/auth/realms/demo/account

  3. 以前に作成したユーザー名とパスワードを入力します。Temporaryのスイッチを以前 Off に切替えていなかった場合は、ログインしたあとに永続的なパスワードを作成する必要があります。

    Update Password

    update password

ユーザー・アカウント・サービスのページが開きます。レルム内の全ユーザーはデフォルトでこのアカウント・サービスにアクセスすることができます。ユーザーのプロファイル情報の更新および認証情報の変更または追加ができます。このサービスについての詳細は、Server Administration Guideを参照ください。

4. JBossサーブレット・アプリケーションのセキュリティー保護

この章では、WildFlyアプリケーション・サーバーのJavaサーブレットのアプリケーションをセキュリティー保護する方法について説明します。まずは、WildFlyアプリケーション・サーバーの配布物にKeycloakクライアント・アダプターをインストールします。次に、Keycloak管理コンソールにクライアント・アプリケーションを作成して登録します。最後に、Keycloakによって保護されるように、アプリケーションを設定します。

4.1. 始める前に

このチュートリアルの操作を始める前に、Keycloakのインストールを完了し、インストールと起動のチュートリアルに沿って初期管理者ユーザーを作成する必要があります。これには注意事項があります。Keycloakサーバーと同じマシンで、別途WildFlyインスタンスを起動する必要があります。この別インスタンスではJavaサーブレット・アプリケーションを起動します。そのため、同じマシンで起動させる際にポートが競合しないように、異なるポートでKeycloakを起動する必要があります。コマンドラインで jboss.socket.binding.port-offset システム・プロパティーを使います。当プロパティーの値は、Keycloakサーバーで開いた全ポートの基準値に加算される数値です。

Keycloakサーバーを起動するには下記を実行します。

Linux/Unix
$ .../bin/standalone.sh -Djboss.socket.binding.port-offset=100
Windows
> ...\bin\standalone.bat -Djboss.socket.binding.port-offset=100

Keycloakを起動したあと、http://localhost:8180/auth/admin/ にて管理コンソールにアクセスすることができます。

4.2. クライアント・アダプターのインストール

WildFly の配布物をダウンロードし、マシンのディレクトリに解凍します。

次に、keycloak.orgからWildFly OpenID Connectアダプターの配布物をダウンロードします。

WildFly 配布物のルートディレクトリに、このファイルを解凍します。

次に、以下の操作を実行します。

WildFly 10・Linux/Unix
$ cd bin
$ ./jboss-cli.sh --file=adapter-install-offline.cli
WildFly 10・Windows
> cd bin
> jboss-cli.bat --file=adapter-install-offline.cli
WildFly 11・Linux/Unix
$ cd bin
$ ./jboss-cli.sh --file=adapter-elytron-install-offline.cli
WildFly 11・Windows
> cd bin
> jboss-cli.bat --file=adapter-elytron-install-offline.cli

このスクリプトにより、アプリケーション・サーバーの配布物に含まれる …​/standalone/configuration/standalone.xml が適切に編集されます。最後に、アプリケーション・サーバーを起動します。

Linux/Unix
$ .../bin/standalone.sh
Windows
> ...\bin\standalone.bat

4.3. アプリケーション・コードのダウンロード、ビルドおよびデプロイ

セキュリティー保護をしようとしているアプリケーションのプロジェクトとコードは、Keycloakクイックスタートリポジトリで入手できます。続行する前に、マシンに下記をインストールして、"PATH"を通しておく必要があります。

  • Java JDK 8

  • Apache Maven 3.1.1以上

  • Git

You can obtain the code by cloning the repository at https://github.com/keycloak/keycloak-quickstarts. The quickstarts are designed to work with the most recent Keycloak release.

以下の手順に沿って、コードをダウンロード、ビルド、およびデプロイします。但し、以下の手順を実行する前に、必ずWildFlyアプリケーション・サーバーが起動している状態にしておきます。

プロジェクトのクローン
$ git clone https://github.com/keycloak/keycloak-quickstarts
$ cd keycloak-quickstarts/app-profile-jee-vanilla
$ mvn clean wildfly:deploy

アプリケーション・サーバーのコンソール・ウィンドウ内に、いくつかテキストがスクロールダウンで表示されます。アプリケーションを正常にデプロイしたあと、以下URLに移動します。

http://localhost:8080/vanilla

アプリケーションのログインページ

app login page

アプリケーションの web.xml ファイルを開くと、 BASIC 認証によってアプリケーションが保護されていることを確認できます。ログインページでログインボタンをクリックすると、ブラウザでBASIC認証ログイン・ダイアログがポップアップ表示されます。

アプリケーションのログイン・ダイアログ

client auth required

このアプリケーションはアイデンティティー・プロバイダーによりセキュリティー保護されていないため、ダイアログ・ボックスに何か入力すると、サーバーから Forbidden というメッセージが送り返されることになります。次のセクションでは、このデプロイしたアプリケーションを入手してセキュリティー保護する方法についてご説明します。

4.4. クライアントの作成と登録

次の手順に沿って、Keycloak管理コンソールでクライアントを定義して登録します。

  1. チュートリアルに沿って以前に作成した管理者アカウントで、管理コンソールにログインします。

  2. 左上のドロップダウン・メニューで、demo レルムを選択して管理します。左側のメニューで Clients をクリックします。クライアントのページが開きます。

    Clients

    clients

  3. 右側にある Create をクリックします。

  4. 下記のとおり、空欄に入力します。

    Add Client

    add client

  5. Save ボタンをクリックすると、クライアント・アプリケーションのエントリが作成されます。ここで、アプリケーションをデプロイしたWildFlyインスタンスに戻り、アプリケーションがKeycloakに保護されるように設定する必要があります。必要な設定のテンプレートは、Keycloak管理コンソールのクライアントエントリ内の Installation タブに移動して入手することができます。

    インストールタブ

    client installation

  6. Keycloak OIDC JBoss Subsystem XML を選択します。 コピーアンドペーストで貼り付ける必要がある XMLテンプレートが生成されます。

    XMLテンプレート

    client install selected

4.5. サブシステムの設定

今インストールページからXMLテンプレートをコピーしたところですが、これを standalone.xml ファイルにペーストする必要があります。standalone.xml ファイルはアプリケーションをデプロイしたアプリケーション・サーバー・インスタンスの standalone/configuration ディレクトリーにあります。

  1. standalone/configuration/standalone.xml ファイルを開き、以下のテキストを検索します。

    <subsystem xmlns="urn:jboss:domain:keycloak:1.1"/>

  2. インストールページからテンプレートをペーストするために、以下のとおりに修正します。

    <subsystem xmlns="urn:jboss:domain:keycloak:1.1">
</subsystem>

  3. <subsystem> 要素内で、テンプレートを貼り付けます。そうすると、以下のようになります。

    <subsystem xmlns="urn:jboss:domain:keycloak:1.1">
  <secure-deployment name="WAR MODULE NAME.war">
    <realm>demo</realm>
    <auth-server-url>http://localhost:8180/auth</auth-server-url>
    <public-client>true</public-client>
    <ssl-required>EXTERNAL</ssl-required>
    <resource>vanilla</resource>
  </secure-deployment>
</subsystem>

  4. WAR MODULE NAME を vanilla に書き換えます。そうすると、以下のとおりになります。

    <subsystem xmlns="urn:jboss:domain:keycloak:1.1">
  <secure-deployment name="vanilla.war">
  ...
</subsystem>

  5. アプリケーション・サーバーを起動します。

  6. http://localhost:8080/vanilla に移動して login をクリックします。Keycloakログインページが開きます。新規ユーザーの作成の章で作成したユーザーを使用してログインすることができます。