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

# システム設定 \{#system-settings}

事前に [HTTPS で疎通確認](/resource/ucidm/docs/on-premise/configuration/proxy.md#local-connection) ができることを確認します。そして Web ブラウザから ID 連携管理画面 (`https://${ホスト名}/sys/`) に `admin` ユーザーでログインしてシステム設定を進めてください。

## ログイン後のパスワード変更 \{#post-login-password-change}

`admin` ユーザーの初期パスワードでログインすると、パスワード変更を求められます。任意のパスワードに変更してください。

![](/resource/ucidm/docs/on-premise/static/image/system-setting-admin-change-password.854f7af529.jpg)
## agent アカウントのパスワード設定 \{#agent-account-password}

[Agent モジュールで設定した agent アカウントのパスワード](/resource/ucidm/docs/on-premise/configuration/agent/account.md) をアカウント一覧画面から `agent` アカウントに対して設定します。パスワード変更しない限り、Agent モジュールから UCIDM API サーバーにアクセスできません。

![](/resource/ucidm/docs/on-premise/static/image/system-setting-account-list1.7a9cf30c92.jpg)
## インストール後のシステム設定 \{#post-install-system-settings}

システム設定を行うには [system-superadmin](/resource/ucidm/docs/on-premise/administration/admin-ui/role.md#system-superadmin) ロールのアカウントでログインしてシステム設定を行います。`admin` ユーザーは初期状態で system-superadmin ロールが設定されています。

システム設定一覧画面に遷移すると、セクションごとの設定項目を確認できます。

セクションの設定によっては、設定内容を反映させるために UCIDM API サーバーの再起動が必要になります。またシステム設定一覧画面から再起動できます。通常、再起動は数秒から十数秒で完了します。

### (共通) 特別な設定値のフォーマット \{#config-value-format}

#### 基準日からの期間を設定する \{#duration-from-base-date}

有効期間を設定する `XXX_TIME` という設定項目があります。次の記法で設定します。

- 5 秒に設定する場合 "5s" を設定する
- 5 分に設定する場合 "5m" を設定する
- 5 時間に設定する場合 "5h" を設定する
- 日数は時間に変換する。たとえば 5 日の場合 "120h" とする

### auth (再起動が必要) \{#auth}

認証・認可に関する設定をします。デフォルト設定の状態で進めて必要に応じて後から設定しても構いません。

お客様の組織のセキュリティポリシーにあわせて設定してください。

### authOpenLDAP (再起動が必要) \{#authOpenLDAP}

認証サーバーが [ソース LDAP](#source-datasource-connection) とは異なる OpenLDAP サーバーを利用するときに設定します。

次にシステムの構成例を示します。

```mermaid
flowchart LR

user[利用者]

subgraph in-directory-service [内部ディレクトリサービス]
  source[("ソース LDAP<br />sourceOpenLDAP<br />sourceActiveDirectory")]
end

subgraph ucidm-server [UCIDM サーバー]
  agent[Agent]
  api[UCIDM API]
  ldap-client[OpenLDAP<br />外部連携モジュール]
end

subgraph auth-server [認証サーバー]
  openam[OpenAM]
  auth-ldap[("authOpenLDAP")]
end

source -- ldaps --> agent
agent --> api
api --> ldap-client
ldap-client -- "ID 連携" --> auth-ldap
api -- "ldaps (TOTP デバイス<br />パスキーの参照・削除)" --> auth-ldap
user -- 認証 --> openam
openam -- ldaps --> auth-ldap
```

原則として OpenAM がアクセスする認証サーバーの OpenLDAP を想定しています。認証サーバーのユーザーエントリーは、[OpenLDAP 外部連携モジュール](/resource/ucidm/docs/on-premise/administration/admin-ui/destination/openldap.md) を介した ID 連携により作成されます。UCIDM API は TOTP デバイスやパスキーを参照・削除するときのみ、認証サーバーへアクセスします。認証時に TOTP デバイスやパスキーを使わないことがわかっている場合は無効設定することを推奨します。

設定内容は [sourceOpenLDAP](#sourceOpenLDAP) にある接続情報とほとんど同じです。

### idFederation \{#idFederation}

外部サービスへの ID 連携に関する設定をします。 **外部連携前であれば**、デフォルト設定の状態で進めて必要に応じて後から設定しても構いません。

#### clientHost

バージョン情報を取得するために外部連携モジュールのコンテナのアクセス先を指定します。

- 複数の外部連携モジュールのコンテナを利用していたとしても、どれか1つのコンテナに対するホスト名とポート番号を指定する
- バージョン情報は 1 時間キャッシュされる。外部連携モジュールのコンテナを更新したとき、最大 1 時間はバージョン情報が更新されない可能性がある

#### primaryID

UCIDM では、各ユーザー/グループを一意に識別するための ID として **primaryID** を使用します。

primaryID はデフォルトでは DN 文字列の RDN0 の値が割り当てられます。

> \[!NOTE]
> 例) cn=test1,ou=people,dc=example,dc=com という DN であれば test1 が primaryID になる

ここで primaryID は必ず一意となるように設定する必要があります。仮に DN 文字列の RDN0 の値のみだと競合してしまうような場合は `userPrimaryIDTemplate` と `groupPrimaryIDTemplate` のテンプレート文字列を使って一意になるような値を割り当ててください。

> \[!NOTE]
> 例) "%\{cn}-%\{uid}" と設定した場合、属性の cn=test1, uid=101 ならば test1-101 が primaryID になる

primaryID は、Microsoft Entra ID、Google Workspace、AD、SCIM の外部サービスへの連携において主要なキー情報として連携されます。[仕様上の制約](/resource/ucidm/docs/on-premise/specification/constraints.md#primaryid-immutable) もご確認ください。

#### membershipRulesEnabled \{#idFederation-membershipRulesEnabled}

メンバーシップルール機能を有効化するかどうかを指定します。

- ユーザー属性からルールに適合したときに自動的にグループメンバーに追加する
  - 通常はユーザーの属性情報を更新したときのみ、ルールの判定が実行される
  - ルールを変更したときにそのルールを即時反映したいときは手動で同期処理を実行する
- 手動でグループメンバーを更新したときは100件までルールの除外リストとして管理する

設定方法はユーザープロファイル画面 (管理者用) の [メンバーシップルール設定](/resource/ucidm/docs/on-premise/administration/ucidm-ui/admin.md) を参照してください。

#### membershipBridgeEnabled \{#idFederation-membershipBridgeEnabled}

メンバーシップブリッジ機能を有効化するかどうかを指定します。

- 専用グループに対するメンバーの所属状況を外部連携先へのプロビジョニングと見立てる
  - メンバー追加: プロビジョニング
  - メンバー削除: デプロビジョニング
- [パスワード保持機能](#passwordRetention) と組み合わせると、プロビジョニング時にユーザーのパスワードも自動連携する

設定方法は ID 連携管理画面の [ブリッジグループ設定](/resource/ucidm/docs/on-premise/administration/admin-ui/index.md) を参照してください。

### loginLockout \{#loginLockout}

連続して認証が失敗した回数が一定数を超えた場合に一定時間ログイン不可の状態にする機能の設定をします。デフォルト設定の状態で進めて必要に応じて後から設定しても構いません。

次の認証方法に対して同じ設定が適用されます。

- アカウント認証
- LDAP 認証

### 連携元データソースの接続設定 \{#source-datasource-connection}

連携元となる内部ディレクトリサービスとの接続情報を設定します。

複数の内部ディレクトリサービスに対応していますが、連携元の設定は次のうちから1つしか有効にできません。

- sourceActiveDirectory
- sourceOpenLDAP
- sourceMicrosoftEntraID

この設定は [UCIDM API](/resource/ucidm/docs/on-premise/configuration/ucidm-api.md) と [Agent モジュール](/resource/ucidm/docs/on-premise/configuration/agent/index.md) の両方で利用されます。設定を更新して UCIDM API サーバーを再起動したときに Agent モジュールもその変更を検知して反映します。

#### sourceActiveDirectory (再起動が必要) \{#sourceActiveDirectory}

sourceOpenLDAP の設定とほとんど同じですが、Active Directory サービスに特化した設定を追加できます。

##### hosts

指定された複数のホストに対して接続を試みます。接続に失敗した場合はリトライせず、次のホストへ接続を試みます。

##### bindDN

通常は接続するユーザーを DN で指定します。

[Windows Server 2003 以降のドメイン コントローラーで Active Directory への匿名 LDAP 操作が無効になっている](https://learn.microsoft.com/ja-JP/troubleshoot/windows-server/identity/anonymous-ldap-operations-active-directory-disabled) ため、Active Directory 向け Agent は anonymous bind をサポートしません。適切な bind ユーザーのアカウントをご用意ください。

##### userSearchBase/groupSearchBase

searchBase と同じ値を設定してください。

##### groupMemberAttribute

グループにおいて、メンバーの値が入る属性の属性名を設定します (例：memberUid) 。

- この設定をした属性の情報はグループのメンバーの情報としてグループとは別に UCIDM API に連携されます
- `ucidm-not-divide-member` の値を設定すると、メンバー情報をグループから分離せず、そのままグループエントリとして連携されます
  - この設定をした際は userGroupLinkAttribute を設定しないようにしてください

##### userGroupLinkAttribute

ユーザーとグループにおいて、紐づけたい属性を設定できます (例：gidNumber) 。

- この設定をした場合、例えば gidNumber を設定した場合は、ユーザーの gidNumber と同じ gidNumber を持つグループのメンバーに該当ユーザーが割り当てられて UCIDM API に連携されます
- 設定値がない場合は、この属性によるユーザーとグループの紐づけは行われません

##### excludeLoggingAttributes

Active Directory サービスに対する登録・更新リクエストのログ出力を除外する属性を指定できます。`unicodePwd` は必ず除外されます。

#### sourceOpenLDAP (再起動が必要) \{#sourceOpenLDAP}

sourceActiveDirectory の設定とほとんど同じですが、OpenLDAP サービスに特化した設定を追加できます。

##### hosts

指定された複数のホストに対して接続を試みます。接続に失敗した場合はリトライせず、次のホストへ接続を試みます。

##### bindDN

通常は接続するユーザーを DN で指定します。Anonymous bind で接続するときは未設定または空文字を設定します。

##### groupMemberAttribute

グループにおいて、メンバーの値が入る属性の属性名を設定します (例：memberUid) 。

- この設定をした属性の情報はグループのメンバーの情報としてグループとは別に UCIDM API に連携されます
- `ucidm-not-divide-member` の値を設定すると、メンバー情報をグループから分離せず、そのままグループエントリとして連携されます
  - この設定をした際は userGroupLinkAttribute を設定しないようにしてください

##### userGroupLinkAttribute

ユーザーとグループにおいて、紐づけたい属性を設定できます (例：gidNumber) 。

- この設定をした場合、例えば gidNumber を設定した場合は、ユーザーの gidNumber と同じ gidNumber を持つグループのメンバーに該当ユーザーが割り当てられて UCIDM API に連携されます
- 設定値がない場合は、この属性によるユーザーとグループの紐づけは行われません

##### excludeLoggingAttributes

OpenLDAP サービスに対する登録・更新リクエストのログ出力を除外する属性を指定できます。`userPassword` は必ず除外されます。

#### sourceMicrosoftEntraID (再起動が必要) \{#sourceMicrosoftEntraID}

##### scopes

Microsoft Graph アプリケーションにあらかじめ必要なアクセス権限を設定します。通常は `https://graph.microsoft.com/.default` を設定します。

##### userProperties

ユーザーにおいて指定したプロパティに対する変更のみが ID 連携されます。

##### groupProperties

グループにおいて指定したプロパティに対する変更のみが ID 連携されます。

### passwordReset \{#passwordReset}

パスワードリセットに関する設定をします。デフォルト設定の状態で進めて必要に応じて後から設定しても構いません。

#### requestMailTemplate

パスワードリセット向けメールのテンプレートを設定します。

アカウントのパスワードを忘れたときにメールを送信してパスワードリセットできます。メールのテンプレートファイルを使ってパスワードリセットメールをカスタマイズできます。

メールのテンプレートファイルでは、次のフィールドに対してテンプレート変数を使ってカスタマイズします。

|  フィールド名  | 説明                      |
| :------: | :---------------------- |
|   From   | パスワードリセットメールの送信元メールアドレス |
|    To    | パスワードリセットメールの送信先メールアドレス |
| Reply-To | パスワードリセットメールの返信先メールアドレス |
|  Subject | パスワードリセットメールの件名         |

次の変数をテンプレートファイルに記述することで、値が入ったメール送信が可能になります。

|         テンプレート変数         | 説明                      |
| :----------------------: | :---------------------- |
| \{\{.SenderMailAddress}} | mailSender に設定した値       |
|      \{\{.UserName}}     | パスワードリセットを行うユーザー名       |
|  \{\{.UserMailAddress}}  | パスワードリセットメールの送信先メールアドレス |
|   \{\{.TemporaryToken}}  | パスワードリセットで使用する一時トークン    |

##### 一時トークンを送付するメールテンプレート \{#temporary-token-email-template}

テンプレートのサンプル設定は次になります。メールヘッダーと本文の間には空行を入れてください。

```
From: <{{.SenderMailAddress}}>
To: {{.UserName}} <{{.UserMailAddress}}>
Reply-To: 返信しないで <no-reply@osstech.co.jp>
Subject: パスワードリセット

パスワードをリセットするための一時トークンを送ります。
このトークンを使って管理画面からパスワードリセットしてください。

一時トークン: {{.TemporaryToken}}

一定時間経過するとパスワードリセットができなくなります。
```

#### successMailTemplate

パスワードリセット完了を連絡するメールテンプレートを設定します。

##### パスワードリセット完了を連絡するメールテンプレート \{#password-reset-complete-email-template}

```
From: <{{.SenderMailAddress}}>
To: {{.UserName}} <{{.UserMailAddress}}>
Subject: パスワードリセット成功

新しいパスワードに更新されました。
```

### passwordRetention \{#passwordRetention}

> \[!CAUTION]
>
> この設定を有効にすると、システム管理者は一般ユーザーのパスワードを復元可能となります。そのため、否認防止性が失われます。お客様の組織のセキュリティポリシーにあわせて設定してください。

複数の属性に対して、個別にパスワード保持のための暗号化の設定ができます。またパスワードは、一般ユーザーが設定した任意の値と、システム管理者が設定した固定の値を使い分けられます。パスワードを連携したい目的に応じて使い分けます。

また OpenAM と暗号化設定をあわせて ID 連携することで代理認証で SSO ができます。

### saml (再起動が必要) \{#saml}

SAML 認証に関する設定をします。[SAML 認証](/resource/ucidm/docs/on-premise/operation/saml.md) を行うときのみ設定してください。

#### spRootURL

SAML 関連のエンドポイントが定義され、メタデータに反映されます。この値はユーザープロファイルのアクセスホスト名:ポート番号を使って、次のように設定してください。

```
＜プロトコル＞://＜ユーザープロファイル画面の HOST ＞:＜ PORT ＞/ui/user/api/
```

#### idpMetadataURL/idpMetadata

SAML IdP のメタデータは次のどちらか一方で設定します。

- `idpMetadataURL`
  - 指定した URL から取得する
  - IdP にて自己証明書を使っている場合は `spTLSSkipVerifyFetchIdPMetadata` を true に設定する
- `idpMetadata`
  - IdP のメタデータを事前にダウンロードしている場合はその内容 (XML) を設定する

#### spAuthType

SAML 認証時に UCIDM で管理している認証種別を関連付けるための設定になります。次の認証方法に対応しています。

- LDAP 認証

#### spRoleName

SAML 認証時に UCIDM で管理しているロールを関連付けるための設定となります。デフォルトでは `ldap-user` ロールを設定します。

### serverInfra (再起動が必要) \{#serverInfra}

デフォルト設定の状態で進めて必要に応じて後から設定しても構いません。

#### xffTrustIPRanges

UCIDM API サーバーは [X-Forwarded-For](https://developer.mozilla.org/ja/docs/Web/HTTP/Headers/X-Forwarded-For) (以下 XFF) ヘッダーを参照してリクエスト元 IP アドレスを履歴に記録します。IP アドレスを詐称できないよう、信頼するネットワークを設定します。

- 信頼できるネットワークはカンマ区切りで複数指定する
  - 設定例) 192.168.0.1/24,172.16.0.0/12,2001:db8::/64
- 指定しないときはコンテナネットワークのゲートウェイ (172.18.0.1) がリクエスト元 IP アドレスとなる

### メールサーバー設定 \{#mail-server-settings}

パスワードリセットなど、メールを送信するときに利用するメールサーバーの設定をします。[パスワードリセット](#passwordReset) 運用を行う前に設定してください。

#### smtp \{#smtp}

特別な認証を必要としない、多くのメールサーバーはこの設定のみでメール送信ができます。

#### xoauth2 \{#xoauth2}

SMTP サーバーと OAuth 2.0 認証するときのみ、必要な設定になります。

[Google Workspace では SMTP サーバーと OAuth 2.0 認証](https://developers.google.com/gmail/imap/xoauth2-protocol?hl=ja) を行うことが推奨されています。次のツールを使ってクライアントシークレットと認証コードからリフレッシュトークンを取得できます。リフレッシュトークンがないと、アクセストークンの有効期限が切れたときに再取得できません。ツールを実行すると、クライアントシークレットと認証コードが求められるので入力します（入力時、文字は表示されません）。

```
./bin/oauth -clientID <OAuth 2.0 認証で使用するクライアントID> -redirectURL <OAuth 2.0 認証で設定したリダイレクトURL> -authURL <OAuth 2.0 認証の認証エンドポイント> -tokenURL <OAuth 2.0 認証のトークンエンドポイント> -scope <OAuth 2.0 認証で設定したスコープ>
```

出力

```
access token: xxxxa0AfB_byAY5...
refresh token: yyyy0elQbS2Fscsi5...
```