Kompira Enterprise OIDC連携設定ガイド
# 1. はじめに
Kompira Enterprise（以後、KEと呼称）ver.2.0.3では、OpenID Connect（OIDC）を利用してKEにログインする機能が追加されました。本ドキュメントでは、OIDCを用いてMicrosoft Entra IDと連携し、Entra ID側で管理しているユーザーでKEにログインするための設定方法について説明します。
# 2. 概要
全体の設定の流れは以下のようになります。
1. Microsoft Entra ID側にKEアプリケーションの登録を行い、登録時に払い出されるアプリケーション（クライアント）IDとクライアントシークレットを記録しておく。
2. KE上の/system/oidc_providersにOIDCプロバイダ型オブジェクトを作成し、アプリケーションID、クライアントシークレット等、必要な設定項目を入力する。
3. KEのシステム設定（/system/config）のOIDCプロバイダの項目に、2で作成したOIDCプロバイダオブジェクトを入力して保存する。
# 3. 設定方法
## 3.1. Microsoft Entra ID側の設定
### 3.1.1. アプリケーションの登録
[Microsoft Entra 管理センター](https://entra.microsoft.com/)にログインして、Kompira Enterpriseのアプリを登録します。
#### ■ 新規登録ボタンを押す
アプリの登録メニューから、新規登録ボタンを押下します。
![image.png](https://image.docbase.io/uploads/3f44f3db-5625-43aa-8077-c33131005520.png =WxH)
#### ■ 新規登録画面
![image.png](https://image.docbase.io/uploads/8db18ddc-e680-4acf-beb8-601a2902f08d.png =WxH)
新規登録画面にて、以下のように項目を入力して、登録ボタンをクリックします。
| 項目名 | 設定内容 | 備考 |
| --- | --- | --- |
| 名前 | 登録するアプリケーション名を指定してください | 自由に設定できます。分かりやすい名称を登録しましょう。 |
| サポートされているアカウントの種類 | 「この組織ディレクトリのみに含まれるアカウント」を選択します |  |
| リダイレクトURI | `https://<Kompiraサーバのホスト名 or IP アドレス>/.auth/complete/oidc/` |  |
#### ■ アプリケーション（クライアント）IDのコピー
3.1.1.で登録したアプリの概要ページから、アプリケーション（クライアント）IDをコピーして、メモ帳など適切な場所に記録しておきます。（ここでコピーした値は、後ほどKompira側の設定で必要になります）
![image.png](https://image.docbase.io/uploads/df689200-85c3-4c22-8b82-fe27f2d4cd19.png =WxH)
#### ■ エンドポイントの確認
3.1.1.で登録したアプリの概要ページから「エンドポイント」タブをクリックして、エンドポイントを表示し、その中から「機関URL（この組織ディレクトリ内のアカウントのみ）」の値をコピーして、メモ帳など適切な場所に記録しておきます。（ここでコピーした値は、後ほどKompira側の設定で必要になります）
![image.png](https://image.docbase.io/uploads/15578fda-f0b5-4b1e-b91f-c7ee1447c372.png =WxH)
### 3.1.2. クライアントシークレットの登録
3.1.1.で登録したアプリの画面から、「証明書とシークレット」のメニューを選択し、新しいクライアントシークレットを登録します。
![image.png](https://image.docbase.io/uploads/fd086244-8733-432a-9712-88924e570334.png =WxH)
説明を入力し、有効期限に適切な期間を選択して、追加ボタンを押してください。
![image.png](https://image.docbase.io/uploads/ba2a36cc-e370-4094-87fa-594c020aa389.png =WxH)
新しく追加されたクライアントシークレットの「値」（シークレットIDではありません）をコピーして、メモ帳など適切な場所に記録しておきます。（ここでコピーした値は、後ほどKompira側の設定で必要になります）
![image.png](https://image.docbase.io/uploads/9f69b774-b864-4b5a-b7b3-b2038cf6b083.png =WxH)
## 3.2. Kompira Enterprise側の設定
### 3.2.1. OIDCプロバイダオブジェクトの作成（登録）
Kompiraに管理者権限を持つユーザー（root）でログインし、OIDCプロバイダ一覧（/system/oidc_providers）の画面から適当な名前でOIDCプロバイダオブジェクトを作成します。
![image.png](https://image.docbase.io/uploads/1ecb4a5d-0cb7-454c-8850-3788dbbe2f0a.png =WxH)
オブジェクトの編集画面で以下の各項目を入力して保存します。（その他の設定項目については、マニュアルをご参照ください）
| 項目名 | 設定内容 | 備考 |
| --- | --- | --- |
| クライアントID | 3.1.1.で記録しておいたクライアントIDを入力します |  |
| クライアントシークレット | 3.1.2.で記録しておいたクライアントシークレットを入力します |  |
| OIDCエンドポイント | 3.1.1.で記録しておいたエンドポイントURL + `/v2.0` を入力します | Kompiraは、ここで設定したURLに`/.well-known/openid-configuration`を付けたURLにHTTP GETリクエストを投げることで、当該OIDCプロバイダーの情報を取得します。 |
| ユーザー名属性 | IDトークンに含まれるクレームの中から、ユーザー名として使用する属性名を指定します | 空の場合はデフォルト値として`preferred_username`が用いられます。 |
![10.20.0.118\_8080\_system\_oidc\_providers.add\_name=entra\_id&order\_by=&page\_size=.png](https://image.docbase.io/uploads/c24a7f71-b382-4684-a893-c1198e06c37b.png =WxH)
作成したオブジェクトのプロパティを編集して、表示名を分かりやすい名称に設定しておくと良いでしょう。（以降では、`Microsoft Entra ID`という名称に設定しています）
### 3.2.2. システム設定からOIDCプロバイダを設定する
Kompiraのシステム設定（/system/config）の画面から設定の変更をクリックし、「OIDCプロバイダ」の項目から3.2.1.で登録したOIDCプロバイダオブジェクトを選択し、保存します。
![image.png](https://image.docbase.io/uploads/d5666a49-606e-4467-9f6b-d2e36393455d.png =WxH)
以上で設定は完了です。
## 3.3. 動作確認
一旦、ログアウトしてから、ログイン画面に移動すると、ログインボタンの下に「○○でログイン」というリンクが追加されていることを確認してください。（○○には3.2.1.で登録したOIDCプロバイダのオブジェクト表示名が表示されます）
![image.png](https://image.docbase.io/uploads/9ffcc8c9-7499-4168-b5d9-5e838ebc9ef7.png =WxH)
#### ■ OIDCによるログイン方法
「○○でログイン」のリンクをクリックすると、Microsoft Entra IDの認証画面に遷移するので、画面の指示に従ってサインインしてください。
![login.microsoftonline.com\_59c61752-de1c-4d8b-b25e-a44928794411\_oauth2\_v2.0\_authorize\_client\_id=486c214a-14aa-4b18-8c63-88f8ddea19a4&redirect\_uri=http\_\_\_10.20.0.118\_8080\_.auth\_complete\_oidc\_&state=frpdr6v5vuwkni6t.png](https://image.docbase.io/uploads/703d85ac-127b-40a1-b8af-794f3ee85f83.png =WxH)
ログインに成功すると、ログインしたKEユーザーのホームディレクトリの画面に遷移します。
# 4. Entra IDのグループを利用する
ここでは、Microsoft Entra IDのグループを参照して、Kompiraのグループにマッピングしたり、Kompiraへのログインを制限したりする方法について説明します。
## 4.1. Entra ID側の設定方法
Microsoft Entra IDのグループを参照するには、トークンIDのロール属性にグループ情報を含めるようにEntra ID側の設定を行う必要があります。Microsoft Entra ID管理センターのアプリの登録画面から、登録したKompiraアプリのページに移動し、「トークン構成」メニューからグループ要求の追加をクリックします。
![image.png](https://image.docbase.io/uploads/a01a80e7-8700-4d6b-90e4-4750d5cd6012.png =WxH)
セキュリティグループをチェックし、IDトークンのプロパティでグループIDを選択し、グループをロール要求として生成するにチェックして追加（保存）します。
![image.png](https://image.docbase.io/uploads/e1b9ff51-6a45-4ccd-86a3-ec9d33e8b5f5.png =WxH)
以上の設定によって、KEが取得するトークンIDのロール属性に、Entra IDで認証したユーザーの所属するグループ情報が含まれるようになります。
## 4.2. Entra IDのグループをKompiraのグループに反映する
Entra IDのユーザーが所属するグループをKompiraのグループに反映させたい場合、3.2.1.で作成したOIDCプロバイダオブジェクトの以下の項目を設定します。
| 項目名 | 設定内容 | 備考 |
| --- | --- | --- |
| グループ変換 | OIDCプロバイダの組織内のロールやグループをKompiraのグループにマッピングするための辞書を定義します。 |  |
たとえば、Entra ID上で作成したKompiraAdminグループをKE上のwheelグループに反映したい場合、KompiraAdminグループのオブジェクトIDを名称とし、値をwheelに設定して保存します。そうすると、KompiraAdminグループが割り当てられたOIDCユーザーがログインすると、当該KEユーザーにKEのwheelグループが割り当てられます。
## 4.2. Entra IDの特定のグループに所属するユーザーのみログインを許可する
Entra IDの特定のグループが割り当てられたOIDCユーザーのみ、Kompiraへのログインを許可したい場合には、3.2.1.で作成したOIDCプロバイダオブジェクトの以下の項目を設定します。
| 項目名 | 設定内容 | 備考 |
| --- | --- | --- |
| 許可グループ | OIDCプロバイダの組織内の特定のロールやグループに所属するユーザーのみにKompiraへのログインを許可したい場合に、許可するロールIDやグループIDを指定します。 | 設定が空の場合、組織内の全てのユーザーがKompiraにログインできるようになります。 |
たとえば、Entra ID上で作成したKompiraUserグループが割り当てられたOIDCユーザーのみ、Kompiraにログインを許可したい場合、KompiraUserのオブジェクトIDを許可グループに追加します。許可グループを複数設定している場合、そのうちのどれか一つのグループに所属していれば、KEのログインが許可されます。
# 5. トラブルシューティング
## 5.1. 特定のユーザーがログインできない
すでにKE上に同名のローカルユーザーや異なるOIDCプロバイダによるユーザーが作成済みの場合、OIDC連携でログインしようとするとログインに失敗します。この場合、既存の同名ユーザーを削除することで、ログインできるようになります。
## 5.2. OIDC認証の途中でエラーになる
Entra IDの認証途中で、以下のようにエラーが発生する場合、認証後のKE上へのリダイレクトURIがマッチしていないことが考えられます。3.1.1.のEntra ID側のアプリ登録の設定で、リダイレクトURIが適切に設定されているかどうか確認してください。
![login.microsoftonline.com\_kmsi.png](https://image.docbase.io/uploads/779ddadb-697f-43a8-a7ef-aaa54d62142c.png =WxH)