xDev Asia

管理コンソールについて理解し、最初の管理者ユーザーを作成し、レルム、レルム設定 (一般、ログイン、電子メール、テーマ、ローカリゼーション、キー、セキュリティ防御)、管理 CLI (kcadm.sh)、および基本的な管理 REST API を作成および構成します。

基本から上級までの Keycloak

パート 1: Keycloak プラットフォーム

xdev.asia

1. 管理コンソールにアクセスする

Keycloak (スタンドアロンまたは Docker) をインストールすると、それにアクセスできるようになります管理コンソール— Keycloakシステム全体の集中管理インターフェース。

アクセスURL

デフォルトでは、管理コンソールは次の場所にあります。

http://localhost:8080/admin

異なるポートマッピングを持つDockerを使用してKeycloakを実行する場合:

http://localhost:<PORT>/admin

最初の管理者ユーザーを作成する

初めて Keycloak にアクセスするときは、Keycloak を作成する必要があります初期管理者ユーザー管理コンソールにログインします。次の 2 つの方法があります。

方法 1: 環境変数を使用する (Docker/実稼働環境に推奨)

docker run -d --name keycloak \
  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
  -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
  -p 8080:8080 \
  quay.io/keycloak/keycloak:26.2.4 start-dev

方法2：ウェルカムページ経由（ローカルホストからアクセスする場合のみ）

アクセスhttp://localhost:8080 をクリックすると、管理者ユーザー作成フォームが表示されます。ユーザー名とパスワードを入力し、クリックします作成する.

方法 3: コマンドライン経由

# Standalone
export KC_BOOTSTRAP_ADMIN_USERNAME=admin
export KC_BOOTSTRAP_ADMIN_PASSWORD=admin
bin/kc.sh start-dev

管理コンソールのインターフェース

ログインすると、次の主要コンポーネントを含む管理コンソールインターフェイスが表示されます。

レルムセレクター(左上隅) - 管理しているレルムを選択します
左側のサイドバー— メインナビゲーションメニュー: クライアント、クライアントスコープ、レルムロール、ユーザー、グループ、セッション、イベント、レルム設定、認証、アイデンティティプロバイダー、ユーザーフェデレーション
メインコンテンツエリア— 選択した項目の詳細な内容を表示します
ユーザードロップダウン(右上隅) — 管理者アカウントの管理、サインアウト

2. 最初のレルムを作成する

マスターレルムとカスタムレルム

Keycloakをインストールする場合、レルムには名前が付けられますマスター。マスター既成の。マスターレルムは、他のレルムを管理するために使用される特別なレルムです。マスターレルムはアプリケーションに使用しないでください.

ベストプラクティス:

使用マスターレルムスーパー管理者のみがKeycloakシステムを管理できる
作成するカスタムレルム各組織、プロジェクト、または環境に固有の
レルムの名前付けには次のような意味があります。私の会社-開発, mycompany-ステージング, 私の会社の製品

管理コンソール経由でレルムを作成する

クリックレルムセレクター(左上隅のドロップダウンに「マスター」が表示されます)
クリックレルムの作成
情報を入力してください:
- レルム名: 私の会社(小文字、数字、ハイフンのみを含む)
- 有効：の上
クリック作成する

JSONファイルからレルムを作成

JSON ファイルからレルムをインポートできます。環境間で構成を再現する場合に便利です。

{
  "realm": "my-company",
  "enabled": true,
  "displayName": "My Company",
  "displayNameHtml": "<strong>My Company</strong>",
  "sslRequired": "external",
  "registrationAllowed": false,
  "loginWithEmailAllowed": true,
  "duplicateEmailsAllowed": false,
  "resetPasswordAllowed": true,
  "editUsernameAllowed": false,
  "bruteForceProtected": true,
  "permanentLockout": false,
  "maxFailureWaitSeconds": 900,
  "minimumQuickLoginWaitSeconds": 60,
  "waitIncrementSeconds": 60,
  "quickLoginCheckMilliSeconds": 1000,
  "maxDeltaTimeSeconds": 43200,
  "failureFactor": 5,
  "defaultSignatureAlgorithm": "RS256",
  "accessTokenLifespan": 300,
  "ssoSessionIdleTimeout": 1800,
  "ssoSessionMaxLifespan": 36000
}

管理コンソール経由でインポート: レルムを作成するときに、ブラウズをクリックして JSON ファイルを選択します。

3. レルム設定の詳細

レルム作成後、アクセスします。レルム設定詳細な設定についてはサイドバーから。

3.1 「全般」タブ

設定	説明する	推奨値
表示名	ログインページに表示される名前	会社名・プロジェクト名
HTML表示名	表示名の HTML サポート	ロゴ+名前
フロントエンド URL	クライアントが接続に使用する URL	https://auth.mycompany.com
SSLを要求する	リクエストにSSLを要求する	`外部の`(開発) /`全て`(製品)
ユーザー管理のアクセス	ユーザーにリソースの管理を許可する (UMA)	オフ (UMA が必要な場合を除く)
ACR から LoA へのマッピング	マッピング認証コンテキストクラスのリファレンス	ステップアップ認証が必要な場合の構成

ログインページの動作を構成します。

設定	説明する	デフォルト
ユーザー登録	新規アカウント登録を許可します	オフ
パスワードをお忘れですか	リンクを表示「パスワードを忘れた場合」	オフ
私を覚えてますか	「ログインを記憶する」チェックボックス	オフ
ユーザー名としての電子メール	電子メールをユーザー名として使用する	オフ
メールでログイン	メールによるログインを許可する	の上
重複したメール	重複したメールは許可されます	オフ
メールの確認	メール認証が必要です	オフ
ユーザー名の編集	ユーザー名の変更を許可する	オフ

生産に関する推奨事項:

User registration: OFF (hoặc ON với reCAPTCHA)
Forgot password: ON
Remember me: ON
Email as username: Tùy yêu cầu
Login with email: ON
Verify email: ON
Edit username: OFF

3.3 「電子メール」タブ

電子メールを送信するように SMTP サーバーを構成します (検証、パスワードのリセット、通知)。

設定	説明する
から	送信電子メールアドレス (例: [email protected])
表示名から	メールに表示される名前
大声で返事をする	返信アドレス (例: [email protected])
ホスト	SMTPサーバーのホスト名
ポート	SMTP ポート (STARTTLS の場合は 587、SSL の場合は 465)
暗号化	SSL または STARTTLS を有効にする
認証	SMTP のユーザー名とパスワード

Gmail SMTP を使用した構成例:

Host: smtp.gmail.com
Port: 587
From: [email protected]
Enable StartTLS: ON
Authentication: ON
Username: [email protected]
Password: app-specific-password

3.4 「テーマ」タブ

さまざまなページの外観をカスタマイズします。

ログインテーマ— ログイン、登録、パスワードリセットページ
アカウントのテーマ— ユーザー向けのアカウント管理ページ
管理コンソールのテーマ— 管理コンソールインターフェイス
電子メールのテーマ— 電子メールのテンプレート

Keycloakはテーマを提供しますキーマント(デフォルト)とkeycloak.v2(アカウントコンソール v3、React ベース)。カスタムテーマを作成できます。これについては次の記事で説明します。

3.5 ローカリゼーションタブ

ログイン、アカウント、電子メールページの多言語サポート:

オンにする国際化：の上
選択サポートされているロケール: en、vi、ja、zh-CN、...
選択デフォルトのロケール: vi (デフォルトのベトナム語インターフェース用)
必要に応じてロケールごとにメッセージバンドルをカスタマイズする

3.6 タブキー

レルムの暗号化キーを管理します。トークンの署名と暗号化に使用されます。

アクティブなキー— キーはトークンの署名に使用されています
パッシブキー— 以前に署名されたトークンを検証するために古いキーが引き続き使用されます
無効なキー— キーはもう使用されていません

デフォルトのキープロバイダー:

プロバイダー	アルゴリズム	目的
RSA で生成された	RS256	JWT トークンに署名する
rsa-enc で生成された	RSA-OAEP	トークンを暗号化する
hmac で生成された	HS512	HMAC 署名
aes で生成された	AES	対称暗号化
ECDSA によって生成された	ES256	楕円曲線署名

キーのローテーション:新しいキープロバイダーを追加します → 新しいキーがアクティブになります → 古いキーがパッシブに変わります → しばらくしてから古いキーを無効にします。

3.7 「トークン」タブ

トークンの有効期間と動作を構成します。

設定	説明する	推奨値
デフォルトの署名アルゴリズム	JWT署名アルゴリズム	RS256
リフレッシュトークンの取り消し	使用後にリフレッシュトークンを取り消す	ON（本番）
SSO セッションのアイドル状態	最大セッションアイドル時間	30分
SSO セッション最大値	最大セッション時間	10時
アクセストークンの有効期間	アクセストークンの有効期間	5分
クライアントのログインタイムアウト	ログインフローの最大時間	5分

3.8 「セキュリティ防御」タブ

レルムのセキュリティ構成:

ヘッダー:

ヘッダ	デフォルト値	説明する
X フレームオプション	同じ原産地	クリックジャッキング対策
コンテンツセキュリティポリシー	フレームソース 'self'; ...	CSPヘッダー
X-コンテンツタイプ-オプション	鼻を鳴らす	MIME スニッフィングを防止する
X-XSS 保護	1;モード=ブロック	XSSフィルター
厳格な輸送セキュリティ	max-age=31536000	HTTPS を要求する
リファラーポリシー	非参照者	リファラーヘッダーを制御する

ブルートフォース検出:

有効: ON (ブルートフォース防止をオンにする)
永久ロックアウト：OFF（時間が経過すると自動でロックが解除されます）
最大ログイン失敗数: 5 (ログイン試行が 5 回失敗するとロックされます)
待機増分：60秒（待ち時間は徐々に増加します）
最大待機時間：900秒（最大待機時間15分）
クイックログインチェック: 1000 ミリ秒 (ログインの検出が速すぎます)

4. 管理 CLI (kcadm.sh)

Keycloakが提供するもの管理者 CLI (kcadm.sh) — 管理コンソールにアクセスせずにKeycloakを管理するためのコマンドラインツール。

4.1 資格情報の構成

管理 CLI を使用する前に、ログインする必要があります。

# Đăng nhập vào Keycloak server bin/kcadm.sh config credentials \ --server http://localhost:8080 \ --realm master \ --user admin \ --password admin Với Docker

docker exec -it keycloak /opt/keycloak/bin/kcadm.sh config credentials --server http://localhost:8080 --realm master --user admin --password admin

セキュリティ上の注意:本番環境では、使用します- クライアントそして- 秘密ユーザー名/パスワードをコマンドラインで直接入力する代わりに。

4.2 CLI を使用したレルム管理

新しいレルムを作成します。

# Tạo realm cơ bản
bin/kcadm.sh create realms \
  -s realm=my-company \
  -s enabled=true \
  -s displayName="My Company"
Tạo realm với nhiều cấu hình
bin/kcadm.sh create realms 

-s realm=my-company 

-s enabled=true 

-s displayName="My Company" 

-s registrationAllowed=false 

-s loginWithEmailAllowed=true 

-s resetPasswordAllowed=true 

-s sslRequired=external 

-s bruteForceProtected=true

レルムのリストを参照してください。

# Lấy tất cả realms
bin/kcadm.sh get realms --fields realm,enabled,displayName
Output:
[ {
"realm" : "master",
"displayName" : "Keycloak",
"enabled" : true
}, {
"realm" : "my-company",
"displayName" : "My Company",
"enabled" : true
} ]

レルムの詳細を参照してください。

bin/kcadm.sh get realms/my-company

レルムの更新:

bin/kcadm.sh update realms/my-company \
  -s displayName="My Company Production" \
  -s sslRequired=all \
  -s bruteForceProtected=true \
  -s failureFactor=5

レルムを削除します:

bin/kcadm.sh delete realms/my-company

4.3 CLI を使用してレルム設定を構成する

ログイン設定を構成します。

bin/kcadm.sh update realms/my-company \
  -s registrationAllowed=true \
  -s resetPasswordAllowed=true \
  -s rememberMe=true \
  -s verifyEmail=true \
  -s loginWithEmailAllowed=true \
  -s duplicateEmailsAllowed=false

トークン設定を構成します。

bin/kcadm.sh update realms/my-company \
  -s accessTokenLifespan=300 \
  -s ssoSessionIdleTimeout=1800 \
  -s ssoSessionMaxLifespan=36000 \
  -s revokeRefreshToken=true \
  -s refreshTokenMaxReuse=0

SMTP 電子メールを構成します。

bin/kcadm.sh update realms/my-company \
  -s 'smtpServer={"host":"smtp.gmail.com","port":"587","from":"[email protected]","fromDisplayName":"My Company","starttls":"true","auth":"true","user":"[email protected]","password":"app-password"}'

レルム構成をエクスポートします。

# Export realm sang file JSON
bin/kcadm.sh get realms/my-company > my-company-realm.json

5. 管理REST API

Keycloakが提供するもの管理REST APIHTTP リクエストによる完全な管理を可能にし、自動化、CI/CD、および他のシステムとの統合に最適です。

5.1 アクセストークンの取得

API を呼び出す前に、マスターレルムからアクセストークンを取得する必要があります。

# Lấy access token bằng admin credentials ACCESS_TOKEN=$(curl -s -X POST \ "http://localhost:8080/realms/master/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "username=admin" \ -d "password=admin" \ -d "grant_type=password" \ -d "client_id=admin-cli" | jq -r '.access_token')

echo $ACCESS_TOKEN

5.2 APIによるレルム管理

レルムのリストを取得します。

curl -s -X GET \
  "http://localhost:8080/admin/realms" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" | jq '.[].realm'

新しいレルムを作成します。

curl -s -X POST \
  "http://localhost:8080/admin/realms" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "realm": "my-company",
    "enabled": true,
    "displayName": "My Company",
    "sslRequired": "external",
    "registrationAllowed": false,
    "loginWithEmailAllowed": true,
    "resetPasswordAllowed": true,
    "bruteForceProtected": true,
    "failureFactor": 5
  }'

レルムの詳細を取得します。

curl -s -X GET \
  "http://localhost:8080/admin/realms/my-company" \
  -H "Authorization: Bearer $ACCESS_TOKEN" | jq .

レルムの更新:

curl -s -X PUT \
  "http://localhost:8080/admin/realms/my-company" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "My Company Updated",
    "sslRequired": "all"
  }'

レルムを削除します:

curl -s -X DELETE \
  "http://localhost:8080/admin/realms/my-company" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

5.3 重要な API エンドポイント

終点	方法	説明する
/admin/レルム	得る	レルムのリスト
/admin/レルム	役職	新しいレルムを作成する
/admin/realms/{レルム}	得る	レルムの詳細
/admin/realms/{レルム}	置く	レルムを更新する
/admin/realms/{レルム}	消去	レルムの削除
/admin/realms/{realm}/users	得る	ユーザー一覧
/admin/realms/{realm}/users	役職	ユーザーの作成
/admin/realms/{realm}/clients	得る	顧客リスト
/admin/realms/{realm}/roles	得る	レルムの役割のリスト
/admin/realms/{realm}/groups	得る	グループ一覧
/admin/realms/{realm}/events	得る	イベントログ

5.4 ポストマンの使用

Keycloakは、管理REST APIのOpenAPI仕様を提供します。 Postman または Swagger UI にインポートして、API を簡単に探索およびテストできます。

# OpenAPI spec URL
http://localhost:8080/admin/realms/{realm}/.well-known/openid-configuration

6. 練習問題

知識を定着させるために次の演習を行ってください。

レルム「dev-company」を作成します管理コンソール経由で次の設定を行います。
- 表示名: 「開発会社」
- メールでログイン：ON
- ユーザー登録：ON
- パスワードを忘れた場合：ON
- 電子メールの確認: オン
- 私を覚えておいてください: オン
ブルートフォース検出の構成新しく作成されたレルムの場合:
- ログイン失敗の最大数: 3
- 待機増分: 120 秒
- 最大待機時間: 600 秒
kcadm.shを使用する同様の構成でレルム「staging-company」を作成します
管理REST APIを使用する(curl) レルム「test-company」を作成し、レルムのリストを取得して検証します。
輸出レルム「dev-company」を JSON に変換し、別の名前で再インポートします

7. まとめ

このレッスンでは、次のことを学びました。

アクセス方法と利用方法管理コンソール
作成する管理者ユーザーまずは多くの方法を経て
作成して構成するレルム— Keycloakの主要な管理ユニット
理解するレルム設定重要: 一般、ログイン、電子メール、テーマ、ローカリゼーション、キー、トークン、セキュリティ防御
使用管理者 CLI(kcadm.sh) コマンドライン経由の管理用
使用管理REST API管理を自動化する

次の記事で詳細な手順を説明しますユーザー、グループ、ユーザープロファイルの管理キークロークで。

レッスン 3: 管理コンソールと最初のレルムの作成

1. 管理コンソールにアクセスする

アクセスURL

最初の管理者ユーザーを作成する

管理コンソールのインターフェース

2. 最初のレルムを作成する

マスターレルムとカスタムレルム

管理コンソール経由でレルムを作成する

JSONファイルからレルムを作成

3. レルム設定の詳細

3.1 「全般」タブ

3.3 「電子メール」タブ

3.4 「テーマ」タブ

3.5 ローカリゼーションタブ

3.6 タブキー

3.7 「トークン」タブ

3.8 「セキュリティ防御」タブ

4. 管理 CLI (kcadm.sh)

4.1 資格情報の構成

Với Docker

4.2 CLI を使用したレルム管理

Tạo realm với nhiều cấu hình

Output:

[ {

"realm" : "master",

"displayName" : "Keycloak",

"enabled" : true

}, {

"realm" : "my-company",

"displayName" : "My Company",

"enabled" : true

`} ]`

4.3 CLI を使用してレルム設定を構成する

5. 管理REST API

5.1 アクセストークンの取得

5.2 APIによるレルム管理

5.3 重要な API エンドポイント

5.4 ポストマンの使用

6. 練習問題

7. まとめ

レッスン 3: 管理コンソールと最初のレルムの作成

1. 管理コンソールにアクセスする

アクセスURL

最初の管理者ユーザーを作成する

管理コンソールのインターフェース

2. 最初のレルムを作成する

マスター レルムとカスタム レルム

管理コンソール経由でレルムを作成する

JSONファイルからレルムを作成

3. レルム設定の詳細

3.1 「全般」タブ

3.2 ログインタブ

3.3 「電子メール」タブ

3.4 「テーマ」タブ

3.5 ローカリゼーションタブ

3.6 タブキー

3.7 「トークン」タブ

3.8 「セキュリティ防御」タブ

4. 管理 CLI (kcadm.sh)

4.1 資格情報の構成

Với Docker

4.2 CLI を使用したレルム管理

Tạo realm với nhiều cấu hình

Output:

[ {

"realm" : "master",

"displayName" : "Keycloak",

"enabled" : true

}, {

"realm" : "my-company",

"displayName" : "My Company",

"enabled" : true

} ]

4.3 CLI を使用してレルム設定を構成する

5. 管理REST API

5.1 アクセストークンの取得

5.2 APIによるレルム管理

5.3 重要な API エンドポイント

5.4 ポストマンの使用

6. 練習問題

7. まとめ

マスターレルムとカスタムレルム

`} ]`