1. 概要

このセクションを編集する 問題を報告する

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

2. インストールと起動

このセクションを編集する 問題を報告する

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

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

このセクションを編集する 問題を報告する

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

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

'keycloak-4.0.0.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. http://localhost:8080/auth/admin/ に移動し、インストールと起動で作成したアカウントを使用してKeycloak管理コンソールにログインします。

  2. Master ドロップダウン・メニューから Add Realm をクリックします。masterレルムにログインすると、このドロップダウン・メニューには既存のすべてのレルムが表示されます。

  3. Name フィールドに demo と入力し、 Create をクリックします。

レルムが作成されると、管理コンソールのメインページが開きます。現在のレルムが demo に設定されていることに注目してください。 Select realm レルムのドロップダウン・メニューのエントリーをクリックして、 master レルムと作成したレルムを切り替えます。

3.3. 新規ユーザーの作成

このセクションを編集する 問題を報告する

demo レルムで新しいユーザーを作成するには、その新しいユーザーの仮パスワードで、次の手順を実行します。

  1. メニューから Users をクリックして、ユーザー一覧ページを開きます。

  2. ユーザーの追加ページを開くには、空のユーザーリストの右側にある Add User をクリックします。

  3. Username フィールドに名前を入力します。唯一の必須フィールドです。 Save をクリックしてデータを保存し、新しいユーザーの管理ページを開きます。

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

  5. 新しいパスワードを入力して確認します。 Reset Password をクリックして、ユーザー・パスワードに新しいパスワードに設定します。

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

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

このセクションを編集する 問題を報告する

  1. 新しいユーザーを作成したら、ユーザーのドロップダウン・メニューを開き、 Sign Off を選択して管理コンソールからログアウトします。

  2. http://localhost:8080/auth/realms/demo/account にアクセスして、作成したばかりのユーザーで demo レルムのユーザー・アカウント・サービスにログインしてください。

  3. 作成したユーザー名とパスワードを入力します。 Temporary 設定を Off に変更した場合を除き、パスワードを作成した後は、正常にログインした後で、永続パスワードを作成する必要があります。

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

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

このセクションを編集する 問題を報告する

このセクションでは、WildFlyアプリケーション・サーバーで、以下の方法でJavaサーブレット・アプリケーションを保護する方法について説明します。

  • WildFlyアプリケーション・サーバー・ディストリビューションにKeycloakクライアント・アダプターをインストールする

  • Keycloak管理コンソールにクライアント・アプリケーションを作成して登録する

  • Keycloakによって保護されるアプリケーションを設定する

4.1. 始める前に

このセクションを編集する 問題を報告する

Javaサーブレット・アプリケーションをセキュリティー保護するには、まずKeycloakのインストールを完了し、インストールと起動に沿って初期管理者ユーザーを作成する必要があります。

1つの注意点があります。Javaサーブレット・アプリケーションを実行するには、Keycloakサーバーと同じマシン上で別のWildFlyインスタンスを実行する必要があります。ポートの競合を避けるため、WildFlyとは異なるポートを使用して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. アプリケーション・コードのダウンロード、ビルドおよびデプロイ

このセクションを編集する 問題を報告する

続行する前に、次のものをマシンにインストールし、PATHで利用可能にする必要があります。

  • Java JDK 8

  • Apache Maven 3.1.1以上

  • Git

https://github.com/keycloak/keycloak-quickstarts のKeycloakクイックスタート・リポジトリーリポジトリーをクローンして、コードを入手することができます。このクイックスタートはKeycloakの最新リリースで動作するように設計されています。

継続する前に、必ずWildFlyアプリケーション・サーバーが起動している状態にしておきます。

コードをダウンロード、ビルド、およびデプロイするは、以下の手順を実行します。

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

インストール中に、アプリケーション・サーバーのコンソール・ウィンドウに何らかのテキスト・スクロールが表示されます。

アプリケーションが正常にデプロイされたことを確認するため、 http://localhost:8080/vanilla にアクセスし、ログインページを表示します。

Login をクリックすると、ブラウザーはBASIC認証ログイン・ダイアログを表示します。ただし、アプリケーションはまだすべてのアイデンティティー・プロバイダーによって保護されていないため、ダイアログ・ボックスに入力したとしても、サーバーによって Forbidden メッセージが返されます。アプリケーションの web.xml ファイル内でその設定を検索すると、アプリケーションが現在 BASIC 認証によって保護されていることを確認できます。

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

このセクションを編集する 問題を報告する

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

  1. 管理者アカウントで管理コンソールにログインします。

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

    Clients

    clients

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

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

    Add Client

    add client

  5. クライアント・アプリケーション・エントリーを作成するには、 Save をクリックします。

  6. Keycloak管理コンソールの Installation タブをクリックして、設定テンプレートを取得します。

  7. Keycloak OIDC JBoss Subsystem XML を選択して、XMLテンプレートを生成します。次のセクションで使用するために、内容をコピーします。

    XMLテンプレート

    client install selected

4.5. サブシステムの設定

このセクションを編集する 問題を報告する

このアプリケーションがKeycloakによって保護されるように、アプリケーションがデプロイされているWildFlyインスタンスを構成するには、次の手順を実行します。

  1. アプリケーションがデプロイされたWildFlyインスタンス内の standalone/configuration/standalone.xml ファイルを開き、以下のテキストを検索します。

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

  2. このテキストを変更して、Keycloak管理コンソールの Installation タブで取得した Keycloak OIDC JBoss Subsystem XML テンプレートの内容をファイルにペーストする準備をします。XMLエントリーを自己クローズ（self-closing）から一対の開始タグと終了タグに変更します。

    <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. 次のように name を vanilla.war に変更してください。

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

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

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