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. レルムとユーザーの作成

In this section you will create a new realm within the Keycloak admin console and add a new user to that realm. You will use that new user to log in to your new realm and visit the built-in user account service that all users have access to.

3.1. 始める前に

最初のレルムを作成する前に、Keycloakのインストールを完了し、インストールと起動に沿って初期管理者ユーザーを作成する必要があります。

3.2. 新規レルムの作成

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

  1. Go to http://localhost:8080/auth/admin/ and log in to the Keycloak Admin Console using the account you created in Install and Boot.

  2. From the Master drop-down menu, click Add Realm. When you are logged in to the master realm this drop-down menu lists all existing realms.

  3. Type demo in the Name field and click Create.

When the realm is created, the main admin console page opens. Notice the current realm is now set to demo. Switch between managing the master realm and the realm you just created by clicking entries in the Select realm drop-down menu.

3.3. 新規ユーザーの作成

To create a new user in the demo realm, along with a temporary password for that new user, complete the following steps:

  1. From the menu, click Users to open the user list page.

  2. On the right side of the empty user list, click Add User to open the add user page.

  3. Enter a name in the Username field; this is the only required field. Click Save to save the data and open the management page for the new user.

  4. Click the Credentials tab to set a temporary password for the new user.

  5. Type a new password and confirm it. Click Reset Password to set the user password to the new one you specified.

This password is temporary and the user will be required to change it after the first login. To create a password that is persistent, flip the Temporary switch from On to Off before clicking Reset Password.

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

  1. After you create the new user, log out of the management console by opening the user drop-down menu and selecting Sign Off.

  2. Go to http://localhost:8080/auth/realms/demo/account and log in to the User Account Service of your demo realm with the user you just created.

  3. Type the username and password you created. You will be required create a permanent password after you successfully log in, unless you changed the Temporary setting to Off when you created the password.

The user account service page will open. Every user in a realm has access to this account service by default. From this page, you can update profile information and change or add additional credentials. For more information on this service see the Server Administration Guide.

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

This section describes how to secure a Java servlet application on the WildFly application server by: * Installing the Keycloak client adapter on a WildFly application server distribution * Creating and registering a client application in the Keycloak admin console * Configuring the application to be secured by Keycloak

4.1. 始める前に

Before you can secure a Java servlet application, you must complete the installation of Keycloak and create the initial admin user as shown in Installing and Booting.

There is one caveat: you must run a separate WildFly instance on the same machine as the Keycloak server to run your Java servlet application. Run the Keycloak using a different port than the WildFly, to avoid port conflicts.

To adjust the port used, change the value of the jboss.socket.binding.port-offset system property when starting the server from the command line. The value of this property is a number that will be added to the base value of every port opened by the Keycloak server.

To start the Keycloak server while also adjusting the port:

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

After starting Keycloak, go to http://localhost:8180/auth/admin/ to access the admin console.

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

Download the WildFly distribution and extract it from the compressed file into a directory on your machine.

Download the WildFly OpenID Connect adapter distribution from keycloak.org.

Extract the contents of this file into the root directory of your WildFly distribution.

Run the appropriate script for your platform:

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 and Linux/Unix
$ cd bin
$ ./jboss-cli.sh --file=adapter-elytron-install-offline.cli
WildFly 11 and Windows
> cd bin
> jboss-cli.bat --file=adapter-elytron-install-offline.cli
This script will make the necessary edits to the …​/standalone/configuration/standalone.xml file of your app server distribution.

Start the application server.

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

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

You must have the following installed on your machine and available in your PATH before you continue:

  • Java JDK 8

  • Apache Maven 3.1.1以上

  • Git

You can obtain the code by cloning the Keycloakクイックスタート・リポジトリー repository at https://github.com/keycloak/keycloak-quickstarts. The quickstarts are designed to work with the most recent Keycloak release.

Make sure your WildFly application server is started before you continue.

To download, build, and deploy the code, complete the following steps.

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

During installation, you will see some text scroll by in the application server console window.

To confirm that the application is successfully deployed, go to http://localhost:8080/vanilla and a login page should appear.

If you click Login, the browser will pop up a BASIC auth login dialog. However, the application is not yet secured by any identity provider, so anything you enter in the dialog box will result in a Forbidden message being sent back by the server. You can confirm that the application is currently secured via BASIC authentication by finding the setting in the application’s web.xml file.

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

To define and register the client in the Keycloak admin console, complete the following steps:

  1. Log in to the admin console with your admin account.

  2. In the top left drop-down menu select and manage the Demo realm. Click Clients in the left side menu to open the Clients page.

    Clients

    clients

  3. On the right side, click Create.

  4. Complete the fields as shown here:

    Add Client

    add client

  5. Click Save to create the client application entry.

  6. Click the Installation tab in the Keycloak admin console to obtain a configuration template.

  7. Select Keycloak OIDC JBoss Subsystem XML to generate an XML template. Copy the contents for use in the next section.

    XMLテンプレート

    client install selected

4.5. サブシステムの設定

To configure the WildFly instance that the application is deployed on so that this app is secured by Keycloak, complete the following steps.

  1. Open the standalone/configuration/standalone.xml file in the WildFly instance that the application is deployed on and search for the following text:

    <subsystem xmlns="urn:jboss:domain:keycloak:1.1"/>
  2. Modify this text to prepare the file for pasting in contents from the Keycloak OIDC JBoss Subsystem XML template we obtained Keycloak admin console Installation tab by changing the XML entry from self-closing to using a pair of opening and closing tags:

    <subsystem xmlns="urn:jboss:domain:keycloak:1.1">
    </subsystem>
  3. Paste the contents of the template within the <subsystem> element, as shown in this example:

    <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. Change the name to vanilla.war:

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

  6. Go to http://localhost:8080/vanilla and click Login. When the Keycloak login page opens, log in using the user you created in Creating a New User.