• 特徴
• 要件
• GitLabの設定
• アイデンティティ・プロバイダの設定
  • Azure の設定手順
    • 属性マッピングの設定
  • Oktaの設定手順
    • Okta 既知のイシュー
• ユーザーアクセスとリンク設定
  • アクセスの遮断
• トラブルシューティング
  • Azure
    • SCIMの設定が正しいことを確認するにはどうすればよいですか？
    • Azure 接続のテスト: 無効な資格情報
    • Azure：（フィールド）を空白にできない同期エラー
    • ユーザがサインインできない原因を診断する方法
    • ユーザの SAML NameId が SCIM externalId と一致することを確認するには、どうすればよいですか。
    • SCIM externalId と SAML NameId の不一致の更新または修正
    • SCIMアプリを変更する必要があります。

GitLab.com グループ用の SAML SSO を使った SCIM プロビジョニング

GitLab.com Silver11.10で導入されました。

System for Cross-domain Identity Management(SCIM)は、ユーザープロビジョニングの自動化を可能にするオープンスタンダードです。 SCIMがGitLabグループに対してプロビジョニングされると、そのグループのメンバーシップはGitLabとアイデンティティプロバイダ間で同期されます。

GitLabのSCIM APIは RFC7644プロトコルの一部を実装しています。

特徴

現在、以下のアクションが可能です：

• ユーザー作成
• ユーザーの更新（Azureのみ）
• ユーザーの無効化

以下の ID プロバイダがサポートされています：

• Azure
• オクタ

要件

• グループシングルサインオンを設定する必要があります。

GitLabの設定

グループシングルサインオンが設定されると、次のことが可能になります：

1. グループに移動し、[管理]→[SAMLSSO]をクリックします。
2. Generate a SCIM tokenボタンをクリックします。
3. 次のステップで使用できるように、トークンとURLを保存します。

アイデンティティ・プロバイダの設定

• アズール
• オクタ

Azure の設定手順

Azure用のシングルサインオンのセットアップ中に作成した SAML アプリケーションを、SCIM 用にセットアップする必要があります。

1. GitLab SAMLアプリの設定を確認し、Name identifier value(NameID)がuser.objectid 、または他のユニークな識別子を指していることを確認してください。これはGitLabで使用されているextern_uid 。

   

2. Azure の SCIM セットアップドキュメントの「SCIM をサポートするアプリケーションへのユーザーとグループのプロビジョニング」のセクションに従って、自動プロビジョニングと管理者認証情報を設定します。

この設定中、以下のことに注意してください：

• Tenant URL とsecret token は前のステップで取得したもの。
• GitLabの可用性に問題がある場合、または同様のエラーが発生した場合、設定された通知メールがそれらを取得します。
• 通知メールを設定し、障害発生時にメール通知を送信するチェックボックスをオンにすることをお勧めします。
• マッピングについては、Synchronize Azure Active Directory Users to AppName のみを有効にしておきます。

接続が成功したら、次に進む前に必ず設定を保存してください。トラブルシューティングについては、以下を参照してください。

属性マッピングの設定

1. Synchronize Azure Active Directory Users to AppName をクリックして、属性マッピングを設定します。
2. mail マッピングの横にある［削除］をクリックします。
3. userPrincipalName をemails[type eq "work"].value にマップし、マッチングの優先順位を 2に変更します。
4. 地図mailNickname からuserName.

5. GitLabがどのようにユーザーを一意に識別するかを決定します。

   • グループに SAML がすでにリンクされているユーザ以外は、objectId を使用します。
   • すでにSAMLにリンクされているユーザーがいる場合は、SAML設定からName ID 。異なる値を使用すると、ユーザーが重複したり、ユーザーがGitLabグループにアクセスできなくなったりする可能性があります。
6. 新しいマッピングを作成します：
   1. 新しいマッピングを追加］をクリックします。
   2. セット：
      • ソース属性には、上記で決定された一意な識別子、通常はobjectIdを指定します。
      • externalIdへのターゲット属性。
      • この属性を使用するオブジェクトを Yesにマッチさせます。
      • 1への優先順位のマッチング.

7. userPrincipalName マッピングをクリックし、この属性を使用するオブジェクトの一致を Noに変更します。

8. 参考として、トラブルシューティングリファレンスで設定例を見ることができます。

   注： objectId以外の一意識別子を使用した場合は、必ずexternalIdにマッピングしてください。

9. マッピングリストの下にある[Show advanced options（詳細オプションを表示）]>[Edit attribute list for AppName（AppNameの属性リストを編集）]をクリックします。

10. id が主で必須フィールドであり、externalId も必須フィールドであることを確認してください。

    注：username は、GitLab SCIMではまだサポートしていないため、プライマリでも必須でもありません。

11. すべての画面を保存し、ProvisioningステップでProvisioning Status をOnに設定します。

    

    注:Scopeを選択することで、実際に同期されるものを制御できます。例えば、Sync only assigned users and groups を選択すると、アプリケーションに割り当てられているユーザー (Users and groups) のみが同期され、そうでない場合は Active Directory 全体が同期されます。

有効にすると、Provisioning画面の下部に同期の詳細とエラーが表示され、監査ログへのリンクも表示されます。

Oktaの設定手順

Okta用のシングルサインオンのセットアップで作成した SAML アプリケーションを、SCIM 用にセットアップする必要があります。 次に進む前に、GitLab の設定プロセスを完了させてください。

1. Oktaにサインインします。

2. 右上に管理者ボタンが表示されている場合は、そのボタンをクリックしてください。 これで管理者エリアにいることが確認できます。

   ヒント:開発者コンソールを使用している場合、トップバーの開発者コンソールをクリックし、クラシックUIを選択します。 そうしないと、次のステップで説明するボタンが表示されない場合があります：
3. アプリケーション]タブで、[アプリケーションの追加]をクリックします。
4. GitLabを検索し、「GitLab」アプリケーションを見つけてクリックします。
5. GitLab アプリケーションの概要ページで、Addをクリックします。
6. Application Visibilityで両方のチェックボックスを選択します。 現在、GitLabアプリケーションはSAML認証をサポートしていないため、アイコンはユーザーに表示されません。
7. アプリケーションの追加を完了するには、[Done]をクリックします。
8. Provisioningタブで、Configure APIintegration をクリックします。
9. APIインテグレーションを有効にする」を選択します。
   • Base URLには GitLab SCIM 設定ページから取得した URL を入力してください。
   • API Tokenには GitLab SCIM 設定ページから取得した SCIM トークンを入力してください。
10. Test API Credentials」をクリックして設定を確認します。
11. Saveをクリックして設定を適用します。
12. APIインテグレーションの詳細を保存すると、左側に新しい設定タブが表示されます。アプリへ」を選択します。
13. 編集をクリックします。
14. ユーザーの作成]と[ユーザーの無効化]の両方で[有効]にチェックを入れます。
15. 保存をクリックします。
16. Assignmentsタブでユーザーを割り当てます。 割り当てられたユーザーはGitLabグループで作成・管理されます。

Okta 既知のイシュー

OktaのGitLabアプリケーションは、現在SCIMのみをサポートしています。 上記の新しいSCIMアプリケーションとともに、別のOktaSAML SSO設定を引き続き使用してください。

ユーザーアクセスとリンク設定

グループSAMLが設定されている限り、同期をオンにする前に、既存のGitLab.comユーザーは以下のいずれかの方法でアカウントにリンクすることができます：

• GitLab.comユーザーアカウントのプライマリEメールアドレスを、IDプロバイダのユーザープロファイルEメールアドレスと一致するように更新すること。

• 以下の手順に従ってください：

  1. 必要に応じてGitLab.comにサインインします。
  2. ID プロバイダーのダッシュボードで GitLab アプリをクリックするか、GitLab シングルサインオン URLにアクセスしてください。
  3. 作成者をクリックします。

新規ユーザーや既存ユーザーの再訪問は、特定プロバイダーのダッシュボードから、または直接リンクにアクセスして、グループにアクセスすることができます。

ロール情報については、グループSAMLのページを参照してください。

アクセスの遮断

グループへのアクセスを取り消すには、特定のアプリのIDプロバイダまたはユーザーリストからユーザーを削除することをお勧めします。

次回の同期時に、ユーザーはデプロビジョニングされ、グループから削除されます。グループ管理アカウントを使用していない限り、ユーザーアカウントは削除されません。

トラブルシューティング

このセクションでは、遭遇する可能性のある問題の解決策について説明します。

Azure

SCIMの設定が正しいことを確認するにはどうすればよいですか？

以下のレビューをご覧ください：

• id の SCIM 値がNameIdの SAML 値と一致していることを確認します。
• externalId の SCIM 値がNameIdの SAML 値と一致していることを確認します。

以下のSCIMパラメータをレビューして、適切な値を確認してください：

• userName
• displayName
• emails[type eq "work"].value

Azure 接続のテスト: 無効な資格情報

接続をテストする際に、「無効な認証情報が入力されているようです。 管理者アカウントの正しい情報を使用していることを確認してください。Tenant URL およびsecret token が正しい場合、グループ・パスに無効な JSON プリミティブと見なされる可能性のある文字（.など）が含まれていないか確認してください。このような文字をグループ・パスから削除すると、通常はエラーが解消されます。

Azure：（フィールド）を空白にできない同期エラー

プロビジョニングの監査ログを確認すると、次のようなエラーが表示されることがあります。Namespace can't be blank, Name can't be blank, and User can't be blank.

これは、すべての必須フィールド（姓や名など）がマッピングされるすべてのユーザに存在しないことが原因であると考えられます。

回避策として、別のマッピングをお試しください：

1. 上記のAzureマッピングの手順に従ってください。
2. name.formatted ターゲット属性エントリを削除します。
3. displayName source属性を、name.formatted target属性に変更してください。

ユーザがサインインできない原因を診断する方法

GitLab が保存しているIdentity(extern_uid) の値は、id やexternalId が変更されるたびに SCIM によって更新されます。GitLab Identity (extern_uid) の値が SAML から送信されたNameId と一致しない限り、ユーザはサインインできません。

この値はまた、SCIMがid、の idユーザーをマッチさせるために使用さidれ、 id externalId の値が変更されるidたびにSCIMによって更新さ idれます。

この SCIMid と SCIMexternalId が、SAMLNameIdと同じ値に設定されていることが重要です。SAML レスポンスは、デバッグツールを使用してトレースでき、エラーがあればSAML トラブルシューティングのドキュメントを参照して確認できます。

ユーザの SAML NameId が SCIM externalId と一致することを確認するには、どうすればよいですか。

グループのオーナーは、グループ SAML SSO 設定ページで、ユーザのリストと各ユーザに保存されているexternalId を確認できます。

あるいは、SCIM API を使用して、ユーザ用に保存したexternalId (external_uid またはNameIdとも呼ばれます) を手動で取得することもできます。

使用例：

curl 'https://example.gitlab.com/api/scim/v2/groups/GROUP_NAME/Users?startIndex=1"' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

SAML NameId として返される値との比較を確認するには、ユーザに SAMLTracerを使用させます。

SCIM externalId と SAML NameId の不一致の更新または修正

値が変更された場合でも、別のフィールドにマッピングする必要がある場合でも、id、externalId、NameId 、すべて同じフィールドにマッピングされることを確認してください。

GitLab のexternalId が SAML NameId と一致しない場合は、ユーザがログインできるように更新する必要があります。ID プロバイダがこのような更新を行うように設定されているのが理想的ですが、ID の変更によってユーザの検索に失敗するなど、場合によっては更新できないこともあります。

SCIM ID プロバイダによって使用されるフィールド（通常、id およびexternalId）を変更する場合は注意してください。これらの ID はユーザを検索するために使用されます。ID プロバイダがこれらのフィールドの現在の値を知らない場合、そのプロバイダは重複ユーザを作成する可能性があります。

ユーザのexternalId が正しくなく、SAML NameID とも一致しない場合は、以下の方法でアドレスに対処できます：

• SAMLauthentication failed: User has already been taken（SAML認証に失敗しました：ユーザは既に登録されています）”セクションに基づいて、ユーザ自身にリンクを解除させ、再リンクさせることができます。
• プロビジョニングをオンにしている間に SAML アプリからすべてのユーザを削除することで、すべてのユーザのリンクを同時に解除できます。
• SCIM API を使用して、externalId 保存されているユーザを externalId手動で修正して SAML にexternalId 一致 externalIdさせることができますexternalId NameId。 ユーザを検索 NameId externalIdするには、SAMLexternalId NameIdに一致する希望の NameId値と、現在の . externalId

その後、例えば手動でSCIM#update要求をイシューすることが可能です：

curl --verbose --request PATCH 'https://gitlab.com/api/scim/v2/groups/YOUR_GROUP/Users/OLD_EXTERNAL_UID' --data '{ "Operations": [{"op":"Replace","path":"externalId","value":"NEW_EXTERNAL_UID"}] }' --header "Authorization: Bearer <your_scim_token>" --header "Content-Type: application/scim+json"

ユーザがサインインできなくなる原因となるため、間違った値に更新しないことが重要です。 また、ユーザが間違ったアカウントにサインインする原因となるため、間違ったユーザに値を割り当てないことも重要です。

SCIMアプリを変更する必要があります。

個々のユーザは、「SAML認証に失敗しました: ユーザは既に登録されています」セクションの指示に従うことができます。

または、SCIMアプリからユーザーを削除することもできます。 この場合、削除されたユーザーはすべてリンク解除され、新しいSCIMアプリで同期をオンにして既存のユーザーをリンクすることができます。