1. 概要

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

このガイドは、Keycloakを使い始めるのに役立ちます。ここではサーバー設定とデフォルトのデータベースの使用について説明します。高度なデプロイメント・オプションはカバーされていません。機能や設定オプションの詳細については、他のリファレンス・ガイドを参照してください。

2. インストールと起動

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

このセクションでは、スタンドアローン・モードでKeycloakサーバーを起動し、初期管理ユーザーを設定し、Keycloak管理コンソールにログインする方法について説明します。

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

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

下記のKeycloakサーバーをダウンロードします。

  • keycloak-4.8.3.Final.[zip|tar.gz]

このファイルは Keycloak downloads からダウンロードできます。

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

任意のディレクトリーにファイルを配置し、 unzip または tar ユーティリティーを使用して解凍します。

Linux/Unix
$ unzip keycloak-4.8.3.Final.zip

または

$ tar -xvzf keycloak-4.8.3.Final.tar.gz
Windows
> unzip keycloak-4.8.3.Final.zip

2.2. サーバーの起動

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

Keycloakサーバーを起動するには、サーバー配布物の bin ディレクトリーに移動して standalone 起動スクリプトを実行します。

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

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

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

サーバーが起動した後、ブラウザーで http://localhost:8080/auth を開きます。ウェルカムページは、サーバーが実行中であることを示します。

ユーザー名とパスワードを入力して、最初の管理ユーザーを作成します。

このアカウントは master レルムの管理コンソールにログインすることができます。レルムとユーザーを作成し、Keycloakによって保護されるアプリケーションを登録します。

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

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

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

最初の管理者アカウントを作成したら、次の手順を実行して管理コンソールにログインします。

  1. Welcome ページの Administration Console リンクをクリックするか、コンソールURLの http://localhost:8080/auth/admin/ に直接アクセスします。

  2. Welcome ページで作成したユーザー名とパスワードを入力して、 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 Out を選択して管理コンソールからログアウトします。

  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つの注意点があります。WildFlyはkeycloakにバンドルされていますが、これをアプリケーション・コンテナーとして使用することはできません。代わりに、Javaサーブレット・アプリケーションを実行するには、Keycloakサーバーと同じマシン上で別のWildFlyインスタンスを実行する必要があります。ポートの競合を避けるため、WildFlyとは異なるポートを使用してKeycloakを実行します。

使用するポートを調整するには、コマンドラインからサーバーを起動する際に jboss.socket.binding.port-offset システム・プロパティーの値を変更します。このプロパティーの値は、Keycloakサーバーによって開かれたすべてのポートの基本値に追加される数値です。

ポートを調整してKeycloakサーバーを起動するには、以下を実行します。

Linux/Unix
$ cd 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
$ cd 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ログインページが開いたら、新規ユーザーの作成で作成したユーザーを使用してログインします。