SAMLグループ同期

SAMLグループ同期を使用して、SAML Identity Provider（IdP）でのユーザーのグループへの割り当てに基づいて、特定のロールを持つユーザーを既存のGitLabグループに割り当てます。SAMLグループ同期を使用すると、SAML Identity ProviderグループとGitLabグループ間の多対多のマッピングを作成できます。

たとえば、ユーザー@ameliaがSAML Identity Providerのsecurityグループに割り当てられている場合、SAMLグループ同期を使用して、@ameliaをメンテナーロールを持つsecurity-gitlabグループ、およびレポーターロールを持つvulnerabilityグループに割り当てることができます。

SAMLグループ同期では、グループは作成されません。最初にグループを作成し、マッピングを作成する必要があります。

GitLab.comでは、SAMLグループ同期はデフォルトで構成されています。GitLab Self-Managedインスタンスでは、手動で構成する必要があります。

ロールの優先順位

グループ同期は、マッピングされたグループ内のユーザーのロールとグループメンバーシップのタイプを決定します。

複数のSAML Identity Provider

ユーザーがサインインすると、GitLabは次の処理を行います:

• 構成されているすべてのSAMLグループリンクを確認します。
• そのユーザーが属するさまざまなIdentity ProviderにわたるSAMLグループに基づいて、対応するGitLabグループにそのユーザーを追加します。

GitLabのグループリンクマッピングは特定のIdentity Providerに紐付けられていないため、すべてのSAML Identity Providerを構成して、SAML応答にグループ属性を含める必要があります。つまり、GitLabは、サインインに使用されたIdentity Providerに関係なく、SAML応答でグループを照合できます。

たとえば、2つのIdentity Provider（SAML1とSAML2）があるとします。

GitLabの特定のグループで、2つのグループリンクを構成しました:

• gtlb-owner => Owner role
• gtlb-dev => Developer role

SAML1では、ユーザーはgtlb-ownerのメンバーですが、gtlb-devのメンバーではありません。

SAML2では、ユーザーはgtlb-devのメンバーですが、gtlb-ownerのメンバーではありません。

ユーザーがSAML1でグループにサインインすると、SAML応答はユーザーがgtlb-ownerのメンバーであることを示すため、GitLabはそのグループ内のユーザーのロールをOwnerに設定します。

その後、ユーザーはサインアウトし、SAML2を使用してグループに再度サインインします。SAML応答は、ユーザーがgtlb-devのメンバーであることを示しているため、GitLabはそのグループ内のユーザーのロールをDeveloperに設定します。

ここで、前の例を変更して、ユーザーがSAML2のgtlb-ownerまたはgtlb-devのメンバーではないようにします。

• ユーザーがSAML1でグループにサインインすると、ユーザーにはそのグループでOwnerロールが付与されます。
• ユーザーがSAML2でサインインすると、構成されているグループリンクのメンバーではないため、ユーザーはグループから削除されます。

複数のSAMLグループ

ユーザーが同じGitLabグループにマップされる複数のSAMLグループのメンバーである場合、ユーザーにはそれらのSAMLグループのいずれかから最高のロールが割り当てられます。

たとえば、あるユーザーがグループでゲストロールを持ち、別のグループでメンテナーロールを持つ場合、メンテナーロールが割り当てられます。

メンバーシップの種類

SAMLグループ内のユーザーのロールが、そのサブグループの1つのロールよりも高い場合、マッピングされたGitLabグループ内のメンバーシップは、マッピングされたグループで割り当てられたロールに基づいて異なります。

グループ同期を介してユーザーに以下が割り当てられた場合:

• より高いロールの場合、グループの直接メンバーになります。
• ロールが同じか低い場合、グループの継承されたメンバーになります。

メンバーの自動削除

グループ同期の後、マッピングされたSAMLグループのメンバーではないユーザーはグループから削除されます。GitLab.comでは、トップレベルグループのユーザーには、削除される代わりにデフォルトのグループメンバーシップロールが割り当てられます。

たとえば、次の図について説明します:

• Alex GarciaはGitLabにサインインし、SAMLグループCに属していないため、GitLabグループCから削除されます。
• Sidney JonesはSAMLグループCに属していますが、まだサインインしていないため、GitLabグループCに追加されません。

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TB
accTitle: Automatic member removal
accDescr: How group membership of users is determined before sign in if group sync is set up.

   subgraph SAML users
      SAMLUserA[Sidney Jones]
      SAMLUserB[Zhang Wei]
      SAMLUserC[Alex Garcia]
      SAMLUserD[Charlie Smith]
   end

   subgraph SAML groups
      SAMLGroupA["Group A"] --> SAMLGroupB["Group B"]
      SAMLGroupA --> SAMLGroupC["Group C"]
      SAMLGroupA --> SAMLGroupD["Group D"]
   end

   SAMLGroupB --> |Member|SAMLUserA
   SAMLGroupB --> |Member|SAMLUserB

   SAMLGroupC --> |Member|SAMLUserA
   SAMLGroupC --> |Member|SAMLUserB

   SAMLGroupD --> |Member|SAMLUserD
   SAMLGroupD --> |Member|SAMLUserC

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TB
accTitle: Automatic member removal
accDescr: User membership for Sidney when she has not signed into group C, and group B has not configured group links.

    subgraph GitLab users
      GitLabUserA[Sidney Jones]
      GitLabUserB[Zhang Wei]
      GitLabUserC[Alex Garcia]
      GitLabUserD[Charlie Smith]
    end

   subgraph GitLab groups
      GitLabGroupA["Group A<br> (SAML configured)"] --> GitLabGroupB["Group B<br> (SAML Group Link not configured)"]
      GitLabGroupA --> GitLabGroupC["Group C<br> (SAML Group Link configured)"]
      GitLabGroupA --> GitLabGroupD["Group D<br> (SAML Group Link configured)"]
   end

   GitLabGroupB --> |Member|GitLabUserA

   GitLabGroupC --> |Member|GitLabUserB
   GitLabGroupC --> |Member|GitLabUserC

   GitLabGroupD --> |Member|GitLabUserC
   GitLabGroupD --> |Member|GitLabUserD

%%{init: { "fontFamily": "GitLab Sans" }}%%
graph TB
accTitle: Automatic member removal
accDescr: How membership of Alex Garcia works once she has signed into a group that has group links enabled.

   subgraph GitLab users
      GitLabUserA[Sidney Jones]
      GitLabUserB[Zhang Wei]
      GitLabUserC[Alex Garcia]
      GitLabUserD[Charlie Smith]
   end

   subgraph GitLab groups after Alex Garcia signs in
      GitLabGroupA[Group A]
      GitLabGroupA["Group A<br> (SAML configured)"] --> GitLabGroupB["Group B<br> (SAML Group Link not configured)"]
      GitLabGroupA --> GitLabGroupC["Group C<br> (SAML Group Link configured)"]
      GitLabGroupA --> GitLabGroupD["Group D<br> (SAML Group Link configured)"]
   end

   GitLabGroupB --> |Member|GitLabUserA
   GitLabGroupC --> |Member|GitLabUserB
   GitLabGroupD --> |Member|GitLabUserC
   GitLabGroupD --> |Member|GitLabUserD

SAML Group Sync

グループ同期構成を追加または変更すると、グループ名がSAML応答にリストされているgroupsと一致しない場合、マッピングされたGitLabグループからユーザーが削除される可能性があります。ユーザーが削除されるのを防ぐために、グループ同期を構成する前に、次のいずれかを確認してください:

• SAML応答にgroups属性が含まれており、AttributeValueの値がGitLabのSAMLグループ名と一致します。
• すべてのグループがGitLabから削除され、グループ同期が無効になります。

SAMLグループ同期を使用し、分散アーキテクチャまたは高可用性アーキテクチャなどで複数のGitLabノードがある場合は、すべてのSidekiqノードに、Railsアプリケーションノードに加えてSAML構成ブロックを含める必要があります。

SAML応答のGroupsまたはgroupsの値は、グループ名またはIDのいずれかです。たとえば、Azure ADは、名前の代わりにAzureグループオブジェクトIDを送信します。SAMLグループのリンクを設定するときは、IDの値を使用してください。

<saml:AttributeStatement>
  <saml:Attribute Name="Groups">
    <saml:AttributeValue xsi:type="xs:string">Developers</saml:AttributeValue>
    <saml:AttributeValue xsi:type="xs:string">Product Managers</saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsなどの他の属性名は、グループのソースとして受け入れられません。

SAML Identity Providerの設定で必要なグループ属性名の構成の詳細については、Azure ADおよびOktaの構成例を参照してください。

SAMLグループリンクを設定する

SAMLグループ同期は、そのグループに1つ以上のSAMLグループリンクがある場合にのみ、グループを管理します。

前提要件:

• GitLab Self-Managedインスタンスで、SAMLグループ同期が構成されている必要があります。

SAMLが有効になっている場合、オーナーロールを持つユーザーには、グループの設定 > SAMLグループのリンクに新しいメニュー項目が表示されます。

• 1つ以上のSAMLグループのリンクを構成して、SAML Identity Providerグループ名をGitLabロールにマップできます。
• SAML Identity Providerグループのメンバーは、次回のSAMLサインイン時にGitLabグループのメンバーとして追加されます。
• グループメンバーシップは、ユーザーがSAMLを使用してサインインするたびに評価されます。
• SAMLグループリンクは、トップレベルグループまたは任意のサブグループに対して構成できます。
• SAMLグループリンクが作成されてから削除され、次の場合があります:
  • 他のSAMLグループリンクが構成されている場合、削除されたグループリンクに含まれていたユーザーは、同期中にグループから自動的に削除されます。
  • 他のSAMLグループリンクが構成されていない場合、ユーザーは同期中にグループに残ります。これらのユーザーは、グループから手動で削除する必要があります。

SAMLグループをリンクするには:

1. SAMLグループ名に、関連するsaml:AttributeValueの値を入力します。ここに入力した値は、SAML応答で送信される値と正確に一致する必要があります。一部のIdentity Providerでは、これはわかりやすいグループ名の代わりに、グループIDまたはオブジェクトID（Azure AD）である場合があります。
2. Access Level（アクセスレベル）で、デフォルトロールまたはカスタムロールを選択します。
3. 保存を選択します。
4. 必要に応じて、追加のグループリンクを追加するために繰り返します。

GitLab Duoシート割り当ての管理

前提要件:

• アクティブなGitLab Duoアドオンサブスクリプション

SAMLグループ同期は、Identity Providerのグループメンバーシップに基づいて、GitLab Duoシートの割り当てと削除を管理できます。シートは、サブスクリプションに残りのシートがある場合にのみ割り当てられます。

Microsoft Azure Activeディレクトリインテグレーション

Microsoft Azureを使用したグループ同期のデモについては、デモを参照してください: Azure ADを使用したSAML Group Syncのデモ。

Azure ADは、groupsクレームで最大150個のグループを送信します。SAMLグループ同期でAzure ADを使用する場合、組織内のユーザーが150を超えるグループのメンバーである場合、Azure ADはグループの超過のためにSAML応答でgroupsクレーム属性を送信し、ユーザーはグループから自動的に削除される可能性があります。

この問題を回避するために、次のAzure ADインテグレーションを使用できます:

• 150個のグループに制限されていません。
• Microsoft Graph APIを使用して、すべてのユーザーメンバーシップを取得するします。Graph APIエンドポイントは、ユーザーオブジェクトIDまたはuserPrincipalNameのみを、Azure構成の一意のユーザー識別子（名前識別子）属性として受け入れます。
• グループ同期を処理する場合、グループの一意の識別子（12345678-9abc-def0-1234-56789abcdeなど）で構成されたグループリンクのみをサポートします。

または、グループクレームをGroups assigned to the application（アプリケーションに割り当てられたグループ）オプションを使用するように変更できます。

Azure ADの構成

インテグレーションの一部として、GitLabがMicrosoft Graph APIと通信できるようにする必要があります。

Azure ADを構成するには:

1. Azure Portalで、Microsoft Entra ID > App registrations（アプリの登録） > All applications（すべてのアプリケーション）に移動し、GitLab SAMLアプリケーションを選択します。
2. Essentialsの下に、Application (client) IDとDirectory (tenant) IDの値が表示されます。これらの値は、GitLab構成に必要なため、コピーします。
3. 左側のナビゲーションで、Certificates & secrets（証明書とシークレット）を選択します。
4. Client secrets（クライアントシークレット）タブで、New client secret（新しいクライアントシークレット）を選択します。
   1. 説明テキストボックスに、説明を追加します。
   2. 有効期限ドロップダウンリストで、認証情報の有効期限を設定します。シークレットの有効期限が切れると、認証情報が更新されるまで、GitLabインテグレーションは機能しなくなります。
   3. 認証情報を生成するには、追加を選択します。
   4. 認証情報の値をコピーします。この値は1回しか表示されず、GitLab構成に必要です。
5. 左側のナビゲーションで、API permissions（APIアクセス許可）を選択します。
6. Microsoft Graph > Application permissions（アプリケーションの権限）を選択します。
7. GroupMember.Read.AllとUser.Read.Allのチェックボックスをオンにします。
8. Add permissions（権限の追加）を選択して保存します。
9. Grant admin consent for <application_name>（の管理者の同意を付与）を選択し、確認ダイアログで可能を選択します。両方の権限のステータス列が、緑色のチェックマークとGranted for <application_name>（Azure ADに付与）に変わるはずです。

GitLabを設定する

Azure ADを構成したら、GitLabがAzure ADと通信するように構成する必要があります。

この構成では、ユーザーがSAMLでサインインし、Azureが応答でgroupクレームを送信すると、GitLabはグループ同期ジョブを開始してMicrosoft Graph APIを呼び出すし、ユーザーのグループメンバーシップを取得します。次に、GitLabのグループメンバーシップがSAMLグループリンクに従って更新されます。

次の表に、GitLab設定と、構成に対応するAzure ADフィールドを示します:

グローバルグループメンバーシップロック

SAMLグループメンバーシップにグローバルロックを適用できます。このロックは、メンバーシップがSAMLグループリンクと同期されているサブグループに新しいメンバーを招待できるユーザーを制限します。

グローバルグループメンバーシップのロックが有効になっている場合:

• グループまたはサブグループをコードオーナーとして設定することはできません。詳細については、グローバルグループメンバーシップロックとの非互換性を参照してください。
• 管理者のみがグループメンバーを管理し、アクセスレベルを変更できます。
• グループメンバーは以下を実行できません:
  • プロジェクトを他のグループと共有する。
  • グループで作成されたプロジェクトにメンバーを招待する。
  • グループリンクが設定されたのメンバーシップは、管理者しか変更できません。

グループメンバーシップをロックする

前提要件:

• GitLab Self-ManagedのSAML SSOが構成されている必要があります。

メンバーシップをSAMLグループリンクの同期にロックするには、次の手順に従います:

1. 左側のサイドバーの下部で、管理者を選択します。新しいナビゲーションをオンにしている場合は、右上隅でアバターを選択し、管理者を選択します。
2. 設定 > 一般を選択します。
3. 表示レベルとアクセス制御セクションを展開します。
4. メンバーシップをSAMLグループリンク同期に限定チェックボックスを選択します。