SAMLグループ同期

プラン: Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

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

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

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

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

役割の優先順位

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

複数のSAML IdP

提供形態: GitLab Self-Managed

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

設定されているすべてのSAMLグループリンクをチェックします。
そのユーザーが異なるIdPで所属しているSAMLグループに基づいて、対応するGitLabグループにそのユーザーを追加します。

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

例として、2つのIdP (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グループにおけるユーザーの役割が、そのサブグループのいずれかにおける役割よりも高い場合、マップされたGitLabグループにおけるユーザーのメンバーシップは、マップされたグループで割り当てられた役割に基づいて異なります。

グループ同期を通じてユーザーが割り当てられた場合:

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

自動メンバー削除

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

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

Alex GarciaがGitLabにサインインすると、SAML Group Cに所属していないため、GitLab Group Cから削除されます。
Sidney JonesはSAML Group Cに所属していますが、まだサインインしていないため、GitLab Group 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グループ同期

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

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

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

SAMLグループ同期を設定するには:

GitLab.comグループのSAML SSOを参照してください。
お使いのSAML Identity Providerが、Groupsまたはgroupsという名前の属性ステートメントを送信していることを確認してください。

SAMLグループ同期を設定するには:

SAML OmniAuthプロバイダーを設定します。

お使いのSAML Identity Providerが、groups_attribute設定の値と同じ名前の属性ステートメントを送信していることを確認してください。この属性は大文字と小文字が区別されます。/etc/gitlab/gitlab.rbにおけるプロバイダー設定の例を参照してください:

gitlab_rails['omniauth_providers'] = [
  {
    name: "saml",
    label: "Provider name", # optional label for login button, defaults to "Saml",
    groups_attribute: 'Groups',
    args: {
      assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback",
      idp_cert_fingerprint: "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8",
      idp_sso_target_url: "https://login.example.com/idp",
      issuer: "https://gitlab.example.com",
      name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
    }
  }
]

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 IdPグループ名をGitLabの役割にマップすることができます。
SAML IdPグループのメンバーは、次回のSAMLサインイン時にGitLabグループのメンバーとして追加されます。
グループメンバーシップは、ユーザーがSAMLを使用してサインインするたびに評価されます。
SAMLグループリンクは、トップレベルグループまたは任意のサブグループに対して設定できます。
SAMLグループリンクが作成されてから削除された場合で、次の条件に該当する場合:
- 他のSAMLグループリンクが設定されている場合、削除されたグループリンクにいたユーザーは、同期中にグループから自動的に削除されます。
- 他のSAMLグループリンクが設定されていない場合、ユーザーは同期中にグループに残ります。これらのユーザーは手動でグループから削除する必要があります。

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

SAMLグループ名に、関連するsaml:AttributeValueの値を入力します。ここに入力された値は、SAML応答で送信された値と正確に一致する必要があります。一部のIdPでは、これはフレンドリーなグループ名の代わりにグループIDまたはオブジェクトID (Azure AD) である場合があります。
Access Levelでデフォルトロールまたはカスタムロールを選択します。
Saveを選択します。
必要に応じて、追加のグループリンクを追加するには繰り返します。

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

提供形態: GitLab.com、GitLab Self-Managed

前提条件:

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

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

GitLab.comの設定方法:

SAMLグループリンクを設定する際に、このグループのユーザーにGitLab Duoのライセンスをアサインしますチェックボックスを選択します。
Saveを選択します。
GitLab Duo ProまたはGitLab Duo Enterpriseシートを割り当てる必要があるすべてのSAMLユーザーに対して、追加のグループリンクを追加するには繰り返します。この設定が有効なグループリンクと一致しないIdentity Providerグループメンバーシップを持つユーザーには、GitLab Duoシートは割り当て解除されます。

アクティブなGitLab Duoアドオンサブスクリプションがないグループの場合、このチェックボックスは表示されません。

Self-Managedを設定するには:

SAML OmniAuthプロバイダーを設定します。

お使いの設定にgroups_attributeとduo_add_on_groupsが含まれていることを確認してください。duo_add_on_groupsの1つ以上のメンバーであるユーザーには、利用可能なシートがある場合、GitLab Duoシートが割り当てられます。/etc/gitlab/gitlab.rbにおけるプロバイダー設定の例を参照してください:

gitlab_rails['omniauth_providers'] = [
  {
    name: "saml",
    label: "Provider name",
    groups_attribute: 'Groups',
    duo_add_on_groups: ['Developers', 'Freelancers'],
    args: {
      assertion_consumer_service_url: "https://gitlab.example.com/users/auth/saml/callback",
      idp_cert_fingerprint: "43:51:43:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8",
      idp_sso_target_url: "https://login.example.com/idp",
      issuer: "https://gitlab.example.com",
      name_identifier_format: "urn:oasis:names:tc:SAML:2.0:nameid-format:persistent"
    }
  }
]

Microsoft Azure Active Directoryインテグレーション

Microsoftは、Azure Active Directory (AD) がEntra IDに名称変更されることを発表しました。

Microsoft Azureを使用したグループ同期のデモについては、デモ: SAMLグループ同期。

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

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

150グループに限定されません。
Microsoft Graph APIを使用してすべてのユーザーのメンバーシップを取得します。The Graph APIエンドポイントは、Azureが設定した固有識別子 (名前識別子) 属性として、ユーザーオブジェクトIDまたはuserPrincipalNameのみを受け入れます。
グループ同期を処理する際、グループ識別子 (例: 12345678-9abc-def0-1234-56789abcde) で設定されたグループリンクのみをサポートします。

または、グループクレームを変更して、Groups assigned to the applicationオプションを使用することもできます。

Azure ADを設定する

このインテグレーションの一環として、GitLabがMicrosoft Graph APIと通信することを許可する必要があります。

Azure ADを設定するには:

Azure Portalで、Microsoft Entra ID > App registrations > All applicationsに移動し、お使いのGitLab SAMLアプリケーションを選択します。
Essentialsの下に、Application (client) IDとDirectory (tenant) IDの値が表示されます。これらの値はGitLabの設定に必要となるため、コピーしてください。
左側のナビゲーションで、Certificates & secretsを選択します。
Client secretsタブで、New client secretを選択します。
1. 説明テキストボックスに説明を追加します。
2. 有効期限ドロップダウンリストで、認証情報の有効期限を設定します。シークレットが期限切れになると、認証情報が更新されるまでGitLabインテグレーションは機能しなくなります。
3. 認証情報を生成するには、追加を選択します。
4. 資格情報の値をコピーします。この値は一度だけ表示され、GitLabの設定に必要です。
左側のナビゲーションで、API permissionsを選択します。
Microsoft Graph > Application permissionsを選択します。
GroupMember.Read.AllとUser.Read.Allチェックボックスを選択します。
保存するには、Add permissionsを選択します。
Grant admin consent forを選択し、その後の確認ダイアログで可能を選択します。両方の権限について、ステータス列がGranted forの緑色のチェックマークに変わるはずです。

GitLabを設定する

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

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

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

GitLab設定	Azureフィールド
テナントID	Directory (tenant) ID
Client ID	Application (client) ID
クライアントシークレット	値 (on Certificates & secretsページ上)

GitLab.comグループのAzure ADを設定するには:

上部のバーで、検索または移動先を選択して、グループを見つけます。このグループはトップレベルにある必要があります。
設定 > SAML SSOを選択します。
グループのSAML SSOを設定します。
Microsoft Azure integrationセクションで、Enable Microsoft Azure integration for this groupチェックボックスを選択します。このセクションは、グループに対してSAML SSOが設定され、有効になっている場合にのみ表示されます。
Azure PortalでAzure Active Directoryを設定した際に取得したテナントID、クライアントID、およびクライアントシークレットを入力します。
オプション。US Government向けAzure ADまたはAzure AD Chinaを使用している場合は、適切なログインAPIエンドポイントとGraph APIエンドポイントを入力します。デフォルト値はほとんどの組織で機能します。
変更を保存を選択します。

前提条件:

管理者アクセス権が必要です。

GitLab Self-Managedを設定するには:

インスタンスのSAML SSOを設定します。
右上隅で、管理者を選択します。
設定 > 一般を選択します。
Microsoft Azure integrationセクションで、Enable Microsoft Azure integration for this groupチェックボックスを選択します。
Azure PortalでAzure Active Directoryを設定した際に取得したテナントID、クライアントID、およびクライアントシークレットを入力します。
オプション。US Government向けAzure ADまたはAzure AD Chinaを使用している場合は、適切なログインAPIエンドポイントとGraph APIエンドポイントを入力します。デフォルト値はほとんどの組織で機能します。
変更を保存を選択します。

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

提供形態: GitLab Self-Managed、GitLab Dedicated

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

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

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

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

前提条件:

GitLab Self-ManagedのSAML SSOが設定されていること。
管理者アクセス権が必要です。

SAMLグループリンク同期へのメンバーシップをロックするには:

右上隅で、管理者を選択します。
設定 > 一般を選択します。
表示レベルとアクセス制御セクションを展開します。
メンバーシップをSAMLグループリンク同期に限定チェックボックスを選択します。