SCIM プロビジョニング (Pro)

DefectDojo Pro は SCIM 2.0 をサポートしており、ID プロバイダーから DefectDojo ユーザーを直接作成、更新、無効化できます。SCIM がない場合、DefectDojo はユーザーがサインインしたときにのみそのユーザーの存在を把握するため、ID プロバイダーから誰かを削除しても以降のログインは止まりますが、DefectDojo のアカウント自体は有効なまま残ります。

SCIM はシングルサインオンとは別の仕組みであり、それを補完します。SSO は誰がサインインできるかを決定し、SCIM はアカウント一覧自体をディレクトリと同期させます。ほとんどの顧客は両方を設定します。認証には SAML または OIDC を、プロビジョニングには SCIM を使用します。

SCIM の設定は Superuser のみが行えます。

What SCIM does in DefectDojo#

SCIM 経由で ID プロバイダーを接続すると、次のことが可能になります。

• アプリケーションが割り当てられたときに DefectDojo ユーザーを作成する
• ディレクトリで名前やメールアドレスが変更されたときに更新する
• 割り当てが解除されたり組織を離れたりしたユーザーを無効化する
• グループを作成し、そのメンバーの追加や削除を行う

SCIM 経由でユーザーを無効化すると、同時に 2 つのことが行われます。アカウントが非アクティブとしてマークされ、ユーザーはサインインできなくなり、そのユーザーの DefectDojo API トークンが削除されます。そのため、オフボーディングは 1 つの操作で両方の入り口を閉じることができ、これが ID プロバイダーだけに頼るのではなく SCIM を使用する主な理由です。

ユーザーレコード自体は保持されます。検出事項、メモ、履歴はそれらを作成した人物を参照しているため、DefectDojo はアカウントを削除するのではなく無効化します。同じ人物が戻ってきた場合、ID プロバイダー経由で再度有効化すれば、履歴を乱すことなくアクセスを復元できます。

Setup#

1. Connect > Authorization を開き、SCIM Provisioning を選択します。SCIM は同じ ID プロバイダーに接続するため、ログインプロバイダーと並んで表示され、ログインページにボタンを追加するプロバイダーと区別するために Provisioning というタグが付けられています。

2. Enable SCIM Provisioning をチェックして送信します。これがオフの間、SCIM のエンドポイントは存在しないかのように振る舞うため、ID プロバイダーからの接続テストではアドレスが見つからないと報告されます。

3. ページに表示されている Tenant URL をコピーします。次のような形式です。

   https://<your-instance>.cloud.defectdojo.com/scim/v2

4. SCIM Tokens パネルで、たとえば「Okta production」のように、どこで使用するかがわかる名前をトークンに付け、Generate Token を選択します。

5. ダイアログに表示されたトークンをコピーし、ID プロバイダーに貼り付けます。DefectDojo はトークンのハッシュのみを保存するため、再度表示することはできません。トークンを紛失した場合は、新しいトークンを生成し、古いトークンを失効させてください。

複数のトークンを同時に有効な状態で保持できます。ローテーションするには、新しいトークンを生成して ID プロバイダーを更新し、その後古いトークンを失効させます。プロビジョニングが機能しなくなる期間はありません。

トークンパネルには各トークンが最後に使用された日時が記録されており、ID プロバイダーが実際に DefectDojo に到達しているかどうかを手早く確認できます。

Okta#

1. Okta の管理コンソールで、Applications > Browse App Catalog に移動し、SCIM 2.0 Test App (Header Auth) を追加します。すでに DefectDojo 用の SAML アプリケーションがある場合は、代わりにそのアプリケーションでプロビジョニングを有効にできます。

2. Provisioning タブを開き、Configure API Integration を選択します。

3. SCIM 2.0 Base Url に、上でコピーした Tenant URL を設定します。

4. API Token に、Bearer という単語と半角スペース 1 つを含めて Bearer <your token> を設定します。このアプリケーションタイプは、値をそのまま Authorization ヘッダーとして送信します。

5. Test API Credentials を選択し、保存します。

6. Provisioning > To App で、Create Users、Update User Attributes、Deactivate Users を有効にします。

7. 人物またはグループをアプリケーションに割り当てます。Okta はまず DefectDojo 内でユーザー名により各人物を検索し、見つからない場合にのみアカウントを作成するため、すでに DefectDojo アカウントを持っている人物が重複作成されることはなく、既存のアカウントにリンクされます。

グループもプッシュするには、Push Groups タブを開き、DefectDojo にミラーリングさせたいグループを追加します。DefectDojo がそれらのグループをどのように扱うかについては、下記の Groups を参照してください。

Microsoft Entra ID#

1. Entra の管理センターで、Enterprise applications > New application > Create your own application に移動し、non-gallery のオプションを選択します。すでに DefectDojo 用のアプリケーションがある場合は、それを使用してください。

2. Provisioning を開き、Provisioning Mode を Automatic に設定します。

3. Tenant URL に、上でコピーした Tenant URL を設定します。

4. Secret Token に SCIM トークンを設定します。Entra はこれをベアラートークンとして送信するため、ここに Bearer という単語を追加しないでください。

5. Test Connection を選択し、保存します。

6. Users and groups でユーザーとグループを割り当て、プロビジョニングを開始します。

Entra は約 40 分周期でプロビジョニングを行います。設定作業中は、Provision on demand を使用すると単一のユーザーまたはグループを即座に適用できるため、設定が正しく機能しているかをはるかに素早く確認できます。

What DefectDojo stores#

DefectDojo は少数の SCIM 属性のみをマッピングし、それ以外は無視します。

電話番号、役職、SCIM のエンタープライズ拡張など、DefectDojo がモデル化していない属性は、拒否されるのではなく受け入れられて無視されます。ID プロバイダー側で余分な属性をマッピングしても問題ありません。

特に注意すべき属性が 2 つあります。

Username。 DefectDojo は、ユーザー名に文字、数字、および @ . + - _ の文字を許可します。ID プロバイダーがそれ以外の文字を含むユーザー名を送信すると、DefectDojo は別のユーザー名を黙って保存するのではなく、問題を示すエラーとともにそのユーザーを拒否します。変更されたユーザー名を保存してしまうと、後で ID プロバイダーがアカウントを見つけられなくなってしまいます。

Email address。 SCIM ではメールアドレスは必須ではなく、DefectDojo はメールアドレスなしでもユーザーを作成します。ただし、スケジュールされたレポートやアラートを含む DefectDojo の通知は、メールアドレスのないユーザーには送り先がなくなる点に注意してください。特別な理由がない限り、emails 属性はマッピングしてください。

SCIM がパスワードを設定することはなく、superuser や staff のステータスを付与することもありません。ID プロバイダーがパスワードを送信するように設定されていても、DefectDojo はそれを無視します。この方法でプロビジョニングされたユーザーは SSO 経由でサインインします。

Groups#

SCIM は自身が作成したグループのみを管理します。DefectDojo の UI で作成したグループや、SAML や Azure AD のグループマッピング経由で届いたグループは SCIM からは見えず、ID プロバイダーによって名前を変更したり、空にしたり、削除したりすることはできません。

これが重要なのは、グループのプッシュが本質的に完全な置き換えだからです。もし ID プロバイダーが既存のグループを引き継げてしまうと、次回の同期でそのグループの慎重に選ばれたメンバーシップが、ディレクトリの内容にそのまま置き換えられてしまいます。そのため、すでに使用されている名前のグループをプッシュすると、競合を説明するメッセージとともに失敗します。既存のグループを ID プロバイダーに引き渡すには、どちらか一方の名前を変更するか、DefectDojo 側のグループを削除してプロバイダーに再作成させてください。

SCIM が管理するグループ内では、メンバーシップは ID プロバイダーに属し、ロールは DefectDojo に属します。

• 新しく追加されたメンバーには Reader ロールが与えられます。
• DefectDojo で誰かをより上位のロールに昇格させた場合、その後の同期でそのロールが変更されることはありません。
• SCIM が管理するグループに手動で追加された人物は、次回の同期で削除されます。誰が所属すべきかについては ID プロバイダーが正となるためです。

SCIM 経由でグループを削除すると、そのグループとメンバーシップが削除されます。所属していた人物自体が削除されることはありません。

Protecting administrator access#

デフォルトでは、SCIM は superuser アカウントを無効化しません。プロビジョニング設定でよくある失敗は、ID プロバイダーの適用範囲が意図したより広くなってしまうことであり、superuser は何か問題が起きたときに DefectDojo に再びアクセスするための手段です。

ID プロバイダーに superuser も管理させたい場合は、SCIM 設定ページで Allow SCIM to deactivate superusers を有効にします。それでも、DefectDojo は残っている最後のアクティブな superuser を無効化することを拒否するため、プロビジョニングによってインスタンスに管理者が一人もいなくなることはありません。

Limitations#

• DefectDojo インスタンスごとに ID プロバイダーは 1 つのみです。
• フィルタリングは userName、displayName、externalId、id に対して、単一の等価比較でサポートされています。これは Okta と Entra がレコードを照合する際に送信する内容をカバーしています。より複雑なフィルターは、その旨を示すエラーとともに拒否されます。
• 一括操作、ソート、/Me エンドポイントは実装されていません。
• グループメンバーシップは Groups エンドポイント経由で管理されます。ユーザーレコードにグループメンバーシップを送信しても効果はなく、これは両プロバイダーの動作と一致しています。

Troubleshooting#

接続テストで「not found」と表示される。 SCIM がオフになっているか、インスタンスがそのライセンスを持っていません。Enable SCIM Provisioning がオンになっていること、およびサブスクリプションに SSO が含まれていることを確認してください。両方が満たされるまで、SCIM のアドレス全体が存在しないかのように振る舞います。

接続テストで認証エラーが表示される。 トークンが間違っているか、失効しています。新しいトークンを生成し、ID プロバイダーを更新してください。Okta の場合は値が Bearer とスペースで始まっていることを確認し、Entra の場合はそうなっていないことを確認してください。

ユーザー名に関するエラーでユーザーのプロビジョニングが失敗する。 ユーザー名に DefectDojo が許可していない文字が含まれています。ID プロバイダーが userName にマッピングしている属性を変更してください。多くの場合、ユーザーのメールアドレスまたはユーザープリンシパル名に変更します。

その名前のグループがすでに存在すると報告され、グループのプッシュが失敗する。 その名前の DefectDojo グループが他の場所で作成されています。上記の Groups を参照してください。

グループメンバーのプロビジョニングが失敗する。 その人物がまだ DefectDojo にプロビジョニングされていません。アプリケーションに割り当てれば、次のサイクルでメンバーシップが成功します。

まず Diagnostics を確認してください。 拒否された SCIM リクエストは、エンドポイント、ステータス、DefectDojo が返したメッセージとともに Connect > Diagnostics に記録されます。通常、ID プロバイダーのログを読むより速く確認でき、やり取りの両側を確認できる唯一の場所です。成功したプロビジョニングはここには記録されず、ユーザーやグループの変更は代わりに監査履歴に表示されます。

すべて成功と表示されるのに、DefectDojo に何も反映されない。 Tenant URL が末尾にスラッシュを付けずに /scim/v2 で終わっていること、および ID プロバイダーが実際にインスタンスに到達していることを確認してください。SCIM Tokens パネルの Last Used 列で、リクエストが届いているかどうかを確認できます。

DefectDojo Pro をご利用の場合: インスタンスが IP アドレスによるアクセス制限を行っている場合は、SCIM を設定する前に、ID プロバイダーのアドレスをファイアウォールの許可リストに追加してください。詳細は Firewall Rules を参照してください。