SCIMのトラブルシューティング

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

ユーザーを削除したら追加できない

ユーザーを削除すると、そのユーザーはグループから削除されますが、アカウントは削除されません（アクセスの削除を参照）。

ユーザーを SCIM アプリに追加し直しても、GitLab は新しいユーザーを作成しません。

2023年8月11日から、skip_saml_identity_destroy_during_scim_deprovision 機能フラグが有効になります。

この日から SCIM によってプロビジョニングを解除されたユーザーについては、SAML ID は削除されません。

そのユーザが SCIM アプリに再び追加されたとき：

  • その SCIM アイデンティティactive 属性はtrue に設定されます。
  • 彼らは SSO を使用してサインインできます。

その日付より前に SCIM によってプロビジョニングを解除されたユーザの SAML ID は破棄されます。

この問題を解決するには

  1. ユーザーに GitLab に直接サインインしてもらいます。
  2. 手動でアカウントをリンクします。

ユーザーがサインインできません。

ユーザーがサインインできない場合、次のような解決策が考えられます：

  • ユーザーが SCIM アプリに追加されていることを確認します。
  • User is not linked to a SAML account エラーが表示された場合、ユーザーは既に GitLab に存在している可能性があります。ユーザーにLink SCIM and SAML identitiesの指示に従ってもらいます。
  • GitLab が保存しているIdentity(extern_uid) の値は、id やexternalId が変更されるたびに SCIM によって更新されます。GitLab Identity (extern_uid) の値が SAML から送信されたNameId と一致しない限り、ユーザーはサインインできません。この値は、SCIM がid, の idユーザーをマッチさせるためにも使用され、externalId の値が変更されるたびに SCidIM によって更新さ idれます。
  • SCIMid および SCIMexternalId は、SAMLNameId と同じ値に設定する必要があります。デバッグツールを使用して SAML レスポンスをトレースし、エラーがあればSAML トラブルシューティング情報と照合することができます。

ユーザの SAMLNameId が SCIM と一致するか不明。externalId

ユーザの SAMLNameId が SCIMexternalId と一致するかどうかを調べるには：

  • 管理者は、管理領域を使用して、ユーザーのSCIM ID をリストできます。
  • グループのオーナーは、グループの SAML SSO 設定ページで、ユーザーのリストと各ユーザーに保存されている識別子を確認できます。
  • SCIM APIを使用して、GitLab がユーザーに対して保存しているextern_uid を手動で取得し、SAML APIから各ユーザーの値を比較することができます。
  • ユーザーにSAML Tracerを使ってもらい、extern_uid と SAMLNameId として返された値を比較します。

SCIMextern_uid と SAML の不一致。NameId

値が変更されたか、別のフィールドにマップする必要があるかにかかわらず、以下は同じフィールドにマップする必要があります：

  • externalId
  • NameId

GitLabextern_uid が SAMLNameId と一致しない場合は、GitLabextern_uid を更新してユーザーがサインインできるようにする必要があります。

SCIM アイデンティティ・プロバイダ（通常はexternalId ）が使用するフィールドを修正する場合は注意してください。アイデンティティ・プロバイダがこの更新を行うように設定されている必要があります。ユーザーの検索に失敗した場合など、ID プロバイダが更新を行えない場合もあります。

GitLabはこれらのIDを使ってユーザーを検索します。ID プロバイダがこれらのフィールドの現在の値を知らない場合、そのプロバイダは重複したユーザーを作成したり、期待したアクションを完了できなかったりする可能性があります。

識別子の値を一致するように変更するには

  1. SAML 認証に失敗しました：ユーザは既に登録されています。
  2. プロビジョニングがオンになっている間に、SCIM アプリからすべてのユーザーを削除して、すべてのユーザーを同時にアンリンクします。
  3. SAML APIまたはSCIM APIを使用して、ユーザーに保存されているextern_uid を手動で修正し、SAMLNameId または SCIMexternalIdと一致させます。

を使用してはなりません：

  • ユーザーがサインインできなくなるためです。
  • ユーザが間違ったアカウントにサインインしてしまうため、間違ったユーザに値を割り当てます。

さらに、ユーザーのプライマリ電子メールは、SCIM ID プロバイダの電子メールと一致する必要があります。

SCIMアプリの変更

SCIMアプリが変わると

  • ユーザーは、「SAML アプリの変更」セクションの指示に従うことができます。
  • ID プロバイダの管理者は、以下のことができます：
    1. SCIM アプリからユーザーを削除すると、削除されたすべてのユーザーのリンクが解除されます。
    2. 新しい SCIM アプリの同期をオンにして、既存のユーザーをリンクします。

SCIM アプリが"User has already been taken","status":409 エラーを返します。

SAML または SCIM の設定またはプロバイダを変更すると、以下の問題が発生する可能性があります：

  • SAML および SCIM ID の不一致。この問題を解決するには
    1. ユーザの SAMLNameId が SCIMextern_uidと一致することを確認します。
    2. 不一致の SCIMextern_uid と SAMLNameIdを更新または修正します。
  • GitLab とアイデンティティプロバイダーの SCIM アプリの間で SCIM アイデンティティが不一致です。この問題を解決するには
    1. GitLabに保存されているユーザーのextern_uid を表示し、SCIMアプリのユーザーexternalId と比較するSCIM APIを使用してください。
    2. 同じ SCIM API を使って、GitLab.com 上のユーザーの SCIMextern_uid を更新します。

Rails のログを検索して SCIM リクエストを探します。

GitLab.com の管理者は、Kibanaのpubsub-rails-inf-gprd-* インデックスを使用してapi_json.log 内の SCIM リクエストを検索できます。内部グループ SCIM APIに基づいて以下のフィルタを使用します：

  • json.path:/scim/v2/groups/<group-path>
  • json.params.value:<externalId>

関連するログエントリでは、json.params.value 、GitLab が受け取る SCIM パラメータの値が表示されます。これらの値を使用して、ID プロバイダの SCIM アプリで設定された SCIM パラメータが意図した通りに GitLab に伝達されているかどうかを確認してください。

例えば、これらの値を、あるアカウントが特定の詳細セットでプロビジョニングされた理由の決定的なソースとして使用します。この情報は、アカウントが SCIM アプリの設定と一致しない詳細で SCIM プロビジョニングされた場合に役立ちます。

Azure Active Directory

以下のトラブルシューティング情報は、Azure Active Directoryを介してプロビジョニングされたSCIMに特化したものです。

SCIMの設定が正しいか確認します。

以下のことを確認してください：

  • externalId のマッチングの優先順位は 1 です。
  • externalId の SCIM 値は、NameId の SAML 値と一致します。

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

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

invalid credentials 接続テスト時のエラー

接続テスト時にエラーが発生する場合があります：

You appear to have entered invalid credentials. Please confirm
you are using the correct information for an administrative account

Tenant URL およびsecret token が正しい場合、グループ・パスに無効な JSON プリミティブと見なされる文字 (. など) が含まれていないか確認してください。グループ・パス内のこれらの文字を削除するか、URLエンコードすると、通常、エラーは解決されます。

(Field) can't be blank 同期エラー

プロビジョニングの監査イベントをチェックすると、Namespace can't be blank, Name can't be blank, and User can't be blank. エラーが表示されることがあります。

このエラーは、マップされるすべてのユーザーに対してすべての必須フィールド（姓や名など）が存在しないために発生する可能性があります。

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

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

Failed to match an entry in the source and target systems Group 'Group-Name' エラー

Azure でのグループプロビジョニングは、Failed to match an entry in the source and target systems Group 'Group-Name' エラーで失敗することがあります。エラーのレスポンスには、GitLab URLhttps://gitlab.com/users/sign_in の HTML 結果を含めることができます。

このエラーは無害で、グループプロビジョニングがオンになっているにもかかわらず、GitLab SCIMインテグレーションがそれをサポートしておらず、またそれを必要としていないために発生します。このエラーを取り除くには、Azure 設定ガイドの指示に従って、Azure Active Directory グループを AppName に同期するオプションを無効にしてください。

Okta

以下のトラブルシューティング情報は、Oktaを通じてプロビジョニングされたSCIMに特化したものです。

Error authenticating: null API SCIM 認証情報をテストする際のメッセージ

Okta SCIMアプリケーションでAPI認証情報をテストする際に、エラーが発生する場合があります：

Error authenticating: null

ユーザーのプロビジョニングやデプロビジョニングを行うには、OktaがGitLabインスタンスに接続できる必要があります。

Okta SCIM アプリケーションで、SCIMBase URLが正しく、有効な GitLab SCIM API エンドポイント URL を指していることを確認してください。このURLに関する情報は、以下のドキュメントを確認してください：

セルフマネージドGitLabインスタンスの場合、Oktaが接続できるようにGitLabが公開されていることを確認してください。必要に応じて、ファイアウォールでOktaのIPアドレスへのアクセスを許可してください。