LDAP同期
- プラン: Premium、Ultimate
- 提供形態: GitLab Self-Managed
LDAPをGitLabと連携するように設定している場合、GitLabはユーザーとグループを自動的に同期できます。
LDAP同期では、LDAPアイデンティティが割り当てられている既存のGitLabユーザーのユーザー情報とグループ情報を更新します。LDAPを通じて新しいGitLabユーザーを作成することはありません。
同期のタイミングは変更可能です。
レート制限が設定されているLDAPサーバー
一部のLDAPサーバーには、レート制限が設定されています。
GitLabは、次のようにLDAPサーバーへのクエリを実行します:
場合によっては、LDAPサーバーへの追加のクエリがトリガーされることがあります。たとえば、グループ同期のクエリでmemberuid属性が返された場合などです。
LDAPサーバーにレート制限が設定されており、その制限に達した場合:
- ユーザー同期プロセスでは、LDAPサーバーはエラーコードを返し、GitLabはそのユーザーをブロックします。
- グループ同期プロセスでは、LDAPサーバーはエラーコードを返し、GitLabはそのユーザーのグループメンバーシップを削除します。
意図しないユーザーのブロックやグループメンバーシップの削除を防ぐために、LDAP同期を設定する際は、LDAPサーバーのレート制限を考慮する必要があります。
ユーザー同期
GitLabは1日に1回ワーカーを実行し、LDAPに対してGitLabユーザーの確認と更新を行います。
このプロセスでは、次のアクセスチェックを実行します:
- ユーザーがLDAPにまだ存在することを確認する。
- LDAPサーバーがActive Directoryの場合、ユーザーがアクティブである(ブロック/無効化されていない)ことを確認する。このチェックは、LDAPの設定で
active_directory: trueが有効になっている場合にのみ実行されます。
Active Directoryでは、ユーザーアカウント制御属性(userAccountControl:1.2.840.113556.1.4.803)のビット2が設定されている場合、そのユーザーは無効/ブロック済みとしてマークされます。
詳細については、Bitmask Searches in LDAP(LDAPにおけるビットマスク検索)を参照してください。
このプロセスでは、次のユーザー情報も更新されます:
- 名前。同期の問題により、ユーザーがプロファイル名を変更できないようにするが有効になっているか、
sync_nameがfalseに設定されている場合、nameは同期されません。 - メールアドレス。
- SSH公開キー(
sync_ssh_keysが設定されている場合)。 - Kerberosアイデンティティ(Kerberosが有効になっている場合)。
LDAPサーバーにレート制限が設定されている場合、ユーザー同期プロセス中にその制限に達する可能性があります。詳細については、レート制限に関するドキュメントを参照してください。
LDAPユーザーのプロファイル名を同期する
デフォルトでは、GitLabはLDAPユーザーのプロファイル名フィールドを同期します。
この同期を回避するには、sync_nameをfalseに設定します。
/etc/gitlab/gitlab.rbを編集します:gitlab_rails['ldap_servers'] = { 'main' => { 'sync_name' => false, } }ファイルを保存して、GitLabを再設定します:
sudo gitlab-ctl reconfigure
Helmの値をエクスポートします:
helm get values gitlab > gitlab_values.yamlgitlab_values.yamlを編集します:global: appConfig: ldap: servers: main: sync_name: falseファイルを保存して、新しい値を適用します:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
docker-compose.ymlを編集します:version: "3.6" services: gitlab: environment: GITLAB_OMNIBUS_CONFIG: | gitlab_rails['ldap_servers'] = { 'main' => { 'sync_name' => false, } }ファイルを保存して、GitLabを再起動します:
docker compose up -d
/home/git/gitlab/config/gitlab.ymlを編集します:production: &base ldap: servers: main: sync_name: falseファイルを保存して、GitLabを再起動します:
# For systems running systemd sudo systemctl restart gitlab.target # For systems running SysV init sudo service gitlab restart
ブロックされたユーザー
ユーザーは、次のいずれかの条件に該当するとブロックされます:
- アクセスチェックに失敗し、そのユーザーがGitLabで
ldap_blocked状態に設定される。 - ユーザーのサインイン時にLDAPサーバーが利用できない。
ユーザーがブロックされると、サインインやコードのプッシュ/プルができなくなります。
ブロックされたユーザーは、次のすべての条件を満たす場合、LDAPでサインインしたときにブロックが解除されます:
- アクセスチェックのすべての条件を満たしている。
- ユーザーのサインイン時にLDAPサーバーが利用可能である。
LDAPユーザー同期の実行時にLDAPサーバーが利用できない場合、すべてのユーザーがブロックされます。
LDAPユーザー同期の実行時にLDAPサーバーが利用できないためにすべてのユーザーがブロックされた場合、その後のLDAPユーザー同期によってこれらのユーザーのブロックが自動的に解除されることはありません。
グループ同期
LDAPがmemberofプロパティをサポートしている場合、ユーザーが初めてサインインするときに、GitLabはユーザーが所属すべきグループの同期をトリガーします。そのため、グループやプロジェクトへのアクセス権が付与されるまで、1時間ごとの同期を待つ必要はありません。
グループ同期プロセスは毎時0分に実行され、グループCNに基づくLDAP同期を機能させるには、LDAP設定でgroup_baseを指定する必要があります。これにより、LDAPグループメンバーに基づいて、GitLabグループメンバーシップを自動的に更新できます。
group_base設定には、GitLabで使用できるようにする必要があるLDAPグループが含まれる、ベースLDAP「コンテナ」(「組織」や「組織単位」など)を指定する必要があります。たとえば、group_baseにはou=groups,dc=example,dc=comのような値を指定します。設定ファイルでは、次のように記述します。
LDAPサーバーにレート制限が設定されている場合、グループ同期プロセス中にその制限に達する可能性があります。詳細については、レート制限に関するドキュメントを参照してください。
/etc/gitlab/gitlab.rbを編集します:gitlab_rails['ldap_servers'] = { 'main' => { 'group_base' => 'ou=groups,dc=example,dc=com', } }ファイルを保存して、GitLabを再設定します:
sudo gitlab-ctl reconfigure
Helmの値をエクスポートします:
helm get values gitlab > gitlab_values.yamlgitlab_values.yamlを編集します:global: appConfig: ldap: servers: main: group_base: ou=groups,dc=example,dc=comファイルを保存して、新しい値を適用します:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
docker-compose.ymlを編集します:version: "3.6" services: gitlab: environment: GITLAB_OMNIBUS_CONFIG: | gitlab_rails['ldap_servers'] = { 'main' => { 'group_base' => 'ou=groups,dc=example,dc=com', } }ファイルを保存して、GitLabを再起動します:
docker compose up -d
/home/git/gitlab/config/gitlab.ymlを編集します:production: &base ldap: servers: main: group_base: ou=groups,dc=example,dc=comファイルを保存して、GitLabを再起動します:
# For systems running systemd sudo systemctl restart gitlab.target # For systems running SysV init sudo service gitlab restart
グループ同期を利用するには、グループのオーナーまたはメンテナーロールを持つユーザーが、1つ以上のLDAPグループリンクを作成する必要があります。
LDAPサーバーとGitLabインスタンスの間で接続の問題が頻繁に発生する場合は、グループ同期ワーカーの実行間隔をデフォルトの1時間よりも長く設定することで、GitLabがLDAPグループ同期を実行する頻度を減らしてみてください。
グループリンクを追加する
CNとフィルターを使用してグループリンクを追加する方法については、GitLabのグループに関するドキュメントを参照してください。
カスタム管理者ロールをLDAPグループにリンクする
CNとフィルターを使用してカスタム管理者ロールのリンクを追加する方法については、LDAPを使用したユーザーの管理に関するドキュメントを参照してください。
管理者同期
グループ同期の拡張機能として、GitLabのグローバル管理者を自動的に管理できます。admin_groupにグループCNを指定すると、LDAPグループのすべてのメンバーに管理者権限が付与されます。設定は次のようになります。
管理者を同期するには、group_baseに加えてadmin_groupも指定する必要があります。また、完全なDNではなく、admin_groupのCNのみを指定してください。さらに、LDAPユーザーにadminロールが付与されていても、admin_groupグループのメンバーではない場合、GitLabは同期の際にそのユーザーのadminロールを失効させます。
/etc/gitlab/gitlab.rbを編集します:gitlab_rails['ldap_servers'] = { 'main' => { 'group_base' => 'ou=groups,dc=example,dc=com', 'admin_group' => 'my_admin_group', } }ファイルを保存して、GitLabを再設定します:
sudo gitlab-ctl reconfigure
Helmの値をエクスポートします:
helm get values gitlab > gitlab_values.yamlgitlab_values.yamlを編集します:global: appConfig: ldap: servers: main: group_base: ou=groups,dc=example,dc=com admin_group: my_admin_groupファイルを保存して、新しい値を適用します:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
docker-compose.ymlを編集します:version: "3.6" services: gitlab: environment: GITLAB_OMNIBUS_CONFIG: | gitlab_rails['ldap_servers'] = { 'main' => { 'group_base' => 'ou=groups,dc=example,dc=com', 'admin_group' => 'my_admin_group', } }ファイルを保存して、GitLabを再起動します:
docker compose up -d
/home/git/gitlab/config/gitlab.ymlを編集します:production: &base ldap: servers: main: group_base: ou=groups,dc=example,dc=com admin_group: my_admin_groupファイルを保存して、GitLabを再起動します:
# For systems running systemd sudo systemctl restart gitlab.target # For systems running SysV init sudo service gitlab restart
グローバルLDAPグループメンバーシップロック
GitLab管理者は、メンバーシップがLDAPと同期されているサブグループに対して、グループメンバーが新しいメンバーを招待できないように制御できます。
グローバルグループメンバーシップのロックは、LDAP同期が設定されているトップレベルグループのサブグループにのみ適用されます。LDAP同期が設定されたトップレベルグループのメンバーシップは、どのユーザーも変更できません。
グローバルグループメンバーシップのロックが有効になっている場合:
- グループまたはサブグループをコードオーナーとして設定することはできません。詳細については、グローバルグループメンバーシップロックとの非互換性を参照してください。
- 管理者のみが、アクセスレベルを含め、グループのメンバーシップを管理できます。
- ユーザーは、プロジェクトを他のグループと共有したり、グループで作成されたプロジェクトにメンバーを招待したりすることはできません。
グローバルグループメンバーシップのロックを有効にするには、次の手順に従います:
- LDAPを設定します。
- 左側のサイドバーの下部で、管理者を選択します。新しいナビゲーションをオンにしている場合は、右上隅でアバターを選択し、管理者を選択します。
- 設定 > 一般を選択します。
- 表示レベルとアクセス制御を展開します。
- メンバーシップをLDAP同期に限定チェックボックスがオンになっていることを確認します。
LDAPグループ同期設定の管理権限を変更する
デフォルトでは、オーナーロールを持つグループメンバーは、LDAPグループ同期設定を管理できます。
GitLab管理者は、グループのオーナーからこの権限を削除できます:
- LDAPを設定します。
- 左側のサイドバーの下部で、管理者を選択します。新しいナビゲーションをオンにしている場合は、右上隅でアバターを選択し、管理者を選択します。
- 設定 > 一般を選択します。
- 表示レベルとアクセス制御を展開します。
- グループオーナーがLDAP関連の設定を管理できるようにするチェックボックスがオンになっていないことを確認します。
グループオーナーがLDAP関連の設定を管理できるようにするが無効になっている場合:
- グループオーナーは、トップレベルグループとサブグループのいずれにおいてもLDAP同期設定を変更できません。
- インスタンス管理者は、そのインスタンス上のすべてのグループに対してLDAPグループ同期設定を管理できます。
外部グループ
external_groups設定を使用すると、指定したグループに属するすべてのユーザーを外部ユーザーとしてマークできます。グループメンバーシップは、LdapGroupSyncバックグラウンドタスクを通じて定期的にチェックされます。
/etc/gitlab/gitlab.rbを編集します:gitlab_rails['ldap_servers'] = { 'main' => { 'external_groups' => ['interns', 'contractors'], } }ファイルを保存して、GitLabを再設定します:
sudo gitlab-ctl reconfigure
Helmの値をエクスポートします:
helm get values gitlab > gitlab_values.yamlgitlab_values.yamlを編集します:global: appConfig: ldap: servers: main: external_groups: ['interns', 'contractors']ファイルを保存して、新しい値を適用します:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
docker-compose.ymlを編集します:version: "3.6" services: gitlab: environment: GITLAB_OMNIBUS_CONFIG: | gitlab_rails['ldap_servers'] = { 'main' => { 'external_groups' => ['interns', 'contractors'], } }ファイルを保存して、GitLabを再起動します:
docker compose up -d
/home/git/gitlab/config/gitlab.ymlを編集します:production: &base ldap: servers: main: external_groups: ['interns', 'contractors']ファイルを保存して、GitLabを再起動します:
# For systems running systemd sudo systemctl restart gitlab.target # For systems running SysV init sudo service gitlab restart
グループのGitLab Duoアドオン
duo_add_on_groups設定を使用すると、LDAPを通じて認証するユーザーに対して、GitLab Duoアドオンのシートを自動的に管理できます。この機能により、組織はLDAPグループメンバーシップに基づいてGitLab Duoシートの割り当てプロセスを効率化できます。
GitLab Duoのシートの同期は、次の2つの方法で行われます:
- On user sign-in(ユーザーサインイン時): ユーザーがLDAP経由でサインインすると、GitLabはそのグループメンバーシップを即座にチェックします。
- Scheduled sync(定刻同期): GitLabは毎日午前2:00(サーバー時刻)に、すべてのLDAPユーザーを自動的に同期し、ユーザーがサインインしていなくてもシート割り当てが最新の状態に保たれるようにします。
グループに対してアドオンシート管理を有効にするには、GitLabインスタンスでduo_add_on_groups設定を指定する必要があります:
/etc/gitlab/gitlab.rbを編集します:gitlab_rails['ldap_servers'] = { 'main' => { 'duo_add_on_groups' => ['duo_group_1', 'duo_group_2'], } }ファイルを保存して、GitLabを再設定します:
sudo gitlab-ctl reconfigure
Helmの値をエクスポートします:
helm get values gitlab > gitlab_values.yamlgitlab_values.yamlを編集します:global: appConfig: ldap: servers: main: duo_add_on_groups: ['duo_group_1', 'duo_group_2']ファイルを保存して、新しい値を適用します:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
docker-compose.ymlを編集します:version: "3.6" services: gitlab: environment: GITLAB_OMNIBUS_CONFIG: | gitlab_rails['ldap_servers'] = { 'main' => { 'duo_add_on_groups' => ['duo_group_1', 'duo_group_2'], } }ファイルを保存して、GitLabを再起動します:
docker compose up -d
/home/git/gitlab/config/gitlab.ymlを編集します:production: &base ldap: servers: main: duo_add_on_groups: ['duo_group_1', 'duo_group_2']ファイルを保存して、GitLabを再起動します:
# For systems running systemd sudo systemctl restart gitlab.target # For systems running SysV init sudo service gitlab restart
グループ同期の技術的な詳細
このセクションでは、実行されるLDAPクエリの内容と、グループ同期によって予想される動作の概要を説明します。
ユーザーのLDAPグループメンバーシップが変更されると、グループのアクセスレベルがダウングレードされることがあります。たとえば、あるユーザーがグループでオーナー権限を持っていても、次回のグループ同期で本来はデベロッパー権限のみであることが判明した場合、そのユーザーのアクセス権はそれに応じて調整されます。唯一の例外は、そのユーザーがグループ内の最後のオーナーである場合です。グループには、管理業務を行うために少なくとも1人のオーナーが必要であるためです。サブスクリプションシートの管理が制限付きアクセスに設定され、使用可能なサブスクリプションシートが残っていない場合、グループの同期中に、ユーザーには自動的に最小アクセスロールが割り当てられます。これにより、シートを消費せずにユーザーを同期できます。
サポートされているLDAPグループのタイプ/属性
GitLabは、メンバー属性を使用するLDAPグループをサポートしています:
membersubmemberuniquemembermemberofmemberuid
つまり、グループ同期は(少なくとも)次のオブジェクトクラスを持つLDAPグループをサポートしています:
groupOfNamesposixGroupgroupOfUniqueNames
その他のオブジェクトクラスも、メンバーが前述の属性のいずれかとして定義されていれば機能するはずです。
Active Directoryはネストされたグループをサポートしています。設定ファイルでactive_directory: trueが指定されている場合、グループ同期はメンバーシップを再帰的に解決します。
ネストされたグループメンバーシップ
ネストされたグループメンバーシップは、ネストされたグループが設定済みのgroup_baseに存在する場合にのみ解決されます。たとえば、GitLabがcn=nested_group,ou=special_groups,dc=example,dc=comというDNを持つネストされたグループを検出しても、設定済みのgroup_baseがou=groups,dc=example,dc=comである場合、cn=nested_groupは無視されます。
クエリ
- 各LDAPグループは、
group_baseをベースとし、フィルター(cn=<cn_from_group_link>)を使用して、最大1回クエリされます。 - LDAPグループに
memberuid属性がある場合、GitLabは各メンバーごとに追加のLDAPクエリを実行し、ユーザーの完全なDNを取得します。これらのクエリは、base、baseObject、およびuser_filterが設定されているかどうかに応じたフィルターを用いて実行されます。フィルターには、(uid=<uid_from_group>)、またはuser_filterの結合条件が使用されます。
ベンチマーク
グループ同期は、可能な限りパフォーマンスが高くなるように設計されています。データはキャッシュされ、データベースクエリは最適化され、LDAPクエリは最小限に抑えられています。直近のベンチマークで得られたメトリクスは次のとおりです:
LDAPユーザー数20,000、LDAPグループ数11,000、各グループに10件のLDAPグループリンクを持つGitLabグループ数1,000の場合:
- 最初の同期(GitLabに既存のメンバーが割り当てられていない状態)は1.8時間
- それ以降の同期(メンバーシップの確認のみ、書き込みなし)は15分
これらのメトリクスはベースラインを提供することを目的としており、実際のパフォーマンスはさまざまな要因によって異なる場合があります。このベンチマークは極端なケースであり、ほとんどのインスタンスにはこれほど多くのユーザーやグループは存在しません。ディスク速度、データベースのパフォーマンス、ネットワーク、LDAPサーバーの応答時間が、これらのメトリクスに影響します。
LDAP同期スケジュールの調整
LDAPがユーザー、グループ、Duoアドオンシートを同期する時間と間隔を変更できます。
ユーザーの場合
デフォルトでは、GitLabは1日に1回、サーバー時刻の午前1時30分にワーカーを実行し、LDAPに対してGitLabユーザーの確認と更新を行います。
同期プロセスを頻繁に実行しないでください。複数の同期が同時に実行される可能性があります。ほとんどのインストールでは、同期スケジュールを変更する必要はありません。詳細については、LDAPのセキュリティに関するドキュメントを参照してください。
cron形式で次の設定値を指定することで、LDAPユーザー同期の時刻を手動で設定できます。必要に応じて、crontab generatorを使用することもできます。以下の例は、LDAPユーザー同期を毎日12時間ごと、各時の0分に実行するように設定する方法を示しています。
/etc/gitlab/gitlab.rbを編集します:gitlab_rails['ldap_sync_worker_cron'] = "0 */12 * * *"ファイルを保存して、GitLabを再設定します:
sudo gitlab-ctl reconfigure
Helmの値をエクスポートします:
helm get values gitlab > gitlab_values.yamlgitlab_values.yamlを編集します:global: appConfig: cron_jobs: ldap_sync_worker: cron: "0 */12 * * *"ファイルを保存して、新しい値を適用します:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
docker-compose.ymlを編集します:version: "3.6" services: gitlab: environment: GITLAB_OMNIBUS_CONFIG: | gitlab_rails['ldap_sync_worker_cron'] = "0 */12 * * *"ファイルを保存して、GitLabを再起動します:
docker compose up -d
/home/git/gitlab/config/gitlab.ymlを編集します:production: &base ee_cron_jobs: ldap_sync_worker: cron: "0 */12 * * *"ファイルを保存して、GitLabを再起動します:
# For systems running systemd sudo systemctl restart gitlab.target # For systems running SysV init sudo service gitlab restart
グループの場合
デフォルトでは、GitLabは毎時0分にグループ同期プロセスを実行します。値はcron形式で指定します。必要に応じて、crontab generatorを使用することもできます。
同期プロセスを頻繁に開始しないでください。複数の同期が同時に実行される可能性があります。ほとんどのインストールでは、同期スケジュールを変更する必要はありません。
次の設定値を指定することで、LDAPグループ同期の時刻を手動で設定できます。以下の例は、グループ同期を毎日2時間ごと、各時の0分に実行するように設定する方法を示しています。
/etc/gitlab/gitlab.rbを編集します:gitlab_rails['ldap_group_sync_worker_cron'] = "0 */2 * * *"ファイルを保存して、GitLabを再設定します:
sudo gitlab-ctl reconfigure
Helmの値をエクスポートします:
helm get values gitlab > gitlab_values.yamlgitlab_values.yamlを編集します:global: appConfig: cron_jobs: ldap_group_sync_worker: cron: "*/30 * * * *"ファイルを保存して、新しい値を適用します:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
docker-compose.ymlを編集します:version: "3.6" services: gitlab: environment: GITLAB_OMNIBUS_CONFIG: | gitlab_rails['ldap_group_sync_worker_cron'] = "0 */2 * * *"ファイルを保存して、GitLabを再起動します:
docker compose up -d
/home/git/gitlab/config/gitlab.ymlを編集します:production: &base ee_cron_jobs: ldap_group_sync_worker: cron: "*/30 * * * *"ファイルを保存して、GitLabを再起動します:
# For systems running systemd sudo systemctl restart gitlab.target # For systems running SysV init sudo service gitlab restart
Duoアドオンシートの場合
デフォルトでは、GitLabは毎日午前2時00分(サーバー時間)にDuoアドオンシートの同期プロセスを実行し、LDAPグループグループメンバーシップをチェックし、それに応じてDuoアドオンシートを割り当てまたは削除します。
同期プロセスを頻繁に開始しないでください。複数の同期が同時に実行される可能性があります。ほとんどのインストールでは、同期スケジュールを変更する必要はありません。
LDAP Duoアドオンシートの同期時間を手動で設定するには、設定値を設定します。次の例は、同期を4時間ごとに1回実行するように設定する方法を示しています。
/etc/gitlab/gitlab.rbを編集します:gitlab_rails['ldap_add_on_seat_sync_worker_cron'] = "0 */4 * * *"ファイルを保存して、GitLabを再設定します:
sudo gitlab-ctl reconfigure
Helmの値をエクスポートします:
helm get values gitlab > gitlab_values.yamlgitlab_values.yamlを編集します:global: appConfig: cron_jobs: ldap_add_on_seat_sync_worker: cron: "0 */4 * * *"ファイルを保存して、新しい値を適用します:
helm upgrade -f gitlab_values.yaml gitlab gitlab/gitlab
docker-compose.ymlを編集します:version: "3.6" services: gitlab: environment: GITLAB_OMNIBUS_CONFIG: | gitlab_rails['ldap_add_on_seat_sync_worker_cron'] = "0 */4 * * *"ファイルを保存して、GitLabを再起動します:
docker compose up -d
/home/git/gitlab/config/gitlab.ymlを編集します:production: &base ee_cron_jobs: ldap_add_on_seat_sync_worker: cron: "0 */4 * * *"ファイルを保存して、GitLabを再起動します:
# For systems running systemd sudo systemctl restart gitlab.target # For systems running SysV init sudo service gitlab restart