Keycloakを試す

このガイドは、プロダクション環境で使用する前に、Keycloakを使用して評価する練習に役立ちます。これには、Keycloakサーバーをスタンドアローン・モードでインストールする手順、ユーザーとアプリケーションを管理するためのアカウントとレルムを作成する手順、およびWildFlyサーバー・アプリケーションを保護する手順が含まれています。

Keycloakのサンプル・インスタンスのインストール

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

サーバーのインストール

サーバーはLinuxまたはWindowsにインストールできます。サーバー・ダウンロードZIPファイルには、Keycloakサーバーを実行するためのスクリプトとバイナリーが含まれています。

手順
  1. Keycloak downloadsから keycloak-11.0.0.[zip|tar.gz] をダウンロードします。

  2. 選択したディレクトリーにファイルを配置します。

  3. unzip、tar、Expand-Archiveなどの適切な unzip ユーティリティーを使用して、ZIPファイルを解凍します。

    Linux/Unix
    $ unzip keycloak-11.0.0.zip
    
    または
    
    $ tar -xvzf keycloak-11.0.0.tar.gz
    Windows
    > Expand-Archive -Path 'C:Downloads\keycloak-11.0.0.zip` -DestinationPath 'C:\Downloads'

Keycloakサーバーの起動

インストールしたシステムでサーバーを起動します。

前提条件
  • Keycloakサーバーのインストール中にエラーが発生していないこと

手順
  1. サーバー配布物の bin ディレクトリーに移動します。

  2. standalone 起動スクリプトを実行します。

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

管理者アカウントの作成

Keycloakを使用する前に、Keycloak管理コンソールへのログインに使用する管理者アカウントを作成する必要があります。

前提条件
  • Keycloakサーバー起動時にエラーが発生していないこと。

手順
  1. Webブラウザーで http://localhost:8080/auth を開きます。

    ウェルカムページが開き、サーバーが実行中であることを確認します。

    ウェルカムページ

    Welcome page

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

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

初期管理者アカウントを作成したら、管理コンソールにログインできます。このコンソールで、ユーザーを追加し、Keycloakによってセキュリティー保護されるアプリケーションを登録します。

前提条件
  • 管理コンソールの管理者アカウントを持っていること。

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

    Administration Consoleは、一般的にKeycloakのドキュメントでは管理コンソール(admin console)と呼ばれています。

  2. Welcome ページで作成したユーザー名とパスワードを入力して、 admin console を開きます。

    管理コンソールのログイン画面

    Admin console login screen

    管理コンソールの初期画面が表示されます。

    管理コンソール

    Admin console

次のステップ

管理コンソールにログインできるようになったので、管理者がユーザーを作成してアプリケーションへのアクセス権を付与できるレルムの作成を開始できます。詳細については、 レルムとユーザーの作成 を参照してください。

レルムとユーザーの作成

Keycloak管理コンソールの最初の使用は、レルムを作成し、そのレルムにユーザーを作成することです。そのユーザーを使用して新しいレルムにログインし、すべてのユーザーがアクセスできる組み込みのアカウント・コンソールにアクセスします。

レルムとユーザー

管理コンソールにログインしたら、オブジェクトを管理する領域であるレルムで作業します。レルムには2つのタイプがあります。

  • Masterレルム - このレルムは、Keycloakの初回起動時に作成されます。初回ログイン時に作成した管理者アカウントが含まれています。このレルムは、他のレルムを作成するためにのみ使用します。

  • その他のレルム - これらのレルムは、masterレルムの管理者によって作成されます。これらのレルムでは、管理者がユーザーとアプリケーションを作成します。アプリケーションはユーザーが所有します。

Realms and applications

レルムの作成

masterレルムの管理者として、管理者がユーザーとアプリケーションを作成するレルムを作成します。

前提条件
  • Keycloakがインストールされていること。

  • 管理コンソールの初期管理者アカウントを持っていること。

手順
  1. http://localhost:8080/auth/admin/ に移動し、adminアカウントを使用してKeycloak管理コンソールにログインします。

  2. Master のメニューから Add Realm を選択し、クリックします。masterレルムにログインすると、このメニューには他のすべてのレルムが一覧表示されます。

  3. Name フィールドに demo と入力します。

    新規レルム

    A new realm

    レルム名では大文字と小文字が区別されるため、使用する値をメモしてください。
  4. Create をクリックします。

    メインの管理コンソールページが開き、レルムが demo に設定されます。

    Demoレルム

    Demo realm

  5. Select realm ドロップダウン・リストのエントリーをクリックして、 master レルムと作成したレルムの管理を切り替えます。

ユーザーの作成

demo レルムで、新しいユーザーとその新しいユーザーの一時的なパスワードを作成します。

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

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

  3. Username フィールドに名前を入力します。

    これは唯一の必須フィールドです。

    ユーザー追加ページ

    Add user page

  4. Email Verified スイッチを On に切り替え、 Save をクリックします。

    新しいユーザーの管理ページが開きます。

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

  6. 新しいパスワードを入力して確認します。

  7. ユーザーのパスワードを指定した新しいパスワードにするには、Set Password をクリックします。

    クレデンシャルの管理ページ

    Manage Credentials page

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

アカウント・コンソールへのログイン

レルム内のすべてのユーザーは、アカウント・コンソールにアクセスできます。このコンソールを使用して、プロファイル情報を更新し、クレデンシャルを変更します。これで、作成したレルムでそのユーザーを使用してログインをテストできます。

手順
  1. ユーザーメニューを開き、 Sign Out を選択して、管理コンソールからログアウトします。

  2. http://localhost:8080/auth/realms/demo/account に移動し、作成したユーザーとして demo レルムにログインします。

  3. 新しいパスワードの入力を求められたら、覚えやすいパスワードを入力します。

    パスワードの更新

    Update password

    このユーザーのアカウント・コンソールが開きます。

    アカウント・コンソール

    account console

  4. このページを使用してテストするには、必要なフィールドに値を入力します。

次のステップ

これで、WildFlyで実行されるサンプル・アプリケーションをセキュリティー保護する最後の手順の準備ができました。 サンプル・アプリケーションのセキュリティー保護 を参照してください。

サンプル・アプリケーションのセキュリティー保護

これで、管理者アカウント、レルム、およびユーザーが作成されたので、Keycloakを使用してサンプルのWildFlyサーブレット・アプリケーションをセキュリティー保護できます。WildFlyクライアント・アダプターをインストールし、管理コンソールでアプリケーションを登録します。そして、Keycloakで動作するようにWildFlyインスタンスを変更し、いくつかのサンプルコードとともにKeycloakを使用してアプリケーションをセキュリティー保護します。

前提条件
  • WildFlyとのポートの競合を回避するには、Keycloakが使用するポートを調整する必要があります。

Keycloakが使用するポートの調整

このガイドの手順は、Keycloakサーバーと同じマシンでWildFlyを実行する場合に適用されます。この状況では、WildFlyがKeycloakにバンドルされていても、WildFlyをアプリケーション・コンテナーとして使用することはできません。サーブレット・アプリケーション用に別のWildFlyインスタンスを実行する必要があります。

ポートの競合を回避するには、KeycloakとWildFlyを実行する異なるポートが必要です。

前提条件
  • 管理コンソールの管理者アカウントを持っていること。

  • demoレルムを作成していること。

  • demoレルムにユーザーを作成していること。

手順
  1. WildFly.org からWildFlyをダウンロードします。

  2. ダウンロードしたWildFlyを解凍します。

    $ unzip <filename>.zip
  3. Keycloakのルート・ディレクトリーに移動します。

  4. jboss.socket.binding.port-offset システム・プロパティーの値を指定して、Keycloakサーバーを起動します。この値は、Keycloakサーバーによって開かれたすべてのポートのベース値に追加されます。この例では、 100 です。

    Linux/Unix
    $ cd bin
    $ ./standalone.sh -Djboss.socket.binding.port-offset=100
    Windows
    > ...\bin\standalone.bat -Djboss.socket.binding.port-offset=100
  5. Keycloakサーバーが実行されていることを確認します。 http://localhost:8180/auth/admin/ にアクセスします。

    管理コンソールが開いたら、WildFlyがKeycloakと連携できるようにするクライアント・アダプターをインストールする準備ができています。

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

WildFlyとKeycloakが同じマシンにインストールされている場合、WildFlyにいくつかの変更が必要です。この変更を行うには、Keycloakクライアント・アダプターをインストールします。

前提条件
  • WildFlyがインストールされていること。

  • ../standalone/configuration/standalone.xml をカスタマイズしている場合は、このファイルのバックアップがあること。

手順
  1. keycloak.org から WildFly OpenID Connect Client Adapter の配布物をダウンロードします。

  2. WildFlyのルート・ディレクトリーに移動します。

  3. ダウンロードしたクライアント・アダプターをこのディレクトリーに解凍します。たとえば次のようにします。

    $ unzip <filename>.zip
  4. binディレクトリーに移動します。

    $ cd bin
  5. 使用しているプラットフォームに適したスクリプトを実行します。

    file not found が出力された場合は、前の手順で unzip を使用したかどうかを確認してください。この解凍方法で、ファイルが適切な場所にインストールされます。

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

    このスクリプトは、 …​/standalone/configuration/standalone.xml ファイルを必要に応じて編集します。

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

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

WildFlyアプリケーションの登録

これで、Keycloak管理コンソールでクライアントを定義および登録できます。

前提条件
  • WildFlyで動作するようにクライアント・アダプターをインストールしていること。

手順
  1. 管理者アカウントで管理コンソールにログインします: http://localhost:8180/auth/admin/

  2. 左上のドロップダウン・リストで Demo レルムを選択します。

  3. 左側のメニューの Clients をクリックして、クライアント・ページを開きます。

    Clients

    Clients

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

  5. Add Clientダイアログで、次のようにフィールドに入力して、 vanilla というクライアントを作成します。

    Add Client

    Add Client

  6. Save をクリックします。

  7. 表示される Vanilla クライアントページで、 Installation タブをクリックします。

  8. Keycloak OIDC JSON を選択して、後の手順で必要なファイルを生成します。

    Keycloak.jsonファイル

    Keycloak.json file

  9. Download をクリックして Keycloak.json を後で見つけられる場所に保存します。

  10. XMLテンプレートを生成するには、 Keycloak OIDC JBoss Subsystem XML を選択します。

    XMLテンプレート

    Template XML

  11. 次の手順で使用するために、 Download をクリックしてWildFlyの設定を含むコピーを保存します。

WildFlyインスタンスの変更

WildFlyサーブレット・アプリケーションは、Keycloakによってセキュリティー保護される前に追加の設定が必要です。

前提条件
  • demo レルムに vanilla という名前のクライアントを作成していること

  • このクライアントのテンプレートXMLファイルを保存していること。

手順
  1. WildFlyのルート・ディレクトリーの standalone/configuration ディレクトリーに移動します。

  2. standalone.xml ファイルを開き、次のテキストを検索します。

    <subsystem xmlns="urn:jboss:domain:keycloak:1.1"/>
  3. 次に示すように、自己終了のXMLエントリーを開始タグと終了タグのペアを使用するように変更します。

    <subsystem xmlns="urn:jboss:domain:keycloak:1.1">
    </subsystem>
  4. この例に示すように、 <subsystem> の要素内のXMLテンプレートの内容をペーストします。

    <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>
  5. WAR MODULE NAME.warvanilla.war に変更します。

    <subsystem xmlns="urn:jboss:domain:keycloak:1.1">
      <secure-deployment name="vanilla.war">
      ...
    </subsystem>
  6. アプリケーション・サーバーを再起動します。

アプリケーションをセキュリティー保護するためのサンプルコードのインストール

最後の手順は、https://github.com/keycloak/keycloak-quickstartsリポジトリーからいくつかのサンプルコードをインストールして、このアプリケーションをセキュリティー保護することです。クイックスタートは最新リリースのKeycloakで機能します。

サンプルコードは app-profile-jee-vanilla クイックスタートです。WARを変更せずに、基本認証で保護されているJavaEEアプリケーションを変更する方法を示します。Keycloakクライアント・アダプター・サブシステムは認証方式を変更し、設定をインジェクトします。

前提条件

次のものがマシンにインストールされており、PATHで使用できること。

  • Java JDK 8

  • Apache Maven 3.1.1以上

  • Git

keycloak.json ファイルがあること

手順
  1. WildFlyアプリケーション・サーバーが起動していることを確認してください。

  2. 次のコマンドを使用して、コードをダウンロードし、ディレクトリーを変更します。

    $ git clone https://github.com/keycloak/keycloak-quickstarts
    $ cd keycloak-quickstarts/app-profile-jee-vanilla/config
  3. keycloak.json ファイルを現在のディレクトリーにコピーします。

  4. 1つ上のレベルの app-profile-jee-vanilla ディレクトリーに移動します。

  5. 次のコマンドを使用してコードをインストールします。

    $ mvn clean wildfly:deploy
  6. アプリケーションのインストールが成功したことを確認します。ログインページが表示される http://localhost:8080/vanilla に移動します。

    ログインページの確認成功

    Login page confirming success

  7. demoレルムで作成したアカウントを使用してログインします。

    demoレルムへのログインページ

    Login page to demo realm

    Keycloakを正常に使用してサンプルのWildFlyアプリケーションをセキュリティー保護したことを示すメッセージが表示されます。おめでとうございます!

    完全な成功

    Complete success