Keycloak 連携

OpenID Connect プロトコルを通じてオープンソースの ID 認証プラットフォーム Keycloak と統合します

Keycloak は広く利用されているオープンソースの ID 認証およびアクセス管理プラットフォームです。MaiAgent は OpenID Connect プロトコルを通じた Keycloak との統合に対応しています。

対象ユーザー：Keycloak で統一的な ID 管理を行っている企業、または Realm 単位でユーザーを管理する必要がある組織

主なメリット：

• Keycloak Realm の分離に対応

• Email を持たないアカウント向けに、仮想 Email ID を自動生成

• サーバーサイドでの Token 失効（ログアウト）に対応

• Keycloak エコシステムの各種機能との統合

設定手順

1. Keycloak で Client を作成する

1. Keycloak Admin Console にログインします

2. 対象の Realm を選択します

3. Clients で Client を新規追加します

4. Client Protocol を openid-connect に設定します

5. Access Type を public に設定します（またはセキュリティ要件に応じて confidential を選択します）

6. Valid Redirect URIs を MaiAgent のフロントエンドドメインに設定します

7. Client ID を控えておきます

2. MaiAgent 管理画面で Keycloak 設定を入力する

Keycloak 認証設定：認証ソース名、Email Domain、サーバー URL を入力します

Keycloak 認証タイプを選択した後、以下の項目を入力する必要があります：

項目	必須	説明
認証ソース名	はい	Realm 名との対応に使用します。Keycloak の Realm 名を使用することを推奨します
Email Domain	はい	仮想 Email を生成するためのドメインです。例：company.com
Server URL	はい	Keycloak サーバーの URL です。例：https://keycloak.company.com/

入力が完了すると、システムが自動的に Login URL を生成します。形式は以下のとおりです：

https://{フロントエンドドメイン}/auth/keycloak?url={Server URL}&clientId={Client ID}&realm={Realm}

3. 保存してテストする

MaiAgent 管理画面で 保存 をクリックし、生成された Login URL を使用してログインフローをテストします。

Keycloak の仮想 Email の仕組み

Keycloak のユーザーは必ずしも Email アドレスを持っているとは限らないため、MaiAgent は一意の識別子として仮想 Email を自動的に生成します：

仮想 Email = {preferred_username}@{email_domain}

例：Email Domain が company.com に設定されている場合、ユーザー john.doe には MaiAgent のユーザー Email として [e-mail] が生成されます。

この仮想 Email はシステム内部での識別のみを目的としており、実際の Email 送信には使用されません。

Keycloak のログアウト

MaiAgent の Keycloak 統合はサーバーサイドでのログアウトに対応しています。ユーザーが MaiAgent からログアウトすると、システムは同時に Keycloak サーバーへ Token 失効リクエストを送信し、Token が Keycloak 側でも無効になることを保証します。

設定項目クイックリファレンス

項目	必須	形式	例
認証ソース名	はい	小文字英数字 + ハイフン、最大 31 文字	company-kc
Email Domain	はい	ドメイン形式	company.com
Server URL	はい	HTTPS URL	https://keycloak.company.com/