> For AI agents: the complete documentation index is available at /resource/ucidm/docs/on-premise/1.9.0/llms.txt, the full documentation bundle is available at /resource/ucidm/docs/on-premise/1.9.0/llms-full.txt.

# Microsoft Entra ID 向け Agent

UCIDM はクラウドの Microsoft Entra ID から ID 情報を取得して UCIDM API に連携します。

Microsoft Entra ID 向け Agent はコンテナとして稼働させます。次のように `compose.yml` に設定します。

```yml
  agent-meid:
    depends_on:
      - api
    container_name: agent-meid
    image: docker.io/osstech/ucidm-agent:latest
    logging: *default-logging
    volumes:
      - type: bind
        source: ./agent-data/meid
        target: ${AGENT_PAGE_KEY_PATH}
        bind:
          create_host_path: true
    entrypoint:
      - ./bin/agent
      - -verbose
      - -jsonl
    environment:
      TZ: "${TZ}"
      PAGE_KEY_PATH: "${AGENT_PAGE_KEY_PATH}"
      RELOAD_INTERVAL: "${AGENT_RELOAD_INTERVAL}"
      API_HOST: "${API_HOST}"
      API_PORT: "${API_PORT}"
      API_ACCOUNT_AUTH_USER: "${API_ACCOUNT_AUTH_USER}"
      API_ACCOUNT_AUTH_PASSWORD: "${API_ACCOUNT_AUTH_PASSWORD}"
    restart: "always"
```

## 前提条件

[Microsoft Graph](https://learn.microsoft.com/ja-jp/graph/) の [デルタクエリを使用して変更を追跡](https://learn.microsoft.com/ja-jp/graph/delta-query-overview) します。Agent モジュールからこれらの機能を使うための Microsoft Graph アプリケーションを登録する必要があります。登録した Microsoft Graph アプリケーションに適切な API のアクセス許可を設定してください。

- アクセス許可の種類
  - 「アプリケーションの許可」
- Microsoft Graph API の権限
  - CrossTenantInformation.ReadBasic.All
  - User.Read.All
  - Group.Read.All

Microsoft Graph アプリケーションの登録については [Microsoft ID プラットフォームにアプリケーションを登録する](https://learn.microsoft.com/ja-jp/entra/identity-platform/quickstart-register-app) などのドキュメントを参照してください。

## Agent の永続化ディレクトリ

永続化が必要なファイルなどは volumes/agent-data/meid 配下に配置されます。

```bash
$ ls volumes/agent-data/meid
```

ここで参照する環境変数は `.env` に設定します。

## 環境変数の設定

接続する Microsoft Entra ID に関する設定は [UCIDM API サーバーのシステム設定](/resource/ucidm/docs/on-premise/1.9.0/configuration/system-setting.md#metaMicrosoftEntraID) で行います。

| 環境変数            |  値  | 既定値 | 説明                     |
| :-------------- | :-: | :-: | :--------------------- |
| TZ              |  任意 |  -- | タイムゾーン情報               |
| PAGE_KEY_PATH   |  任意 |  -- | 同期状況の保存先ディレクトリ         |
| RELOAD_INTERVAL |  任意 |  1m | システム設定の更新を定期的に問い合わせる間隔 |

- Microsoft Entra ID から正常にエントリを取得して UCIDM API サーバーへの連携に失敗 (リトライしても失敗) したときは自動で復旧しません
  - [別途ツールで運用対応する](/resource/ucidm/docs/on-premise/1.9.0/operation/resync.md) 必要があります

### API サーバー

接続する UCIDM API サーバーの設定をします。

- [アカウント認証は agent アカウントの利用を推奨](/resource/ucidm/docs/on-premise/1.9.0/configuration/agent/account.md)

| 環境変数                      |   値   |    既定値    | 説明                           |
| :------------------------ | :---: | :-------: | :--------------------------- |
| API_SCHEME                | https |    http   | UCIDM API サーバーのプロトコル         |
| API_HOST                  |   任意  | localhost | UCIDM API サーバー名              |
| API_PORT                  |   任意  |   18080   | UCIDM API サーバーのポート番号         |
| API_ACCOUNT_AUTH_USER     |   任意  |     --    | 接続する UCIDM API のアカウント認証ユーザー  |
| API_ACCOUNT_AUTH_PASSWORD |   任意  |     --    | 接続する UCIDM API のアカウント認証パスワード |

UCIDM API サーバーへのリクエストに失敗 (ステータスコードが 500 以上を返す) したときのリトライの設定をします。

| 環境変数                  |  値  | 既定値 | 説明            |
| :-------------------- | :-: | :-: | :------------ |
| CLIENT_RETRY_WAIT_MIN |  任意 |  1s | 1回目のリトライの待ち時間 |
| CLIENT_RETRY_WAIT_MAX |  任意 | 30s | リトライの最大の待ち時間  |
| CLIENT_RETRY_MAX      |  任意 |  4  | リトライの最大回数     |