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

このセクションでは、発生する可能性のある問題に対する考えられる解決策を紹介します。

削除後にユーザーを追加できない

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

ユーザーがSCIMアプリに再度追加されると、GitLabは新しいユーザーを作成しません。ユーザーはすでに存在するためです。

2023年8月11日より、skip_saml_identity_destroy_during_scim_deprovision機能フラグが有効になっています。

その日以降にSCIMによってプロビジョニング解除されたユーザーの場合、そのSAMLアイデンティティは削除されません。そのユーザーがSCIMアプリに再度追加されると:

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

その日より前にSCIMによってプロビジョニング解除されたユーザーの場合、そのSAMLアイデンティティは削除されます。この問題を解決するには、ユーザーが既存のGitLab.comアカウントにSAMLをリンクする必要があります。

GitLab Self-Managed

GitLabセルフマネージドの場合、そのインスタンスの管理者は代わりにユーザーアイデンティティを自分で追加できます。管理者が複数のアイデンティティを再度追加する必要がある場合、これにより時間を節約できる可能性があります。

ユーザーがサインインできない

以下は、ユーザーがサインインできない問題に対する考えられる解決策です:

• ユーザーがSCIMアプリに追加されたことを確認します。
• User is not linked to a SAML accountエラーが表示された場合、ユーザーはGitLabにすでに存在している可能性があります。ユーザーにSCIMとSAMLアイデンティティをリンクする手順に従ってもらいます。または、セルフマネージドの管理者はユーザーアイデンティティを追加できます。
• GitLabによって保存されるアイデンティティ（extern_uid）の値は、idまたはexternalIdが変更されるたびにSCIMによって更新されます。サインイン方法のGitLab識別子（extern_uid）がプロバイダーから送信されたID（SAMLによって送信されたNameIdなど）と一致しない限り、ユーザーはサインインできません。この値は、idでユーザーをマップするためにSCIMでも使用され、idまたはexternalIdの値が変更されるたびにSCIMによって更新されます。
• GitLab.comでは、SCIM idとSCIM externalIdは、SAML NameIdと同じ値に設定する必要があります。デバッグツールを使用してSAMLの応答をトレーシングし、SAMLのトラブルシューティング情報を確認してエラーをチェックできます。

ユーザーのSAML NameIdがSCIM externalIdと一致するかどうかが不明な場合

ユーザーのSAML NameIdがSCIM externalIdと一致するかどうかを確認するには:

• 管理者は、管理者エリアを使用してユーザーのSCIMアイデンティティをリスト表示できます。
• グループオーナーは、グループSAML SSO設定ページで、各ユーザーに対して保存されているユーザーのリストと識別子を確認できます。
• SCIMを使用して、extern_uid GitLabがユーザーに対して保存したものを手動で取得し、SAMLの各ユーザーの値を比較できます。
• ユーザーにSAMLトレーサーを使用させ、SAML NameIdとして返される値とextern_uidを比較させます。

SCIM extern_uidとSAML NameIdが一致しません

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

• extern_Id
• NameId

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

通常extern_IdであるSCIMアイデンティティプロバイダーで使用されるフィールドを修正する場合は注意してください。アイデンティティプロバイダーは、この更新を実行するように設定する必要があります。アイデンティティプロバイダーが更新を実行できない場合があります。たとえば、ユーザーのルックアップが失敗した場合などです。

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

識別子の値を一致するように変更するには、次のいずれかを実行します:

• ユーザーに自分のリンクを解除して再リンクさせます。これは、SAML認証が失敗しましたに基づいています: ユーザーはすでに取得されていますセクション。

• プロビジョニングがオンになっている間に、SCIMアプリからすべてのユーザーを削除して、すべてのユーザーのリンクを同時に解除します。

  これにより、トップレベルグループとサブグループ内のすべてのユーザーのロールが設定されたデフォルトのメンバーシップロールにリセットされます。

• SAMLまたはSCIMを使用して、ユーザーに対して保存されているextern_uidを手動で修正し、SAML NameIdまたはSCIM externalIdと一致させます。

行ってはいけないこと:

• これらを正しくない値に更新しないでください。これにより、ユーザーがサインインできなくなります。
• 値を間違ったユーザーに割り当てないでください。これにより、ユーザーが間違ったアカウントにサインインすることになります。

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

SCIMアプリの変更

SCIMアプリが変更された場合:

• ユーザーはSAMLアプリの変更セクションの手順に従うことができます。
• アイデンティティプロバイダーの管理者は、次のことができます:
  1. SCIMアプリからユーザーを削除します。これは、次のようになります:
     • GitLab.comでは、削除されたすべてのユーザーがグループから削除されます。
     • GitLabセルフマネージドでは、ユーザーをブロックします。
  2. 新しいSCIMアプリの同期をオンにして、既存のユーザーをリンクします。

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

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

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

メンバーのメールアドレスはこのグループでは許可されていません

SCIMプロビジョニングがHTTPステータス412で失敗し、次のエラーメッセージが表示される場合があります:

The member's email address is not allowed for this group. Check with your administrator.

このエラーは、次の両方が当てはまる場合に発生します:

• ドメインによるグループアクセス制限がグループに対して設定されています。
• プロビジョニングされるユーザーアカウントに、許可されていないメールドメインがあります。

この問題を解決するには、次のいずれかを実行します:

• ユーザーアカウントのメールドメインを、許可されたドメインのリストに追加します。
• すべてのドメインを削除して、ドメインによるグループアクセス制限機能を無効にします。

SCIMリクエストのRailsログを検索

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

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

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

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

メンバーのメールアドレスがSCIMログのエラーにリンクされていません

GitLab.comでSCIMユーザーをプロビジョニングしようとすると、GitLabはそのメールアドレスを持つユーザーがすでに存在するかどうかを確認します。次の場合、次のエラーが表示されることがあります:

• ユーザーは存在しますが、SAMLアイデンティティがリンクされていません。
• ユーザーは存在し、SAMLアイデンティティがあり、と active: falseに設定されたSCIMアイデンティティを持っています。
• ユーザーは存在しますが、関連付けられているトップレベルグループのメンバーではなく、SAML SSOの適用が有効になっています。

The member's email address is not linked to a SAML account or has an inactive
SCIM identity.

このエラーメッセージは、ステータス412で返されます。

これにより、影響を受けるエンドユーザーが自分のアカウントに正しくアクセスできなくなる可能性があります。

最初の回避策は次のとおりです:

1. エンドユーザーに既存のGitLab.comアカウントにSAMLをリンクしてもらいます。
2. ユーザーがこれを完了したら、アイデンティティプロバイダーからSCIM同期を開始します。SCIM同期が同じエラーなしで完了した場合、GitLabはSCIMアイデンティティを既存のユーザーアカウントに正常にリンクしており、ユーザーはSAML SSOを使用してサインインできるようになっているはずです。

エラーが解決しない場合は、ユーザーがすでに存在し、SAMLとSCIMアイデンティティの両方があり、active: falseに設定されたSCIMアイデンティティを持っている可能性が非常に高くなります。これを解決するには:

1. オプション。最初にSCIMを設定したときにSCIMトークンを保存しなかった場合は、新しいトークンを生成します。新しいSCIMトークンを生成する場合は、must（必ず）アイデンティティプロバイダーのSCIM設定でトークンを更新する必要があります。そうしないと、SCIMが機能しなくなります。

2. SCIMトークンを見つけます。

3. を使用して、単一のSCIMプロビジョニングされたユーザーを取得します。

4. 返された情報を確認して、次のことを確認してください:

   • ユーザーの識別子（id）とメールが、アイデンティティプロバイダーが送信しているものと一致します。
   • activeがfalseに設定されます。

   この情報のいずれかが一致しない場合は、GitLabサポートに連絡してください。

5. を使用して、SCIMプロビジョニングされたユーザーのactiveの値をtrueに更新します。

6. 更新がステータスコード204を返す場合は、ユーザーにSAML SSOを使用してサインインを試みてもらいます。

Azure Active Directory v2

次のトラブルシューティング情報は、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 URL https://gitlab.com/users/sign_inのHTML結果が含まれる場合があります。

このエラーは無害であり、グループプロビジョニングがオンになっていることが原因で発生しますが、GitLab SCIMインテグレーションはそれをサポートまたは必要としません。エラーを削除するには、Azure設定ガイドの手順に従って、Azure Active DirectoryグループをAppNameに同期するオプションを無効にします。

Okta

次のトラブルシューティング情報は、Oktaを介してSCIMプロビジョニングされた場合に固有の情報です。

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

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

Error authenticating: null

Oktaは、ユーザーをプロビジョニングまたはプロビジョニング解除するために、GitLabインスタンスに接続できる必要があります。

Okta SCIMアプリケーションで、SCIMのBase URL（ベースURL）が正しく、有効なGitLab SCIMエンドポイントURLを指していることを確認してください。このURLに関する情報を見つけるには、次のドキュメントを確認してください:

• GitLab.comグループ。
• GitLab Self-Managed。

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