> For AI agents: the complete documentation index is available at /resource/ucidm/docs/on-premise/1.8.0/llms.txt, the full documentation bundle is available at /resource/ucidm/docs/on-premise/1.8.0/llms-full.txt.
# Windows AD 外部連携モジュール
UCIDM は [Windows AD](https://learn.microsoft.com/ja-jp/windows-server/identity/ad-ds/active-directory-domain-services) に対して ID 連携できます。
Windows AD 外部連携モジュールはコンテナとして稼働させます。次のように `compose.yml` に設定します。
```yml
consumer-ad:
depends_on:
rabbitmq:
condition: service_healthy
container_name: consumer-ad
image: docker.io/osstech/ucidm-consumer:latest
logging: *default-logging
ports:
- 7099:7099
volumes:
- type: bind
source: ./server-data
target: /ucidm
bind:
create_host_path: false
entrypoint:
- ./bin/app-main
- -jsonl
environment:
TZ: "${TZ}"
DESTINATION_ID: "ad-001"
MONGO_USER: "${MONGO_USER}"
MONGO_PASSWORD: "${MONGO_PASSWORD}"
MONGO_HOSTS: "${MONGO_HOSTS}"
MONGO_REPLICA_SET: "${MONGO_REPLICA_SET}"
RABBITMQ_USER: "${RABBITMQ_USER}"
RABBITMQ_PASSWORD: "${RABBITMQ_PASSWORD}"
RABBITMQ_HOST: "${RABBITMQ_HOST}"
LDAP_URL: "${AD_URL}"
LDAP_BIND_DN: "${AD_BIND_DN}"
LDAP_BIND_PASSWORD: "${AD_BIND_PASSWORD}"
restart: "always"
```
ここで参照する環境変数は `.env` に設定します。
## 起動時のオプション設定
entrypoint では次の設定ができます。
- `-verbose`: デバッグログを出力
- `-jsonl`: JSON 形式でログを出力
## 環境変数の設定
| 環境変数 | 値 | 既定値 | 説明 |
| :--------------------- | :------------: | :---: | :---------------------------------------------------------- |
| TZ | 任意 | -- | タイムゾーン情報 |
| DESTINATION_ID | 任意 | -- | 外部連携先 ID
管理画面で作成した外部連携先 ID を指定 |
| MONGO_USER | 任意 | -- | 接続する MongoDB のユーザ名 |
| MONGO_PASSWORD | 任意 | -- | 接続する MongoDB のパスワード |
| MONGO_HOSTS | 任意 | -- | 接続する MongoDB のホスト |
| MONGO_REPLICA_SET | 任意 | -- | 接続する MongoDB のレプリカセットの名前 |
| RABBITMQ_USER | 任意 | -- | 接続する RabbitMQ のユーザ名 |
| RABBITMQ_PASSWORD | 任意 | -- | 接続する RabbitMQ のパスワード |
| RABBITMQ_HOST | 任意 | -- | 接続する RabbitMQ のホスト |
| LDAP_URL | 任意 | -- | 接続する AD の URL
(例: ldaps\://) |
| LDAP_BIND_DN | 任意 | -- | AD の Bind DN |
| LDAP_BIND_PASSWORD | 任意 | -- | AD の Bind DN のパスワード |
| ENABLE_SCRIPT_PASSWORD | true または false | false | ユーザーパスワード更新時に
外部連携の前処理/後処理スクリプトに
パスワードの値を連携するかどうか |
## AD 動作設定
管理画面にて AD の動作設定をすることができます。
設定項目と内容は次になります。
- TLS の検証をスキップ
- TLS の検証をスキップするかを指定します
- 有効無効設定情報を使用する
- ユーザープロファイルのステータス設定画面で指定した有効無効設定の情報を利用して、ユーザーのステータスの値を取得する場合は は on にします
- ステータス用属性名
- 有効無効設定情報を使用しない場合にこちらの設定が使われます
- マッピング後の属性について、AD のユーザーステータスして反映させたい属性を指定します
- 本属性には true/false の真偽値が連携されてくる必要があります（有効化の場合は true、無効化の場合は false が割り当てられる必要があります）
- ステータス用属性に指定した属性については、AD のユーザ送信データにそのまま含まれるということはありません
- 値が未設定の場合は、連携先 AD へのステータス情報の反映は行われません
- ドライランモード
- 接続の取得やエントリの検索は行いますが、実際にエントリの追加/変更/削除は行わないモードとなります
- 主にテスト時の動作確認等に使うことを想定しています
- ドメイン
- AD のドメイン名を指定します（例：destad.com）
- 主に userPrincipalName の値の自動生成に使われます
- ベース DN
- AD のベース DN を指定します
- 主に sAMAccountName をキーにしてユーザ/グループ検索を行う際の検索基点として使われます
- プライマリグループ用属性名
- ユーザのリクエストにおいて、primaryGroupID に設定したいグループの sAMAccountName の値を入れる属性を指定します
- プライマリグループ用属性に指定した属性については、AD のユーザ送信データにそのまま含まれるということはありません
- ユーザー追加/更新を行わない
- AD に対してユーザー追加/更新を行わない場合は、この項目をオン（true）にしてください
- ユーザー削除を行わない
- AD に対してユーザー削除を行わない場合は、この項目をオン（true）にしてください
- ユーザーパスワード更新を行わない
- AD に対してユーザーパスワード更新を行わない場合は、この項目をオン（true）にしてください
- グループ追加/更新を行わない
- AD に対してグループ追加/更新を行わない場合は、この項目をオン（true）にしてください
- グループ削除を行わない
- AD に対してグループ削除を行わない場合は、この項目をオン（true）にしてください
- グループメンバー追加を行わない
- AD に対してグループメンバー追加を行わない場合は、この項目をオン（true）にしてください
- グループメンバー削除を行わない
- AD に対してグループメンバー削除を行わない場合は、この項目をオン（true）にしてください
## AD マッピング設定
AD は次のマッピング設定をすることができます。
- DN マッピング
- ObjectClass マッピング
- 属性マッピング
それぞれのマッピング設定について説明します。
### DN マッピング
UCIDM で保持するエントリは DN がキーとなり連携されてきます。
この DN の値を、AD の DN の値にマッピングする設定をすることができます。
- DN の変換元部分
- 変換前の DN にて、変換したい箇所を指定します
- DN の変換先部分
- 上記変換したい箇所に、変換したい値を指定します
- DN 変換先の RDN 属性名
- 変換後の DN において、最初の要素の属性名を指定します（CN を指定してください）
例えば、uid=test01,dc=srcldap,dc=com を cn=test01,dc=example,dc=com にマッピングしたい場合は、次のように指定します。
- DN の変換元部分
- dc=srcldap,dc=com
- DN の変換先部分
- dc=example,dc=com
- DN 変換先の RDN 属性名
- cn
### ObjectClass マッピング
連携元からくる ObjectClass のデータを、連携先の AD に連携するための ObjectClass にマッピングする設定をすることができます。
- 連携先に追加で連携する ObjectClass
- 連携先 AD に追加で連携する ObjectClass を指定します
- 複数値を指定することができます
- 連携先に連携しない ObjectClass
- 連携元からくる ObjectClass のデータにて、連携先 AD に連携しない ObjectClass を指定します
- 複数値を指定することができます
例えば、連携元から、`["top", "inetOrgPerson", "organizationalPerson", "posixAccount"]` のデータが来た際に、連携先に送信する ObjectClass として、`["top", "person", "organizationalPerson", "user"]` を指定したい場合は、次のように設定します。
- 連携先に追加で連携する ObjectClass
- person
- user
- 連携先に連携しない ObjectClass
- inetOrgPerson
- posixAccount
### 属性マッピング
次の [属性マッピング設定](/resource/ucidm/docs/on-premise/1.8.0/administration/admin-ui/mappings.md) を参考にしてください。
ユーザステータスの有効化/無効化の制御をしたい場合は、ステータス用の属性のマッピングも指定してください。
また、以下の属性は Windows AD 外部連携モジュール独自のマッピングになるため、合わせてご参照ください。
#### ユーザー・グループ共通の属性
##### cn 属性
本属性については、連携されてきた DN （例：cn=test1,ou=people,dc=example,dc=com）の RDN （例：test1）の値が自動でセットされるので、マッピング設定は必要ありません。
##### sAMAccountName 属性
本属性については、連携されてきた primaryID の値が自動でセットされるので、マッピング設定は必要ありません。
この属性の値は 20 文字以下としなければいけない制限がございます。
- [https://learn.microsoft.com/ja-jp/windows/win32/adschema/a-samaccountname](https://learn.microsoft.com/ja-jp/windows/win32/adschema/a-samaccountname)
#### ユーザー属性
##### accountExpires 属性
accountExpires 属性は AD ユーザーのアカウント有効期限をセットするために利用されます。
この属性に値をセットする際は、以下のいずれかの形式で値をセットしてください。
- RFC 3339 の形式（2023-08-28T00:00:00+00:00）
- タイムゾーンを自由に指定するにはこの形式にて値をセットしてください
- "2023-08-28 10:00:00" の形式
- 本形式で値がセットされると、例として上記値であれば、UTC の "2023-08-28 10:00:00" として有効期限が設定されます
- "2023-08-28" の形式
- 本形式で値がセットされると、例として上記値であれば、UTC の "2023-08-28 00:00:00" として有効期限が設定されます
- "NEVER_EXPIRES" の形式
- "NEVER_EXPIRES" という文字列をセットすることで、アカウントの有効期限を無期限に設定できます
### 前処理・後処理スクリプト設定
UCIDM では、外部連携処理の前後で任意のシェルスクリプトを実行することができます。
次の [外部連携の前処理/後処理で実行するスクリプトの配置](/resource/ucidm/docs/on-premise/1.8.0/configuration/destination/script.md) を参考に、スクリプトファイルを配置後、[外部連携の前処理/後処理で実行するスクリプトの設定](/resource/ucidm/docs/on-premise/1.8.0/configuration/destination/script.md) を参考に、実行したいスクリプトファイルを指定してください。
## AD 外部連携モジュールの留意事項
### ユーザーステータスの変更
UCIDM では、上記「ステータス用属性名」の属性に連携されてきた値（true/false）をみて、AD のユーザーステータスの変更します。
### ユーザーの primaryGroupID の変更
UCIDM では、上記「プライマリグループ用属性名」の属性に連携されてきた値（グループの sAMAccountName）をみて、AD のユーザーの primaryGrouoID の値をセットします。
プライマリグループに設定したいグループのメンバーに、そのユーザーが所属していない場合には、エラーになります。（グループに対象のユーザーをメンバーとして追加後、再度 primaryGroupID の連携を行う必要がございます。）